wao 0.40.1 → 0.41.0

package/esm/tgql-d1.js

@@ -0,0 +1,407 @@
+// D1-backed GQL query engine
+// Replaces O(n) scan in tgql.js with indexed SQL queries
+
+import { reverse, is, isNil, last, clone, pick, map, includes } from "ramda"
+
+const subs = {
+  owner: ["address", "key"],
+  fee: ["winston", "ar"],
+  quantity: ["winston", "ar"],
+  data: ["size", "type"],
+  tags: ["name", "value"],
+  block: ["id", "timestamp", "height", "previous"],
+  parent: ["id"],
+  bundledIn: ["id"],
+}
+
+const field = (key, val = true) => {
+  if (includes(key, ["id", "anchor", "signature", "recipient"])) {
+    return { key }
+  } else if (subs[key]) {
+    let _subs = []
+    if (val === true) val = subs[key]
+    else if (is(Object, val) && !is(Array, val)) {
+      let _val = []
+      let isTrue = false
+      let isFalse = false
+      for (const k in val)
+        if (val[k] === true) isTrue = true
+        else if (val[k] === false) isFalse = true
+      if (!isTrue && isFalse) {
+        for (const k of subs[key]) if (val[k] !== false) _val.push(k)
+      } else {
+        for (const k in val) if (val[k] === true) _val.push(k)
+      }
+      val = _val
+    } else if (!is(Array, val)) val = subs[key]
+    for (const v2 of val) {
+      if (is(String, v2) && includes(v2, subs[key])) _subs.push(v2)
+    }
+    if (_subs.length === 0) return null
+    return { key, subs: _subs }
+  }
+  return null
+}
+
+const field_blocks = (key, val = true) => {
+  if (includes(key, ["id", "timestamp", "height", "previous"])) {
+    return { key }
+  }
+  return null
+}
+
+function applyFieldProjection(tx, opt) {
+  if (isNil(opt.fields)) return tx
+
+  let _tx2 = { cursor: tx.cursor }
+  let fields = []
+  if (is(Array, opt.fields) && opt.fields.length > 0) {
+    for (const v of opt.fields) {
+      if (is(String, v)) {
+        const fld = field(v)
+        if (fld) fields.push(fld)
+      } else if (is(Object, v) && !is(Array, v)) {
+        for (const k in v) {
+          const fld = field(k, v[k])
+          if (fld) fields.push(fld)
+        }
+      }
+    }
+  } else if (is(Object, opt.fields) && !is(Array, opt.fields)) {
+    for (const k in opt.fields) {
+      const fld = field(k, opt.fields[k])
+      if (fld) fields.push(fld)
+    }
+  }
+  for (const f of fields) {
+    if (isNil(f.subs)) {
+      _tx2[f.key] = tx[f.key] ?? ""
+    } else {
+      _tx2[f.key] = {}
+      if (is(Array, tx[f.key])) {
+        _tx2[f.key] = map(pick(f.subs))(tx[f.key])
+      } else {
+        for (const f2 of f.subs) {
+          _tx2[f.key][f2] = tx[f.key]?.[f2] ?? ""
+        }
+      }
+    }
+  }
+  return _tx2
+}
+
+export default class D1GQL {
+  constructor({ d1, mem }) {
+    this.d1 = d1
+    this.mem = mem
+  }
+
+  async txs(opt = {}) {
+    let _block = {}
+    if (is(Number, opt.block)) {
+      _block = { min: opt.block, max: opt.block }
+    } else if (is(Array, opt.block) && opt.block.length > 0) {
+      _block = {}
+      if (!isNil(opt.block[0])) _block.min = opt.block[0]
+      if (!isNil(opt.block[1])) _block.max = opt.block[1]
+    } else if (is(Object, opt.block)) {
+      if (!isNil(opt.block.min)) _block.min = opt.block.min
+      if (!isNil(opt.block.max)) _block.max = opt.block.max
+    }
+
+    const first = opt.first ?? 10
+    let tags = []
+    for (const k in opt.tags ?? {}) {
+      if (is(String, opt.tags[k])) {
+        tags.push({ name: k, values: [opt.tags[k]] })
+      } else if (is(Array, opt.tags[k])) {
+        tags.push({ name: k, values: opt.tags[k] })
+      }
+    }
+
+    let recipients = null
+    if (is(Array, opt.recipients)) recipients = opt.recipients
+    else if (is(String, opt.recipient)) recipients = [opt.recipient]
+
+    let owners = null
+    if (is(Array, opt.owners)) owners = opt.owners
+    else if (is(String, opt.owner)) owners = [opt.owner]
+
+    let ids = null
+    if (is(Array, opt.ids)) ids = opt.ids
+    else if (is(String, opt.id)) ids = [opt.id]
+
+    // Build SQL query
+    const conditions = []
+    const params = []
+
+    if (!isNil(_block.min)) {
+      conditions.push("t.block_height >= ?")
+      params.push(_block.min)
+    }
+    if (!isNil(_block.max)) {
+      conditions.push("t.block_height <= ?")
+      params.push(_block.max)
+    }
+    if (ids && ids.length > 0) {
+      conditions.push(`t.id IN (${ids.map(() => "?").join(",")})`)
+      params.push(...ids)
+    }
+    if (owners && owners.length > 0) {
+      conditions.push(`t.owner IN (${owners.map(() => "?").join(",")})`)
+      params.push(...owners)
+    }
+    if (recipients && recipients.length > 0) {
+      conditions.push(`t.recipient IN (${recipients.map(() => "?").join(",")})`)
+      params.push(...recipients)
+    }
+    if (!isNil(opt.bundledIn) && opt.bundledIn.length > 0) {
+      conditions.push(`t.bundle_id IN (${opt.bundledIn.map(() => "?").join(",")})`)
+      params.push(...opt.bundledIn)
+    }
+
+    // Tag filters — each tag filter requires ALL to match (AND)
+    for (const tag of tags) {
+      const valuePlaceholders = tag.values.map(() => "?").join(",")
+      conditions.push(
+        `t.id IN (SELECT tx_id FROM tx_tags WHERE name = ? AND value IN (${valuePlaceholders}))`
+      )
+      params.push(tag.name, ...tag.values)
+    }
+
+    // After cursor (pagination)
+    if (!isNil(opt.after)) {
+      // Get the block_height of the cursor tx to paginate correctly
+      const cursorRow = await this.d1
+        .prepare("SELECT block_height FROM txs WHERE id = ?")
+        .bind(opt.after)
+        .first()
+      if (cursorRow) {
+        if (opt.asc === true) {
+          conditions.push("(t.block_height > ? OR (t.block_height = ? AND t.id > ?))")
+          params.push(cursorRow.block_height, cursorRow.block_height, opt.after)
+        } else {
+          conditions.push("(t.block_height < ? OR (t.block_height = ? AND t.id < ?))")
+          params.push(cursorRow.block_height, cursorRow.block_height, opt.after)
+        }
+      }
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : ""
+    const order = opt.asc === true ? "ASC" : "DESC"
+
+    const sql = `
+      SELECT t.id, t.block_id, t.block_height, t.owner, t.recipient,
+             t.anchor, t.signature, t.data_size, t.data_type, t.bundle_id, t.parent_id,
+             b.height, b.timestamp, b.previous
+      FROM txs t
+      JOIN blocks b ON t.block_id = b.id
+      ${where}
+      ORDER BY t.block_height ${order}, t.id ${order}
+      LIMIT ?
+    `
+    params.push(first)
+
+    const { results: rows } = await this.d1
+      .prepare(sql)
+      .bind(...params)
+      .all()
+
+    // Fetch tags for all result txs in one query
+    const txIds = rows.map(r => r.id)
+    let tagMap = {}
+    if (txIds.length > 0) {
+      const tagSql = `SELECT tx_id, name, value FROM tx_tags WHERE tx_id IN (${txIds.map(() => "?").join(",")})`
+      const { results: tagRows } = await this.d1
+        .prepare(tagSql)
+        .bind(...txIds)
+        .all()
+      for (const t of tagRows) {
+        tagMap[t.tx_id] ??= []
+        tagMap[t.tx_id].push({ name: t.name, value: t.value })
+      }
+    }
+
+    // Fetch addrmap for owners
+    const ownerAddrs = [...new Set(rows.map(r => r.owner).filter(Boolean))]
+    let addrMap = {}
+    if (ownerAddrs.length > 0) {
+      const addrSql = `SELECT address, key FROM addrmap WHERE address IN (${ownerAddrs.map(() => "?").join(",")})`
+      const { results: addrRows } = await this.d1
+        .prepare(addrSql)
+        .bind(...ownerAddrs)
+        .all()
+      for (const a of addrRows) {
+        addrMap[a.address] = { address: a.address, key: a.key }
+      }
+    }
+
+    const data = rows.map(row => {
+      let _tx = {
+        cursor: row.id,
+        id: row.id,
+        recipient: row.recipient || "",
+        tags: tagMap[row.id] || [],
+        parent: row.parent_id ? { id: row.parent_id } : { id: "" },
+        bundledIn: row.bundle_id ? { id: row.bundle_id } : { id: "" },
+        block: {
+          id: row.block_id,
+          timestamp: row.timestamp,
+          height: row.height,
+          previous: row.previous || "",
+        },
+        anchor: row.anchor || "",
+        signature: row.signature || "",
+        owner: addrMap[row.owner] || { address: row.owner, key: "" },
+        fee: { ar: "0.000000000000", winston: "0" },
+        quantity: { ar: "0.000000000000", winston: "0" },
+        data: { size: row.data_size || "0", type: row.data_type || "" },
+      }
+      return applyFieldProjection(_tx, opt)
+    })
+
+    if (opt.next === true) {
+      let cursor = null
+      if (data.length > 0) cursor = last(data).cursor
+      const next = !cursor
+        ? null
+        : async () => {
+            let _opt = clone(opt)
+            _opt.after = cursor
+            return await this.txs(_opt)
+          }
+      return { data, next }
+    }
+    return data
+  }
+
+  async blocks(opt = {}) {
+    let _block = {}
+    if (is(Number, opt.block)) {
+      _block = { min: opt.block, max: opt.block }
+    } else if (is(Array, opt.block) && opt.block.length > 0) {
+      _block = {}
+      if (!isNil(opt.block[0])) _block.min = opt.block[0]
+      if (!isNil(opt.block[1])) _block.max = opt.block[1]
+    }
+    const first = opt.first ?? 20
+
+    let ids = null
+    if (is(Array, opt.ids)) ids = opt.ids
+    else if (is(String, opt.id)) ids = [opt.id]
+
+    const conditions = []
+    const params = []
+
+    if (!isNil(_block.min)) {
+      conditions.push("height >= ?")
+      params.push(_block.min)
+    }
+    if (!isNil(_block.max)) {
+      conditions.push("height <= ?")
+      params.push(_block.max)
+    }
+    if (ids && ids.length > 0) {
+      conditions.push(`id IN (${ids.map(() => "?").join(",")})`)
+      params.push(...ids)
+    }
+
+    if (!isNil(opt.after)) {
+      const cursorRow = await this.d1
+        .prepare("SELECT height FROM blocks WHERE id = ?")
+        .bind(opt.after)
+        .first()
+      if (cursorRow) {
+        if (opt.asc === true) {
+          conditions.push("height > ?")
+          params.push(cursorRow.height)
+        } else {
+          conditions.push("height < ?")
+          params.push(cursorRow.height)
+        }
+      }
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : ""
+    const order = opt.asc === true ? "ASC" : "DESC"
+
+    const sql = `
+      SELECT id, height, timestamp, previous
+      FROM blocks
+      ${where}
+      ORDER BY height ${order}
+      LIMIT ?
+    `
+    params.push(first)
+
+    const { results: rows } = await this.d1
+      .prepare(sql)
+      .bind(...params)
+      .all()
+
+    let data = rows.map(row => {
+      let block = {
+        cursor: row.id,
+        id: row.id,
+        height: row.height,
+        timestamp: row.timestamp,
+        previous: row.previous || "",
+      }
+
+      // Apply field projection
+      if (!isNil(opt.fields)) {
+        let block2 = { cursor: block.id }
+        let fields = []
+        if (is(Array, opt.fields) && opt.fields.length > 0) {
+          for (const v of opt.fields) {
+            if (is(String, v)) {
+              const fld = field_blocks(v)
+              if (fld) fields.push(fld)
+            } else if (is(Object, v) && !is(Array, v)) {
+              for (const k in v) {
+                const fld = field_blocks(k, v[k])
+                if (fld) fields.push(fld)
+              }
+            }
+          }
+        } else if (is(Object, opt.fields) && !is(Array, opt.fields)) {
+          for (const k in opt.fields) {
+            const fld = field_blocks(k, opt.fields[k])
+            if (fld) fields.push(fld)
+          }
+        }
+        for (const f of fields) {
+          if (isNil(f.subs)) {
+            block2[f.key] = block[f.key] ?? ""
+          } else {
+            block2[f.key] = {}
+            if (is(Array, block[f.key])) {
+              block2[f.key] = map(pick(f.subs))(block[f.key])
+            } else {
+              for (const f2 of f.subs) {
+                block2[f.key][f2] = block[f.key]?.[f2] ?? ""
+              }
+            }
+          }
+        }
+        block = block2
+      }
+
+      return block
+    })
+
+    if (opt.next === true) {
+      let cursor = null
+      if (data.length > 0) cursor = last(data).cursor
+      const next = !cursor
+        ? null
+        : async () => {
+            let _opt = clone(opt)
+            _opt.after = cursor
+            return await this.txs(_opt)
+          }
+      return { data, next }
+    }
+    return data
+  }
+}

package/esm/tgql.js

@@ -1,3 +1,4 @@
+import D1GQL from "./tgql-d1.js"
 import { reverse, includes, map, is, isNil, last, clone, pick } from "ramda"
 
 const subs = {
@@ -48,10 +49,20 @@ const field_blocks = (key, val = true) => {
 }
 
 export default class GQL {
-  constructor({ mem }) {
+  constructor({ mem, d1 }) {
     this.mem = mem
+    this.d1 = d1 || null
+    if (this.d1) {
+      this._d1gql = new D1GQL({ d1: this.d1, mem: this.mem })
+    }
   }
   async txs(opt = {}) {
+    if (this._d1gql) {
+      try { return await this._d1gql.txs(opt) } catch (e) {
+        // Fall through to O(n) scan only if D1 schema is missing
+        if (!e?.message?.includes("no such table")) throw e
+      }
+    }
     let block_max = null
     let block_min = null
     let _block = {}
@@ -91,7 +102,7 @@ export default class GQL {
     let count = 0
     let after = false
     for (const v of blocks) {
-      const block = clone(this.mem.blockmap[v])
+      const block = clone(await this.mem.get("blockmap", v))
       if (!isNil(_block.min) && block.height < _block.min) continue
       if (!isNil(_block.max) && block.height > _block.max) continue
       let txs = block.txs
@@ -103,6 +114,7 @@ export default class GQL {
         }
         if (!isNil(opt.after) && count === 0 && !after) continue
         let tx = await this.mem.getTx(v2)
+        if (!tx) continue
         if (!isNil(ids) && ids.length > 0) {
           if (!includes(tx.id, ids)) continue
         }
@@ -113,10 +125,13 @@ export default class GQL {
         if (!isNil(recipients) && recipients.length > 0) {
           if (!includes(tx.recipient, recipients)) continue
         }
+        if (!isNil(opt.bundledIn) && opt.bundledIn.length > 0) {
+          if (!tx.bundledIn?.id || !includes(tx.bundledIn.id, opt.bundledIn)) continue
+        }
         let tag_unmatch = false
         for (const v of tags) {
           let ex = false
-          for (const v2 of tx.tags) {
+          for (const v2 of (tx.tags || [])) {
             if (v2.name === v.name && includes(v2.value, v.values)) {
               ex = true
               break
@@ -132,17 +147,16 @@ export default class GQL {
           cursor: tx.id,
           id: tx.id,
           recipient: tx.recipient ?? "",
-          data: tx._data,
-          tags: tx.tags,
+          tags: tx.tags || [],
           parent: tx.parent ?? { id: "" },
           bundledIn: tx.bundledIn ?? { id: "" },
           block: pick(["id", "timestamp", "height", "previous"], block),
           anchor: tx.anchor ?? "",
           signature: tx.signature ?? "",
-          owner: { address: tx.owner, key: this.mem.addrmap[tx.owner] },
+          owner: { address: tx.owner, key: await this.mem.get("addrmap", tx.owner) },
           fee: { ar: "0.000000000000", winston: "0" },
           quantity: { ar: "0.000000000000", winston: "0" },
-          data: { size: "0", type: "" },
+          data: tx._data?.type ? tx._data : { size: tx._data?.size || tx.data_size || (tx.data ? String(tx.data.length) : "0"), type: (tx.tags || []).find(t => t.name === "Content-Type")?.value || "" },
         }
         if (!isNil(opt.fields)) {
           let _tx2 = { cursor: tx.id }
@@ -173,7 +187,7 @@ export default class GQL {
               _tx2[f.key] = {}
               if (is(Array, _tx[f.key])) {
                 _tx2[f.key] = map(pick(f.subs))(_tx[f.key])
-              } else {
+              } else if (_tx[f.key] != null) {
                 for (const f2 of f.subs) {
                   _tx2[f.key][f2] = _tx[f.key][f2] ?? ""
                 }
@@ -204,6 +218,11 @@ export default class GQL {
     }
   }
   async blocks(opt = {}) {
+    if (this._d1gql) {
+      try { return await this._d1gql.blocks(opt) } catch (e) {
+        if (!e?.message?.includes("no such table")) throw e
+      }
+    }
     let block_max = null
     let block_min = null
     let _block = {}
@@ -226,7 +245,7 @@ export default class GQL {
     let count = 0
     let after = false
     for (const v of blocks) {
-      let block = clone({ ...this.mem.blockmap[v], cursor: v })
+      let block = clone({ ...(await this.mem.get("blockmap", v)), cursor: v })
       delete block.txs
       if (!isNil(_block.min) && block.height < _block.min) continue
       if (!isNil(_block.max) && block.height > _block.max) continue
@@ -260,7 +279,7 @@ export default class GQL {
             block2[f.key] = {}
             if (is(Array, block[f.key])) {
               block2[f.key] = map(pick(f.subs))(block[f.key])
-            } else {
+            } else if (block[f.key] != null) {
               for (const f2 of f.subs) {
                 block2[f.key][f2] = block[f.key][f2] ?? ""
               }

package/esm/workspace/.claude/agents/tester.md

@@ -29,7 +29,7 @@ yarn test                          # all tests
 yarn test test/aos.test.js         # specific file
 ```
 
-The test command runs: `node --experimental-wasm-memory64 --test --test-concurrency=1`
+The test command runs: `node --test --test-concurrency=1` (Node 24+ enables wasm-memory64 by default and rejects the experimental flag; Node 22 users add `--experimental-wasm-memory64` via NODE_OPTIONS).
 
 ## Systematic Debugging
 
@@ -59,7 +59,7 @@ Report test results with specifics: which tests pass, which fail, and the error
 ## Common Issues
 
 - **Port already in use**: Kill stale `beam.smp` processes
-- **WASM memory error**: Ensure `--experimental-wasm-memory64` flag is present
+- **WASM memory error**: On Node 22 set `NODE_OPTIONS=--experimental-wasm-memory64`. On Node 24+ the flag is default-on (and rejected if passed explicitly — "bad option: --experimental-wasm-memory64")
 - **Process not found**: Check that `src_data` path is correct
 - **HyperBEAM timeout**: Ensure `hbeam.kill()` is called in `after()`
 - **Send().receive() hangs**: Does NOT work on genesis-wasm — use fire-and-forget `Send()` + separate Handlers.add calls

package/esm/workspace/.claude/skills/build/SKILL.md

@@ -210,5 +210,5 @@ Never force a task to `done` status with failing tests. The TaskCompleted hook w
 - Verify task statuses — a task stuck as `in_progress` blocks progression
 
 ### Permission denied on yarn test
-- Check `node --version` is 20+
-- Verify `--experimental-wasm-memory64` flag is present in package.json
+- Check `node --version` is 22+ (24+ recommended)
+- On Node 22, set `NODE_OPTIONS=--experimental-wasm-memory64`; on Node 24+ the flag is default-on and is rejected if passed explicitly

package/esm/workspace/.claude/skills/test/SKILL.md

@@ -51,5 +51,6 @@ yarn test
 - Check `package.json` has `"wao"` in dependencies
 
 ### WASM memory error
-- Ensure `--experimental-wasm-memory64` flag is in the test command
-- Node.js 20+ required
+- Node 24+ enables wasm-memory64 by default — DO NOT pass `--experimental-wasm-memory64` (it's rejected with "bad option")
+- Node 22: set `NODE_OPTIONS=--experimental-wasm-memory64` before running
+- Node.js 22+ required

package/esm/workspace/CLAUDE.md

@@ -95,7 +95,7 @@ yarn deploy --mainnet                    # remote HyperBEAM (push-1)
 yarn deploy --mainnet --lua              # remote HyperBEAM (Lua mode)
 ```
 
-Runs: `node --experimental-wasm-memory64 --test --test-concurrency=1`
+Runs: `node --test --test-concurrency=1` (Node 24+; on Node 22 prefix with `--experimental-wasm-memory64`)
 
 ## Deployment Targets
 
@@ -109,7 +109,7 @@ Runs: `node --experimental-wasm-memory64 --test --test-concurrency=1`
 - **Remote nodes**: Use `push-1` through `push-10` for full compute. `push.forward.computer` is push-only (no compute).
 - **Lua mode**: Faster but no `receive()` — use `msg.reply()` pattern instead.
 - **Wallet**: Run `yarn keygen` to generate `.wallet.json`.
-- **HyperBEAM fork**: `git clone -b wao-beta3 https://github.com/weavedb/HyperBEAM.git`
+- **HyperBEAM fork**: `git clone -b wao-final https://github.com/weavedb/HyperBEAM.git`
 
 ### Frontend Commands
 

package/esm/workspace/README.md

@@ -52,7 +52,7 @@ yarn deploy --local-hb --lua src/counter.lua
 
 **Remote nodes**: Use `push-1` through `push-10` for full compute. `push.forward.computer` is push-only (no compute).
 
-**HyperBEAM fork**: `git clone -b wao-beta3 https://github.com/weavedb/HyperBEAM.git && cd HyperBEAM && rebar3 compile`
+**HyperBEAM fork**: `git clone -b wao-final https://github.com/weavedb/HyperBEAM.git && cd HyperBEAM && rebar3 compile`
 
 ---
 

package/esm/workspace/docs/debug.md

@@ -144,13 +144,17 @@ await hb.schedule({
 
 **Problem:** `WebAssembly.Memory` errors or WASM module fails to load.
 
-**Fix:** Ensure the `--experimental-wasm-memory64` flag is present:
+**Fix:** Node 24+ enables wasm-memory64 by default (and rejects the experimental flag at startup with "bad option"). On Node 22 or older, prefix with `--experimental-wasm-memory64`:
 
 ```bash
+# Node 24+: no flag needed
+node --test test/aos.test.js
+
+# Node 22:
 node --experimental-wasm-memory64 --test test/aos.test.js
 ```
 
-The `yarn test` script should already include this flag.
+The `yarn test` script ships without the flag (Node 24+ default); set `NODE_OPTIONS=--experimental-wasm-memory64` if you're on older Node.
 
 ### Genesis-WASM Server
 
@@ -202,7 +206,8 @@ The `yarn test` script should already include this flag.
 | `badarg in list_to_atom` | Atom not pre-registered | Add to preRegisterAtoms |
 | `multiple_matches` | Duplicate message content | Add nonce to messages |
 | `timeout` | Process or server hung | Kill stale processes, increase timeout |
-| `WASM memory error` | Missing memory64 flag | Add `--experimental-wasm-memory64` |
+| `WASM memory error` | Missing memory64 (Node 22) | Set `NODE_OPTIONS=--experimental-wasm-memory64` (Node 22) — Node 24+ has it default-on |
+| `bad option: --experimental-wasm-memory64` | Passing the flag on Node 24+ | Remove the flag — Node 24+ rejects it |
 | `Process not found` | Bad pid or deploy failed | Check deploy result, verify pid |
 | `Insufficient balance` | Payment balance too low | Top up via simple-pay or p4 |
 | `Not signed` | Missing wallet/JWK | Call `.init(jwk)` before operations |
@@ -215,7 +220,7 @@ When tests fail, check in order:
 
 1. **Ports clear?** `lsof -ti :10000-10010 | xargs -r kill -9`
 2. **beam.smp killed?** `pkill -f beam.smp`
-3. **WASM flag?** `--experimental-wasm-memory64` in test command
+3. **WASM flag?** Node 24+ default-on; on Node 22 add `--experimental-wasm-memory64` (and on Node 24+ remove it — it's rejected)
 4. **HyperBEAM dir?** `ls ./HyperBEAM` exists
 5. **Wallet exists?** `.wallet.json` present (auto-generated)
 6. **hbeam.kill() in after()?** Always clean up

package/esm/workspace/docs/hyperbeam-devices.md

@@ -348,7 +348,7 @@ const result = await hb.computeLegacy({ pid, slot })
 **Limitations:**
 - External CU is single-pass — **`Send().receive()` does NOT work**
 - Auto-starts CU server at port 6363
-- Requires `--experimental-wasm-memory64` Node.js flag
+- Requires wasm-memory64 (Node 24+ default; Node 22 needs `--experimental-wasm-memory64`)
 
 Functions: `init/3`, `compute/3`, `snapshot/3`, `import/3`
 
@@ -540,6 +540,55 @@ Query Arweave via GraphQL from within HyperBEAM.
 
 ---
 
+## v0.9-FINAL Devices (new since beta3)
+
+### location@1.0 — Scheduler-Location Registry
+
+Replaces the old `/~scheduler@1.0/location` endpoint. Stores per-address scheduler-location records (with DNS/IP resolution and a TTL) in a node-local cache, with fallback to the Arweave gateway.
+
+- `POST /~location@1.0/node` — operator generates and registers a record (signed)
+- `POST /~location@1.0/known` — cache a peer's record if newer than the local one
+- Read via `dev_whois` / `dev_location_cache`
+
+### metering@1.0 — Dynamic P4 Pricing
+
+A P4 pricing device that records resource usage per request/response lifecycle.
+
+- `estimate/3` opens a process-local session
+- `consume/3` increments usage during the session
+- `price/3` closes the session and returns the integer charge
+- Operator sets `metering-rates` in node message (resource → AO units per resource unit)
+
+### blacklist@1.0 — Content Moderation by Blacklist
+
+A request hook for filtering. Operator configures `blacklist-providers` (list) in node message; each provider returns a moderation set.
+
+### bundler@1.0 — ANS-104 Bundler Integration
+
+Outbound bundler for posting ANS-104 transactions to upstream Arweave bundlers (e.g. `up.arweave.net`).
+
+### gzip@1.0 — gzip Codec
+
+Compress/decompress message bodies via gzip during processing.
+
+### rate-limit@1.0 — Per-Address Rate Limiting
+
+Operator-configurable per-address rate limits applied as a request hook.
+
+### tx@1.0 — Arweave TX Helpers
+
+Helpers for fetching and validating Arweave transactions inline.
+
+### b32-name@1.0 — Base-32 Name Encoding
+
+Helpers for base-32 name encoding/decoding used by other devices.
+
+### arweave@2.9 — Arweave Block + GraphQL Integration
+
+Renamed in v0.9-FINAL (was `arweave@2.9-pre`). Provides Arweave block cache, offset helpers, and common Arweave protocol primitives.
+
+---
+
 ## Multi-Instance Setup
 
 Running multiple HyperBEAM nodes requires unique ports and Erlang node names: