writeonce/docs/stories/language-runtime-database/05-language-surface.md
shoney.arickathil c0b0dbb846 docs: audit all markdown against the code, fix findings, flatten status folders
- README: shipped concurrency/HTTP/WebSockets sat in the roadmap as "not yet
  available"; "no package manager" contradicted [deps]; the deps example
  would not have compiled (the key IS the module name)
- runtime/README: leads with wovm, wo-rt.c demoted to a historical section;
  dropped 2 nonexistent recipes, crates/rt, @gc refcounting, 13 suites -> 18
- employee + log-watcher READMEs claimed "does not compile"; both are gates
- error catalog: +10 emitted codes incl WO-E250, the only diagnostic the
  shipped query surface raises; recorded why the sweep rotted
- language-surface: group-by parses, then the typechecker refuses it
- 00-code-review + 00-link-audit re-run; history kept, not rewritten
- 48 dead Rust-era exploration links de-linked rather than re-pointed (their
  prose names the retired plan by number); successor map -> discarded.md
- 08-project-structure: compiler/plan/ never existed; corpus has 9 dirs, 5 empty
- releasing.md: dropped a --draft step the workflow never had
- new docs/00-doc-audit.md: findings + disposition, incl one row where the
  audit was wrong and the doc it accused was right
- status folders removed: 34 stories flat, status only in frontmatter; 252
  links recomputed from resolved paths; board/board-views/structure retaught
- story 24 -> in-progress, since frontmatter is now the only truth
- new iteration 38: fs mutation verbs + net.connect, the two capability
  families no iteration owned
- new iteration 39: gofiber/fiber v3.5.0 parity study. The ledger called
  CSRF/sessions unblocked by iteration 34's HMAC, but the runtime has no
  source of randomness at all
- linkcheck skips .dev/.superpowers: 0 broken paths, 0 bad anchors

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-26 19:20:22 +02:00

74 lines
3.1 KiB
Markdown

---
iteration: "5"
status: done
---
# Iteration 5 — language surface (Haxe-parity adoptions)
> Format: `product/story-iteration-template`. Part of
> [Story — one language, one runtime, one database, one binary](00-story.md).
> **Status: ✅ COMPLETE 2026-08-20.** The *grammar* half landed 2026-08-14 —
> modules, `and`/`or`, interpolation, `const`, loop control, switch
> expressions, typedef records, enum payloads, try/catch, `nil`/`?T`,
> statics, `pub(read)` syntax, container literals, `for k, v in m`, `as`.
> The *strictness* half landed in three waves: `?T` forced handling
> (WO-E211/212/213 + narrowing) and reject rows (WO-E105) on 2026-08-18;
> the final three on 2026-08-20 (branch `language-surface-strictness`,
> developer directive overriding the post-12 park) — **`pub(read)` write
> enforcement** (WO-E219, class-owned writes, corpus-pinned),
> **`using` static extensions** (compile-time rewrite to a free-fn call,
> WO-E220 on method collision, zero owner/emit awareness), and **`#if`
> build flags** (`woc -D name`, token-level filter, WO-E003 misuse).
> `is`/`throw` stay cut (0 workload uses); `abstract` is a reject row.
> Plan 8 is closed.
## Goals
- The language grows from milestone grammar to a daily-driver surface: the
systems-track verdict table's every **adopt** row — switch expressions,
typedef records with `?fields`, `?T` optionals with null-narrowing,
enum payload variants, try/catch/throw over traps, `static` members,
`abstract` newtypes, `using` extensions, `use` modules, `is`, `pub` /
`pub(read)`, `#if` build flags, string interpolation, loop control.
- Every **reject** row (inheritance, `Dynamic`, `cast`, macros, FFI…)
refuses with a diagnostic citing doctrine — the language's boundaries are
as deliberate as its features.
## Acceptance Criteria
- What to achieve?
- **Given** the verdict table in the systems-track spec,
- **when** the corpus runs,
- **then** every adopt row has at least one golden fixture and one
must-fail fixture passing, and every reject row that would parse
produces its doctrine-citing diagnostic.
- What to achieve?
- **Given** a switch over a union missing one variant and lacking
`default`,
- **when** it compiles,
- **then** the diagnostic names exactly the missing variants.
- What to achieve?
- **Given** the three fenced VM changes (catch frames, variant objects,
boxed scalar optionals),
- **when** they land,
- **then** the format doc is updated in the same change and all prior
trap fixtures still pass byte-for-byte.
## Out Of Scope
- Stdlib modules and program mode (iteration 6).
- Any new VM capability beyond the three fenced changes.
## Info
- Normative table: `docs/superpowers/specs/2026-08-01-systems-track-design.md` Part 1.
- Order inside the plan matters: modules first (everything imports through
them), data shapes before optionals, rejects last.
## Proposed Solution
- Execute the existing plan: `compiler/plan/2026-08-01-haxe-parity-language.md`
(nine tasks, each shipping its fixtures and error-catalog entries in the
same task).