Implement the first public ASPL MVP

Archived MVP specification. For ASPL 0.7.0, see the current reference and native HTTP guide.

Status: ready-for-agent Source: Find the ASPL MVP specification and all resolved decision tickets linked from that map.

Problem Statement

Arabic-speaking systems programmers do not have an implementation of the specified ASPL MVP that they can evaluate in Arabic, use from a self-contained Linux tool, or try safely in a browser. The repository currently contains a closed planning map, primary research, decision prototypes, and detailed acceptance obligations, but no conforming compiler, VM, CLI, native packager, website, release archive, or conformance evidence.

The implementation must preserve one language across Arabic and English source vocabulary. It must also make the native and browser capability boundaries honest. In particular, the browser cannot load Linux shared libraries or execute ELF files, and the native C boundary supports only two exact function types. The project must not turn a finished specification into claims of implementation conformance or release readiness until the required evidence passes.

Solution

Build the ASPL 0.1.1 common, native, and browser profiles defined by the resolved map. The official implementation is a portable C11 compiler and register VM with required Linux APIs, distributed for baseline x86-64 Linux with glibc 2.34 or later as one aspl executable. The tool checks, runs, and builds one .aspl source file without starting a compiler, assembler, or linker. Native builds copy a validated PIE VM template and append canonical ASPL bytecode. Native execution may load compatible shared libraries through the two specified foreign adapter profiles.

Compile the same compiler core and VM ahead of time into one single-threaded WebAssembly module running in a dedicated worker. Put it behind an Arabic-default, bilingual website and browser-local playground with token-aware mixed-direction editing, explicit resource limits, stoppable execution, and no server-side source execution.

Ship the language, CLI, browser experience, documentation, installation path, conformance suite, and release evidence as one versioned product. Use the ASPL conformance manifest to trace every normative requirement to external evidence. Reserve the official release claim until the common and both host profiles, clean-system matrix, accessibility review, performance gates, reproducible build, and distribution checks all pass without waivers.

User Stories

As an Arabic-speaking systems programmer, I want ASPL to use Arabic as its canonical vocabulary, so that I can read and write systems-oriented source in Arabic.
As an English-speaking programmer, I want exact English keyword aliases, so that I can use the same language model without entering a separate dialect.
As a bilingual programmer, I want Arabic and English aliases to mix per occurrence, so that vocabulary choice never changes program meaning.
As a programmer sharing source with another user, I want source vocabulary preserved, so that interface language changes do not rewrite my program.
As an Arabic keyboard user, I want Arabic-form digits converted to ASCII in executable source, so that ordinary numeric input works without changing strings or comments.
As a programmer editing mixed-direction code, I want token-aware RTL and LTR display, so that punctuation, identifiers, numbers, and comments appear in a safe readable order.
As a programmer inspecting suspicious source, I want invisible directional controls shown explicitly in diagnostics, so that they cannot silently reorder the meaning I see.
As a programmer naming functions and bindings, I want strict Unicode and identifier rules, so that normalized and confusable names have predictable behavior.
As a programmer, I want one statically typed language core, so that native and browser implementations agree on accepted programs.
As a programmer, I want exact bool, i64, f64, string, and c_ptr value types, so that stored values have clear semantics.
As a programmer, I want unit to mean that no value exists, so that no-result functions cannot leak placeholder values into ordinary code.
As a programmer, I want initialized immutable bindings by default, so that mutation is explicit and uninitialized locals are impossible.
As a programmer who needs loops, I want explicit mutable local bindings, so that I can update state without making every binding mutable.
As a programmer, I want lexical scope without visible-name shadowing, so that every name use has one obvious target.
As a programmer, I want typed top-level functions and source-order-independent resolution, so that direct recursion, mutual recursion, and later definitions work predictably.
As a programmer, I want one reserved no-argument entry function returning i64, so that program startup and process status have one contract.
As a programmer, I want process statuses outside 0 through 255 to trap, so that the runtime never silently truncates the entry result.
As a programmer, I want operands and arguments evaluated left to right, so that side effects and traps occur deterministically.
As a programmer, I want Boolean operators to short-circuit, so that excluded branches do not run.
As a programmer doing integer work, I want checked i64 arithmetic, so that overflow and invalid division stop with named traps instead of invoking C undefined behavior.
As a programmer doing floating-point work, I want defined IEEE 754 binary64 behavior, so that native and browser results agree on signed zero, infinities, rounding, and NaN.
As a programmer converting numbers, I want explicit conversions, so that type changes and conversion traps are visible in source.
As a programmer using text, I want immutable UTF-8 string literals with embedded NUL support, so that string values preserve their exact bytes.
As a programmer, I want exact string equality, so that comparison does not depend on storage identity or hidden normalization.
As a programmer interacting with C, I want opaque nullable pointers, so that ordinary ASPL code can relay a C object without pretending it can inspect or own it.
As a programmer, I want اطبع and print to name one safe output builtin, so that both hosts can write exact string bytes without requiring C interoperability.
As a programmer, I want the output builtin to add no newline or terminator, so that the bytes written are exactly the bytes I supplied.
As a programmer, I want every foreign declaration and call marked unsafe at its own site, so that the C boundary remains visible wherever it is introduced or used.
As a native ASPL programmer, I want to call int(const char *) functions through a named adapter, so that compatible functions such as puts have an exact supported contract.
As a native ASPL programmer, I want to call double(double) functions through a named adapter, so that compatible functions such as sqrt have an exact supported contract.
As a programmer passing an ASPL string to C, I want a call-scoped NUL-terminated copy, so that ASPL string storage and lifetime are not misrepresented as C string storage.
As a programmer, I want unsupported C signatures rejected while checking, so that a dynamic symbol is never called through an approximate C type.
As a programmer, I want missing foreign libraries and symbols detected before main, so that program side effects do not begin after partial native preparation.
As a programmer, I want browser foreign imports rejected as a host-policy result, so that a valid language feature is not misreported as a syntax error.
As a programmer, I want source findings to carry stable reason keys and typed arguments, so that wording changes do not change diagnostic identity.
As an Arabic CLI user, I want Arabic diagnostics and help by default, so that the primary interface follows the product's Arabic-first commitment.
As an English CLI user, I want an explicit English diagnostic option, so that I can select equivalent English wording without changing results.
As a programmer, I want exact source spans and safe excerpts, so that I can locate failures in UTF-8 and mixed-direction source.
As a programmer, I want compiler recovery to report independent errors without cascading noise, so that one mistake does not hide unrelated findings.
As a programmer, I want traps, limits, load failures, cancellation, host failures, and internal failures kept separate, so that I can tell what stopped the program.
As a programmer debugging a direct run, I want source-mapped trap locations and bounded call traces, so that runtime failures point back to responsible source.
As a programmer running a generated native program, I want bytecode function and instruction locations when source maps are absent, so that failures still have a stable technical location.
As a CLI user, I want aspl check to run the complete compilation and bytecode-validation path, so that success means later compiler stages also accepted the source.
As a CLI user, I want aspl run to execute a validated program in process, so that there is no hidden child compiler or runner.
As a CLI user, I want aspl build to create a standalone native program, so that the compiler and runtime need not remain installed beside it.
As a CLI user, I want all workflows to accept exactly one .aspl file, so that the MVP does not imply a module or package system.
As a CLI user, I want strict option parsing and stable failure statuses, so that scripts can detect usage and tool failures predictably.
As a CLI user, I want successful check and build commands to be silent, so that automation receives output only when something needs attention.
As a CLI user, I want program stdout left unprefixed and uncaptured during run, so that ASPL program output behaves like ordinary process output.
As a builder, I want build output published atomically, so that a failed build cannot expose a partial executable or overwrite the previous good artifact.
As a builder, I want deterministic native artifacts, so that identical release, source, and options produce identical bytes.
As a builder, I want check and build to avoid opening declared shared libraries, so that compilation does not depend on the deployment machine's library set.
As a user of a built ASPL program, I want the VM and bytecode embedded in one executable, so that no separately installed ASPL runtime is required.
As a user of a built ASPL program, I want native loading to validate both the payload envelope and bytecode before execution, so that malformed artifacts fail before imports or main.
As a browser visitor, I want a runnable Arabic example in the first viewport, so that I can evaluate the language before reading a long introduction or installing it.
As a browser visitor, I want source checking and execution to stay on my device, so that my source is never uploaded to a runner.
As a browser visitor, I want the interface to state that it runs bytecode only, so that I do not mistake the playground for Linux ELF or shared-library execution.
As a playground user, I want automatic checking after a short pause, so that diagnostics update without running the program.
As a playground user, I want every Run to perform a fresh complete check, so that execution never trusts stale validation.
As a playground user, I want execution to use an immutable source snapshot, so that edits made during a run cannot alter the active program.
As a playground user, I want stale results labeled as belonging to a previous snapshot, so that I do not confuse them with the current editor contents.
As a playground user, I want Stop to terminate and replace the worker immediately, so that an infinite loop or stuck WebAssembly call cannot freeze the page.
As a playground user, I want output shown as it is accepted, so that I can see progress before normal completion or a failure.
As a playground user, I want partial output retained after Stop, a trap, or a limit, so that useful bytes are not erased when execution ends abnormally.
As a playground user, I want non-printing output rendered visibly, so that control characters cannot reorder or hide surrounding interface content.
As a playground user, I want explicit compile, execution, memory, recursion, instruction, time, and output ceilings, so that the evaluation environment stays responsive.
As a playground user, I want examples in Arabic, English, and mixed vocabulary, so that I can compare equivalent notation in the same implementation.
As a website visitor, I want one guided route through Try, Learn, Reference, C interoperability, and Install, so that I can move from evidence to exact contracts without dead ends.
As a documentation reader, I want short lessons aimed at programmers who know basic C, so that the material does not spend the MVP on a beginner curriculum.
As a documentation reader, I want every example labeled by supported host, so that I know whether it runs in the browser, native Linux, or both.
As a documentation reader, I want exact accepted and rejected forms with named outcomes, so that reference pages are useful for implementation and debugging.
As a reader switching locales, I want Arabic and English pages to have one-to-one counterparts, so that neither locale weakens or adds normative rules.
As a reader switching locales, I want the current page, anchor, source example, run state, focus, and scroll position preserved, so that language switching does not reset my work.
As a keyboard user, I want every website and playground action reachable with visible focus, so that mouse input is never required.
As a screen-reader user, I want correct landmarks, announcements, reading order, and source locations in both locales, so that the product is operable with assistive technology.
As a low-vision user, I want WCAG 2.2 AA contrast, zoom, reflow, and non-color status cues, so that the interface remains understandable under my display settings.
As a privacy-conscious visitor, I want no analytics, remote fonts, source upload, server runner, or update check, so that trying ASPL causes only necessary same-origin static requests.
As a Linux user, I want the supported x86-64 and glibc 2.34 floor stated before download, so that I can verify compatibility before spending time installing.
As a Linux user, I want a single versioned release archive with SHA-256 verification, so that I can check archive integrity before extraction.
As a Linux user, I want a user-owned installation under .local/bin, so that the default setup does not require administrator privileges.
As a Linux user, I want exact upgrade, rollback, and uninstall instructions, so that I can control which immutable release is active.
As a recipient, I want the complete MIT and Apache-2.0 license texts, so that I can choose either license with the archive in hand.
As a performance-sensitive user, I want the complete small-program build to meet the documented warm-cache p95 budget, so that the fast-build claim measures the real command and publication path.
As a contributor, I want one manifest linking every atomic requirement to evidence, so that implementation work cannot quietly omit a settled rule.
As a contributor, I want tests to exercise public profile behavior first, so that refactoring C module boundaries does not invalidate correct tests.
As a contributor, I want a narrow conformance driver for otherwise hidden facts, so that canonical bytecode, structured diagnostics, injected failures, and source maps remain testable without becoming public APIs.
As a contributor, I want independent bytecode, ELF, archive, and website inspectors, so that production code does not certify its own output.
As a contributor, I want deterministic failure injection, sanitizer runs, and fuzz targets, so that allocation, cleanup, parser, loader, and packager failures receive evidence.
As a third-party implementer, I want common, native, and browser profiles stated separately, so that I can make a precise self-attested claim for the profiles I actually pass.
As a release maintainer, I want evidence tied to one frozen candidate identity, so that changed inputs automatically invalidate stale results.
As a release maintainer, I want byte-identical production builds from fresh directories, so that published native, browser, documentation, archive, and checksum bytes are reproducible.
As a release maintainer, I want clean tests on RHEL 9, Ubuntu 22.04, and Debian 12 without build tools installed, so that the Linux distribution and self-contained build claims have direct evidence.
As a release maintainer, I want witnessed Arabic-primary and screen-reader sessions, so that automated checks do not stand in for mixed-direction and assistive-technology review.
As a release maintainer, I want immutable artifacts, evidence, old releases, and suite revisions, so that a published claim can still be audited later.
As a project reader, I want limitations published in Arabic and English from the conformance manifest, so that unsupported features and narrow guarantees are not softened by marketing copy.
As a project reader, I want specification completion kept separate from implementation and release completion, so that the resolved map is not mistaken for a shipped language.

Implementation Decisions

Product and profile boundaries

ASPL 0.1.1 is one Arabic-first language with exact English source aliases. The MVP includes the language, compiler, register VM, native CLI, C interoperability, browser playground, bilingual website and documentation, distribution, conformance system, and official release gates.
The official compiler and VM use portable C11 plus required Linux APIs. User builds start no compiler, assembler, linker, or other build subprocess. The release has no required third-party compiler or runtime library and no vendored compiler or runtime library.
The common profile covers source notation, semantics, diagnostics, canonical bytecode, VM behavior, and the output builtin. The native profile adds the Linux CLI, C interoperability, native limits, and ELF packaging. The browser profile adds browser host policy, worker execution, browser limits, output handling, and playground behavior.
A conforming implementation claim names its implementation, version, claimed profiles, suite revision, manifest hash, and evidence bundle. The unqualified claim requires both native and browser profiles. Only the project may call a build the Official ASPL 0.1.1 release.
The first native target is baseline x86-64 Linux with glibc 2.34 or later. Musl, other architectures, and non-Linux hosts are unsupported in the MVP.

Source notation and Unicode

Source files use .aspl, strict UTF-8, and pinned Unicode 17.0 data. A BOM is permitted only at byte zero. Source spans are half-open original-byte ranges with one-based logical line and Unicode scalar columns for presentation.
Arabic keyword spellings are canonical. The exact English aliases normalize to the same parser tokens before grammar rules run: دالة/fn, دع/let, متغير/var, إذا/if, وإلا/else, طالما/while, أرجع/return, خارجي/foreign, غير_آمن/unsafe, صواب/true, خطأ/false, عدم/null, منطقي/bool, ص64/i64, ع64/f64, نص/string, مؤشر_سي/c_ptr, وحدة/unit, and ابدأ_الرئيسية/start_main. The reserved equality aliases are يطابق/matches and تطابق/matches; the other reserved operator aliases are و/and and أو/or.
Every keyword and operator alias is reserved throughout the file. A file has no language mode. Alias mixing is accepted without warning and cannot change semantics.
The output builtin aliases are اطبع/print. The foreign adapter aliases are سي_صحيح__مؤشر_محرف_ثابت/c_int__const_char_ptr and سي_مزدوج__مزدوج/c_double__double. Vocabulary conversion may rewrite only resolved aliases, never ordinary identifiers or literal contents.
Identifiers are case-sensitive NFC names drawn from the specified Arabic-or-Latin XID_Start and XID_Continue profile plus underscore. One identifier cannot mix Arabic and Latin strong scripts. The compiler rejects non-ASCII digits, default-ignorables, disallowed identifier characters, and characters outside the Unicode security profile.
Direction-aware confusable checks produce warnings only. They do not alter name equality. Exact normalized collisions remain errors.
The compiler parses logical source order. LRM and RLM are permitted only at settled token boundaries and are semantically invisible. Diagnostics render all direction controls visibly. Raw controls in strings and comments produce warnings.
ASCII punctuation and digits are structural forms. Call and other non-block statements end with either . or ;; canonical Arabic examples use periods and English examples use semicolons, while mixed source may use either. Equality uses the reserved aliases matches, يطابق, and تطابق; Arabic source chooses either Arabic equality form according to its grammatical context. Conjunction and disjunction use و/and and أو/or. Functions and control flow use braces. Parameters and annotated locals use a colon, and function results use an ASCII arrow.
Numeric literals use decimal ASCII digits with constrained underscore separators. Floating literals require a fraction or exponent. String literals use double quotes and only the settled escapes for backslash, quote, NUL, newline, carriage return, tab, and Unicode scalar value. Comments use line or non-nesting block forms.
Canonical formatting uses four spaces, no tabs or column padding, braces on the header line, else on the preceding closing-brace line, one statement per line, and visible statement terminators.
Token-aware presentation preserves stored logical bytes. Numeric atoms stay LTR, comments choose direction from their contents, and all other atoms, including punctuation, use the selected RTL or LTR atom direction. A plain RTL text area or preformatted block does not conform.
Editors convert Arabic-Indic and Extended Arabic-Indic digits to ASCII only when the lossless lexical view proves the insertion is executable source. Strings and comments retain exact digits. Uncertain malformed text stays unchanged and receives a compiler diagnostic with a complete replacement edit.

Language semantics

Storable values have exactly five types: bool, i64, f64, immutable UTF-8 string, and opaque nullable c_ptr. unit is a function result only and has no runtime value or register slot.
One source file contains only top-level ASPL function definitions and foreign declarations. There are no file-scope values or executable statements.
Exactly one entry function is spelled with either reserved entry alias, takes no arguments, returns i64, cannot be foreign, and cannot be called from ASPL source. Values 0 through 255 become normal process statuses. Other values trap.
ASPL functions, foreign declarations, and builtin aliases share one callable namespace. There are no overloads. A visible local, parameter, function, foreign name, or builtin alias cannot be shadowed. A name may be reused after its lexical scope ends.
Every local has an initializer. Immutable bindings are the default. A local may opt into mutation, while parameters remain immutable. Assignment is a statement and evaluates its complete right side before updating the local.
Functions are typed top-level definitions. Resolution is source-order independent and supports direct and mutual recursion. Calls pass exact typed values by value. There are no nested functions, closures, methods, default arguments, function values, or variadic ASPL functions.
Every reachable path in a non-unit function returns a value. Structural analysis rejects proven unreachable statements. A loop never proves that a containing function returns.
Expressions include literals, value references, calls, explicit numeric conversions, grouping, and the settled unary and binary operations. Assignment and conditionals are not expressions. Only a call may appear as a value-discarding statement.
Evaluation proceeds left to right for operands, call arguments, and initializers. Boolean and and or short-circuit. Conditions require bool; there is no truthiness.
i64 supports negation, arithmetic, equality, and ordered comparisons. Overflow, zero division or remainder, and minimum integer divided or remaindered by negative one trap. Division truncates toward zero and remainder follows the dividend sign.
f64 follows IEEE 754 binary64 with round-to-nearest, ties-to-even. The VM preserves signed zero and infinities and canonicalizes every NaN. Build options cannot relax these semantics.
Numeric conversion is explicit. i64 to f64 uses IEEE rounding. f64 to i64 truncates toward zero and traps for NaN, infinity, or an out-of-range result.
Equality requires the same type. Strings compare exact UTF-8 bytes. Pointers compare opaque identity including null. unit cannot be compared.
Strings originate only from literals in the MVP. They may be stored, passed, returned, discarded, and compared. There is no concatenation, indexing, slicing, interpolation, mutation, or runtime string construction.
Ordinary code may relay and compare c_ptr but cannot dereference it, inspect its address, perform pointer arithmetic, free it, or convert it to another ordinary type.
The output builtin has type (string) -> unit on both hosts. It writes exact bytes synchronously with no newline, terminator, prefix, or formatting. An output failure is a host failure or limit stop, never an ASPL trap or value.
Every foreign declaration and every foreign call has its own unsafe marker. There is no general unsafe block. Unsafe markers disappear before serialization and do not contain arbitrary foreign behavior.

Diagnostics and outcomes

Structured outcomes distinguish normal halt, source diagnostic, policy rejection, load failure, trap, limit stop, cancellation, host failure, and internal failure.
Every diagnostic or failure has a stable lowercase ASCII kebab-case reason plus typed arguments. Final Arabic or English prose never forms part of its identity.
Source diagnostics carry severity, one primary span, ordered labeled secondary spans, typed arguments, and at most one non-overlapping machine-applicable edit. Independent caps allow 20 errors and 20 warnings and report separate truncation flags.
Modern Standard Arabic is the default catalog. English is selected explicitly. Catalog selection never depends on process locale, source aliases, identifier script, or page direction. Both catalogs must have the same keys, arguments, labels, notes, and suggestions with no runtime fallback.
Renderers preserve reason keys and exact technical fields, use ASCII digits, directionally isolate interpolated values, and render controls and unsafe bytes visibly. Terminal output uses a safe logical-order excerpt and omits a caret when exact visual placement is unsafe. Browser output maps exact spans through token-aware presentation.
Malformed UTF-8 stops before lexing. Lexing and parsing recover only at settled boundaries. Checking begins only after lexical and syntax success. Independent semantic errors continue after an internal error type suppresses cascades. No later representation is published after a source error.
Diagnostic order is primary byte offset, then errors before warnings at the same offset, then reason. Exact duplicate records are removed. Warnings survive later errors and do not block a successful workflow.
Version 1 defines five ASPL traps: integer overflow, integer zero divisor, invalid f64 to i64 conversion, invalid process status, and foreign string containing NUL. Each trap carries its settled typed arguments and keeps the frame stack available for reporting.
Direct execution and the playground use an in-memory source map. It maps each final function and instruction pair to the smallest responsible source span and maps imports to declaration spans. Serialized bytecode and generated ELF programs contain no source map.
Call traces show the current frame first. Up to 16 frames are complete. Deeper traces show eight inner and eight outer frames plus the exact omitted count. They never expose C addresses or native frames.

Compiler, VM, and bytecode contracts

The buffer-oriented compiler pipeline is SourceText, LexedSource, ParsedProgram, CheckedProgram, BytecodeModule, canonical byte buffer, bytecode validator, and immutable VmProgram. A successful compile returns the exact bytes, the VmProgram decoded from those bytes, and an optional SourceMap.
Execution prepares a VmProgram under a host policy, creates a fresh execution with its own frames, slots, counters, limits, cancellation control, and callbacks, then returns one structured outcome. Packaging consumes compiled bytes and a validated VM template and returns a completed ELF buffer.
Major representations are opaque outside their owning modules, immutable after successful construction, explicitly owned, and destructible. Module interfaces expose stable IDs, spans, read-only queries, and visitors rather than C struct layouts or pointers into growable storage.
Compiler and VM modules perform no file I/O, terminal rendering, process exit, locale lookup, or subprocess launch. The Linux CLI owns filesystem and terminal behavior. The browser wrapper exchanges buffers. Native foreign loading stays behind the native host adapter.
Every stage accepts explicit limits, a checked allocator, and cancellation control. Allocation failure unwinds complete owned state. Deterministic allocator fault injection is required.
Static checking is host-neutral. A host capability gate runs after checking and before lowering. The browser rejects source imports there, and the bytecode loader independently rejects imported raw bytecode under browser policy.
There is no optimizer. Lowering emits checked unused functions and imports, preserves left-to-right evaluation, uses deterministic table ordering, assigns typed registers monotonically without temporary reuse, stages call arguments in contiguous ranges, and uses one canonical control-flow form per source construct.
Keyword-only alias changes, resolved builtin alias changes, whitespace, and comments do not change canonical bytecode when identifiers, literal contents, declarations, and declaration order stay the same.
ASPL bytecode is a private, documented, versioned format. Version 1 is little-endian, smaller than 2^32 bytes, uses a fixed 48-byte header and eight canonical sections, and accepts no minor negotiation or unknown extension data.
Bytecode type IDs are fixed as bool=1, i64=2, f64=3, string=4, c_ptr=5, and function-result-only unit=6.
Every instruction is four u32 words and 16 bytes. The settled opcode table contains typed loads, copy, conversions, Boolean not, integer and floating arithmetic, typed comparisons, jumps, ASPL and foreign value or discard calls, value or unit returns, and WRITE_STRING as opcode 42. Unknown opcodes and nonzero unused operands are invalid.
Functions have fixed typed register files. Parameters occupy the first registers. Calls use contiguous caller-register argument ranges and fresh bounded VM frames. The bytecode has no operand stack, SSA form, dynamic register growth, NOP, HALT, generic trap, allocation instruction, or extension opcode.
Integer and floating constants store exact 64-bit patterns. Only the canonical quiet NaN pattern is valid in a constant table. String references address strict UTF-8 byte ranges and permit embedded NUL.
The bytecode CRC uses the settled CRC-32/ISO-HDLC parameters and covers the full artifact with its own field treated as zero. It detects accidental corruption and does not authenticate code.
One canonical loader validates the exact envelope, section layout, counts, offsets, padding, strings, constants, function signatures, adapter IDs, instructions, register types, control flow, reachability, and definite assignment before constructing VmProgram. Compiler output crosses the same validator. A failure there is internal for fresh compiler bytes and a load failure for external or embedded bytes.
The VM uses private tagged values and an internal uninitialized slot state. unit has no slot. VM calls use bounded frame and value arrays rather than C recursion. Each released frame clears its slots before reuse.
A validated program is immutable and reusable by fresh execution instances. Execution checks frame, slot, memory, instruction, output, time, cancellation, register tag, and bounds contracts at the settled points. A broken post-validation invariant is an internal VM failure, not an ASPL trap.

C interoperability and native packaging

Native x86-64 glibc interoperability uses exactly two precompiled foreign adapter profiles. Adapter ID 1 is exact C type int (*)(const char *) with ASPL signature (string) -> i64. Adapter ID 2 is exact C type double (*)(double) with ASPL signature (f64) -> f64.
Foreign declarations contain one ASPL name and signature, one exact adapter alias, a literal library name, and a literal C symbol. The checker requires exact profile agreement and rejects duplicate library and symbol byte pairs.
Library and symbol strings are nonempty UTF-8 without NUL. The runtime does not add prefixes, suffixes, versions, or project search directories. It passes names unchanged to normal glibc lookup.
Native preparation sorts imports by library bytes, symbol bytes, then adapter ID. It opens each library once with RTLD_NOW | RTLD_LOCAL, resolves the exact symbol through the dlerror protocol, converts it only to the adapter's exact function pointer type, and completes all imports before main.
A profile 1 call rejects embedded NUL, copies exact string bytes into temporary NUL-terminated storage, loans it for the call only, and frees it after return. A profile 2 call restores ASPL's floating-point environment and canonicalizes returned NaN.
The MVP does not observe errno, floating exception flags, or library-specific error conventions. It has no variadic, aggregate, callback, data-symbol, object-pointer, header-parsing, or arbitrary runtime-shaped call support.
Foreign code may crash, exit, stall, corrupt memory, retain a loan, or violate its declared type. Those cases are outside ASPL trap and cleanup guarantees and must be documented as such.
Native builds copy one release-owned, normalized x86-64 PIE VM template. The template has fixed glibc startup and dependencies, no section table, no writable-executable segment, a non-executable stack, valid RELRO, and a final read-only load segment reserved for the payload.
The distributed tool embeds the template and a manifest containing its exact size, CRC, payload header index, file and virtual offsets, alignment, and immutable ELF facts. The builder parses and validates bytes rather than casting them to C structs.
Native payload version 1 uses a 24-byte little-endian envelope with ASPLELF magic, exact version and header size, the canonical bytecode length, and zero flags. Canonical bytecode follows immediately with no padding or trailing bytes.
Building patches only the final payload segment file and memory sizes. It validates the completed ELF and embedded bytecode before publication. For fixed release, source, and options, the ELF contains no timestamps, paths, destination names, random bytes, or other host-dependent data.
Native startup finds the payload through loaded program headers and the linker-defined payload symbol, validates the envelope and segment, then passes the unchanged bytecode to the canonical loader. It opens program libraries and enters main only after validation succeeds.

Linux CLI

The public commands are check, run, and build. Common options are exactly --diagnostic-language=ar|en and --color=auto|always|never, placed before the command. Build alone accepts -o OUTPUT or --output=OUTPUT before the source. The strict grammar, help and version forms, duplicate handling, and -- behavior from the resolved CLI decision are normative.
Every workflow receives one nonempty regular-file path ending in case-sensitive .aspl. Standard input, multiple operands, directories, devices, FIFOs, and sockets are unsupported. Argument and suffix checks finish before filesystem access.
check runs the full pipeline through serialization and validation, renders findings, writes no artifact, opens no foreign library, and executes nothing.
run uses the same complete compile path, prepares every native import, then executes in the aspl process with inherited current directory, environment, stdin, stdout, and stderr. It supplies no arguments to main and adds no sandbox.
build uses the same compile path, packages and validates the complete ELF in memory, then publishes it through an exclusive temporary in the destination directory and an atomic rename. Failures before rename preserve the old destination and leave no intended partial artifact.
Default build output removes one final lowercase .aspl suffix. Explicit output is used byte for byte. The builder rejects output equal to the source by operand or existing hard-link identity, replaces an output symlink as a directory entry, refuses a directory, and creates no missing parent directory.
Published files use mode 0777 filtered by umask. Publication does not preserve an old destination's metadata and makes no fsync or power-loss durability promise.
Arabic help and diagnostics are the default. English is explicit. Color follows only the option: never disables styling, always emits it, and auto checks whether stderr is a terminal. Help and version are never colored.
Source diagnostics and all non-success classes go to stderr. Successful check and build are silent. Run adds no success text to inherited program stdout.
Stable failure statuses are source error 1, usage 2, policy rejection 3, load failure 4, trap 5, limit stop 6, cancellation 7, host failure 8, and internal failure 9. A normal run or generated program returns the exact entry result from 0 through 255 even when it overlaps a failure number.
Generated native programs accept only --aspl-diagnostic-language=ar|en and --aspl-color=auto|always|never, each at most once in full form. Any other argument fails before envelope validation, import loading, or main.
Native builtin output writes unchanged bytes to stdout, retries interrupted and short writes, reports a failed accepted prefix when possible, and installs no SIGPIPE handler.
The fixed native source and compiler ceilings are 16 MiB of source, 1,048,576 lexical items, 1,048,576 syntax nodes, nesting 256, and 512 MiB of compiler memory.
Fixed native bytecode ceilings are 64 MiB total, 65,536 functions, 4,096 imports, 1,048,576 entries in each numeric and string-reference constant table, 16 MiB of string bytes, 4,194,304 instructions, and 65,536 registers per function.
Fixed native execution ceilings are 4,096 frames, 1,048,576 value slots, and 256 MiB of VM-owned execution memory. The native product sets no output or wall-time ceiling and no practical instruction ceiling below the counter's representational maximum.

Browser playground

The C compiler core and VM are compiled ahead of time into one statically linked, single-threaded Emscripten module. It runs synchronously inside one dedicated worker and exposes buffer-oriented operations with a fixed small host import set.
The browser omits Linux foreign loading, ELF execution, process APIs, filesystem, network, generic JavaScript access, source upload, and server execution. It accepts only bytecode with zero imports.
A new session uses Arabic interface text, a runnable Arabic example, and RTL atom order. It does not restore old edits. The playground has one in-memory source buffer and no account, persistence, files, projects, packages, or multi-file editing.
Desktop layout places status and actions above the editor and a result rail at the inline end. Narrow layout keeps actions above and moves results below. All controls, confirmations, diagnostic navigation, Run, and Stop work by keyboard.
The example set covers Arabic, equivalent English, mixed vocabulary, an infinite loop, a browser-rejected foreign import, and unconverted Arabic-form digits. Replacing edited source requires an inline keep-or-replace confirmation.
Edits schedule the complete browser check 350 milliseconds after the last change. Every job has a monotonic ID and source revision. Obsolete work terminates the worker, stale messages are ignored, and the latest source is rechecked after replacement.
Run always captures current source and repeats the complete check. Execution uses an immutable snapshot while the editor remains usable. Newer-source checking waits while the one worker executes. Old results and output remain visibly marked as belonging to a previous snapshot until the next Run.
Stop immediately terminates the worker during check or execution, invalidates the job, preserves accepted output, records cancellation for an explicit user stop, creates a clean worker, and automatically checks the latest source after reload.
Worker start or unexpected-exit failures are host failures with stable browser operation identities and a Retry action. Initial module loading is excluded from check and run clocks.
Browser output uses the same WRITE_STRING byte semantics, retains exact bytes for accounting, shows accepted bytes live, rejects a whole call that would cross the cumulative cap, preserves partial prior output, and displays non-printing controls safely.
Fixed browser source and compiler ceilings are 1 MiB of source, 131,072 lexical items, 131,072 syntax nodes, nesting 128, 128 MiB of compiler memory, and a 2-second check deadline after a loaded worker accepts the job.
Fixed browser bytecode ceilings are 8 MiB total, 4,096 functions, zero imports, 131,072 entries in each numeric and string-reference table, 2 MiB of string bytes, 524,288 bytecode instructions, and 8,192 registers per function.
Fixed browser execution ceilings are 10,000,000 executed instructions, 512 frames, 131,072 slots, 64 MiB of VM-owned memory, 256 KiB of accepted output, and a 3-second execution deadline. WebAssembly linear memory has a 256 MiB maximum and only one worker job may exist.
The main thread enforces monotonic wall deadlines by terminating the worker. The first observed instruction, output, or time ceiling supplies the outcome.

Website and documentation

The website uses the adopted Guided line and bilingual civic route-board design. Arabic is the default. The first desktop viewport and a 390 by 844 pixel mobile viewport contain token-aware Arabic source and the real Run action.
The global route is Try, Learn, Reference, C interoperability, then Install. The route remains available at every width. Guides link to exact reference contracts and reference pages link back to runnable or checkable evidence.
Arabic is available at the root and canonical Arabic locale path. English has an equivalent locale tree. Each page has one counterpart with the same stable ASCII anchors and normative meaning. Locale URLs are authoritative and copyable.
Language switching preserves the page, semantic anchor, selected example, atom order, execution snapshot or result, focus, and scroll position. It changes only interface and documentation prose.
Arabic and English pages set the matching language and page direction. Layout mirrors through logical properties without reversing DOM or keyboard order. Technical fields receive explicit direction isolation.
The learning path assumes basic C or systems knowledge and covers program shape, types and control flow, functions and classified diagnostics, and explicit native C interoperability. Every example names browser, native, or shared applicability.
Reference pages state the contract, accepted and rejected forms, Arabic and checked English examples where relevant, named failures, host applicability, and a run or check path. Documentation CI compiles or runs registered examples and checks locale, anchor, version, host, output, and outcome parity.
The C guide starts with the narrow compatibility limit, documents both adapters and the call-scoped string loan, uses native puts as its main walkthrough, and places a clear browser rejection notice beside it.
The installation route states host compatibility before download, presents archive, size, licenses, and checksum together, installs one tool, then verifies version and a silent successful aspl check before linking to run and build.
The visual design uses warm reading fields, enamel blue routes, green active or successful states, amber decisions, square geometry, and Alexandria typography. Color never carries status alone. Elevation is reserved for the working source board and persistent header.
The site targets WCAG 2.2 AA and must pass keyboard, visible focus, landmarks, live announcements, contrast, reduced motion, 320 CSS-pixel reflow, text zoom, screen-reader order, and mixed-direction source and diagnostic checks in both locales.
All website code, WebAssembly, fonts, and documentation load from the project origin. Editing, checking, running, stopping, diagnostics, and output cause no network request. There are no analytics, advertising, remote fonts, upload, server runner, or update check.
A normative bilingual MVP limits page is generated from manifest requirements tagged as limitations. Other pages link to it rather than restating narrower versions of the rules.

Distribution, performance, and release

The current release version is 0.1.1 under Semantic Versioning. During pre-1.0, each release states whether it preserves accepted source and documented CLI invocations within its minor line. A pre-1.0 release may make named incompatible language, CLI, bytecode, or packaging changes.
Release assets are immutable. A correction receives a new version. Older archives, checksums, licenses, notices, release notes, and evidence remain available and are marked archived when no longer recommended.
The exact archive is aspl-0.1.1-x86_64-linux-gnu.tar.xz. It contains one same-named directory with aspl, LICENSE-MIT, LICENSE-APACHE, and THIRD-PARTY-NOTICES only when required. It contains no installer, runtime directory, links, absolute paths, or parent traversal.
The executable and containing directory use mode 0755. License and notice files use 0644. The adjacent SHA256SUMS contains one GNU-compatible lowercase SHA-256 line for the compressed archive. SHA-256 is presented as integrity, not publisher authentication.
The default install copies aspl to the user's .local/bin after checksum, extraction, and extracted-version checks. Documentation also gives an explicit administrator install, PATH verification, upgrade, archived-version rollback, and uninstall without automatically editing shell files or deleting user artifacts.
The project is dual licensed under MIT or Apache-2.0 at the recipient's choice. Both complete license texts ship in every archive.
The native fast-build gate measures fresh aspl build processes, complete through atomic publication, on the fixed Intel Core i7-6820HQ reference host. After 10 warm-ups, 200 warm-cache samples must have nearest-rank p95 strictly below 100 ms. Cold results remain informational.
Hosted CI alternates 50 merge-base and candidate samples after warm-up. It fails when the candidate median grows by both more than 10 percent and 2 ms, or p95 grows by both more than 15 percent and 5 ms, unless a reviewed baseline change records the tradeoff.
Native benchmark artifacts must satisfy the settled payload and final-size equations and byte-for-byte determinism. Bytecode and ELF growth use the settled percentage plus absolute regression thresholds.
Firefox and Chromium on the reference host must meet p95 budgets for cold worker ready at 2,000 ms, warm worker ready at 750 ms, loaded-worker check at 250 ms, Run recheck to execution start at 250 ms, small execution at 50 ms, and worker replacement at 750 ms.
The repository carries a checked JSON conformance manifest. Atomic requirement IDs use ASPL-<AREA>-NNNN, are never reused, and name their owner, complete rule, profiles, evidence method, cases, environment, oracle fields, hashed inputs, and limitation status.
The conformance driver exists only for structured or injected facts unavailable through public behavior. Public CLI, generated executables, playground, and deployed website still receive black-box profile tests. Independent inspectors do not call production serializer, loader, packager, or routing code.
Every source fixture has canonical Arabic source. A generator creates English equivalents by changing only resolved aliases, and a hand-written mixed corpus covers every alias. Equivalent success cases compare checked targets, canonical bytecode, output, and outcome. Equivalent rejection cases compare structured findings and construct locations.
The official implementation builds without warnings under pinned GCC and Clang in strict C11 mode. Native suites also pass under AddressSanitizer and UndefinedBehaviorSanitizer with leak detection and injected failure cleanup.
Four sanitizer-backed fuzz targets cover source decoding and parsing, full compilation, raw bytecode loading, and native-envelope loading for at least 60 CPU-seconds each against the frozen candidate. Every discovered failure becomes a permanent named regression.
Clean-system tests use fresh pinned x86-64 RHEL 9, Ubuntu 22.04, and Debian 12 images on real x86-64 hardware, without a compiler, assembler, linker, prior ASPL tool, or installed ASPL runtime.
The browser release pins exact stable Firefox and Chromium versions and tests desktop, 390 by 844, and 320-pixel reflow. One Arabic-primary reviewer covers both browsers, and one screen-reader reviewer uses Firefox with Orca across both locales.
Production builds run twice from fresh directories in the same pinned environment and produce byte-identical native, template, table, WebAssembly, JavaScript, CSS, documentation, archive, and checksum bytes. An independent audit checks glibc symbol floor, baseline x86-64 code, dependencies, archive contents, licenses, and same-origin website assets.
All evidence belongs to one candidate identity containing source commit, version, toolchain and template hashes, website and fixture hashes, manifest hash, suite revision, generated-table hashes, and build-environment identity. A changed named input invalidates every dependent record.
An immutable evidence bundle contains machine JSON and equivalent Arabic and English summaries with complete zero-skip case results, inspector results, build and environment records, clean-host logs, sanitizer and fuzz results, raw benchmarks, artifact hashes, browser and documentation results, accessibility results, and witnessed sessions.
The official release order is specification audit, candidate freeze, two reproducible builds, common and host profile gates, internal and fuzz gates, clean-system and browser gates, performance and documentation gates, immutable asset upload, public-byte retest, immutable version tag, then recommended-release promotion. A failure returns to the earliest invalidated step and cannot be waived by a later success.

Testing Decisions

Tests use one conceptual profile seam. The conformance manifest routes each requirement to the highest observable boundary: public CLI and generated processes for native behavior, the public page and worker protocol for browser behavior, and the contributor-only conformance driver only for facts the product intentionally does not expose.
The public seam is preferred over module-level tests. A test should assert source acceptance or rejection, structured finding, exact output bytes, process status or signal, generated artifact facts, browser state, accessible semantics, or published release bytes. It should not assert C filenames, header organization, struct layout, allocation addresses, hash iteration order, or private helper calls.
The conformance driver is a single narrow additional seam for exact source bytes under host policy, structured diagnostics, checked identities, source maps, canonical bytecode, raw-bytecode loading, controlled VM execution, cancellation, injected failures, owned ELF buffers, and test worker events. It is suite-versioned and never becomes a supported product API.
Deterministic contributor-only structural dumps may support snapshots. They are not compatibility formats. Representative bytecode, ELF, archive, and website outputs also receive independent inspectors and fixed byte-level goldens.
The common-profile suite covers strict UTF-8 and Unicode locations, every alias and mixed vocabulary, identifier and bidi rules, lexical and parser recovery, every semantic success and rejection, all five traps, output bytes, canonical lowering, bytecode serialization and corruption, VM validation, source mapping, all configured limits, cancellation, and allocator failure cleanup.
Prior art for common-profile tests is the semantic acceptance matrix, bilingual notation prototype, Unicode research cases, compiler-pipeline test contract, bytecode validator checklist, diagnostics catalog, and builtin acceptance matrix in the resolved map.
Canonical successful fixtures include hello, sum_loop, recursive_factorial, mutual_recursion, short_circuit, string_identity, float_round_trip, unit_call, builtin_output, null_round_trip, and maximum_status. Rejections and traps remain separate fixtures so an earlier outcome cannot hide another.
Every source-level fixture has canonical Arabic, generated English, and where applicable hand-written mixed evidence. Success compares target identity, bytecode, output, and outcome. Failure compares reason, severity, typed arguments, spans, edit meaning, ordering, and truncation.
Raw bytecode tests name every header, directory, section, record, offset, count, alignment, padding, CRC, version, opcode, type, register, call, branch, reachability, definite-assignment, import, and host-policy rule. Exact boundary and one-past-boundary cases are mandatory.
VM tests observe immutable program reuse with fresh execution state, frame and slot behavior, instruction accounting, output callback outcomes, mapped and unmapped locations, frame-preserving traps, foreign failures, limit stops, cancellation, and injected invariant failures.
Native black-box tests cover every accepted and rejected CLI grammar, Arabic and English output, color modes, paths and file types, all statuses, stream behavior, warning order, exact source labels, source size defense, and help and version behavior.
Build tests cover default and explicit names, source collisions, hard links, symlink replacement, directory and missing-parent failures, every temporary-publication operation, cleanup, mode under several umasks, old-output preservation before rename, atomic visibility, and identical ELF bytes across irrelevant host inputs.
Generated-program tests cover all reserved VM options, rejection before loading or main, exact normal statuses, traps and load failures, signal behavior, independence from an installed aspl, and unchanged library lookup.
Foreign tests call real puts and sqrt, plus a test-only library with the two exact signatures. They cover negative C int conversion, NaN canonicalization, floating-point environment restoration, another compatible library, missing libraries and symbols before side effects, no library opening during check or build, embedded-NUL traps before C entry, and malformed raw imports.
Browser tests use the adopted playground prototype as interaction prior art, not as production code. They cover the 350 ms debounce, mandatory Run recheck, IDs and revisions, stale-message rejection, immutable snapshots, editing during execution, delayed checks, immediate Stop, clean worker replacement, retries, unexpected exits, live and partial output, safe control display, and every limit at and past its boundary.
Browser and website behavior runs in exact pinned Firefox and Chromium versions at desktop, 390 by 844, and 320-pixel reflow. Tests cover keyboard operation, focus, live announcements, accessibility tree, contrast, reduced motion, locale preservation, source atom order, diagnostic navigation, and permanent host-capability labels.
Website and documentation tests use the adopted Guided line and bilingual website prototype as prior art. They verify route order, Arabic-first viewport, locale parity, stable anchors, source examples, expected output and outcome, native or browser labels, C warnings, installation commands, same-origin asset policy, and the generated limitations page.
Accessibility automation is necessary but not sufficient. One Arabic-primary witnessed session covers keyboard and mixed direction in both pinned browsers. A screen-reader witnessed session uses Firefox with Orca across both locales. Any failed scenario blocks release.
Native performance tests use the prescribed fresh-process harness, physical-host preflight, exact fixture hashes, raw nanosecond samples, nearest-rank percentiles, functional artifact checks, and baseline comparison. Browser performance uses the prescribed loaded-worker and worker-replacement timing boundaries in both pinned browsers.
Official implementation tests build with pinned GCC and Clang, then rerun the native suite under AddressSanitizer and UndefinedBehaviorSanitizer with leak detection. Deterministic injected failures enumerate every reachable allocation, publication operation, diagnostic write, and builtin output operation.
Four fuzz targets run concurrently under sanitizers against the exact candidate for at least 60 CPU-seconds each. Fuzzing and property tests add evidence but never replace named negative and boundary cases.
Clean-host release tests run the published installation and execution flow on RHEL 9, Ubuntu 22.04, and Debian 12 without compiler or linker tools. They verify checksums, extraction, version, PATH, all three workflows, builtin and foreign behavior, missing imports, generated-program independence, and the glibc floor.
Reproducibility tests compare complete bytes from two fresh production builds. Independent audits inspect native dependencies, glibc symbol versions, instruction baseline, archive members and modes, notices, website origin policy, and final candidate hashes.
A gate passes only with zero mandatory failures, skips, quarantines, or flaky retries. Environment faults invalidate the affected run. Manifest coverage is 100 percent, every named failure operation runs, and no waiver counts as a pass.
The repository has no production implementation test suite yet. The resolved ticket acceptance matrices, research artifacts, and three adopted prototypes are the current prior art. They define behavior and evidence but do not count as executed conformance results.

Out of Scope

Native machine-code generation, LLVM, assembly, self-hosting, or release builds that bypass the register VM.
Static C archives, automatic header parsing, inline C functions, macros, variadic calls, callbacks, aggregates, data symbols, complete C ABI coverage, arbitrary runtime-shaped calls, or a claim of full C compatibility.
Structs, arrays, modules, package management, multiple source files, program arguments, user-managed heap allocation, generics, concurrency, metaprogramming, closures, nested functions, function values, or a user-extensible prelude.
Globals, executable top-level statements, bitwise operations, shifts, break, continue, runtime string construction, general unsafe blocks, pointer arithmetic, pointer dereference, integer-pointer conversion, or language-level cleanup.
Arabic-Indic or Extended Arabic-Indic digits as stored executable syntax, non-ASCII punctuation alternatives, invented Arabic operators beyond يطابق, تطابق, و, and أو, locale-dependent source behavior, or translation of identifiers and literal data.
Stable public bytecode, a public VM ABI, a stable C embedding API, plugin compiler stages, configurable passes, incremental compilation, persistent caches, serialized syntax trees, or on-disk intermediate files.
Browser ELF execution, Linux shared-library loading, filesystem or network bridges, source upload, server execution, accounts, persistence, projects, packages, or multi-file editing.
Native sandboxing or guarantees against crashes, exits, stalls, memory corruption, dangling pointers, retained loans, and other contract violations inside unsafe foreign code.
Non-Linux native targets, non-x86-64 releases, musl support, package-manager repositories, installers, automatic updates, automatic shell configuration edits, release signing, or a security-support-duration promise.
A beginner curriculum, blog, forum, community platform, package registry, full compiler-internals manual, production-readiness claim, practical C-replacement claim, or certification of third-party implementations.
A production website stack or deployment platform choice beyond the settled product behavior, static-origin policy, bilingual routing, visual system, and release requirements.

Further Notes

The resolved map has no remaining fog. Its ## Answer sections remain the normative authority for detailed grammar tables, opcode assignments, diagnostics, validation rules, numeric limits, prototype choices, and acceptance obligations. This spec gathers those decisions into one implementation brief without replacing their exact contracts.
Specification completion is already established by the closed map. Implementation conformance and the Official ASPL 0.1.1 release remain future evidence-based gates.
ASPL, Arabic Systems Programming Language, is the temporary public name. Source files use .aspl.
The canonical public hello.aspl program sums 1 through 10, writes exact bytes 55\n through اطبع on success, and returns 0. Its generated English and hand-written mixed counterparts must preserve the same checked meaning, bytecode, output, and outcome.
The browser and website prototypes record adopted interaction and visual decisions. They are evidence for those choices, not production implementations or substitutes for browser conformance.