WASI-0.3.0-official inventory sweep: docs truth-sweep + system-clock host support

.dev/debt.yaml

@@ -3,6 +3,83 @@
 # Refresh on every /continue resume — .claude/skills/continue/RESUME.md Step 0.5.
 
 entries:
+  - id: "D-523"
+    layer: "test"
+    status: "note"
+    front: D-wasi03
+    description: |-
+      The committed wasip3 conformance fixtures (`test/component/wasip3/*.wasm`,
+      7 rust CLI components) import **wasi 0.2.6 interfaces** (`wasi:cli@0.2.6`,
+      `wasi:io@0.2.6`, `wasi:clocks/wall-clock@0.2.6`; verified via
+      `wasm-tools component wit` 2026-07-17). The corpus therefore certifies
+      the CM-async export ABI + the 0.2 host surface, NOT the official 0.3.0
+      WIT (system-clock, via-stream stdio, async sockets).
+      **Nightly-bump hypothesis REFUTED by measurement (2026-07-17)**: rust
+      std pins `wasip3 = 0.6.0+wasi-0.3.0-rc-2026-03-15` since ~2026-04-22,
+      and a regen on nightly-2026-06-24 (which compiles that crate) STILL
+      emits all-0.2.6 imports + sync `wasi:cli/run@0.2.0` — the imports come
+      from the BORROWED WASIP2 WASI-LIBC (`-lc` in the link recipe) through
+      which sync-main stdio/env/clock route, not from the nightly's std
+      bindings. (Also measured: nightlies 2026-07-08/-16 cannot build-std for
+      wasip3 at all — upstream `std/sys/env/wasi.rs` `OsStringExt` regression
+      — so 2026-06-24 is pinned as newest-known-good; recipe re-verified.)
+      DISCHARGE now requires one of: (a) upstream ships a wasip3-native
+      wasi-libc/self-contained objects (drop the wasip2 borrow, regen); or
+      (b) switch the fixture path to wit-bindgen-generated 0.3.0 bindings
+      (official wasi-testsuite path ①), heavier toolchain. TRIGGER: rust
+      wasip3 target maturing past Tier-3 / wasi-libc wasip3 release / first
+      real 0.3.0-built consumer.
+    first_raised: "2026-07-17"
+    last_reviewed: "2026-07-17"
+    refs: |-
+      proposal_watch 2026-07-17 entry; D-335 (P3 front); D-448 (wasip3
+      toolchain recipe). Test-side half of the official-0.3.0 alignment
+      (host-side half = D-524).
+  - id: "D-524"
+    layer: "code"
+    status: "note"
+    front: D-wasi03
+    description: |-
+      Official WASI 0.3.0 host-surface residual (host-side half of the
+      official-0.3.0 alignment; spec = `~/Documents/OSS/WASI/proposals/*/wit/`):
+      (1) `wasi:clocks/monotonic-clock@0.3.0` `wait-until: async func(when)` /
+      `wait-for: async func(how-long)` — ASYNC host funcs; need a host-side
+      timer waitable wired into the P3 scheduler (driveScheduler), not a
+      sync trampoline; (2) `wasi:filesystem` via-stream data-plane +
+      `wasi:sockets` async rework + `wasi:http` — already scoped FUTURE-BUCKET
+      under D-335 REMAINING(2), listed here only for the 0.3.0 mapping;
+      (3) interface-version gating: the adapter matches names with `@version`
+      stripped, so 0.2-vs-0.3 signature drift on a SAME-NAMED interface
+      (none today — system-clock/instant took a new name) would need a
+      version-aware dispatch row before any such interface is served.
+      Sync 0.3.0 clocks surface (`system-clock.now/get-resolution` +
+      `monotonic-clock.get-resolution`) SHIPPED in this sweep — see refs.
+    first_raised: "2026-07-17"
+    last_reviewed: "2026-07-17"
+    refs: |-
+      proposal_watch 2026-07-17 entry; D-335 REMAINING(2); D-523 (test-side)
+  - id: "D-525"
+    layer: "build"
+    status: "note"
+    description: |-
+      The `-Dgc` build option is INERT: `build.zig` threads it to
+      `build_options.enable_gc`, whose only reader is the
+      `src/feature/gc/register.zig` re-export that nothing consumes —
+      GC compiles in (and executes) whenever `-Dwasm=v3_0` (the default);
+      the actual strip lever is the wasm-level DCE (`check_build_dce.sh`
+      asserts `gc_struct`/`i31_new` absent from v1_0/v2_0 builds only).
+      ADR-0115 §3 planned `enable_gc` as the op-handler compile-time gate
+      ("WAMR-equivalent nuclear strip") but the op handlers never adopted
+      it. DISCHARGE (pick one): (a) wire the gate — branch the wasm_3_0
+      GC per-op registrations/handlers on `enable_gc` + extend
+      check_build_dce with a `-Dgc=false` leg (binary-size relevant,
+      cf. ADR-0204); or (b) retire the flag + the register.zig re-export
+      and amend ADR-0115 §3. Docs corrected 2026-07-17 (migration guide
+      no longer claims "GC opt-in via -Dgc").
+    first_raised: "2026-07-17"
+    last_reviewed: "2026-07-17"
+    refs: |-
+      ADR-0115 §3; scripts/check_build_dce.sh; migration_v1_to_v2.md §3.2
   - id: "D-522"
     layer: "api"
     status: "note"

.dev/handover.md

@@ -5,14 +5,13 @@
 
 ## Current state — MAINTENANCE MODE (post-v2.0.0)
 
-**v2.2.1 is Latest** (tag `v2.2.1` @62b13a6c9, 2026-07-16 — binary-size
-campaign ADR-0204: CLI −21% ReleaseSafe via D-522 stage 1; release.yml
-auto-built Release + 5 assets; tag USER-GRANTED in-session per ADR-0156.
-v2.2.0 = the 2026-07-09 AOT-full-fidelity line). v1 frozen at `v1.11.1`. Dev model: cut
+**v2.3.0 is the release line** (tag cut 2026-07-17, USER-GRANTED in-session
+per ADR-0156 — WASI-0.3.0-official sweep + system-clock + Homebrew tap
+`brew install clojurewasm/tap/zwasm`; v2.2.1 = 2026-07-16 binary-size line,
+v2.2.0 = 2026-07-09 AOT line). v1 frozen at `v1.11.1`. Dev model: cut
 a `develop/<slug>` branch from `main` → PR → CI `ci-required` 3-OS gate must be
 green to merge. **Release stays user-only (ADR-0156)** — never autonomously tag /
-publish / cut over (v2.2.1 tag was user-granted 2026-07-16 in-session). No
-active campaign; no cron self-re-arm.
+publish / cut over. No active campaign; no cron self-re-arm.
 
 ## Binary-size campaign — CLOSED 2026-07-16 (ADR-0204 Implemented, v2.2.1)
 
@@ -35,18 +34,18 @@ DA-critique 20/20) · close #146 (refutation record + v2.2.1). Key outcomes:
 
 ## AOT-full-fidelity campaign — CLOSED 2026-07-09 (ADR-0203 Implemented)
 
-Kickoff #136 (phases I–III) · stage 1 #137 (36 helper bakes → `[rt+off]`
-slots, D-516) · stage 2 #138 (format v0.5 + `load_compiled.zig`
-deserializer, D-519) · stage 3 #139 (run-path swap, mini-runtime DELETED,
-§4.5.4 start-func JIT bug fixed, D-517+D-518, D-520 CI hole) · stage 4
-#140 (elision serialization D-515(1)) · stage 5 #141 (`--cache` D-508;
-DA-critique failure-path fixes: HIT header-gate + self-heal, refusal =
-BYPASS, interp bypass) · stage V #142 (retro: bench parity record, docs,
-`.cwasm --engine interp` loud refusal, lesson
-failure-path-tests-certified-the-defect). Net: `zig build test-aot-diff`
-cross-process differential 63/63 incl. cache lanes. **Residual =
-D-515(2)** (spec-assert corpus under elision; harness memory
-provisioning) + D-514 (SIMD elision symmetry) — both in debt.yaml.
+PRs #136-#142: format v0.5 full-fidelity, run-path swap (mini-runtime
+DELETED), elision serialization, `--cache` (D-508). `zig build
+test-aot-diff` 63/63 incl. cache lanes. Residual = D-515(2) + D-514
+(debt.yaml). Details: ADR-0203 + CHANGELOG 2.2.0.
+
+## WASI-0.3.0-official sweep — 2026-07-17 (branch develop/wasm30-wasi03-inventory-sweep)
+
+**WASI 0.3.0 released 2026-06-11** (spec at `~/Documents/OSS/WASI/`, clones
+pulled). Docs truth-sweep (README 0.3 row, --help/canon.zig/3.0-runner lies,
+`-Dgc` is INERT → D-525) + `system-clock`/`get-resolution` host support
+(instant{s64,u32}, DA check #12). Fixtures import 0.2.6 → D-523; async
+wait-until/wait-for → D-524. Full diff = proposal_watch 2026-07-17 entry.
 
 ## Active front — G-senior-gap (2026-07-06, /continue entry point)
 

.dev/proposal_watch.md

@@ -5,7 +5,7 @@
 > re-evaluated when they advance. Phase 4 non-web proposals are the
 > v0.2.0 line.
 
-Last reviewed: **2026-07-03**.
+Last reviewed: **2026-07-17**.
 
 > **WASI 0.3.0 RATIFIED 2026-06-11** (Bytecode Alliance; Wasmtime 43+). It
 > rebases WASI onto the **Component Model async primitives** (`async` func,
@@ -83,10 +83,28 @@ Text Encoding Builtins` (skip).
 
 | WASI version   | zwasm phase   | Notes                                   |
 |----------------|---------------|-----------------------------------------|
-| 0.1 (preview1) | Phases 4 / 11 | de-facto baseline; complete in Phase 11 |
-| 0.2 (preview2) | **Phase 17 (ACTIVE)** | Component Model required; full campaign per ADR-0170 (`component_model_plan.md`) |
-| 0.3            | post-v0.1.0 (post-v0.2.0) | **released 2026-06-11**; rebases WASI on CM async — streams/futures replace 0.2 poll/`pollable`; breaking vs 0.2; impl gated on CM-async + stack-switching (D-300, DEFER) |
-
+| 0.1 (preview1) | ✅ COMPLETE   | de-facto baseline; complete since Phase 11 |
+| 0.2 (preview2) | ✅ COMPLETE (default-ON) | Component Model campaign done 2026-06-13 (ADR-0170); official corpus 158/0/0 |
+| 0.3            | 🚧 core SHIPPED (opt-in `-Dwasi=p3`) | **released 2026-06-11**; rebases WASI on CM async (async func / `stream<T>` / `future<T>` — NOT core stack-switching, see callout). zwasm ships the CM-async substrate + cli/clocks/random host; official-0.3.0 interface deltas tracked in the 2026-07-17 entry below |
+
+- **2026-07-17** — **WASI-0.3.0-official diff inventory** (reference clones
+  pulled: WASI monorepo → 2026-07-15 HEAD incl. the `v0.3.0` release of
+  2026-06-11; wasmtime v48; wasm-tools v1.252; the per-interface
+  `WebAssembly/wasi-*` repos were ARCHIVED upstream 2025-11-25 — living WIT =
+  `WASI/proposals/*/wit/`). Deltas between the official 0.3.0 WIT and zwasm's
+  draft-era P3 surface: (1) `wasi:clocks/wall-clock` was RENAMED
+  `system-clock`, `datetime{u64,u32}` → `instant{seconds: s64, ns: u32}`, +
+  `get-resolution`; (2) `wasi:clocks/monotonic-clock` gains `get-resolution` +
+  `wait-until`/`wait-for` **async funcs**; (3) `wasi:cli` stdio via-stream
+  shapes match zwasm's ADR-0190 impl (stdout/stderr `write-via-stream(stream<u8>)
+  -> future<result<_,error-code>>`); (4) `wasi:io` is deleted upstream (CM
+  builtins replace it) — zwasm's P2 wasi:io host stays for 0.2 guests. ALSO
+  measured: the committed `test/component/wasip3/*.wasm` fixtures import
+  **wasi 0.2.6 interfaces** — root cause is the borrowed wasip2 wasi-libc in
+  the link recipe, NOT the nightly pin (nightly-bump hypothesis refuted by a
+  regen on nightly-2026-06-24, which compiles std's `wasip3 0.6.0
+  +wasi-0.3.0-rc` crate yet still emits all-0.2.6; details in D-523).
+  Host-side `system-clock` support added this sweep.
 - **2026-07-03** — **post-v2.0.0 maintenance sweep** (reference clones refreshed
   ff-only: wasmtime / WAMR / wasm-tools / component-model to upstream HEAD; spec +
   testsuite left at their `wg-3.0` / `spec_pin.yaml` pins). **No proposal phase

.dev/reference_clones.md

@@ -14,8 +14,8 @@ material, not project state.
 
 | Path                                             | What it is                                                             |
 |--------------------------------------------------|------------------------------------------------------------------------|
-| `~/Documents/MyProducts/zwasm/`                  | zwasm v1 (current main, ClojureWasm consumer) — **read, never copy**   |
-| `~/Documents/MyProducts/ClojureWasmFromScratch/` | cw v1 — procedural template that this project mirrors                  |
+| `~/Documents/MyProducts/zwasm/`                  | THIS repo (v2 on `main`; v1 frozen at tag `v1.11.1` in the same history — **read v1, never copy**) |
+| `~/Documents/MyProducts/ClojureWasm/`            | cljw — downstream consumer (pins zwasm by git tag-hash) + procedural template this project mirrored |
 | `~/Documents/OSS/wasmtime/`                      | wasmtime + cranelift (winch / regalloc2 reference)                     |
 | `~/Documents/OSS/zware/`                         | Zig idiomatic interpreter                                              |
 | `~/Documents/OSS/wasm3/`                         | wasm3 (M3 IR + tail-call dispatch interpreter)                         |
@@ -34,36 +34,31 @@ material, not project state.
 | `~/Documents/OSS/poop/`                          | Andrew Kelley's perf-bench tool (Zig)                                  |
 | `~/Documents/OSS/hyperfine/`                     | Hyperfine source (bench tool used in `bench/`)                         |
 | `~/Documents/OSS/extism/`                        | Extism (multi-language Wasm host SDK reference)                        |
-| `~/Documents/OSS/WebAssembly/spec/`              | reference interpreter (OCaml) + spec text — see version pin note below |
+| `~/Documents/OSS/WebAssembly/spec/`              | reference interpreter (OCaml) + spec text — checked out at `wg-3.0`; see version pin note below |
 | `~/Documents/OSS/WebAssembly/testsuite/`         | spec testsuite — see version pin note below                            |
 | `~/Documents/OSS/WebAssembly/<proposal>/`        | per-proposal spec + tests (multi-value, simd, gc, eh, ...)             |
+| `~/Documents/OSS/WASI/`                          | WASI spec monorepo — `specifications/wasi-0.3.0/` (released 2026-06-11) + live `proposals/*/wit/` WIT sources. NOTE: the per-interface `WebAssembly/wasi-*` repos below were ARCHIVED 2025-11-25; this monorepo is the living source |
+| `~/Documents/OSS/WebAssembly/wasi-<iface>/`      | archived (2025-11-25) per-interface WASI repos (cli/clocks/filesystem/http/io/random/sockets) — historical WIT incl. `wit-0.3.0-draft/`; prefer `WASI/proposals/` for current WIT |
+| `~/Documents/OSS/WebAssembly/component-model/`   | Component Model spec (canonical ABI, async, WIT) — WASI 0.2/0.3 substrate |
+| `~/Documents/OSS/wasi-testsuite/`                | WASI testsuite (P1 + p3 guest tests)                                   |
+| `~/Documents/OSS/wasmtime-py/`                   | wasmtime Python embedding (host-API shape reference)                   |
 | `~/Documents/OSS/zig/`                           | Zig 0.16 stdlib source                                                 |
 
-## Version pin policy (Wasm 2.0 scope per ADR-0061)
+## Version pin policy (Wasm 3.0 scope; historical 2.0 policy = ADR-0061)
 
-Phase 9 keeps strictly to Wasm 2.0 (W3C Rec 2024-12). Upstream
-`WebAssembly/spec` and `WebAssembly/testsuite` track `main`,
-which has accumulated Wasm 3.0 amendments (typed-refs,
-extended-const, multi-memory, tail-call) in historically-2.0
-wast files (`local_tee.wast`, `func.wast`, etc.). Behaviour:
+The authoritative pin is [`.dev/spec_pin.yaml`](spec_pin.yaml) —
+`WebAssembly/spec` + `WebAssembly/testsuite` SHAs acknowledged as the
+vendoring baseline for the committed `test/spec/` conformance corpora.
+`scripts/check_spec_bump.sh` alerts when upstream advances beyond the
+pin; drift is assessed at the quarterly `proposal_watch.md` review
+(benign drift → pin bump, `test/core/` changes → re-vendor + re-distil).
 
-- The regen scripts (`scripts/regen_spec_2_0_assert.sh`,
-  `scripts/regen_spec_simd_assert.sh`) invoke `wast2json`
-  **without `--enable-*` flags for 3.0 proposals**. wast files
-  that have been amended with 3.0 syntax fail parsing and the
-  regen script logs `skip $n (wast2json rejected)`.
-- Existing `test/spec/wasm-2.0-assert/$n/` directories
-  generated by prior regens (under the pre-d-31 flag policy)
-  are **preserved on rejection** — they contain only 2.0
-  content (the prior flags accepted both 2.0 and 3.0 syntax,
-  and the python distillation filters to scalar shapes).
-- Recommended pin (not auto-enforced): check out the spec
-  repo at the `wg-2.0` tag for full reproducibility of
-  generated corpora. `cd ~/Documents/OSS/WebAssembly/spec &&
-  git checkout wg-2.0`. The current loop does not gate on
-  this; if a regen run produces drift, see ADR-0061
-  Alternative C (vendoring) for the escalation path.
-- Wasm 3.0 corpora (`memory64/`, `multi-memory/`, `gc/`,
-  `relaxed-simd/`, `exceptions/`, `function-references/`,
-  `tail-call/`, etc.) are **never added to NAMES** until
-  Phase 10+ lands the corresponding runtime.
+- The local `WebAssembly/spec` clone sits on the `wg-3.0` branch
+  (Wasm 3.0, W3C Rec 2025-09) — the scope zwasm v2 ships.
+- Wasm 3.0 corpora (`test/spec/wasm-3.0-assert/{memory64,multi-memory,
+  gc,function-references,tail-call,exception-handling}/`) are committed
+  and wired into `test-all`; the historical Phase-9 rule "never add 3.0
+  corpora until the runtime lands" (ADR-0061) is fulfilled and retired.
+- `git pull` on these clones is fine (they are reference material);
+  regen/re-distil of committed corpora happens only via the
+  `scripts/regen_spec_*.sh` flow against the pinned SHAs.

CHANGELOG.md

@@ -12,6 +12,55 @@ SemVer compatibility guarantees start at the first stable `v2.0.0` tag.
 
 _No changes yet._
 
+## [2.3.0] - 2026-07-17
+
+Inventory sweep against the officially released **WASI 0.3.0**
+(2026-06-11): the first slice of the official interface set, plus a
+docs truth-sweep and Homebrew packaging.
+
+### Added
+
+- **Official WASI 0.3.0 clocks surface** — `wasi:clocks/system-clock`
+  (0.3.0's renamed `wall-clock`; `instant{seconds: s64, nanoseconds:
+  u32}`, pre-1970 instants representable with the floored split) and
+  `get-resolution` on both clocks, served on the component host. The
+  async `wait-until` / `wait-for` need scheduler-wired timer waitables
+  and are tracked as debt (D-524).
+- **Homebrew**: `brew install clojurewasm/tap/zwasm` (macOS arm64,
+  Linux x86_64 / aarch64), packaging the release binaries.
+
+### Changed
+
+- **wasip3 fixture toolchain repinned** nightly-2026-06-14 →
+  nightly-2026-06-24 (the newest nightly that can still `-Z build-std`
+  wasm32-wasip3 — 2026-07-08/-16 hit an upstream std regression) and
+  the conformance fixtures regenerated. Measured: the emitted imports
+  are unchanged (wasi 0.2.6) because they come from the borrowed
+  wasip2 wasi-libc, not the nightly's std bindings — the official-WIT
+  fixture gap remains open as D-523.
+
+### Fixed
+
+- **`zwasm --help` engine wording**: the usage text claimed
+  `interp (default)`; the real default (since 2.0.0) is `auto` — prefers
+  the JIT with transparent interpreter fallback. The help now matches
+  `docs/reference/cli.md` and the README, and also lists the `--cache` /
+  `--cache-clear` flags shipped in 2.2.0.
+
+### Documentation
+
+- **WASI 0.3 documented**: README gains a WASI 0.3 row (Component-Model
+  native-async core, opt-in `-Dwasi=p3`; official WASI 0.3.0 released
+  2026-06-11 — `wasi:filesystem`/`wasi:sockets` data-plane and `wasi:http`
+  pending), and the migration guide's "until it settles" framing is
+  replaced accordingly.
+- **GC build default corrected in the migration guide**: WasmGC is
+  compiled in and executes by default (part of `-Dwasm=v3_0`); the guide
+  previously described it as opt-in via `-Dgc`, which is inert (tracked
+  as debt).
+- **README gains an Install section** (Homebrew + prebuilt release
+  binaries).
+
 ## [2.2.1] - 2026-07-16
 
 Binary-size campaign (ADR-0204, PRs #144-#146), triggered by downstream
@@ -139,7 +188,7 @@ Windows x86_64). Earlier pre-releases were tagged `v2.0.0-alpha.*`.
 
 - **WebAssembly 3.0** — all 9 proposals: GC, exception handling, tail
   calls, memory64, multi-memory, typed function references,
-  extended-const, relaxed-SIMD. Plus full Wasm 1.0 + 2.0 (multi-value,
+  extended-const, relaxed-SIMD, custom annotations. Plus full Wasm 1.0 + 2.0 (multi-value,
   SIMD-128, bulk-memory, reference-types, non-trapping FP→int conversion,
   sign-extension, mutable globals). Spec testsuite green, `skip-impl == 0`.
 - **Execution backends** — interpreter (full WASI), JIT for ARM64