wenay-common2 1.0.69 → 1.0.70

package/README.md

@@ -8,4 +8,13 @@
 - Extended API cheat sheet: [`doc/wenay-common2-rare.md`](doc/wenay-common2-rare.md)
 - Naming migrations: [`doc/NAMING_RENAMES.md`](doc/NAMING_RENAMES.md)
 - Recent changes: [`doc/changes/`](doc/changes/)
-- Project rules for AI/code maintenance: [`CLAUDE.md`](CLAUDE.md)
+- Project rules for AI/code maintenance: [`CLAUDE.md`](CLAUDE.md)
+
+## Living examples (shipped in the npm package)
+
+- [`demo/`](demo/) — runnable stand (`npm run demo`): shared cursors in two browser tabs over the
+  Peer SDK, relay ⇄ WebRTC direct hand-off next to a legacy rpc key.
+- [`replay/`](replay/) · [`observe/`](observe/) · [`oracle/`](oracle/) — the oracle suites CI runs on
+  every push; each file doubles as a worked usage example of one subsystem.
+- Note: examples import from the repo's `src/`; in the installed package the same API comes from
+  `wenay-common2` / `wenay-common2/peer` / `wenay-common2/replay` / `wenay-common2/observe`.

package/demo/client.ts

@@ -0,0 +1,100 @@
+// Demo stand client: shared cursors over the Peer SDK — relay by default,
+// "Go direct" promotes to a real RTCPeerConnection datachannel, "Back to relay"
+// re-interposes. The route hand-off is gap-free by seq; the cursor never jumps.
+import {io} from 'socket.io-client'
+import {createRpcClientHub} from '../src/Common/rcp/rpc-clientHub'
+import {createPeerClient} from '../src/Common/peer/peer-index'
+
+type World = {cursor: {x: number, y: number}, color: string, name: string}
+
+const params = new URLSearchParams(location.search)
+const me = params.get('me') ?? 'a'
+const other = params.get('peer') ?? (me == 'a' ? 'b' : 'a')
+
+const el = (id: string) => document.getElementById(id)!
+const logBox = () => el('log') as HTMLDivElement
+
+function log(line: string) {
+    const box = logBox()
+    const row = document.createElement('div')
+    row.textContent = `${new Date().toLocaleTimeString()}  ${line}`
+    box.prepend(row)
+    while (box.children.length > 30) box.lastChild?.remove()
+}
+
+async function main() {
+    document.title = `peer ${me}`
+    el('who').textContent = `me: ${me}  ·  watching: ${other}`
+
+    const hub = createRpcClientHub(
+        () => io({transports: ['websocket'], auth: {account: me}}),
+        r => ({app: r<any>('app')}) as const,
+    )
+    const clients = await hub.setToken(null)
+    await clients.app.readyStrict()
+    log('rpc connected; legacy serverTime() = ' + await clients.app.func.serverTime())
+
+    // debug tap: every signaling envelope this account receives
+    ;(clients.app.func.peer.signal.signals as any).on((env: any) => {
+        log(`sig<- ${env.type} ${env.from}->${env.to}` +
+            (env.sdp ? ` sdp.len=${String(env.sdp).length}` : '') +
+            (env.candidate ? ` cand=${JSON.stringify(env.candidate).slice(0, 70)}` : ''))
+    })
+
+    const client = createPeerClient<World>({
+        remote: clients.app.func.peer,
+        account: me,
+        initial: {
+            cursor: {x: 160, y: 120},
+            color: me == 'a' ? '#4f8ef7' : '#f7a44f',
+            name: me,
+        },
+        rtc: () => new RTCPeerConnection(),
+        drain: 'micro',
+    })
+    const peer = client.peer(other)
+    client.onRoute(ev => log(`route ${ev.key}: ${ev.from} -> ${ev.to}${ev.reason ? ` (${String(ev.reason)})` : ''}`))
+    peer.ready.then(() => log('peer mirror ready (keyframe landed)')).catch(e => log('mirror error: ' + e))
+
+    // ============== input: own cursor -> own store ==============
+    const canvas = el('canvas') as HTMLCanvasElement
+    canvas.addEventListener('mousemove', function onMove(e) {
+        const r = canvas.getBoundingClientRect()
+        client.store.state.cursor = {x: Math.round(e.clientX - r.left), y: Math.round(e.clientY - r.top)}
+    })
+
+    // ============== render loop: own + mirrored cursor ==============
+    const ctx = canvas.getContext('2d')!
+    function drawCursor(c: {x: number, y: number}, color: string, name: string) {
+        ctx.beginPath()
+        ctx.arc(c.x, c.y, 8, 0, Math.PI * 2)
+        ctx.fillStyle = color
+        ctx.fill()
+        ctx.fillStyle = '#333'
+        ctx.font = '12px sans-serif'
+        ctx.fillText(name, c.x + 12, c.y + 4)
+    }
+    function frame() {
+        ctx.clearRect(0, 0, canvas.width, canvas.height)
+        const mine = client.store.state
+        drawCursor(mine.cursor, mine.color, mine.name + ' (me)')
+        const theirs = peer.store.state
+        if (theirs?.cursor) drawCursor(theirs.cursor, theirs.color ?? '#999', (theirs.name ?? other) + ` [${peer.route()}]`)
+        el('route').textContent = `route: ${peer.route()}  ·  state: ${peer.state()}  ·  seq: ${peer.seq()}`
+        requestAnimationFrame(frame)
+    }
+    frame()
+
+    // ============== route controls ==============
+    el('direct').addEventListener('click', async function goDirect() {
+        log('promoteDirect...')
+        const res = await peer.promoteDirect({timeoutMs: 8000})
+        log(res.ok ? `direct: ok (${res.state})` : `direct failed: ${String(res.reason)}`)
+    })
+    el('relay').addEventListener('click', async function backToRelay() {
+        const res = await peer.reinterposeRelay('manual')
+        log(res.ok ? 'back on relay' : `re-interpose failed: ${String(res.reason)}`)
+    })
+}
+
+main().catch(e => { console.error(e); log('FATAL: ' + e) })

