@cero-base/tools 0.8.4

package/README.md

@@ -0,0 +1,79 @@
+# @cero-base/tools
+
+Passive devtools for [cero](https://www.npmjs.com/package/@cero-base/cero) — observe a running instance's **data**, its **event log**, and its **p2p/replication stats** from another process, without ever touching the swarm it measures.
+
+A `cero.use(devtools())` extension taps the instance over a **local out-of-band pipe** (never the app's hyperswarm), so connection counts, core lengths, and replication numbers stay exactly as they'd be with no devtools attached. Read-only by construction; identity secrets are structurally unreachable.
+
+## Install
+
+```sh
+npm install @cero-base/tools
+```
+
+## Agent side — attach the tap
+
+```js
+import { cero } from '@cero-base/cero'
+import { devtools, loopback } from '@cero-base/tools'
+
+cero.use(devtools({ transport: loopback({ port: 9111 }) }))
+// ...then create your instance as usual; the tap follows it and every child handle.
+```
+
+`devtools(opts)`:
+
+| opt              | default | meaning                                                                             |
+| ---------------- | ------- | ----------------------------------------------------------------------------------- |
+| `transport`      | —       | a `{ accept(handler) }` source of consumer connections (use `loopback({ port })`)   |
+| `bufferSize`     | `1000`  | event ring buffer size (drop-oldest)                                                |
+| `sampleInterval` | `1000`  | stats sampling interval (ms)                                                        |
+| `redact`         | —       | a `(ref, row) => row` masker, or a config `{ fields, match, deny }` (see Redaction) |
+
+Zero footprint when not registered; all cleanup is bound to the root handle's `close`.
+
+## Consumer side — connect
+
+```js
+import { connect, dial } from '@cero-base/tools'
+
+const session = await connect(dial({ port: 9111 }))
+
+await session.handles() // [{ id, type }, ...] — root + open children
+await session.get('messages') // { data, total, size } — reuses cero's read operators
+await session.count('members') // number
+session.watch('messages') // Readable of live snapshots
+session.events() // Readable of { op, name, row, writerKey, seq } — local AND remote
+session.stats() // Readable of { network, bee, cores }
+session.close()
+```
+
+## CLI
+
+```sh
+cero-tools <port> [refs...]
+# prints the handle tree + state for each ref, then tails events + stats until Ctrl-C
+```
+
+## Redaction
+
+App rows can hold anything, so `devtools({ redact })` masks matched fields in both snapshots and events — content hidden, shape kept (`‹redacted:bytes(32)›`):
+
+```js
+devtools({ redact: {} }) // default denylist: seed/secret/token/private/...
+devtools({ redact: { fields: ['profile.apiKey'] } })
+devtools({ redact: { match: (key) => key.endsWith('Secret') } })
+```
+
+Identity credentials (the seed and keypairs) need no redaction: they're `local` builtins and the inspection surface only serves declared `meta.refs`, so they're never reachable.
+
+## API
+
+`devtools(opts)` · `serve(stream, me, opts)` · `connect(stream)` · `stats(handle)` · `redact(config)` · `loopback(opts)` · `dial(opts)`
+
+## Status
+
+MVP: local-pipe transport, `get`/`watch`/`count` + events + sampled stats, redaction, a CLI. Deferred to later phases: a whitelisted swarm transport, a read-only replication / time-travel plane, and an MCP/UI consumer.
+
+## License
+
+Apache-2.0

package/bin/cero-tools.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { dial } from '../src/transport.js'
+import { connect } from '../src/connect.js'
+import { formatHandles, formatState, formatEvent, formatStats } from '../src/format.js'
+
+const arg = process.argv[2]
+if (!arg) {
+  console.log('usage: cero-tools [host:]<port> [refs...]')
+  process.exit(1)
+}
+
+const [hostPart, portPart] = arg.includes(':') ? arg.split(':') : [undefined, arg]
+const host = hostPart
+const port = Number(portPart)
+
+const socket = dial({ host, port })
+const session = await connect(socket)
+
+console.log(formatHandles(await session.handles()))
+
+for (const ref of process.argv.slice(3)) {
+  console.log(formatState(ref, await session.get(ref)))
+}
+
+const events = session.events()
+const live = session.stats()
+events.on('data', (e) => console.log(formatEvent(e)))
+live.on('data', (s) => console.log(formatStats(s)))
+
+process.on('SIGINT', () => {
+  session.close()
+  process.exit(0)
+})

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@cero-base/tools",
+  "version": "0.8.4",
+  "description": "Passive devtools for cero — observe data, events, and p2p/replication stats over a local out-of-band pipe.",
+  "type": "module",
+  "main": "./src/index.js",
+  "bin": {
+    "cero-tools": "./bin/cero-tools.js"
+  },
+  "imports": {
+    "net": {
+      "bare": "bare-net",
+      "default": "net"
+    }
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./connect": "./src/connect.js",
+    "./stats": "./src/stats.js"
+  },
+  "scripts": {
+    "test": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
+  },
+  "dependencies": {
+    "@cero-base/cero": "^0.8.4",
+    "@cero-base/core": "^0.8.4",
+    "b4a": "^1.8.1",
+    "bare-net": "^2.3.1",
+    "compact-encoding": "^3.1.0",
+    "streamx": "^2.22.0"
+  },
+  "devDependencies": {
+    "@hyperswarm/testnet": "^3.1.4",
+    "brittle": "^4.0.0",
+    "typescript": "^5.7.0"
+  },
+  "license": "Apache-2.0"
+}

package/src/connect.js

@@ -0,0 +1,106 @@
+import { Readable } from 'streamx'
+
+import { Framed } from './protocol.js'
+
+/**
+ * Consumer SDK for a tap server reached over a local Duplex `stream`. Returns
+ * a session exposing read methods (`handles`/`get`/`count`) and stream methods
+ * (`watch`/`events`/`stats`). Stream methods return a streamx Readable that
+ * cancels its server-side source when destroyed.
+ *
+ * @param {any} stream  A streamx Duplex connected to a tap server.
+ * @returns {Promise<{ handles(): Promise<any>, get(ref: string, query?: any, handleId?: string): Promise<any>, count(ref: string, query?: any, handleId?: string): Promise<any>, watch(ref: string, query?: any, handleId?: string): import('streamx').Readable, events(): import('streamx').Readable, stats(): import('streamx').Readable, close(): void }>}
+ */
+export async function connect(stream) {
+  return new Session(stream)
+}
+
+export class Session {
+  constructor(stream) {
+    this.stream = stream
+    this.pending = new Map()
+    this.streams = new Map()
+    this.seq = 0
+    this.wire = new Framed(stream, (msg) => this._onMessage(msg))
+  }
+
+  _onMessage(msg) {
+    if ('frame' in msg || msg.end) {
+      const r = this.streams.get(msg.id)
+      if (!r) return
+      if (msg.end) {
+        this.streams.delete(msg.id)
+        r.push(null)
+      } else {
+        r.push(msg.frame)
+      }
+      return
+    }
+    const p = this.pending.get(msg.id)
+    if (!p) return
+    this.pending.delete(msg.id)
+    if (msg.ok === false) p.reject(new TapError(msg.error, msg.code))
+    else p.resolve(msg.data)
+  }
+
+  _newId() {
+    return ++this.seq
+  }
+
+  _request(method, fields) {
+    return new Promise((resolve, reject) => {
+      const id = this._newId()
+      this.pending.set(id, { resolve, reject })
+      this.wire.send({ id, method, ...fields })
+    })
+  }
+
+  _stream(method, fields) {
+    const id = this._newId()
+    const r = new Readable({
+      destroy: (cb) => {
+        if (this.streams.delete(id))
+          this.wire.send({ id: this._newId(), method: 'cancel', cancelId: id })
+        cb(null)
+      }
+    })
+    this.streams.set(id, r)
+    this.wire.send({ id, method, ...fields })
+    return r
+  }
+
+  handles() {
+    return this._request('handles', {})
+  }
+
+  get(ref, query, handleId) {
+    return this._request('get', { ref, query, handleId })
+  }
+
+  count(ref, query, handleId) {
+    return this._request('count', { ref, query, handleId })
+  }
+
+  watch(ref, query, handleId) {
+    return this._stream('watch', { ref, query, handleId })
+  }
+
+  events() {
+    return this._stream('events', {})
+  }
+
+  stats() {
+    return this._stream('stats', {})
+  }
+
+  close() {
+    this.stream.end()
+  }
+}
+
+class TapError extends Error {
+  constructor(message, code) {
+    super(message)
+    this.code = code
+  }
+}

package/src/format.js

@@ -0,0 +1,71 @@
+import b4a from 'b4a'
+
+const ROW_MAX = 80
+
+function shortRow(row) {
+  if (row == null) return ''
+  const s = JSON.stringify(row)
+  return s.length > ROW_MAX ? s.slice(0, ROW_MAX - 1) + '…' : s
+}
+
+function shortKey(key) {
+  if (key == null) return ''
+  if (b4a.isBuffer(key) || key instanceof Uint8Array) return b4a.toString(key, 'hex').slice(0, 8)
+  return String(key).slice(0, 8)
+}
+
+/**
+ * Render a handle tree (`[{ id, type }]`) as a short list.
+ *
+ * @param {Array<{ id: string, type: string | null }>} tree
+ * @returns {string}
+ */
+export function formatHandles(tree) {
+  if (!tree || !tree.length) return 'handles: (none)'
+  const lines = tree.map((h) => `  ${h.type || 'root'} ${h.id}`)
+  return `handles (${tree.length}):\n${lines.join('\n')}`
+}
+
+/**
+ * Render a `get()` reply — `{ data, total, size }` for collections or
+ * `{ data }` for single refs — as a compact summary.
+ *
+ * @param {string} ref
+ * @param {{ data: any, total?: number, size?: number }} result
+ * @returns {string}
+ */
+export function formatState(ref, result) {
+  const data = result?.data
+  if (Array.isArray(data)) {
+    const total = result.total ?? data.length
+    const head = data.slice(0, 3).map(shortRow)
+    return `${ref} (${total}):\n${head.map((r) => '  ' + r).join('\n')}`
+  }
+  return `${ref}: ${shortRow(data)}`
+}
+
+/**
+ * Render one applied-op event as a single line.
+ *
+ * @param {{ op: string, name: string, row: any, writerKey?: any, seq?: number }} e
+ * @returns {string}
+ */
+export function formatEvent(e) {
+  const writer = shortKey(e.writerKey)
+  const tail = writer ? ` (${writer})` : ''
+  return `#${e.seq ?? '?'} ${e.op} ${e.name} ${shortRow(e.row)}${tail}`
+}
+
+/**
+ * Render a stats snapshot as a single line.
+ *
+ * @param {{ network?: { connections: number, peers: number }, bee?: { local: number }, cores?: any[] }} s
+ * @returns {string}
+ */
+export function formatStats(s) {
+  const conns = s?.network?.connections ?? 0
+  const peers = s?.network?.peers ?? 0
+  const local = s?.bee?.local ?? 0
+  const cores = s?.cores?.length ?? 0
+  return `net ${conns}c/${peers}p · bee ${local} · cores ${cores}`
+}

package/src/index.js

@@ -0,0 +1,6 @@
+export { stats } from './stats.js'
+export { redact } from './redact.js'
+export { devtools } from './tap.js'
+export { serve } from './server.js'
+export { connect } from './connect.js'
+export { loopback, dial } from './transport.js'

package/src/protocol.js

@@ -0,0 +1,62 @@
+import b4a from 'b4a'
+
+const BYTES = '$b'
+
+function toWire(v) {
+  if (b4a.isBuffer(v) || v instanceof Uint8Array) return { [BYTES]: b4a.toString(v, 'hex') }
+  if (Array.isArray(v)) return v.map(toWire)
+  if (v && typeof v === 'object') {
+    const o = {}
+    for (const k of Object.keys(v)) o[k] = toWire(v[k])
+    return o
+  }
+  return v
+}
+
+function fromWire(v) {
+  if (Array.isArray(v)) return v.map(fromWire)
+  if (v && typeof v === 'object') {
+    if (typeof v[BYTES] === 'string') return b4a.from(v[BYTES], 'hex')
+    const o = {}
+    for (const k of Object.keys(v)) o[k] = fromWire(v[k])
+    return o
+  }
+  return v
+}
+
+/**
+ * Length-prefixed JSON framing over a Duplex `stream`. Buffers incoming chunks
+ * and delivers each decoded frame to `onMessage`; `send` writes a framed frame.
+ */
+export class Framed {
+  constructor(stream, onMessage) {
+    this.stream = stream
+    this.onMessage = onMessage
+    this.buf = b4a.alloc(0)
+    stream.on('data', (chunk) => this._onData(chunk))
+  }
+
+  _onData(chunk) {
+    this.buf = b4a.concat([this.buf, chunk])
+    while (this.buf.length >= 4) {
+      const len = new DataView(this.buf.buffer, this.buf.byteOffset, 4).getUint32(0, true)
+      if (this.buf.length < 4 + len) break
+      const body = b4a.toString(this.buf.subarray(4, 4 + len))
+      this.buf = this.buf.subarray(4 + len)
+      let msg
+      try {
+        msg = fromWire(JSON.parse(body))
+      } catch {
+        continue
+      }
+      this.onMessage(msg)
+    }
+  }
+
+  send(obj) {
+    const body = b4a.from(JSON.stringify(toWire(obj)))
+    const head = b4a.alloc(4)
+    new DataView(head.buffer, head.byteOffset, 4).setUint32(0, body.length, true)
+    this.stream.write(b4a.concat([head, body]))
+  }
+}

package/src/redact.js

@@ -0,0 +1,44 @@
+import b4a from 'b4a'
+
+// Obvious secret-ish field names, masked by default once redaction is enabled.
+const DEFAULT_DENY = /^(seed|secret|secretkey|password|passphrase|token|private|privatekey)$/i
+
+/**
+ * Build a row masker for devtools. A field is masked when its dotted path is in
+ * `fields`, its name matches `deny` (default denylist above), or `match(key,
+ * value, path)` returns true. Masked values become a typed placeholder —
+ * `‹redacted:bytes(32)›` / `‹redacted:string›` — so the shape stays visible but
+ * the content is hidden. Everything else passes through untouched.
+ *
+ * @param {{ fields?: string[], deny?: RegExp | false, match?: (key: string, value: any, path: string) => boolean }} [config]
+ * @returns {(ref: string, row: any) => any}
+ */
+export function redact(config = {}) {
+  const fields = new Set(config.fields || [])
+  const deny = config.deny === false ? null : config.deny || DEFAULT_DENY
+  const match = typeof config.match === 'function' ? config.match : null
+
+  const isBytes = (v) => b4a.isBuffer(v) || v instanceof Uint8Array
+  const mask = (v) =>
+    isBytes(v) ? `‹redacted:bytes(${v.length})›` : `‹redacted:${v === null ? 'null' : typeof v}›`
+
+  const walk = (value, path) => {
+    if (isBytes(value)) return value
+    if (Array.isArray(value)) return value.map((v) => walk(v, path))
+    if (value && typeof value === 'object') {
+      const out = {}
+      for (const k of Object.keys(value)) {
+        const p = path ? `${path}.${k}` : k
+        const v = value[k]
+        out[k] =
+          fields.has(p) || (deny && deny.test(k)) || (match && match(k, v, p))
+            ? mask(v)
+            : walk(v, p)
+      }
+      return out
+    }
+    return value
+  }
+
+  return (ref, row) => (row && typeof row === 'object' && !isBytes(row) ? walk(row, '') : row)
+}

package/src/server.js

@@ -0,0 +1,153 @@
+import { get, count, watch } from '@cero-base/cero'
+
+import { Framed } from './protocol.js'
+
+/**
+ * Read-only inspection server over a local Duplex `stream`. Serves the live
+ * handle tree rooted at `me`, exposing only MAIN refs declared in each
+ * handle's `spec.meta.refs` — local secret refs (master/keypair/
+ * handle-keypairs) are never reachable, since they live in `meta.local.refs`.
+ *
+ * @param {any} stream  A streamx Duplex carrying length-prefixed JSON frames.
+ * @param {any} me  The live root cero handle.
+ * @param {{ events?: { snapshot(): any, subscribe(fn: (e: any) => void): () => void }, stats?: { snapshot(): any, subscribe(fn: (s: any) => void): () => void }, redact?: (ref: string, row: any) => any }} [opts]
+ * @returns {{ close(): void }}
+ */
+export function serve(stream, me, opts) {
+  return new TapServer(stream, me, opts)
+}
+
+export class TapServer {
+  constructor(stream, me, opts = {}) {
+    this.stream = stream
+    this.me = me
+    this.redact = opts.redact || ((ref, row) => row)
+    this.opts = opts
+    this.tracked = new Map()
+    this.wire = new Framed(stream, (req) => this.onRequest(req))
+    this._cleanup = () => this._teardown()
+    stream.on('close', this._cleanup)
+  }
+
+  async onRequest(req) {
+    const handler = this[req.method]
+    if (!handler || !METHODS.has(req.method)) {
+      this._send({
+        id: req.id,
+        ok: false,
+        error: `unknown method '${req.method}'`,
+        code: 'UNKNOWN'
+      })
+      return
+    }
+    try {
+      await handler.call(this, req)
+    } catch (err) {
+      this._send({ id: req.id, ok: false, error: String(err.message || err), code: err.code })
+    }
+  }
+
+  handles(req) {
+    const me = this.me
+    const data = [
+      { id: me.id, type: 'root' },
+      ...[...(me.children || [])].map((c) => ({ id: c.id, type: c.type || null }))
+    ]
+    this._send({ id: req.id, ok: true, data })
+  }
+
+  async get(req) {
+    const ref = this._resolveRef(req)
+    const r = await get(ref, req.query)
+    const data = Array.isArray(r.data)
+      ? r.data.map((row) => this.redact(req.ref, row))
+      : r.data && this.redact(req.ref, r.data)
+    this._send({ id: req.id, ok: true, data: { ...r, data } })
+  }
+
+  async count(req) {
+    const ref = this._resolveRef(req)
+    this._send({ id: req.id, ok: true, data: (await count(ref, req.query)).data })
+  }
+
+  watch(req) {
+    const ref = this._resolveRef(req)
+    const s = watch(ref, req.query)
+    this._track(req.id, () => s.destroy())
+    s.on('data', (d) => {
+      const data = Array.isArray(d.data) ? d.data.map((row) => this.redact(req.ref, row)) : d.data
+      this._send({ id: req.id, frame: { ...d, data } })
+    })
+    s.on('end', () => this._send({ id: req.id, end: true }))
+  }
+
+  events(req) {
+    this._source(req, this.opts.events)
+  }
+
+  stats(req) {
+    this._source(req, this.opts.stats)
+  }
+
+  cancel(req) {
+    this._drop(req.cancelId)
+  }
+
+  _resolveRef(req) {
+    const me = this.me
+    const handle =
+      req.handleId === me.id || !req.handleId
+        ? me
+        : [...(me.children || [])].find((c) => c.id === req.handleId)
+    const info = handle?.spec?.meta?.refs?.[req.ref]
+    if (!handle || !info) throw new CodeError('UNKNOWN', `unknown ref '${req.ref}'`)
+    return handle[req.ref]
+  }
+
+  _source(req, src) {
+    if (!src) {
+      this._send({ id: req.id, end: true })
+      return
+    }
+    const snap = src.snapshot()
+    const items = Array.isArray(snap) ? snap : snap == null ? [] : [snap]
+    for (const item of items) this._send({ id: req.id, frame: item })
+    const off = src.subscribe((e) => this._send({ id: req.id, frame: e }))
+    this._track(req.id, off)
+  }
+
+  _track(id, off) {
+    this.tracked.set(id, off)
+  }
+
+  _drop(id) {
+    const off = this.tracked.get(id)
+    if (off) {
+      this.tracked.delete(id)
+      off()
+    }
+  }
+
+  _send(obj) {
+    this.wire.send(obj)
+  }
+
+  _teardown() {
+    for (const off of this.tracked.values()) off()
+    this.tracked.clear()
+  }
+
+  close() {
+    this._teardown()
+    this.stream.destroy()
+  }
+}
+
+const METHODS = new Set(['handles', 'get', 'count', 'watch', 'events', 'stats', 'cancel'])
+
+class CodeError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.code = code
+  }
+}

package/src/stats.js

@@ -0,0 +1,45 @@
+/**
+ * Read-only snapshot of a handle's existing p2p/storage counters. Pure: no
+ * listeners, no mutation, never reads a secret. `dht.stats` and the corestore
+ * `cores` map are undocumented internals, so they are guarded — a fresh handle
+ * (pre-ready) yields zeros rather than throwing.
+ *
+ * @param {any} handle  A cero root or child handle.
+ * @param {number} [at]  Sample timestamp, stamped by the caller.
+ * @returns {{ handleId: string, network: { connections: number, peers: number, dht: any }, bee: { local: number }, cores: Array<{ length: number, byteLength: number, peers: number }>, at: number }}
+ */
+export function stats(handle, at = 0) {
+  const net = handle.network
+  const bee = handle.store?.bee
+
+  const cores = []
+  try {
+    const map = handle.store?.store?.cores
+    if (map) {
+      for (const core of map.values()) {
+        cores.push({
+          length: core.length ?? 0,
+          byteLength: core.byteLength ?? 0,
+          peers: core.peers?.length ?? 0
+        })
+      }
+    }
+  } catch {}
+
+  let dht = null
+  try {
+    dht = net?.swarm?.dht?.stats ?? null
+  } catch {}
+
+  return {
+    handleId: handle.id,
+    network: {
+      connections: net?.connections?.size ?? 0,
+      peers: net?.peers?.size ?? 0,
+      dht
+    },
+    bee: { local: bee?.local?.length ?? 0 },
+    cores,
+    at
+  }
+}

package/src/tap.js

@@ -0,0 +1,105 @@
+import { stats } from './stats.js'
+import { serve } from './server.js'
+import { redact } from './redact.js'
+
+/**
+ * `cero.use(devtools())` tap extension. Bound to the root handle's lifecycle,
+ * it feeds every applied op into a bounded ring buffer, samples `stats(me)` on
+ * an interval, and — if given a `transport` — serves a read-only inspection
+ * surface to out-of-band consumers. Nothing here touches the app swarm.
+ *
+ * @param {{ bufferSize?: number, sampleInterval?: number, redact?: ((ref: string, row: any) => any) | { fields?: string[], match?: Function, deny?: RegExp | false }, transport?: { accept(handler: (stream: any) => void): void } }} [opts]
+ * @returns {{ setup(me: any): () => void }}
+ */
+export function devtools(opts = {}) {
+  return {
+    setup(me) {
+      const events = new Ring(opts.bufferSize ?? 1000)
+      const sampler = new Sampler(me, opts.sampleInterval ?? 1000)
+      const redactor = makeRedactor(opts.redact)
+      const offs = []
+      const servers = new Set()
+
+      const follow = (handle) => {
+        const off = handle.store.onApply((e) =>
+          events.push(redactor ? { ...e, row: redactor(e.name, e.row) } : e)
+        )
+        offs.push(off)
+        if (handle !== me) handle.once('close', off)
+      }
+
+      follow(me)
+      for (const child of me.children) follow(child)
+      me.on('handle', (child) => follow(child), { signal: me.signal })
+
+      if (opts.transport) {
+        opts.transport.accept((stream) => {
+          const server = serve(stream, me, { events, stats: sampler, redact: redactor })
+          servers.add(server)
+          stream.on('close', () => servers.delete(server))
+        })
+      }
+
+      return () => {
+        sampler.stop()
+        for (const off of offs) off()
+        for (const server of servers) server.close()
+        servers.clear()
+      }
+    }
+  }
+}
+
+function makeRedactor(opt) {
+  if (!opt) return null
+  return typeof opt === 'function' ? opt : redact(opt)
+}
+
+/** Bounded ring buffer with snapshot + live subscription. */
+class Ring {
+  constructor(max) {
+    this.max = max
+    this.items = []
+    this.subs = new Set()
+  }
+
+  push(e) {
+    this.items.push(e)
+    if (this.items.length > this.max) this.items.shift()
+    for (const fn of this.subs) fn(e)
+  }
+
+  snapshot() {
+    return this.items.slice()
+  }
+
+  subscribe(fn) {
+    this.subs.add(fn)
+    return () => this.subs.delete(fn)
+  }
+}
+
+/** Periodic `stats(me)` sampler with snapshot + live subscription. */
+class Sampler {
+  constructor(me, interval) {
+    this.subs = new Set()
+    this.latest = stats(me, Date.now())
+    this.timer = setInterval(() => {
+      this.latest = stats(me, Date.now())
+      for (const fn of this.subs) fn(this.latest)
+    }, interval)
+  }
+
+  snapshot() {
+    return this.latest
+  }
+
+  subscribe(fn) {
+    this.subs.add(fn)
+    return () => this.subs.delete(fn)
+  }
+
+  stop() {
+    clearInterval(this.timer)
+  }
+}

package/src/transport.js

@@ -0,0 +1,45 @@
+import net from 'net'
+
+/**
+ * Loopback TCP transport implementing the tap `{ accept(handler) }` contract
+ * plus lifecycle. Each inbound connection's socket is a streamx-compatible
+ * Duplex, ready to pass straight to `serve()`.
+ *
+ * @param {{ port?: number, host?: string }} [opts]
+ * @returns {{ accept(handler: (socket: any) => void): void, ready(): Promise<{ port: number }>, port: number | null, close(): void }}
+ */
+export function loopback(opts = {}) {
+  const host = opts.host ?? '127.0.0.1'
+  let server = null
+  return {
+    accept(handler) {
+      server = net.createServer((socket) => handler(socket))
+      server.listen(opts.port ?? 0, host)
+    },
+    ready() {
+      return new Promise((resolve, reject) => {
+        if (!server) return reject(new Error('accept() not called'))
+        if (server.listening) return resolve({ port: server.address().port })
+        server.once('listening', () => resolve({ port: server.address().port }))
+        server.once('error', reject)
+      })
+    },
+    get port() {
+      return server?.listening ? server.address().port : null
+    },
+    close() {
+      server?.close()
+    }
+  }
+}
+
+/**
+ * Dial a loopback tap server and return the connected socket, ready for
+ * `connect()`.
+ *
+ * @param {{ port: number, host?: string }} [opts]
+ * @returns {any} A streamx-compatible Duplex socket.
+ */
+export function dial(opts = {}) {
+  return net.connect(opts.port, opts.host ?? '127.0.0.1')
+}