ReviewOS

home-lang/home

docs: reconcile AOT, concurrency and safety claims with the code

#813
Closed chris opened this 9 days ago ·
9 days ago

Problem

Several docs claim more than the code delivers, or less:

  • TS_PARITY_PLAN.md lists "Native AOT — Real, ships TS→x64"; no TS→native lowering exists.
  • The README says single-entrypoint LLVM builds work; that path is effectively dead.
  • PARITY-STATUS.md / ROADMAP-WEB-COMPETITIVE.md / packages/runtime/README.md mark single-file builds "not started", but they landed on Aug 28.
  • hir.zig says native codegen consumes HIR; codegen imports only ast.
  • ROADMAP-WEB-COMPETITIVE.md marks "No data races (Send/Sync) – Done ✅"; nothing enforces it.
  • PARITY-NODE.md says worker_threads is "🔴 Not implemented", while it passes 34/34.
  • THREADING_IMPLEMENTATION.md describes priority-inheritance, robust mutexes and timed locks that don't exist.
  • The README lists "threading" as a stdlib feature.

Evidence (origin/main @ d4b219507)

Scope

  • Every AOT, concurrency and safety claim links a test, or is marked 🚧 / not implemented.

Acceptance criteria

  • No claim in the listed files lacks either a test reference or a 🚧 marker.

Part of #814.

9 days ago

First evidence-backed reconciliation batch pushed as d73153f. README, TS_PARITY_PLAN, PARITY-STATUS, the runtime README, and the HIR source contract now distinguish Home AST native codegen from JSC-hosted bundled JS/TS standalones. The false TS-to-x64 and HIR-consumed-by-native-codegen claims are removed; standalone module graphs are marked landed, while TypeScript AOT and the cross-target matrix remain explicitly in progress. Claims link the actual codegen and standalone regression suites. Validation: zig fmt --check and git diff --check passed; referenced test files exist. Pickier reported only pre-existing whole-file findings outside the changed lines. Remaining #813 concurrency, safety, Node worker, and threading claims stay open for subsequent batches.

9 days ago

Second reconciliation batch pushed as 610504234. The roadmap no longer claims Send/Sync data-race freedom; PARITY-NODE moves worker_threads from unimplemented to partial with direct corpus links; and THREADING_IMPLEMENTATION now documents only the actual spin-based primitives, APIs, and tests while linking remaining work in #802, #803, #805, and #806. Scoped Pickier validation completed with zero errors and only three pre-existing warnings outside changed lines; git diff --check was clean.

9 days ago

Completed by d73153f2c, 610504234, and 9ad690ab9. Every claim called out in this issue now has direct test/source evidence or an explicit 🚧/experimental marker: JS/TS AOT and standalone behavior, HIR consumers, data-race enforcement, worker_threads, threading semantics, and the README/stdlib memory-safety wording. The final three-file batch passed scoped Pickier validation under a 1,024 MB guard and git diff --check; all commits are on origin/main.

Sign in to comment on this issue.