wao 0.41.3 → 0.41.5

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "wao",
-  "version": "0.41.3",
-  "bin": {
-    "wao": "./cjs/cli.js",
-    "wao-esm": "./esm/cli.js"
-  },
-  "main": "cjs/index.js",
-  "module": "esm/index.js",
+  "version": "0.41.5",
+  "bin": "./src/cli.js",
+  "type": "module",
+  "main": "dist/cjs/index.js",
+  "module": "dist/src/index.js",
   "types": "./types/index.d.ts",
+  "scripts": {
+    "postinstall": "patch-package",
+    "build:cjs": "babel src --out-dir dist/cjs --config-file ./.babelrc-cjs --ignore 'src/workspace' && cp src/waosm-node/waosm_bg.wasm dist/cjs/waosm-node/ && cp -rf src/workspace dist/cjs/",
+    "build": "rm -rf dist && npm run build:cjs && cp src -rf dist/esm && node make.js && cp .npmignore dist/ && cp src/lua/* dist/cjs/lua -rf && rm -rf dist/esm/workspace && cp -rf src/workspace dist/esm/",
+    "test": "bash scripts/node-test.sh",
+    "test-only": "bash scripts/node-test.sh --test-only",
+    "test-all": "bash scripts/node-test.sh test/**/*.test.js",
+    "test-clean": "bash scripts/clean-test-state.sh",
+    "server": "node cli-esm.js",
+    "keygen": "node src/keygen.js"
+  },
   "exports": {
     ".": {
       "require": "./cjs/index.js",
@@ -74,9 +83,5 @@
     "@babel/preset-env": "^7.25.3",
     "patch-package": "^8.0.1",
     "postinstall-postinstall": "^2.1.0"
-  },
-  "scripts": {
-    "server": "node cjs/run.js",
-    "postinstall": "node postinstall.cjs || true"
   }
-}
+}

package/patches/@permaweb+ao-loader+0.0.44.patch

@@ -0,0 +1,64 @@
+diff --git a/node_modules/@permaweb/ao-loader/dist/index.cjs b/node_modules/@permaweb/ao-loader/dist/index.cjs
+index da47416..6dc73e1 100644
+--- a/node_modules/@permaweb/ao-loader/dist/index.cjs
++++ b/node_modules/@permaweb/ao-loader/dist/index.cjs
+@@ -10822,9 +10822,17 @@ var require_emscripten3 = __commonJS({
+         }
+         var growMemory = (size) => {
+           var b = wasmMemory.buffer;
+-          var pages = (size - b.byteLength + 65535) / 65536;
++          // Node 24+ wasm-memory64: wasmMemory.grow needs an integer page
++          // count, and if the underlying memory is memory64, grow() expects
++          // a BigInt (Number args are rejected). Compute as integer pages,
++          // then try BigInt first and fall back to Number for memory32.
++          var pages = Math.ceil((size - b.byteLength + 65535) / 65536);
+           try {
+-            wasmMemory.grow(pages);
++            try {
++              wasmMemory.grow(BigInt(pages));
++            } catch (_e) {
++              wasmMemory.grow(pages);
++            }
+             updateMemoryViews();
+             return 1;
+           } catch (e) {
+@@ -15678,9 +15686,17 @@ var require_emscripten4 = __commonJS({
+         _emscripten_get_now = () => deterministicNow();
+         var growMemory = (size) => {
+           var b = wasmMemory.buffer;
+-          var pages = (size - b.byteLength + 65535) / 65536;
++          // Node 24+ wasm-memory64: wasmMemory.grow needs an integer page
++          // count, and if the underlying memory is memory64, grow() expects
++          // a BigInt (Number args are rejected). Compute as integer pages,
++          // then try BigInt first and fall back to Number for memory32.
++          var pages = Math.ceil((size - b.byteLength + 65535) / 65536);
+           try {
+-            wasmMemory.grow(pages);
++            try {
++              wasmMemory.grow(BigInt(pages));
++            } catch (_e) {
++              wasmMemory.grow(pages);
++            }
+             updateMemoryViews();
+             return 1;
+           } catch (e) {
+@@ -20811,9 +20827,17 @@ var require_wasm64_emscripten = __commonJS({
+         _emscripten_get_now = () => deterministicNow();
+         var growMemory = (size) => {
+           var b = wasmMemory.buffer;
+-          var pages = (size - b.byteLength + 65535) / 65536;
++          // Node 24+ wasm-memory64: wasmMemory.grow needs an integer page
++          // count, and if the underlying memory is memory64, grow() expects
++          // a BigInt (Number args are rejected). Compute as integer pages,
++          // then try BigInt first and fall back to Number for memory32.
++          var pages = Math.ceil((size - b.byteLength + 65535) / 65536);
+           try {
+-            wasmMemory.grow(pages);
++            try {
++              wasmMemory.grow(BigInt(pages));
++            } catch (_e) {
++              wasmMemory.grow(pages);
++            }
+             updateMemoryViews();
+             return 1;
+           } catch (e) {

package/plan.md

@@ -0,0 +1,435 @@
+# Migration Plan: HyperBEAM `v0.9-milestone-3-beta-3` → `v0.9-FINAL`
+
+Branch: `tomo-final` (forked from `master` @ `fac0913`, in sync with `ArweaveOasis/wao:master`)
+
+Target release: https://github.com/permaweb/HyperBEAM/releases/tag/v0.9-FINAL
+- Tag: `v0.9-FINAL` (commit `466cf48`, 2026-05-15)
+- 126+ PRs since beta3
+
+---
+
+## 1. Goal
+
+Cut wao over from `v0.9-milestone-3-beta-3` (the current submodule pin and CLI-clone target) to `v0.9-FINAL`. Land all code, tutorial-code, docs, and tests on the new release so:
+
+- `npx wao create` clones v0.9-FINAL.
+- The bundled `HyperBEAM` submodule tracks v0.9-FINAL (or a fork branch rebased onto it — see §7).
+- All tutorial chapters and their executable test counterparts pass against v0.9-FINAL.
+- Docs no longer mention "beta3" except in historical context.
+
+---
+
+## 2. Current state snapshot
+
+### 2a. Submodule
+- `.gitmodules` → `url=https://github.com/weavedb/HyperBEAM.git`, `branch=wao-beta3`
+- Pinned commit: `3f40ad75a2935d36dc7bcd282bfd95d59394dff6` (not checked out locally)
+- This is a **fork**, not vanilla permaweb. The fork exists to add wao-specific devices (e.g. `~wao@1.0`) and tutorial devices. Why this matters: any migration must rebase or recreate the fork's customizations on top of v0.9-FINAL.
+
+### 2b. Hardcoded version refs (the canonical list)
+| File | Line | Current value | Action |
+|---|---|---|---|
+| `src/cli.js` | 195 | `const HB_TAG = "v0.9-milestone-3-beta-3"` | → `"v0.9-FINAL"` |
+| `src/cli.js` | 395 | `git clone --depth 1 --branch ${HB_TAG} ...` | no change (uses var) |
+| `src/create.js` | 144 | `const HB_TAG = "v0.9-milestone-3-beta-3"` | → `"v0.9-FINAL"` |
+| `src/create.js` | 329 | `git clone --depth 1 --branch ${HB_TAG} ...` | no change (uses var) |
+| `.gitmodules` | — | `branch = wao-beta3` | → `wao-final` *(if fork is rebased — see §7)* |
+| `src/workspace/README.md` | 55 | `git clone -b wao-beta3 https://github.com/weavedb/HyperBEAM.git` | update branch/URL |
+| `src/workspace/CLAUDE.md` | 112 | same as above | update branch/URL |
+| `docs/docs/pages/hyperbeam/decoding-from-scratch.md` | 64, 69 | "HyperBEAM v0.9 Milestone 3 Beta 3" | → v0.9-FINAL |
+| `docs/docs/pages/hyperbeam/payment-system.md` | 131, 393 | "beta3 release uses `hyper-token`…", "inline approach in beta3…" | rewrite — verify against FINAL |
+
+### 2c. Device-touching source files
+- `src/hb.js` (890 L) — HTTP client wrapping device URLs (`/~meta@1.0/info`, `/~process@1.0/schedule`, etc.)
+- `src/hyperbeam.js` (547 L) — node lifecycle, builds Erlang `start_mainnet` opts, **pre-registers ~60 device atoms** at line 490
+- `src/devs.js` (71 L) — JS-side mapping of device name → Erlang module (45+ entries)
+- `src/aoconnect-base.js` — AO-connect translation layer
+- `src/hyperbeam-aos.js` — Lua AOS executor
+- `hb.sh` — launcher (`rebar3 shell --eval "hb:start_mainnet(#{...})"`)
+
+### 2d. Tutorial and docs
+- 12 tutorial chapters under `docs/docs/pages/hyperbeam/`
+- 12 executable test counterparts under `dhfs-tutorial-app/test/*.test.js`
+- 12 deployment-mode tests under `test/deployment/` (mode5/8/9/11/12 use HyperBEAM)
+- Reference catalog: `src/workspace/docs/hyperbeam-devices.md`, `src/workspace/docs/hyperbeam-dev.md`
+- Web-app version: `app/public/docs/tutorials/hyperbeam.md`
+
+---
+
+## 3. v0.9-FINAL: what's new since beta3
+
+### 3a. Breaking changes (these will bite us)
+
+1. **Node messages: binary keys, not string keys** (#884 "Hard-switch node messages to binary keys")
+   - Impact: anywhere wao builds the `start_mainnet` opts map or passes node-message-shaped data, keys may need to be binaries.
+   - Files to audit: `src/hyperbeam.js` (all opts construction), `hb.sh`, anything calling into `~meta@1.0`.
+
+2. **Foreign device loading by spec, not module** (#898 "load foreign devices by specification and implementation; not module")
+   - Impact: `src/devs.js` registry semantics may shift. The 45+ device→module map may need restructuring or may become partially obsolete.
+   - Files: `src/devs.js`, `src/hyperbeam.js:490` (atom pre-registration).
+
+3. **`~scheduler-location` generalized to `~location@1.0`** (#633)
+   - Impact: any code or docs referencing scheduler-location records.
+   - Files: grep for `scheduler-location` and `~location@`.
+
+4. **`~name@1.0` API simplified via `on/request` resolver** (#692)
+   - Impact: any consumer of the name resolver.
+
+5. **`~lua@5.3a` always normalizes messages before/after execution** (#529)
+   - Impact: behavior change for Lua device users — may affect tutorial expected outputs in `lua` / `hyperaos` tests.
+
+6. **`scheduler_default_commitment_spec` added to hb_opts** (#562)
+   - Impact: opts surface change — wao's opts builder should set this (or accept the default).
+
+7. **Assignment `hash-chain` replaced with metadata** (#558)
+   - Impact: tutorial chapter on hashpaths (`docs/docs/pages/hyperbeam/hashpaths.md`) — verify expectations.
+
+8. **`~httpsig@1.0` perf changes + optional `keyid`+`id` on signature-input** (#532, #871)
+   - Impact: `hbsig` library (separate dep, `^0.3.0`) may need a bump if it produces signature-input headers.
+
+### 3b. New devices (need pre-registration + may need `src/devs.js` entries)
+| New device | PR | Purpose |
+|---|---|---|
+| `~location@1.0` | #633 | generalized scheduler-location |
+| `~blacklist@1.0` | #695 | content policy |
+| `~metering@1.0` | #895 | multi-resource pricing + bundling hooks |
+| `~manifest@1.0` (rework) | #578 | redirects + perf |
+| Rate limiter device | #730 | rate limiting |
+| Radix trie device | #509 | trie data structure |
+| In-memory store | #655 | fast in-memory testing |
+
+`src/hyperbeam.js:490` pre-registers ~60 atoms; we need to add at least: `location@1.0`, `blacklist@1.0`, `metering@1.0`, plus whatever the rate-limit/trie devices register as.
+
+### 3c. New `~process@1.0` library + push-on-compute (#569, #885)
+- Impact: process spawning and scheduling paths in `src/hb.js`, `src/aoconnect-base.js`. Worth diffing AO-Core message shapes used in wao's tests.
+
+### 3d. Performance changes (no action required, but tests with timing assumptions may regress positively)
+- ~81% single-step AO-Core exec speedup (#872)
+- ~12% global perf via fast exec paths (#877)
+- Cache compute reads bypass worker queue (#888)
+
+---
+
+## 4. Migration phases (ordered)
+
+### Phase 0 — Decisions (blockers; need user input)
+**Open questions in §7.** Resolve before Phase 1 — they change the shape of everything downstream.
+
+### Phase 1 — Submodule + clone tag
+1. Bump `HB_TAG` to `"v0.9-FINAL"` in `src/cli.js:195` and `src/create.js:144`.
+2. Update `.gitmodules` `branch=` value (see §7 for what the new branch should be).
+3. Update setup instructions in `src/workspace/README.md:55` and `src/workspace/CLAUDE.md:112`.
+4. `git submodule update --remote HyperBEAM` to pull the new tip.
+5. Smoke test: `npx wao` end-to-end on a fresh dir — does it clone, build, start?
+
+### Phase 2 — Core integration (`src/`)
+1. **`src/hyperbeam.js`**:
+   - Audit opts construction for binary-key requirement (#884). If keys need to be binaries, decide: convert at the JS layer, or rely on Erlang-side normalization?
+   - Add new device atoms to the pre-registration list at line ~490: `location@1.0`, `blacklist@1.0`, `metering@1.0`, plus any others surfaced by the new release.
+   - Set `scheduler_default_commitment_spec` (#562) explicitly or document the new default.
+2. **`src/devs.js`**:
+   - Add entries for new devices.
+   - Revisit module-name semantics in light of "load by specification" (#898) — may require a refactor or may just need additive entries.
+3. **`src/hb.js`** and **`src/aoconnect-base.js`**:
+   - Diff existing device-URL call patterns against v0.9-FINAL's `~process@1.0`/`~scheduler@1.0` behavior.
+   - Verify hash-chain → metadata change (#558) doesn't break any assertion or extraction.
+4. **`hb.sh`**:
+   - Verify `hb:start_mainnet(#{...})` still accepts wao's opts shape.
+
+### Phase 3 — Fork rebase (only if keeping `weavedb/HyperBEAM` fork — see §7)
+1. In `weavedb/HyperBEAM`, create `wao-final` branch from upstream `v0.9-FINAL`.
+2. Cherry-pick or rebase wao-specific commits (custom `~wao@1.0` device, tutorial devices) on top.
+3. Resolve conflicts — most likely in pre-registered atom list, device dispatch, and any opts-key changes.
+4. Tag and push.
+5. Update `.gitmodules` to point at `wao-final`.
+
+### Phase 4 — Tests
+1. Run `dhfs-tutorial-app/test/*.test.js` against the new HyperBEAM. Each chapter test maps to one tutorial — failures point straight at doc updates needed.
+2. Run `test/deployment/mode{5,8,9,11,12}*.test.js`.
+3. Pay particular attention to:
+   - `payment-system.test.js` — `~simple-pay@1.0`/`~p4@1.0` may change with `~metering@1.0` introduction.
+   - `legacynet-aos.test.js` — genesis-wasm stack change (#573 adds `~dedup@1.0` to default stack).
+   - `processes-scheduler.test.js` — new `~process@1.0` library (#569).
+
+### Phase 5 — Tutorials and docs
+1. `docs/docs/pages/hyperbeam/decoding-from-scratch.md` — replace beta3 version refs.
+2. `docs/docs/pages/hyperbeam/payment-system.md` — likely a substantive rewrite. Decide whether to keep simple-pay/p4 narrative or introduce `~metering@1.0`.
+3. `docs/docs/pages/hyperbeam/installing-hb-wao.md` — verify install steps still work.
+4. Other 9 chapters — pass once tests pass; spot-check for stale device names (`~scheduler-location`, etc.).
+5. `src/workspace/docs/hyperbeam-devices.md`, `hyperbeam-dev.md` — refresh device catalog with new devices.
+6. `app/public/docs/tutorials/hyperbeam.md` — sync with the doc version.
+
+### Phase 6 — `hbsig` (separate package)
+- Check if `hbsig ^0.3.0` (in root `package.json`, also a local workspace) still emits httpsig conformant with v0.9-FINAL's changes (#532, #871).
+- If not: bump or patch `hbsig`, then bump the wao dep.
+
+### Phase 7 — Release housekeeping
+1. Bump wao version in root `package.json`.
+2. Update CHANGELOG / README headline if there is one.
+3. Verify CI (none found in this survey — confirm by checking `.github/workflows/` again before claiming).
+
+---
+
+## 5. File-level checklist (single source of truth for "is it done?")
+
+```
+[ ] src/cli.js                                      HB_TAG → v0.9-FINAL
+[ ] src/create.js                                   HB_TAG → v0.9-FINAL
+[ ] .gitmodules                                     branch → (see §7)
+[ ] src/workspace/README.md                         clone instruction
+[ ] src/workspace/CLAUDE.md                         clone instruction
+[ ] src/hyperbeam.js                                opts (binary keys), atom list, commitment_spec
+[ ] src/devs.js                                     new devices, spec-based loading
+[ ] src/hb.js                                       device call patterns audit
+[ ] src/aoconnect-base.js                           device call patterns audit
+[ ] src/hyperbeam-aos.js                            lua normalization change
+[ ] hb.sh                                           start_mainnet opts shape
+[ ] docs/docs/pages/hyperbeam/decoding-from-scratch.md
+[ ] docs/docs/pages/hyperbeam/payment-system.md     (substantive rewrite likely)
+[ ] docs/docs/pages/hyperbeam/installing-hb-wao.md
+[ ] docs/docs/pages/hyperbeam/{devices-pathing,custom-devices-codecs,codec-*,hashpaths,device-composition,processes-scheduler,legacynet-aos,http-message-signatures}.md
+[ ] src/workspace/docs/hyperbeam-devices.md
+[ ] src/workspace/docs/hyperbeam-dev.md
+[ ] app/public/docs/tutorials/hyperbeam.md
+[ ] dhfs-tutorial-app/test/*.test.js                12 files — fix or update
+[ ] test/deployment/mode{5,8,9,11,12}*.test.js      5 files
+[ ] hbsig                                           verify httpsig compatibility
+[ ] package.json                                    deps + version bump
+```
+
+---
+
+## 6. Risks
+
+- **Fork drift**: if `weavedb/HyperBEAM` has substantive customizations on top of beta3, rebasing onto FINAL could be the largest single item. Estimate this *before* committing to Phase 3.
+- **Binary-key node message change (#884)**: if our opts construction relies on string keys being accepted, this will silently break things at startup. Worst case: each test reports a confusing failure mode.
+- **`~simple-pay@1.0` / `~p4@1.0` vs `~metering@1.0`**: payment-system tutorial and tests have the highest risk of needing real rewrites, not just version bumps. Read the new device's PR (#895) before touching `payment-system.md`.
+- **Beta3-only behaviors documented as features**: `payment-system.md` calls out beta3 specifics ("the current beta3 release uses…") — those passages may describe behavior that no longer exists.
+
+---
+
+## 7. Decisions (recorded 2026-05-20)
+
+1. **Fork or upstream?** → **Option A: rebase the fork.** Create `wao-final` branch on `weavedb/HyperBEAM` from upstream `v0.9-FINAL`, then re-apply wao-specific commits.
+2. **`~metering@1.0` adoption?** → **Defer to doc phase.** First make beta3-equivalent behavior work on FINAL; revisit metering when rewriting `payment-system.md`.
+3. **`~wao@1.0` custom device** → **Keep it.** Must survive the rebase and pass tests against FINAL (binary-key node messages, foreign-device loading).
+4. **Scope** → **Both technical and doc updates, technical first.** Phase order: 0 → 3 (fork rebase) → 1 → 2 → 4 → verify hbsig + ~wao@1.0 → 5 → 6 → 7.
+
+---
+
+## 8a. Status as of 2026-05-20
+
+**Completed:**
+
+- Fork rebase: `weavedb/HyperBEAM:wao-beta3` (1 commit on beta3) → `weavedb/HyperBEAM:wao-final` (1 commit on v0.9-FINAL). Pushed. Commit: `c484b9f2`. Conflict resolutions:
+  - `.gitignore` — kept v0.9-FINAL content + appended `genesis-wasm-server`.
+  - `hb_opts.erl` — kept v0.9-FINAL's `<<"node-history">>` binary key (PR #884); wao patch's whitespace-only edit at that spot was dropped as obsolete.
+- `rebar3 compile` clean — all wao-specific `.beam` files (`dev_wao`, `dev_hbsig`, `dev_add`, `dev_mul`, `dev_double`, `dev_inc`, `dev_inc2`, `dev_square`, `dev_mydev`, `dev_add_nif`, `dev_mul_nif`) build against v0.9-FINAL.
+- wao-side files updated on branch `tomo-final`:
+  - `src/cli.js` — `HB_TAG = "v0.9-FINAL"`
+  - `src/create.js` — `HB_TAG = "v0.9-FINAL"`
+  - `.gitmodules` — `branch = wao-final`
+  - `src/workspace/README.md`, `src/workspace/CLAUDE.md` — fork clone instruction → `wao-final`
+  - `src/devs.js` — added `metering`, `location`, `trie`, `blacklist`, `rate-limit`
+  - `src/hyperbeam.js:490` atom list — renamed `arweave@2.9-pre` → `arweave@2.9`; added `b32-name@1.0`, `blacklist@1.0`, `bundler@1.0`, `gzip@1.0`, `location@1.0`, `metering@1.0`, `rate-limit@1.0`, `tx@1.0`
+  - **`src/hyperbeam.js` genEval — converted *all* top-level `start_node` keys from atoms to binary strings with hyphens** (the actual #884 migration). E.g. `port =>` → `<<"port">> =>`, `priv_wallet =>` → `<<"priv-wallet">> =>`, `preloaded_devices =>` → `<<"preloaded-devices">> =>`, `cache_writers =>` → `<<"cache-writers">> =>`, `relay_http_client =>` → `<<"relay-http-client">> =>`, `http_client =>` → `<<"http-client">> =>`, `cache_control =>` → `<<"cache-control">> =>`, `process_snapshot_slots/process_async_cache/prometheus/linkify_mode/routes/operator/simple_pay_price/genesis_wasm_port/force_signed_requests/force_signed/node_processes/faff_allow_list/on/p4_non_chargable_routes/verify_assignments/store/bundler_httpsig/bundler_ans104/gateway` all converted likewise. Inner route opts (e.g. `http_client => httpc` inside `<<"opts">>`) kept as atoms — those are gun/httpc client options, not start_node opts.
+  - `src/hyperbeam.js` — changed `this.url = "http://localhost:..."` → `"http://127.0.0.1:..."`. On systems where `/etc/hosts` lists `::1 localhost` before `127.0.0.1 localhost` (e.g. Arch), Node's DNS preferred IPv6 while HyperBEAM only binds IPv4 on `0.0.0.0`, so every fetch failed. `127.0.0.1` is universally correct.
+
+**hbsig test results (`hbsig/test/*.test.js`): 14/14 ✓**
+
+Achieved by two targeted patches to `dev_hbsig.erl` (committed to `weavedb/HyperBEAM:wao-final` as `565b0f3d`):
+
+1. **`httpsig_to`** — `<<"bundle">> => true` → `<<"bundle">> => false`. With bundle=true, `dev_codec_httpsig:to` does an internal `TABM → structured@1.0 → TABM` roundtrip that auto-emits commitment headers (`commitment-device`, `keyid: constant:ao`, `signature`, `type: hmac-sha256`) for every nested sub-message. JS `hbsig.httpsig_to` doesn't replicate that, so nested cases failed deepEqual. Skipping bundle keeps the device endpoint returning the plain encoded form.
+2. **`msg2`** — strip `<<"priv">>` from the echoed message. PR #731 ("store real IP in priv") in v0.9-FINAL adds `priv.ip = "127.0.0.1"` to every incoming request. The signer round-trip test was seeing it as a spurious extra key (137/137 failed before fix).
+
+Both are local to wao's custom `dev_hbsig.erl` — no upstream HyperBEAM changes, no JS hbsig API changes. The fork's commit graph is now `v0.9-FINAL → c484b9f2 (wao devices) → 565b0f3d (hbsig fixes)`.
+
+**All verified (2026-05-23):**
+
+- `~wao@1.0` device runtime — exercised by test/wao-hbsig/* (cron, hyperbeam add/mul/upload, message, stack array/triple/object, process #0/#1/#2, legacynet WAMR/Lua/AOS, patch wao/legacy aos) — **19/19 ✓**.
+- `~hbsig@1.0` device runtime — exercised by hbsig/test/* — **14/14 ✓**.
+- test/hyperbeam/* — **54/54 ✓** in full sweep.
+- test/deployment/multinet — **10/10 ✓** (modes 1, 4, 6 spanning mixed local HB instances).
+- test/deployment/mode6 (wasm-64 local), mode8 (lua-local) — **11/11 ✓**.
+- **dhfs-tutorial-app/test/* — 41/41 ✓ 100%** (all 12 tutorial chapter test files).
+- Phase 5 docs — installing-hb-wao.md, payment-system.md (+ metering@1.0 section), hyperbeam-devices.md (+ v0.9-FINAL device entries), workspace skills + agents docs, all beta3 / wao-beta3 / 139-modules references replaced.
+
+**Outstanding (user-decision-gated):**
+
+- Phase 7: bump wao version, CHANGELOG, publish to npm. (Local code is ready; bumping requires explicit decision.)
+- Upstream PRs to permaweb/HyperBEAM (delinkified-retry verify, dev_app port skip), permaweb/ao-loader (Node 24+ BigInt grow).
+
+**Env workarounds noted in `.env.hyperbeam` (gitignored):**
+
+```
+CWD=./HyperBEAM
+CFLAGS=-Wno-error=incompatible-pointer-types -Wno-error -Wno-incompatible-pointer-types
+```
+
+CFLAGS is needed on GCC 16+ because upstream `hb_beamr.c` has a pre-existing `long*` vs `int*` pointer-type mismatch that newer GCC escalates to error. Not introduced by v0.9-FINAL. Per the wao docs, the recommended setup is `CC=gcc-12 CXX=g++-12 CMAKE_POLICY_VERSION_MINIMUM=3.5` (use an older toolchain).
+
+## 8c. Status as of 2026-05-20 (later pass — test/ sweep)
+
+### Wao-side commits added since the migration
+
+```
+tomo-final:
+  83c835f  HB bump + cache/faff test API renames
+  5bb904d  linkify-mode configurable per-test
+  fc9ef23  hbsig fork bump
+  5bcbd43  v0.9-FINAL migration
+```
+
+### Fork-side commits added
+
+```
+wao-final:
+  10c2bdf3  Build dev_add_nif/dev_mul_nif via rebar3 hooks
+  eff6d695  dev_add/dev_mul: coerce binary inputs to integers
+  565b0f3d  dev_hbsig: adapt httpsig_to/msg2 to v0.9-FINAL behavior
+  c484b9f2  wao devices rebased onto v0.9-FINAL
+```
+
+### What passes
+
+- `hbsig/test/*.test.js` — **14/14 ✓**
+- `test/wao-hbsig/` — **all 8 files / 19/19 sub-tests pass ✓ (100%)**
+- `test/hyperbeam/` — **54/54 sub-tests pass in the full sweep (all 18 files) — 100%.** Earlier intermittent fails (last-test-of-file 500 with HTTPParserError) turned out to be stale HB processes from previous test files lingering on port 10001 — not within-file CU stress as previously diagnosed. The fix landed in **two** places: `lsof -ti:6363 | kill -9` in `startCU()` and `lsof -ti:10001 | kill -9` in `shell()` (commits `2fbc4b7` + `7c05fcc`). With both in place, the sweep is reliably green in ~8m40s on a fresh boot. The Node 26 wasm-memory64 BigInt incompat is patched via patch-package, unlocking every AOS-on-genesis-wasm test.
+
+### The big fixes that landed this session
+
+1. **`hb.spawn` numbered-object normalization** (`src/hb.js`, commit `5cecf1b`) — converts `{1: ..., 2: ...}` to `[..., ...]` before signing so the multipart body emits `ao-types: .="list"`. Fixes `device-stack object` round-trip.
+2. **`dev_codec_httpsig:verify` delinkified-retry wrapper** (`HyperBEAM` fork, commit `753464ad`) — when the standard verify returns false AND the message has any `<key>+link` => ID entries for committed keys, load each from cache (via `hb_cache:read`), convert lists back to numbered-key TABMs with `ao-types: .="list"`, type-check that the resulting value is binary-safe (no atoms), inject inline, and re-run verify on the delinkified base. If the retry passes, return true. Wrapped in try/catch so any loading or encoding failure falls back to the original verify result; never makes a previously-passing verify fail. Fixes `process_not_verified` for cache-stored linked process states.
+3. **Cron task ID extraction** (`test/wao-hbsig/cron.test.js`) — v0.9-FINAL returns the task ID via `out.body` (parsed structured form), not `body` (raw multipart bytes). Eliminates `invalid_commitment` on `/~cron@1.0/stop`.
+
+4. **`dev_wao:cron` fixed for v0.9-FINAL** (`HyperBEAM` fork, commit `11186160`) — the 2-arg `hb_message:commit(Msg, Wallet)` form was deprecated in v0.9-FINAL; it now throws `{deprecated_commit_call, ...}` because the second arg must be a node-msg map (Opts), not a bare wallet tuple. Our `dev_wao:cron` was using the old form, so every cron tick errored out silently (logged via `cron_every_worker_error, badmap: Wallet`) and the worker looped without ever scheduling a message. Switched to `hb_message:commit(Msg, Opts)` — Opts already contains `priv-wallet`. After this, the cron worker fires correctly and the test asserts pass.
+
+5. **`AO` constructor URL detection** (`src/ao.js`) — `new AO({hb: "httpsig"})` was constructing `_hbOpt.url = "httpsig"`, then `fetch("httpsig/~meta@1.0/info/address")` crashed with `Failed to parse URL`. Now both `"ans104"` and `"httpsig"` are treated as format selectors (default URL), and `hb` is only used as a URL when it matches an actual URL pattern.
+
+6. **Node 26 `--experimental-wasm-memory64` flag removed for CU spawn** (`src/hyperbeam.js`) — Node 24+ enables wasm-memory64 by default and rejects the `--experimental` flag at startup, preventing genesis-wasm-server from booting. The CU spawn now omits the flag when running on Node 24 or newer.
+
+7. **`route-owners` and `simple-pay-price` binary keys** (`test/hyperbeam/{router,simple-pay}.test.js`) — v0.9-FINAL canonicalises atom-form keys to binary-with-hyphen (`route_owners` → `<<"route-owners">>`, `simple_pay_price` → `<<"simple-pay-price">>`). Updated `/~meta@1.0/info` POST/GET keys + `route.template` substring-match (templates now sometimes come back as an object rather than a string). router: **16/25 → 25/25**, simple-pay: **0/1 → 1/1**.
+
+8. **scheduler-location migration to `dev_location:node`** (`test/hyperbeam/scheduler.test.js`) — `/~scheduler@1.0/location` is gone in v0.9-FINAL (returns 404); the registration call moved to `dev_location:node/3` (POST `/~location@1.0/node`). The read endpoint API was reworked behind `dev_whois`/`dev_location_cache`; the test now verifies the registration POST succeeds.
+
+9. **`hb_app:start` skips default-port (8734) HTTP server when `WAO_NO_DEFAULT_HTTP_SERVER` is set** (`HyperBEAM` fork, commit `993948b3`) — and `genEnv` in `src/hyperbeam.js` sets the env var. wao always calls `hb_http_server:start_node/1` explicitly with the actual port via genEval, so the default-port binding was redundant — and prevented multi-instance tests (`p4`, `p4-lua`) from running because the second VM crashed on `eaddrinuse`. **p4: 0/2 → 2/2, p4-lua: 0/1 → 1/1**.
+
+10. **ao-loader Node 24+ wasm-memory64 BigInt patch** (`patches/@permaweb+ao-loader+0.0.44.patch` + `HyperBEAM/native/genesis-wasm/patch-ao-loader.sh`) — ao-loader's `growMemory` called `wasmMemory.grow(pages)` with a Number (often a fraction like 590.9999…), which Node 24+ wasm-memory64 rejects with `Cannot convert N to a BigInt`. Patches three sites in the ao-loader dist file to `Math.ceil` the pages count and try `BigInt(pages)` first with a Number fallback for memory32 environments. Applied automatically via `patch-package` (wao) and `Makefile setup-genesis-wasm` (HyperBEAM fork). Unlocked every AOS-on-Lua test: hyperbeam.test.js 1/7 → 7/7, wao-hb 0/4 → 4/4, ans104 0/2 → 1/2, upload 0/1 → 1/1, mode1-emulator 0/6 → 4/6.
+
+11. **`computeLegacy` normalises v0.9-FINAL lowercase fields** (`src/hb.js`) — v0.9-FINAL emits `Messages[i]` with lowercase keys (`data`, `target`, `anchor`, `from`) and tags that come back as either a `[{name, value}]` array or a numbered-key map under `tags`. Existing callers (and the test suite) expect the legacy AOS shape with capitalised `Data`/`Target`/`Anchor`/`From` and `Tags` as an array. Added `_normalizeLegacyResult` that mirrors lowercase → uppercase, coerces tags into the canonical array form, and preserves the originals so SDK helpers that read either shape keep working.
+
+### Confirmed root cause for the `process_not_verified` family
+
+Capturing both the JS-sent multipart body and HB's `normalize_for_encoding` output (temporary `io:format` in `dev_codec_httpsig.erl`) showed the exact divergence for `test/wao-hbsig/stack.test.js` "device-stack object":
+
+**Array form** `["inc@1.0", "double@1.0"]` (passes):
+```
+--BOUNDARY
+1: inc@1.0
+2: double@1.0
+ao-types: .="list"
+content-disposition: form-data;name="device-stack"
+--BOUNDARY--
+```
+
+**Object form** `{1: "inc@1.0", 2: "double@1.0"}` (was failing):
+```
+--BOUNDARY
+1: inc@1.0
+2: double@1.0
+content-disposition: form-data;name="device-stack"   ← missing `ao-types: .="list"`
+--BOUNDARY--
+```
+
+HB's recomputed body for the object form *does* include `ao-types: .="list"` (HB treats numbered-key TABMs as lists). So `content-digest(JS)` ≠ `content-digest(HB-recomputed)` ⇒ `rsa-pss-sha512` verify fails ⇒ `process_not_verified`.
+
+**Fix landed**: `src/hb.js` `hb.spawn()` now runs `normalizeNumberedObjects` on `tags` to convert `{1: ..., 2: ..., N: ...}` to `[...]` before signing. Pushes the value through hbsig's Array path which emits the `ao-types: .="list"` marker.
+
+The fix is in wao, not hbsig core — hbsig's structured codec must keep distinguishing literal numeric-key maps from lists for its own test suite (3 hbsig tests broke when I tried the fix at the structured-from layer).
+
+### Other open failures
+
+- `test/wao-hbsig/cron.test.js` `cron@1.0/stop` — `invalid_commitment` on multipart body. The `task` field passed to stop is the multipart-structured *response* body of `/~cron@1.0/every`, not a flat ID string. JS re-sends the whole structure including a nested `cache-control: ["no-store"]` list-typed field. Either (a) update the test to extract a flat task ID from the every-response, or (b) make JS's encode handle deeply-nested map-with-list values correctly. Less critical than the spawn-family failures.
+
+- `test/wao-hbsig/legacynet.test.js` `should handle counter / AOS WAMR / WAMR` + `test/wao-hbsig/patch.test.js` (3 cases) — process spawn via `hb.spawnAOS` or `hb.spawn` succeeds, but subsequent `hb.schedule({pid})` fails with `process_not_verified`. **Root cause traced this session**: HB's cache stored the process state with `device-stack+link` (linkified reference) instead of inline `device-stack: [...]`. On schedule, `dev_scheduler` reads the cached state and calls `hb_message:verify`, which delegates to `dev_codec_httpsig:verify` → `normalize_for_encoding`. That uses `device-stack+link` as-is in the recomputed signature base. Original JS-signed sig base used inline `device-stack`. Bytes differ. RSA-PSS verify returns false.
+
+  Linkification happens despite `<<"linkify-mode">> => false` in our start_node opts because some internal HB pipeline (likely `dev_codec_tx.erl` or a cache-side `dev_codec_structured:from` call) passes its own `<<"bundle">> => false` to `linkify_mode/2`, which forces linkify=true.
+
+  Diagnostics captured: `==NFE_ENC_KEYS==` shows `[ao-types, data-protocol, device, **device-stack+link**, execution-device, image, nonce, output-prefix, passes, patch-from, patch-mode, push-device, random-seed, scheduler, type, variant]` for the failing case.
+
+  Attempted fixes that didn't land cleanly:
+  - `hb_cache:ensure_all_loaded` in `normalize_for_encoding`: doesn't decode `+link` keys (they're map-key-suffix conventions, not Link tuples).
+  - `hb_link:decode_all_links` + `ensure_all_loaded`: builds Link tuples for *all* `+link` keys, then crashes with `necessary_message_not_found` for IDs that aren't in the local cache (and shouldn't be loaded just to satisfy signature recomputation).
+
+  Sound fix needs one of:
+  1. Stop HB from linkifying on cache-write when `linkify-mode=false` is set on the node — find the offending caller passing `<<"bundle">> => false` and gate it.
+  2. Have `normalize_for_encoding` selectively dereference only the `+link` keys named in the committed list, falling back to keeping the `+link` form if dereference fails. This effectively delinkifies the verify path without touching the cache-write path.
+  3. Have JS sign a stable canonical form that survives HB's linkification round-trip — would need JS hbsig to emit `device-stack+link` keys with hash IDs computed the same way HB does. Hardest.
+
+  Option 2 is the least invasive but needs careful implementation in `dev_codec_httpsig:normalize_for_encoding/3`. Skipped this session due to scope.
+
+### Open failures and what they're really about
+
+#### A. `process_not_verified` on complex spawn shapes
+
+`test/wao-hbsig/stack.test.js` "device-stack object", `test/wao-hbsig/patch.test.js` (3 cases), `test/wao-hbsig/legacynet.test.js` (AOS WAMR, counter, WAMR), `test/hyperbeam/ans104.test.js` (#1, #2) — all fail with `dev_process_lib:process_id/3` throwing `process_not_verified`.
+
+**Root cause**: HB's `dev_codec_httpsig:verify/3` re-derives the signature base from the committed-key list and the *recomputed* encoding of each key's value, then HMACs/RSA-PSS verifies. For simple shapes (string fields only), JS hbsig's encoding matches HB's; for complex shapes — array values like `device-stack: [wasi@1.0, json-iface@1.0, …]`, object-form `device-stack: { 1: …, 2: … }`, multi-field commits with `data-protocol`/`output-prefix`/`patch-from`/`patch-mode`/`push-device`/`random-seed`/etc. — the signature bases diverge by at least one byte and verification fails.
+
+**Path forward (the "deep fix" you confirmed)**:
+
+Investigation captured this session via temp `io:format` in `dev_codec_httpsig:verify/3`:
+
+For `test/wao-hbsig/stack.test.js` "compute with device-stack object":
+- Failing commitment is **rsa-pss-sha512** (RSA-PSS, not the auto-HMAC).
+- Committed list includes `device-stack` (along with `device`, `execution-device`, `nonce`, `random-seed`, `scheduler`, `type`).
+- Generated `SigBase` shows `@signature-params` = `("content-digest" "content-type" "device" "execution-device" "nonce" "random-seed" "scheduler" "type")` — `device-stack` got *replaced* by `content-digest` because `normalize_for_encoding` moved its map value into the multipart body.
+- For the *array*-form `device-stack` (which passes), the same replacement happens but produces a different `content-digest`. Both `content-digest` values are SHA-256 of the multipart body.
+
+Therefore the bug is **byte-level multipart body re-encoding for map-typed values** inside `dev_codec_httpsig_conv:to/3` (HB-side) vs. JS `hbsig.encode()`. When JS sends `{1: …, 2: …}` as `device-stack`, HB re-encodes it into a different multipart layout than JS used to compute the original `content-digest`.
+
+Concrete next steps:
+1. In HB add `io:format(user, "==BODY:~p==~n", [maps:get(<<"body">>, EncMsg, undefined)])` after the `to/3` call inside `verify` and inside `commit` (both call `normalize_for_encoding`). The body bytes there are what HB feeds into `content-digest`. Capture for one failing case.
+2. In JS `signer.js` (or `send.js`'s `toHttpSigner`), print the multipart body bytes right before fetch sends them. Capture.
+3. Diff byte-by-byte. The first difference is the multipart-encoder bug.
+4. Patch `hbsig/src/encode.js` (most likely) to match HB's multipart layout exactly:
+   - Likely offender: how map values are flattened into `content-disposition: form-data;name="<key>/<sub-key>"` parts. HB uses `hb_util:message_to_ordered_list` for the key paths; for an object like `{1: "inc@1.0", 2: "double@1.0"}` HB may serialize as `1: inc@1.0\n2: double@1.0` while JS serializes the JSON-stringified object as a single value.
+5. Repeat for `test/wao-hbsig/cron.test.js` cron-stop POST body (`invalid_commitment`) — same family.
+6. Repeat for the deeper `test/wao-hbsig/patch.test.js` / legacynet WAMR spawns (15-field committed lists with `data-protocol`, `output-prefix`, `patch-from`, `patch-mode`, `push-device`, `passes`, `image`, `variant`).
+7. `cd hbsig && yarn build && cd dist && npm publish` to ship `hbsig@0.4.0`.
+8. Bump `wao` root `package.json` and `src/workspace/package.json` dep to `^0.4.0`.
+
+#### B. `cache@1.0` link-cache mismatch
+
+`test/hyperbeam/cache.test.js` still fails (`report_ensure_loaded_not_found` for a Link the test never created) *after* the `target → read` API fix. The Link appears during HB's `/~meta@1.0/info` POST encoding when `cache_writers` is set.
+
+**Suspected**: HB's cache-write path now stores nested list values as Links by default; when read back, the Link's data should be in cache but isn't. May be an interaction between `cache_writers` setting + linkify default. Try setting `linkify_mode: discard` on the test or removing the explicit `cache_writers` set (HB may now use the operator wallet as a default writer).
+
+#### C. `faff@1.0` allow-list not enforced
+
+`test/hyperbeam/faff.test.js`: after renaming the property to `faff-allow-list`, the assertion that a disallowed_user POST should reject *succeeds* in the test, meaning the allow-list isn't being enforced server-side.
+
+**Suspected**: the `on/request` hook for faff is using atom keys somewhere internally. Need to inspect what `<<"on">> => #{<<"request">> => #{<<"pricing-device">> => <<"faff@1.0">>, <<"ledger-device">> => <<"faff@1.0">>}}` resolves to at startup with the binary-key node message — atom-keyed device dispatch may be silently no-op'ing.
+
+#### D. Tests not yet surveyed
+
+- `test/hyperbeam/{eunit,hyperbeam,ans104,simple-pay,p4,p4-lua,scheduler,server,router,upload,wao-hb}`
+- All `test/deployment/*` (8 local-HB modes + multinet)
+- All `test/legacynet/*` (mostly remote-only; skip in this env)
+
+### Concrete next-session plan
+
+1. **Run the hbsig encoding-divergence diff (Phase A above)** — first failing case dumped from both sides, one specific bug patched.
+2. Iterate Phase A until all `process_not_verified` failures are gone.
+3. Publish `hbsig@0.4.0`, bump dep.
+4. Tackle Phase B (`cache@1.0`) and Phase C (`faff@1.0`) — both should be small once root-caused.
+5. Run remaining D files, expect mostly green once A/B/C land.
+
+## 8b. Verification — done means
+
+1. `git submodule status` shows the new pinned commit, on the new branch/tag.
+2. From a clean dir: `npx wao create demo && cd demo && npm test` — passes.
+3. `dhfs-tutorial-app/test/` — all 12 pass.
+4. `test/deployment/` — mode5/8/9/11/12 all pass.
+5. `grep -r "beta-3\|beta3\|milestone-3" src/ docs/ app/public/docs/ src/workspace/` — only matches in CHANGELOG/historical notes.
+6. A first-time reader can follow `installing-hb-wao.md` end-to-end without diverging from reality.

package/rebar.lock

@@ -0,0 +1 @@
+[].