package/demo/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>wenay-common2 peer stand</title>
+<style>
+    body { font-family: sans-serif; margin: 16px; color: #222; }
+    #canvas { border: 1px solid #bbb; border-radius: 6px; background: #fafafa; display: block; }
+    #bar { display: flex; gap: 12px; align-items: center; margin: 8px 0; flex-wrap: wrap; }
+    #route { font-family: monospace; }
+    button { padding: 6px 14px; border-radius: 6px; border: 1px solid #888; background: #fff; cursor: pointer; }
+    button:hover { background: #f0f0f0; }
+    #log { font-family: monospace; font-size: 12px; margin-top: 8px; max-height: 180px; overflow-y: auto; color: #555; }
+</style>
+</head>
+<body>
+<h3>wenay-common2 — shared cursors (relay ⇄ WebRTC direct)</h3>
+<div id="bar">
+    <span id="who">connecting…</span>
+    <button id="direct">Go direct</button>
+    <button id="relay">Back to relay</button>
+    <span id="route"></span>
+</div>
+<canvas id="canvas" width="640" height="360"></canvas>
+<div id="log"></div>
+<script src="client.js"></script>
+</body>
+</html>

package/demo/server.ts

@@ -0,0 +1,43 @@
+// Demo stand server: the Peer SDK next to a legacy rpc key, static page hosting.
+// Run: npm run demo  ->  open the two printed URLs in two tabs.
+import express from 'express'
+import {createServer} from 'http'
+import path from 'path'
+import {Server as SocketIOServer} from 'socket.io'
+import {listen} from '../src/Common/events/Listen'
+import {createPeerHost} from '../src/Common/peer/peer-index'
+import {createRpcServerAuto} from '../src/Common/rcp/rpc-server-auto'
+
+const PORT = Number(process.env.PORT ?? 8390)
+
+const host = createPeerHost()
+const app = express()
+app.use(express.static(path.resolve(__dirname, 'public')))
+app.get('/', (_req, res) => res.sendFile(path.resolve(__dirname, 'public', 'index.html')))
+
+const httpServer = createServer(app)
+const ioServer = new SocketIOServer(httpServer)
+
+ioServer.on('connection', function onDemoConnection(socket) {
+    const account = String(socket.handshake.auth?.account ?? 'anon')
+    const peer = host.connection(account)
+    const [disconnect, disconnectListen] = listen<[]>()
+    socket.on('disconnect', () => { disconnect(); peer.close() })
+    createRpcServerAuto({
+        socket: {emit: (key, data) => socket.emit(key, data), on: (key, cb) => socket.on(key, cb)},
+        socketKey: 'app',
+        object: {
+            // legacy key on the SAME connection — the SDK does not displace old code
+            serverTime: () => new Date().toISOString(),
+            peer: peer.fragment,
+        },
+        disconnectListen,
+    })
+    console.log(`[demo] ${account} connected`)
+})
+
+httpServer.listen(PORT, function onDemoListen() {
+    console.log('[demo] shared-cursor stand is up:')
+    console.log(`  tab A: http://localhost:${PORT}/?me=a&peer=b`)
+    console.log(`  tab B: http://localhost:${PORT}/?me=b&peer=a`)
+})

package/doc/changes/1.0.70.md

@@ -0,0 +1,4 @@
+# 1.0.70
+
+- Ship the living examples in the npm package: the oracle suites (`replay/`, `observe/`, `oracle/`) and the demo stand (`demo/`, without the generated bundle) — each oracle doubles as a worked usage example of one subsystem, kept honest by CI on every push.
+- README: a "Living examples" section with the src-vs-package import note (examples import the repo's `src/`; installed packages use `wenay-common2` / `wenay-common2/peer` / `wenay-common2/replay` / `wenay-common2/observe`).

package/observe/PLAN.md

@@ -0,0 +1,131 @@
+# observe — status and contract
+
+`observe` is the small reactive core for coarse, consistent invalidation.
+It is intentionally not a MobX/Vue clone: the API does not expose deltas,
+paths, old values, or computed values.
+
+Implemented surface:
+
+```ts
+import {reactive, onUpdate, flushReactive, listenUpdate} from './reactive'
+
+const state = reactive({
+    price: 100,
+    balances: {BTC: 1, ETH: 10},
+})
+
+const off = onUpdate(state.balances, () => {
+    const total = Object.values(state.balances).reduce((a, b) => a + b, 0)
+})
+
+state.balances.BTC = 2
+state.balances = {SOL: 250, DOT: 150, ADA: 100}
+await flushReactive(state.balances)
+off()
+```
+
+## Core idea
+
+Subscribe to the fact that something under a node changed. The callback receives
+no `(key, value)`, no diff, and no string path. It fires after the settled batch;
+the consumer re-reads the current state through normal typed property access.
+
+This is the intended trading/backend use case:
+
+- a feed applies several synchronous mutations;
+- subscribers fire once after the batch;
+- aggregate code reads a consistent snapshot;
+- replacing a whole subtree does not break existing subscribers on that subtree.
+
+## What is implemented
+
+- `reactive(obj, opts?)` wraps a plain object/array tree in stable proxies.
+- `onUpdate(node, cb)` subscribes to a reactive node and returns an idempotent `off()`.
+- `flushReactive(node)` resolves after queued drains for that reactive tree settle.
+- `listenUpdate(node)` adapts a node to the project's existing `Listen` shape for RPC.
+- Synchronous bursts are coalesced into one callback per subscribed node.
+- A callback that mutates state queues a follow-up drain instead of recursing.
+- A throwing callback does not stop sibling subscribers; the first error is re-thrown asynchronously.
+- Whole-subtree replacement preserves existing child proxy identity where possible.
+- `depth` makes deeper objects opaque leaves.
+- `eager` pre-walks/wraps the tree to `depth`.
+- `drain` is pluggable: `'immediate'`, `'micro'`, `number`, or custom scheduler.
+- Plain objects and arrays are reactive. `Date`, `Map`, `Set`, and class instances are opaque leaves.
+
+## Chosen laziness model
+
+The original design considered subscription-driven wrapping with `subtreeSubs`.
+The implemented model is simpler and is now the contract:
+
+- root is always a proxy;
+- child proxies are created lazily on read, up to `depth`;
+- with zero subscribers, writes only mutate and do not schedule drains;
+- built-in/class objects are not proxied.
+
+So this is **lazy-on-read**, not subscription-driven wrapping. That is a conscious
+tradeoff: it keeps normal `onUpdate(state.a.b, cb)` usage simple and avoids the
+identity caveat of fully lazy upgrades.
+
+## Options
+
+```ts
+type Drain =
+    | 'micro'
+    | 'immediate'
+    | number
+    | ((flush: () => void) => void)
+
+type Opts = {
+    drain?: Drain      // default: 'immediate'
+    depth?: number     // default: Infinity
+    eager?: boolean    // default: false
+}
+```
+
+Drain semantics:
+
+- `'immediate'`: uses `setImmediate` when available, otherwise `setTimeout(0)`.
+- `'micro'`: uses `queueMicrotask`.
+- `number`: uses `setTimeout(ms)` and coalesces to the last state.
+- custom scheduler: receives the flush function.
+
+Use `flushReactive(node)` in tests/examples instead of guessing event-loop order.
+
+## Verified by oracle
+
+Run:
+
+```bash
+npx tsx observe/reactive.test.ts
+npx tsx observe/usage.ts
+```
+
+The oracle covers:
+
+- plain and nested read/write;
+- cold writes with no subscribers;
+- one fact per batch;
+- the `$500` whole-map replacement case;
+- subscriber survival across middle-node replacement;
+- root subscriber behavior;
+- unsubscribe before flush;
+- mutation from inside callback;
+- arrays;
+- opaque `Date`/`Map`/class leaves;
+- `depth` behavior;
+- callback error isolation.
+
+## Not implemented here
+
+These are intentionally not part of the finished local core:
+
+- per-key delta streams;
+- string paths;
+- `computed`/derived graph primitives;
+- dependency tracking by reads;
+- automatic network mirror over RPC.
+
+`listenUpdate(node)` already stacks with `createRpcServerAuto` as a notification
+stream. The larger mirror extension remains separate: subscribe to a subtree,
+send whole snapshots on settle/throttle, and atomically replace the mirror branch
+on the client.

package/observe/README.md

@@ -0,0 +1,226 @@
+# observe
+
+Minimal reactive object core for coarse, consistent invalidation.
+
+The idea is simple: subscribe to the fact that a reactive subtree changed, then
+re-read the current state. There are no deltas, no string paths, no old/new
+values, and no computed graph in the core.
+
+## API
+
+```ts
+import {reactive, onUpdate, flushReactive, listenUpdate} from './reactive'
+```
+
+### `reactive(obj, opts?)`
+
+Wraps a plain object/array tree.
+
+```ts
+const state = reactive({
+    balances: {BTC: 100, ETH: 400},
+    price: 0,
+})
+```
+
+You read and write normally:
+
+```ts
+state.price = 101
+state.balances.BTC = 120
+state.balances = {SOL: 250, DOT: 150, ADA: 100}
+```
+
+### `onUpdate(node, cb)`
+
+Subscribes to a node. The callback receives no arguments. It means only:
+
+> Something under this node changed; the batch is settled; read the state now.
+
+```ts
+const off = onUpdate(state.balances, () => {
+    const total = Object.values(state.balances).reduce((a, b) => a + b, 0)
+    console.log(total)
+})
+
+off()
+```
+
+### `flushReactive(node)`
+
+Returns a promise that resolves after queued updates for this reactive tree
+settle. Use it in tests, demos, and scripts instead of guessing event-loop order.
+
+```ts
+state.balances.BTC = 200
+await flushReactive(state.balances)
+```
+
+### `listenUpdate(node)`
+
+Adapts an Observe node to the project's existing `Listen` shape. This is the
+bridge for RPC: `createRpcServerAuto` already knows how to expose `Listen`
+objects as remote subscriptions.
+
+```ts
+const facade = {
+    getBalances: () => state.balances,
+    balancesChanged: listenUpdate(state.balances),
+}
+```
+
+## Full Example
+
+```ts
+import {reactive, onUpdate, flushReactive} from './reactive'
+
+const sum = (o: Record<string, number>) =>
+    Object.values(o).reduce((a, b) => a + b, 0)
+
+async function main() {
+    const account = reactive({
+        balances: {BTC: 100, ETH: 400},
+        positions: {
+            BTC: {qty: 0.5},
+        },
+    })
+
+    let balanceRecalc = 0
+    let positionSync = 0
+
+    const offBalances = onUpdate(account.balances, () => {
+        balanceRecalc++
+        console.log('balances total:', sum(account.balances))
+    })
+
+    const offPositions = onUpdate(account.positions, () => {
+        positionSync++
+        console.log('positions changed:', Object.keys(account.positions))
+    })
+
+    // Several synchronous mutations become one callback.
+    account.balances.BTC = 120
+    account.balances.ETH = 380
+    account.balances.SOL = 0
+    await flushReactive(account.balances)
+
+    console.log('balance recalculations:', balanceRecalc) // 1
+
+    // Whole-subtree replacement is the important case:
+    // the old account.balances proxy keeps working as a subscription target.
+    account.balances = {SOL: 250, DOT: 150, ADA: 100}
+    await flushReactive(account.balances)
+
+    console.log('new total:', sum(account.balances))       // 500
+    console.log('balance recalculations:', balanceRecalc) // 2
+
+    // Deep writes under an already-read branch are reactive.
+    account.positions.BTC.qty = 0.7
+    account.positions.ETH = {qty: 3}
+    await flushReactive(account.positions)
+
+    console.log('position syncs:', positionSync) // 1
+
+    offBalances()
+    offPositions()
+}
+
+main()
+```
+
+## Options
+
+```ts
+type Opts = {
+    drain?: 'immediate' | 'micro' | number | ((flush: () => void) => void)
+    depth?: number
+    eager?: boolean
+}
+```
+
+Defaults:
+
+```ts
+reactive(obj, {
+    drain: 'immediate',
+    depth: Infinity,
+    eager: false,
+})
+```
+
+Drain modes:
+
+- `'immediate'`: `setImmediate` when available, otherwise `setTimeout(0)`.
+- `'micro'`: `queueMicrotask`.
+- `number`: `setTimeout(number)`, useful as a throttle.
+- custom function: bring your own scheduler.
+
+Example throttle:
+
+```ts
+const md = reactive({price: 0}, {drain: 50})
+let heavyRecalc = 0
+
+onUpdate(md, () => {
+    heavyRecalc++
+})
+
+for (let i = 0; i < 1000; i++) md.price = i
+await flushReactive(md)
+
+console.log(heavyRecalc) // 1
+```
+
+## Current Contract
+
+- Root is always a proxy.
+- Child proxies are created lazily on read.
+- With zero subscribers, writes do not schedule drains.
+- Plain objects and arrays are reactive.
+- `Date`, `Map`, `Set`, and class instances are opaque leaves.
+- Callback errors do not stop sibling subscribers; the first error is re-thrown asynchronously.
+- A callback that mutates state queues a follow-up drain instead of recursing.
+
+## What Was Finished
+
+- Local in-process core: `reactive`, `onUpdate`, `flushReactive`.
+- RPC bridge: `listenUpdate(node)` returns a `Listen` object.
+- Coalesced settled updates.
+- Whole-subtree replacement.
+- Depth/eager/drain options.
+- Edge-case oracle in `reactive.test.ts`.
+- Usage scenarios in `usage.ts`.
+
+## What Is Not Part Of This Core
+
+- Per-key delta streams.
+- String-path subscriptions.
+- `computed` or dependency tracking.
+- Automatic RPC snapshot/mirror layer.
+
+Those live in the layers built ON TOP of this core, not inside it.
+
+## Where This Went
+
+The sandbox has been assembled: the canonical core is
+`src/Common/Observe/reactive.ts`, exported from the package as `Observe`.
+Layers on top of it (documented in `wenay-common2.md` / `wenay-common2-rare.md`):
+
+- **Store** — `createStore` wraps the core with typed path nodes (`state` / `node` /
+  `update(mask)`), `src/Common/Observe/store.ts`.
+- **Mirror sync** — `exposeStore` ⇄ `createStoreMirror`: snapshots + changed
+  notifications over RPC, optional push channels (`patches` / `changedData`).
+- **Sequenced replay line** — the store's patch stream numbered by seq: keyframe
+  catch-up, reconnect by seq, per-client conflation, archived history with
+  time-travel. Exported as `Replay` (generic line) and via `Observe`
+  (`exposeStoreReplay` / `syncStoreReplay` / `storeReplayAt`); oracles in `replay/`,
+  status in `replay/PLAN.md`.
+
+## Run
+
+```bash
+npx tsx observe/reactive.test.ts
+npx tsx observe/store.test.ts
+npx tsx observe/usage.ts
+npx tsx observe/usage-real-socket.ts
+```

package/observe/hot-write.test.ts

@@ -0,0 +1,95 @@
+// ============================================================
+//  observe/hot-write.test.ts
+//
+//  Hot-write масштабирование reactive: тикающая карта котировок
+//  (state[symbol] = quote, тысячи разных ключей за drain-окно) при
+//  подключённом changedPaths-потребителе (pathLive > 0).
+//  Оракул: дедуп dirty-путей keyed-структурой (не линейным сканом) →
+//  окно из 4x ключей стоит ~4x времени, НЕ ~16x. Плюс корректность:
+//  дедуп в окне, symbol-идентичность ключей, отсутствие склейки
+//  строковых сегментов.
+//  Запуск:
+//      npx ts-node observe/hot-write.test.ts
+// ============================================================
+
+import {reactive, onUpdatePaths, flushReactive} from '../src/Common/Observe/reactive'
+
+let fails = 0
+const ok = (condition: any, message: string) => {
+    if (!condition) { fails++; console.log('  FAIL', message) }
+    else console.log('  OK  ', message)
+}
+
+async function benchWindow(n: number, rounds: number) {
+    const state = reactive<any>({quotes: {}}, {drain: 'micro'})
+    for (let i = 0; i < n; i++) state.quotes['s' + i] = 0    // ключи заранее: меряем чистые записи
+    const off = onUpdatePaths(state, () => {})
+    await flushReactive(state)
+    let best = Infinity
+    for (let r = 1; r <= rounds; r++) {
+        const t0 = process.hrtime.bigint()
+        for (let i = 0; i < n; i++) state.quotes['s' + i] = r * n + i
+        await flushReactive(state)
+        best = Math.min(best, Number(process.hrtime.bigint() - t0) / 1e6)
+    }
+    off()
+    return best
+}
+
+async function main() {
+    console.log('\n[hot-write] changedPaths correctness under a hot window')
+    {
+        const state = reactive<any>({quotes: {}}, {drain: 'micro'})
+        const windows: PropertyKey[][][] = []
+        const off = onUpdatePaths(state, ch => windows.push(ch.paths))
+        for (let i = 0; i < 5; i++) state.quotes['s' + i] = i
+        for (let i = 0; i < 5; i++) state.quotes['s' + i] = i + 100   // повторное касание тех же ключей
+        await flushReactive(state)
+        ok(windows.length == 1, 'one settled batch')
+        ok(windows[0].length == 5, `same key touched twice dedups to one path (got ${windows[0].length})`)
+        ok(windows[0].every(p => p.length == 2 && p[0] == 'quotes'), 'paths are root-relative [quotes, key]')
+        off()
+    }
+
+    console.log('\n[hot-write] symbol keys stay identity-safe in the dedup')
+    {
+        const s1 = Symbol('k'), s2 = Symbol('k')                      // одинаковое описание, разная идентичность
+        const state = reactive<any>({}, {drain: 'micro'})
+        const windows: PropertyKey[][][] = []
+        const off = onUpdatePaths(state, ch => windows.push(ch.paths))
+        state[s1] = 1
+        state[s2] = 2
+        state[s1] = 3                                                 // повтор первого символа
+        await flushReactive(state)
+        ok(windows[0].length == 2, `two same-description symbols = two paths, repeat dedups (got ${windows[0].length})`)
+        off()
+    }
+
+    console.log('\n[hot-write] string segments cannot glue across boundaries')
+    {
+        const state = reactive<any>({'a': {'b|c': 0}, 'a|b': {'c': 0}}, {drain: 'micro'})
+        const windows: PropertyKey[][][] = []
+        const off = onUpdatePaths(state, ch => windows.push(ch.paths))
+        state['a']['b|c'] = 1
+        state['a|b']['c'] = 2
+        await flushReactive(state)
+        ok(windows[0].length == 2, `[a][b|c] and [a|b][c] are distinct paths (got ${windows[0].length})`)
+        off()
+    }
+
+    console.log('\n[hot-write] near-linear scaling with a changedPaths subscriber')
+    {
+        await benchWindow(200, 2)                                     // прогрев (JIT)
+        const n = 500, m = 2000, rounds = 5
+        const tN = await benchWindow(n, rounds)
+        const tM = await benchWindow(m, rounds)
+        const ratio = tM / tN
+        console.log(`  [bench] ${n} keys/window: ${tN.toFixed(2)}ms · ${m} keys/window: ${tM.toFixed(2)}ms · ratio ${ratio.toFixed(1)}x`)
+        ok(ratio < 10, `4x keys cost ~4x, not ~16x (ratio ${ratio.toFixed(1)}x < 10x)`)
+    }
+
+    console.log(fails ? `\n${fails} FAILED` : '\nall passed')
+    if (fails) process.exit(1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })