docs(stdlib): settle namespace model — real modules + qualified paths (#132) (#151)

Records the ruling that gates the rest of the #128 stdlib-AOT epic
(#133/#135/#137/#138): the stdlib uses real modules with qualified
paths, not a flat de-duplicated prelude.

- ADR-011 (accepted) added to .machine_readable/6a2/META.a2ml using the
  existing [[adr]] schema.
- Ledger entry in docs/specs/SETTLED-DECISIONS.adoc.
- Dated decision section + downstream sequencing table in the named
  docs/history/MODULE-SYSTEM-PROGRESS.md.

Rationale: the compiler already has module/use/:: + module_loader.ml,
and the newer stdlib files already use it; only the legacy core files
are flat. Single ownership resolves the prelude/option/result
signature-divergent duplicates. No code change.

Closes #132
Refs #128

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/META.a2ml

@@ -669,3 +669,77 @@ references = [
   "docs/DESIGN-VISION.adoc (faces section)",
   "docs/specs/faces.adoc",
 ]
+
+[[adr]]
+id = "ADR-011"
+status = "accepted"
+date = "2026-05-17"
+title = "Stdlib namespace model: real modules with qualified paths"
+context = """
+The AffineScript stdlib was never compiled through the static
+resolve → typecheck → codegen pipeline as a coherent unit (issue #128).
+Its core files (prelude, option, result, collections, string, io,
+testing, effects, math, traits) are interpreter-era code: a flat global
+namespace with no `module`/`use`/`open`, and conflicting duplicate
+definitions across files — `prelude.affine` and `option.affine` both
+define `is_some`/`unwrap`/`map`/… with *incompatible* signatures
+(`prelude.map(arr, f)` vs `option.map(f, opt)`). Commit b895374 seeded
+`Some/None/Ok/Err` as builtins to make `string.affine` resolve
+standalone, a band-aid that entrenches the flat namespace.
+
+Issue #132 required a single ruling — real modules vs intentionally
+flat-and-deduplicated — because #133 (dedup), #135 (whole-stdlib
+compile), #137 (multi-module integration test) and #138 (band-aid
+removal) all branch on it.
+
+The compiler already has the machinery: the grammar accepts
+`module X;`, `use path;` and `::`-qualified paths; `module_loader.ml`
+resolves module paths to files with search paths, nested modules and
+caching; and the *newer* stdlib files (Core, Crypto, Ajv, Sqlite,
+Grammy, Deno, Network, Vscode, VscodeLanguageClient) already declare
+`module X;` and use qualified constructors (`Ordering::Less` in
+traits.affine). Only the legacy core files are flat.
+"""
+decision = """
+The stdlib uses **real modules with qualified paths**, not a flat
+de-duplicated prelude.
+
+- Every `stdlib/*.affine` declares `module <Name>;` and is addressed by
+  its module path.
+- Cross-file use is explicit: `use option::{Option, Some, None};` /
+  qualified references `Result::unwrap`.
+- There is exactly one canonical definition per name, owned by its
+  module. The `prelude`/`option`/`result` overlaps are resolved by
+  giving each name a single owning module and having the others `use`
+  it (no duplicate, signature-divergent copies).
+- A minimal, explicit prelude module may re-export the few universally
+  needed names (`Option`, `Result`, `Some`, `None`, `Ok`, `Err`); it
+  contains *re-exports*, not independent redefinitions.
+- The b895374 seeded builtins are removed once resolution flows through
+  the module path (tracked by #138); they are not load-bearing.
+
+This is the path consistent with the machinery the compiler and the
+newer stdlib already use; it makes the AOT pipeline exercise real
+cross-module resolution, which is the actual #128 objective.
+"""
+consequences = """
+- #133 removes the duplicate/conflicting prelude/option/result defs by
+  assigning each name one owning module; non-owners `use` it.
+- #135 brings the legacy core files under `module`/`use` as it makes
+  each compile through resolve → typecheck → codegen.
+- #137 (multi-module integration test) is meaningful: it exercises
+  several modules `use`d together, which the flat model could not test.
+- #138 can delete the seeded-builtins band-aid once the prelude
+  re-export module exists and resolution uses it.
+- Slightly more up-front import wiring than a flat prelude, but it is
+  the model the language already commits to elsewhere (ADR pointer:
+  newer stdlib + `module_loader.ml`), so no new compiler design debt.
+- This decision is settled; do not reopen without amending this ADR.
+"""
+references = [
+  "https://github.com/hyperpolymath/affinescript/issues/128",
+  "https://github.com/hyperpolymath/affinescript/issues/132",
+  "docs/history/MODULE-SYSTEM-PROGRESS.md (2026-05-17 decision section)",
+  "lib/module_loader.ml",
+  "lib/parser.mly (module_decl / import_decl / COLONCOLON)",
+]

docs/history/MODULE-SYSTEM-PROGRESS.md

@@ -349,3 +349,54 @@ type context = {
 2. Phase 2: Function call implementation
 
 **Current State:** Ready to begin Phase 3 (Advanced Type System)
+
+---
+
+## Decision: stdlib namespace model (2026-05-17, issue #132 / ADR-011)
+
+Settles the open question gating the #128 stdlib-AOT epic: does the stdlib
+have real modules, or stay flat-and-deduplicated?
+
+**Decision: real modules with qualified paths.** Not a flat de-duplicated
+prelude. Status: **accepted, settled** (ADR-011 in
+`.machine_readable/6a2/META.a2ml`; ledger entry in
+`docs/specs/SETTLED-DECISIONS.adoc`).
+
+### Rationale
+
+The compiler already has the machinery — the grammar accepts `module X;`,
+`use path;` and `::`-qualified paths; `module_loader.ml` resolves module
+paths with search paths, nested modules and caching; and the *newer*
+stdlib files (Core, Crypto, Ajv, Sqlite, Grammy, Deno, Network, Vscode,
+VscodeLanguageClient) already declare `module X;` and use qualified
+constructors (`Ordering::Less`). Only the legacy core files (prelude,
+option, result, collections, string, io, testing, effects, math, traits)
+are flat interpreter-era code with conflicting duplicate definitions
+(`prelude.map(arr, f)` vs `option.map(f, opt)`). Choosing real modules
+aligns the legacy files with the model the language already commits to,
+and makes the AOT pipeline exercise real cross-module resolution — the
+actual objective of #128.
+
+### Model
+
+- Every `stdlib/*.affine` declares `module <Name>;`.
+- Cross-file use is explicit: `use option::{Option, Some, None};` /
+  qualified `Result::unwrap`.
+- Exactly one canonical definition per name, owned by its module. The
+  prelude/option/result overlaps are resolved by single ownership; the
+  others `use` the owner (no signature-divergent copies).
+- A minimal prelude module may *re-export* the universally needed names
+  (`Option`, `Result`, `Some`/`None`/`Ok`/`Err`) — re-exports only.
+- The b895374 seeded `Some/None/Ok/Err` builtins are removed once
+  resolution flows through the module path (#138); not load-bearing.
+
+### Downstream sequencing (this epic)
+
+| Issue | Work unlocked by this decision |
+|---|---|
+| #133 | Remove prelude/option/result conflicting dups via single ownership; non-owners `use` the owner. |
+| #135 | Bring legacy core files under `module`/`use` as each is made to compile resolve→typecheck→codegen. |
+| #137 | Multi-module integration test (`use`s several stdlib modules together) — now a meaningful test. |
+| #138 | Delete the b895374 seeded-builtins band-aid once the prelude re-export module exists. |
+
+No code change in #132 (decision + documentation only).

docs/specs/SETTLED-DECISIONS.adoc

@@ -132,3 +132,25 @@ Neither role is subordinate. They are kept distinct in documentation and in
 
 See `typed-wasm/docs/architecture/AGGREGATE-LIBRARY-VISION.adoc` for the
 aggregate library design.
+
+== Stdlib Namespace Model: Real Modules (ADR-011)
+
+The standard library uses real modules with qualified paths, *not* a flat
+de-duplicated prelude.
+
+Every `stdlib/*.affine` declares `module <Name>;`; cross-file use is
+explicit (`use option::{Option, Some, None};` / `Result::unwrap`); there is
+exactly one canonical definition per name, owned by its module. A minimal
+prelude module may *re-export* the universally needed names (`Option`,
+`Result`, `Some`/`None`/`Ok`/`Err`) — re-exports, never independent
+redefinitions.
+
+This resolves the `prelude` vs `option` vs `result` signature-divergent
+duplicates (`prelude.map(arr, f)` vs `option.map(f, opt)`) by single
+ownership, and makes the AOT pipeline exercise real cross-module
+resolution — the actual objective of issue #128. It is consistent with
+the machinery the compiler (`module_loader.ml`, `module`/`use`/`::`
+grammar) and the newer stdlib files (Core, Deno, Vscode, …) already use.
+
+Settles issue #132; gates #133/#135/#137/#138. Full ADR in
+`.machine_readable/6a2/META.a2ml` (ADR-011).