@qvac/harness 0.2.8 → 0.2.9

package/.claude/skills/js-house-style/SKILL.md

@@ -1,671 +0,0 @@
----
-name: js-house-style
-description: House style for writing, structuring, reviewing, or refactoring JavaScript — for Bare, Node, or both. Use for essentially any authoring or review task in a JS package: writing a module, refactoring, code review, judging structure and layering, making something composable, weighing a dependency, or adding tests. Also governs comments, whitespace, and PR shape everywhere in the repo. Encodes how we build — small single-responsibility modules composed on primitives, do-more-with-less, no defensive programming — and the judgment behind it.
-version: 1.1.0
----
-
-# JS house style
-
-How we write JavaScript — for Bare, for Node, for both. Small modules. One thing each. Do more with less. Compose tiny pieces through a few shared conventions so that many small modules behave like one coherent system.
-
-The most important rule comes first because it governs all the others:
-
-**Don't follow rules without thinking. Make the best code you can, always.**
-
-Everything below is a default with a reason attached. Defaults exist so you don't re-derive them every time, and so a codebase reads consistently. But a default you can't justify in the moment is a default you should question. Important things are made well and thoughtfully — the judgment about _when a rule earns its place_ is the actual skill. The rest is scaffolding for that judgment.
-
-If you internalize five things:
-
-1. **One module, one responsibility — perfect at one thing, composed with the rest.** If you can't describe it in one sentence without "and", it's two modules. Build on the layer below rather than reimplementing it (compact-encoding → hyperschema → hrpc; hypercore → hyperbee → hyperdb → autobee). Build the smallest piece that validates the rest first.
-2. **Make construction cheap; do real work lazily; tear down explicitly.** No async in constructors. Open on first use, close cleanly. `ready-resource` / `ready-guard` give you this when it fits — use them where lifecycle matters, skip them where it doesn't.
-3. **Streams for flows, events for notifications, no defensive guards.** `streamx` for data that flows. Events for "something happened." Don't program defensively — let caller bugs crash; surface real operational failure on the resource. The README, tests, and semver are the contract, not runtime guard code.
-4. **Write for Bare and Node at once.** `b4a` instead of the `Buffer` global; `compact-encoding` for wire and disk formats. These cost nothing on Node and make the same code run on Bare. That portability is the default because we target both.
-5. **Every dependency is a liability you pay for forever.** Each must earn its place in one sentence. A 40-line module you understand beats a 4000-line one you don't. Reach for the small ecosystem primitives before inventing or importing.
-
----
-
-## Scope
-
-This is the repo's single code-style document. Everything about how code is shaped lives here — structure, layering, naming, typing, comments, whitespace, tests. If you're writing or reviewing code in this repo, this is the style.
-
-It is **not** the place for workflow. Commit, branch-naming, and push/PR-delivery rules live in [`CLAUDE.md`](../../../CLAUDE.md).
-
-**TypeScript everywhere.** Bare runs TS natively now, so the old "plain JS for Bare, TS for the app" split is gone — there is no longer a runtime reason to drop types. No new raw `.js`/`.cjs` product sources.
-
-For anything Bare loads, set **`"erasableSyntaxOnly": true`** in the tsconfig (already the case in this repo's `tsconfig.json`). Bare strips types rather than compiling them, so only erasable syntax survives: no `enum`, no `namespace`, no parameter properties (`constructor (private x)`), no `declare` class fields. `erasableSyntaxOnly` makes `tsc` reject those at build time instead of letting Bare fail to load the module at runtime — which presents as an opaque load failure you have to bisect file-by-file. Use plain `const` objects (`as const`) instead of `enum`, and assign fields in the constructor body.
-
-Exports follow what the code _is_, not which runtime it targets:
-
-- **Product source** — `lib/`, `worker/`, `schema/` — **named exports**, one concept per file.
-- **Standalone publishable modules** — a holepunch-style module that stands on its own and could be `npm i`-ed — a **single default export**, per the module anatomy below.
-
-When in doubt you are writing product source; the default export is for the module you'd publish. Everything else in this document applies to both without exception.
-
-## The method: work backwards from ambition, iterate like hell
-
-Before structure comes direction. The way we approach a problem (mafintosh's framing, which the whole way of working is built on):
-
-- Start from the **great ambition** — the real thing you want to exist.
-- Plan _backwards_ into small, self-contained pieces. Sort them topologically.
-- Build the **smallest piece that most efficiently validates the rest** first. Scope it down until the first iteration is a couple of days. Then execute immediately — never stall, never wait for a grand plan to be complete.
-- Lineage example: "unstoppable P2P file sharing" → Hypercore → "address Merkle-tree nodes efficiently" → `flat-tree`, built day 0. Each layer is a small publishable module that stands on its own.
-
-Two failure modes this guards against, both worth catching in review:
-
-- **Working hard in the wrong direction.** Effort mimics progress — tasks closed, bugs fixed — while the direction is wrong. Run the complexity check continuously: _is this the right way, and is there a simpler way to execute the ambition?_ Sunk cost is real. Cut early.
-- **Scope creep.** It kills projects. Small modules are the antidote — each is independently finishable, testable, replaceable.
-
-On using AI to do this work (heed it, since this skill is often _for_ an AI): AI with human comprehension is powerful; without it, quickly destructive. **Don't generate a subsystem you can't evaluate.** If you don't know what _good_ looks like for the thing (the canonical cautionary tale: a BBR congestion-control implementation that looked fine and wasn't), generating it costs more than it saves. Build the comprehension first, or get it from someone who has it, then generate.
-
-Practical upshot: bias to the smallest correct thing, make it composable, move on.
-
----
-
-## Build on primitives — let each module be perfect at one thing
-
-This is the heart of the style. A module should do **one thing perfectly** and expose it cleanly. The next capability up doesn't reimplement that thing, doesn't reach around it, doesn't fork it — it **composes** it. The ecosystem is a stack of layers where each one is a thin, sharp module sitting on the one below.
-
-The two canonical lineages:
-
-```
-compact-encoding  →  hyperschema  →  hrpc
-   (the wire)         (typed         (RPC over
-                       structs on      typed messages
-                       the wire)       on the wire)
-
-hypercore  →  hyperbee  →  hyperdb  →  autobee
- (append-      (B-tree      (typed,      (multiwriter
-  only log)     KV on the    indexed      hyperbee via
-                log)         collections  autobase)
-                             on the bee)
-```
-
-Read those left to right: each arrow is "built _on_, not instead of." `hyperschema` doesn't invent its own serialization — it generates `compact-encoding` codecs. `hrpc` doesn't invent a message format — it speaks `hyperschema`. `hyperbee` doesn't invent storage — it's a B-tree over a `hypercore`. `hyperdb` doesn't invent a tree — it's collections and indexes over a `hyperbee`. `autobee` doesn't invent consensus from scratch — it's a `hyperbee` made multiwriter through `autobase`.
-
-What this means when you write code:
-
-- **Find the lowest layer that already solves your sub-problem and build the thin next layer on it.** Before writing storage, ask which of hypercore/hyperbee/hyperdb already gives you 90% of it. You are almost never starting from zero — you're adding one sharp capability to an existing primitive.
-- **Each layer is independently perfect and independently usable.** Someone who needs just the wire format uses `compact-encoding` and never sees `hrpc`. Don't bundle concerns upward — a lower layer must never depend on a higher one, and must be useful on its own.
-- **Don't reach around a layer.** If you're on `hyperdb` and find yourself poking at the underlying `hypercore` directly to do something the bee/db layer should express, that's a smell: either the layer is missing a capability (add it _there_, in its own module) or you're at the wrong layer.
-- **Don't collapse layers "for convenience."** A module that does encoding _and_ storage _and_ RPC is the thing this style exists to prevent. Three modules, each perfect, composed. The seams are the feature — they're where reuse, testing, and replacement happen.
-- **Composition is by passing the lower thing in.** A higher module takes the primitive it builds on as a constructor argument (the `store`, the `core`, the `bee`), it doesn't construct it secretly or hard-wire it. That's what keeps layers swappable and testable.
-
-When you reach for a new capability, the instinct is: _which primitive is this one honest step above, and what is the smallest module that adds exactly that step?_
-
----
-
-## Module anatomy
-
-A well-shaped module is a single default export, an options bag, cheap construction, and — where it has resources — a clean teardown.
-
-```js
-const b4a = require('b4a')
-
-module.exports = class Thing {
-  constructor(store, opts = {}) {
-    this.store = store
-    this.foo = opts.foo ?? defaultFoo
-    this._internal = null // declare every field here, even if null
-  }
-
-  async open() {
-    this._internal = await this.store.get()
-  }
-
-  async doWork(arg) {
-    // ...
-  }
-}
-```
-
-The conventions, each with its reason:
-
-- **One thing per module, exported once.** A standalone publishable module is a single default export; product source uses named exports, one concept per file. Either way, a second unrelated export is usually a sign you have two modules. _Reason: composition is by importing the thing, and one-concept modules slot together predictably._
-- **`(required, opts = {})` constructor.** Positional for the one or two things the module fundamentally _is_ (the store, the key, the core); everything else in the options bag with `??` defaults. _Reason: the signature documents what's essential vs. configurable._
-- **Declare all instance fields in the constructor**, even `null` ones. _Reason: a reader sees the whole shape in one place, and the engine keeps a stable hidden class._
-- **No async work in the constructor.** Construction is synchronous and cheap; async setup happens in an `open`/`ready` step, lazily. _Reason: constructors can't await, and an object that's secretly half-built is a footgun._
-- **Opts pass down.** An options bag lets a caller configure without touching the signature, and lets a parent hand its opts to the child it constructs.
-  ```js
-  function aThing(somethingSuperImportantLikeACorestore, opts = {}) {
-    const { signal } = opts
-    this._otherThing = new OtherThing(opts)
-  }
-  ```
-- **Functions under ~20 lines**, one responsibility, early returns over nesting. Flat over nested; group by feature, not by type. No `utils.ts` dumping grounds.
-- **Split on domains, never on line count.** Splitting before there's a real seam buys import graphs, indirection, and shared-state plumbing in exchange for nothing. But a long file is only legitimate once everything separable has actually been taken out of it.
-
-  `@qvac/core → lib/core/mesh.ts` is the worked example. It's ~680 lines, and it should stay one file — but only because each domain it touches already lives somewhere else:
-
-  ```ts
-  import { syncChanges } from './sync/index.ts' // per-domain sync: knowledge, chunks, devices, chats
-  import { registerRoutes } from './contract/index.ts' // the RPC surface
-  import { createSyncActivity } from './sync-status.ts' // activity tracking
-  ```
-
-  `sync/` in turn is five files of 8–122 lines, one per domain, because keeping them together would blur independent implementations into one.
-
-  In this repo the same shape is `lib/capabilities/` and `lib/models/`: `index.ts` composes, each sibling owns one capability.
-
-  So the 443 lines are **residual, not undivided** — what's left is mesh lifecycle itself, which has no seam that isn't arbitrary. That's the test in both directions: a long file is fine if you can't name a domain still trapped inside it, and a split is right the moment you can name one.
-
-  **Split by domain, not by operation.** The same file's `blob-sweep.ts` is the counter-example — it carves out one _verb_ on blobs, so blob logic ends up spread across files that each own a fraction of it. Blobs are one domain: `blobs.ts`, holding sweep alongside the rest of blob handling. If the filename is a verb phrase, you probably split an operation off its domain rather than splitting two domains apart.
-
-  Corollary: a file growing past what you can hold in your head is a prompt to ask whether a second domain crept in — not a mandate to cut it at a line number.
-
-- **Match the surrounding project on CommonJS vs ESM.** Read the package and be consistent within it. Don't mix in one package without a reason.
-
-### Parameters
-
-The constructor rule above — one or two positional things, everything else in an options bag — is not special to constructors. It is how every function takes arguments.
-
-Positional is for the one or two things the function fundamentally acts _on_. Everything else goes in an object, because at the call site an object labels itself and a position doesn't.
-
-```ts
-// no — eight positional args, and three adjacent numbers that all accept each other
-frameProgress(update, mainSrc, srcs[i], i, srcs.length, completedBytes, expectedSize, totalBytes)
-
-// yes — the subject stays positional, the rest is named
-frameProgress(update, {
-  setKey: mainSrc,
-  currentFile: srcs[i],
-  fileIndex: i,
-  totalFiles: srcs.length,
-  completedBytes,
-  expectedSize,
-  totalBytes
-})
-```
-
-**The trigger is ambiguity, not arity.** Three parameters of three distinct types read fine. _Two_ adjacent parameters of the same type are already a hazard — swap them and it compiles, runs, and quietly produces a wrong answer that no test you thought to write will catch. Count makes it worse; sameness makes it dangerous.
-
-- **Same-typed neighbours go in an object.** Especially numbers, and especially sizes/offsets/indexes, which are indistinguishable to the compiler and to the reader.
-- **Never take a positional boolean.** `render(node, true, false)` is unreadable at the call site. Use named options — and prefer that the flag not exist at all.
-- **Loop-invariant values don't belong in a per-iteration signature.** If half the arguments are the same on every call, bind them once in a closure or a small factory and pass only what varies. That usually shrinks the function more than the object would.
-- **Object properties are also where defaults live** (`?? fallback`), so adding an option later doesn't churn every call site.
-
-Same instinct as the rest of the style: make the wrong call hard to write, rather than adding a check that catches it later.
-
-### Naming
-
-- Readable prose: `inviteDevice`, not `inv`. `ServiceResult`, not `SvcRes`.
-- File names describe content. No abbreviations unless universally understood (`id`, `url`, `http`).
-- No magic strings for domain identifiers — enums, schemas, or `as const` constants.
-
-### Typing
-
-Types are the cheapest contract you get. Keep them honest at the boundary and the interior needs no guards.
-
-- **Zero `as` casts.** Parse untrusted data with Zod (or the package's typed boundary) and derive types with `z.infer<>`. A cast is you telling the compiler to stop helping.
-- **Zero `any`.** If a type is genuinely unknown, narrow it at the boundary.
-- **Minimize `unknown`** — acceptable only at a true boundary (IPC handler, `JSON.parse`), narrowed immediately.
-- **Explicit return types on exported functions.** `readonly` on object properties, `ReadonlyArray<T>` over `T[]`.
-- Test files may use narrow casts for mock wiring or intentionally invalid fixtures. Keep them local; never copy into production code.
-
-This is the typed counterpart of _don't program defensively_ below — the type checker enforces the contract statically, so you don't re-check it at runtime.
-
-### Comments and whitespace
-
-Well-structured code in small modules with honest names does not need narration. Comments are the exception, not the habit.
-
-- **Prefer no comment.** If a comment explains _what_ the code does, delete it and fix the name. The API, the README, and the tests are the documentation.
-- **One line, maximum.** A comment that needs a second line is a sign the code needs a seam, not a paragraph. Never write a comment block.
-- **Only ever explain _why_** — a non-obvious constraint, a workaround with a reason, why an operational error is safe to swallow.
-- **Long AI-generated comment blocks are an anti-pattern.** They restate the obvious, drift out of date silently, and mislead the next reader. Don't emit them.
-
-### Whitespace groups the code
-
-Blank lines are the structure a reader navigates by. They are not padding, and removing them is not tidiness — an unbroken wall of statements is _harder_ to read than the same code grouped, because nothing signals where one thought ends and the next begins.
-
-Group by what the code is doing: setup, then action, then the assertions or effects that follow from it. A new group starts wherever the reader's question changes.
-
-```js
-// no — one wall, no seam between setup, the four scenarios, or their assertions
-const { ragSearch } = await toolModeApi({ ragEnabled: false })
-const tool = await ragSearch({
-  chatId: 'chat-1',
-  query: 'alpha fuel pressure',
-  mode: 'tool',
-  limit: 5
-})
-t.ok(tool.enabled, 'the toggle does not gate tool mode')
-t.ok((tool.hits?.length ?? 0) > 0, 'hits found on a toggle-off chat')
-const injection = await ragSearch({ chatId: 'chat-1', query: 'alpha fuel pressure' })
-t.absent(injection.enabled, 'injection mode still honors the toggle')
-```
-
-```js
-// yes — setup, then one group per scenario
-const { ragSearch } = await toolModeApi({ ragEnabled: false })
-
-const tool = await ragSearch({
-  chatId: 'chat-1',
-  query: 'alpha fuel pressure',
-  mode: 'tool',
-  limit: 5
-})
-t.ok(tool.enabled, 'the toggle does not gate tool mode')
-t.ok((tool.hits?.length ?? 0) > 0, 'hits found on a toggle-off chat')
-t.absent(tool.targetDocumentId, 'tool mode never resolves a target document')
-
-const injection = await ragSearch({ chatId: 'chat-1', query: 'alpha fuel pressure' })
-t.absent(injection.enabled, 'injection mode still honors the toggle')
-
-const missing = await ragSearch({ chatId: 'chat-404', query: 'alpha', mode: 'tool', limit: 3 })
-t.absent(missing.enabled, 'an unknown chat never searches, even in tool mode')
-```
-
-Split a group further when it grows its own phases — _set up this case_, _wait for the state_, _check it_ — rather than letting one group run long. The grouping is what a comment would otherwise have to say, which is most of why the comment isn't needed.
-
-What isn't grouping, and shouldn't appear: banner or section-divider comments, columns aligned with padding spaces, a blank line immediately after `{` or before `}`, and two blank lines where one does the job.
-
-### Cleanliness
-
-Say the thing once, in the simplest form that expresses it. Two habits to hold:
-
-**Let `undefined` propagate — never conditionally spread.**
-
-```js
-// no
-{ ...(runStream.signal ? { signal: runStream.signal } : {}) }
-
-// yes
-{ signal: runStream.signal }
-```
-
-The conditional spread adds a branch, a nested object, and a second reading of the same value to express nothing — an absent key and a key set to `undefined` behave identically at every consumer that matters. For an optional field, type it `signal?: AbortSignal | undefined` and assign it plainly.
-
-**No dead scaffolding.** No commented-out code, no unused parameter kept "for symmetry", no option nothing reads, no re-export that only forwards. Delete it — git remembers.
-
-### Derived state
-
-Every value that exists twice will eventually disagree. Most "impossible" bugs are two things that were supposed to stay in sync and didn't.
-
-**One source of truth per value.** If a number is already available, don't carry a second copy of it beside the first. A consumer then has to know which to read, and the day they diverge nobody will know which was right.
-
-**But check the contract before you call it duplication.** Two fields holding the same value are sometimes two _channels_ that are documented to mean different things, and which happen to agree right now. Then the defect isn't the copy — it's that a value was written into the wrong channel, and deleting a field would be the wrong fix.
-
-Find the contract first: the type declaration and its comments, and the order a consumer reads the fields in. A reader that prefers one field over another _is_ the contract, even where nothing is written down.
-
-```ts
-// looks like duplication — the same number in four places
-{ downloaded, total, percentage, fileSetInfo: { overallDownloaded, overallTotal, overallPercentage } }
-```
-
-Here the type said top-level is _this asset_ and `fileSetInfo` is _the whole transfer_, and the consumer read `fileSetInfo` in preference. So the real defect was writing the aggregate over the per-asset fields — a contract violation, fixed by putting each value in its own channel, not by deleting either.
-
-The two diagnoses lead to opposite fixes, so get the diagnosis right:
-
-- **Distinct documented meanings** → put each value in its own channel. Both fields stay.
-- **No contract distinguishing them** → genuine duplication. Emit it once; give a nested shape only the fields that add information.
-
-**Precompute the invariant; don't maintain it incrementally.** A running accumulator has to be advanced correctly at every step, and every future edit to the loop can break it. A table computed once cannot drift:
-
-```ts
-// no — a mutable offset the loop must remember to advance, at exactly the right moment
-let completedBytes = 0
-for (...) { /* use completedBytes */ ; completedBytes += size }
-
-// yes — offsets computed once, correct by construction
-const offsets = []
-let running = 0
-for (const src of srcs) { offsets.push(running); running += sizes[src] }
-```
-
-The second version is the same arithmetic with the mutation confined to where it's obviously right, and the loop body doesn't participate in keeping it true.
-
-**Don't launder a bad value into a plausible one.** `Math.max(x, 0)`, `?? 0`, and `|| 0` on something that should never have been negative, null, or absent don't fix anything — they convert a loud failure into a wrong number that flows onward and gets debugged three layers away. Clamping for a _presentational_ guarantee (a progress bar that must not go backwards) is legitimate; clamping because you aren't sure what the producer sends is not. Know which one you're writing.
-
-Note the repo's own trap here: an optional `uint` decodes to `0` rather than `null` when absent, so `??` won't catch a missing timestamp and `||` is the correct operator.
-
-### README shape
-
-Ship the same structure on every module — OSS, private, or throwaway. Consistency is the point:
-
-```
-# module-name
-One-line description.
-## Installation   npm i module-name
-## Usage          the smallest runnable real example
-## API            constructor + each method
-## License        match the project
-```
-
-Keep Usage runnable and minimal — it's the first thing anyone copies.
-
----
-
-## Lifecycle: a pattern, used where it earns its place
-
-When a thing owns resources — a file, a core, a socket, a watcher — it needs orderly setup and teardown. `ready-resource` and `ready-guard` give you that, and most of our stateful code uses them. But this is a **pattern, not a mandate**. A pure function or a stateless helper doesn't need a lifecycle; bolting one on is over-engineering. Use it where lifecycle genuinely matters; skip it where it doesn't. Same judgment applies to every primitive below — reach for it because it fits, not because it's on a list.
-
-When it does fit, `ready-resource` gives you:
-
-- `ready()` — idempotent; runs `_open()` exactly once, concurrent callers await the same promise. Safe to call on every method.
-- `close()` — idempotent; runs `_close()` once. Safe before `ready()`, safe twice.
-- `opened` / `closed` / `opening` / `closing` state, and a `'close'` event.
-
-The rules when you use it:
-
-- **Implement `_open`/`_close`; never call them directly.** `ready()`/`close()` are the public surface.
-- **`_open` opens dependencies in order; `_close` reverses it.** Close the watcher before the core it watches.
-- **Enter public async methods behind the opened guard:**
-
-  ```js
-  if (!this.opened) await this.ready()
-  ```
-
-  Not a bare `await this.ready()`. `ready()` is idempotent and returns an already-resolved promise once open, but awaiting it still costs a microtask tick on _every_ call — on a hot path that's a tick per operation for no work. The guard makes the common case synchronous and only awaits the first time. This is the laziness contract: construct, then call, and the first call opens.
-
-- **Make every async step interruptible.** Check `closing` before and after each suspension point, in `_open` and in any long-running method:
-
-  ```js
-  async _open () {
-    this.core = await this.store.get()
-    if (this.closing) return
-    this.watcher = this.core.watch()
-  }
-  ```
-
-  Without that, a `close()` landing mid-setup leaves a half-built resource — the watcher gets created after teardown already ran, and nothing will ever close it.
-
-- **Set state before you await, not after.** The state field is the guard other calls read; if you flip it after the await, a concurrent caller sees stale state and does the work twice. Don't add a parallel `parked`/`busy` boolean beside the real one — one source of truth.
-- **Teardown must actually finish.** `_close` releases everything `_open` took: streams destroyed, watchers closed, locks unlocked in `finally`, timers cleared, listeners removed. A process that won't exit is a `_close` that missed something.
-
-If you're writing an `init()` method, stop — that's `ready()`, and you're reimplementing it.
-
-### Fix the source, not the symptom
-
-Lifecycle bugs are where this matters most, because the symptom is almost always cheaper to paper over than the cause — and papering over is how the cause becomes permanent.
-
-- A process that doesn't exit is a resource you didn't close. **Don't** add a force-exit, a kill timer, or logic that reaps a stale lock holder at next launch. Find what's still open.
-- A value that's occasionally missing is a race. **Don't** retry it or wait longer. Wait on the signal from the layer that knows.
-- A test that's flaky is telling you the code is order-dependent. **Don't** extend the timeout or add a stabilisation sleep. Gate on the actual state you need.
-
-Each of those workarounds converts a reproducible bug into an intermittent one, and moves the cost from you now to everyone later.
-
-### Bare safety
-
-Bare is not Node, and two differences bite specifically around lifecycle:
-
-- **`AbortSignal` listeners fire synchronously.** Fire-and-forget work in an abort listener is fine; anything that blocks or awaits inside one can deadlock, because the abort is still unwinding. Signal the intent and let the async work happen outside the listener.
-- **Type stripping, not compiling.** See the `erasableSyntaxOnly` note in [Scope](#scope) — a non-erasable construct fails at module load as an opaque error you have to bisect for, not as a type error.
-
-Everything in [Buffers and wire formats](#buffers-and-wire-formats-bare--node) applies for the same reason: write it once, run it on both.
-
----
-
-## Streams, events, errors
-
-### Flows → streamx
-
-Use `streamx`, not Node core `stream`. _Reason: lighter, predictable backpressure, runs on Bare, and it's what the ecosystem speaks._ `Readable`/`Writable`/`Duplex`/`Transform` plus `pipeline`.
-
-```js
-const { Readable } = require('streamx')
-
-class Query extends Readable {
-  constructor(db, range) {
-    super()
-    this.db = db
-    this.range = range
-    this._it = null
-  }
-
-  _open(cb) {
-    this._it = this.db.iterator(this.range)
-    cb(null)
-  }
-
-  async _read(cb) {
-    const { done, value } = await this._it.next()
-    if (done) this.push(null)
-    else this.push(value)
-    cb(null)
-  }
-
-  _destroy(cb) {
-    this._it?.close().then(() => cb(null), cb)
-  }
-}
-```
-
-streamx's stream hooks (`_open`/`_read`/`_write`/`_destroy`, callback-style) are not ReadyResource's promise-based `_open`/`_close` — don't conflate them. Prefer returning a stream over building a giant array when results are large or unbounded; `for await (const x of stream)` is the consumer idiom.
-
-### Notifications → events
-
-EventEmitter (or streamx's emitter) for "something happened": `'close'`, `'update'`, `'peer-add'`. Fire-and-forget signals, not data pipes, not request/response.
-
-### Errors: don't program defensively
-
-We do **not** program defensively. We don't litter methods with arg-type checks, null guards, or "did you call this in the right order" assertions. _Reason: defensive code is complexity you write, read, and pay for at runtime forever — to handle a case that is a caller bug, not a real condition._ The contract is the README and the tests; semver protects it. A dev who uses the API totally wrong gets a native crash, and that is the correct outcome — fail fast, fail loud, fix the call site.
-
-- **Let misuse fail.** Pass a string where a buffer goes? It throws from deep in the stack. Fine. That's a bug in their code, surfaced immediately, not a state your module should anticipate or absorb.
-- **Don't validate inputs you've documented.** The documented type _is_ the validation. Re-checking it in code is redundant with the README and the tests.
-- **Operational failure is different — that travels with the resource.** A dropped peer, a replication error, a disk hiccup are real runtime conditions, not caller bugs → emit `'error'`, reject the in-flight promise, or expose state. Don't take the process down for a network blip.
-- **`safety-catch`** rethrows real bugs while swallowing benign teardown rejections, so a genuine programmer error still crashes loudly rather than getting silently eaten:
-  ```js
-  const safetyCatch = require('safety-catch')
-  somePromise().catch(safetyCatch)
-  ```
-- **Never swallow silently.** If you catch and ignore an _operational_ error, leave a comment on why it's safe.
-
-The line to hold: **caller bug → let it crash. Runtime condition → handle it on the resource.** Don't blur the two by defending against the first.
-
----
-
-## Concurrency: scope-lock
-
-Async interleaving is the recurring tax. The answer is `scope-lock` — concurrency semantics around entering a scope — to serialize access to a shared resource. It's `lock()` / `unlock()`, not acquire-a-release-fn.
-
-```js
-const ScopeLock = require('scope-lock')
-
-const l = new ScopeLock()
-
-async function append(data) {
-  await l.lock()
-  try {
-    await reallyAppend(data)
-  } finally {
-    l.unlock()
-  }
-}
-```
-
-`lock()` queues — callers run in order, one at a time. Always `unlock()` in `finally`; a lock you never release deadlocks the scope silently.
-
-It also has a **debounced** mode, for when you don't need every queued entry to run — only the first and the last. Coalescing a burst of "something changed, re-sync" calls into one leading and one trailing run is the classic use:
-
-```js
-const d = new ScopeLock({ debounce: true })
-
-async function resync() {
-  if (await d.lock()) {
-    // only the entries that actually get the scope return true
-    try {
-      await doResync()
-    } finally {
-      d.unlock()
-    }
-  }
-}
-
-await d.flush() // wait for all current work in the scope to drain
-```
-
-Use a plain lock when every call must run; use debounce when intermediate calls are redundant and only the latest state matters. Don't reach for either when the operation is already atomic, and don't build an elaborate queue when a scope lock suffices.
-
-### Closures capture the variable, not its value
-
-A callback that outlives the statement that created it reads whatever the variable holds _when it fires_, not when it was passed. Combine that with a mutation after an `await` and you have a bug that only appears under real timing:
-
-```ts
-let completedBytes = 0
-for (let i = 0; i < srcs.length; i++) {
-  const onProgress = (u) => report(completedBytes + u.downloaded) // reads it later
-  await download(srcs[i], { onProgress })
-  completedBytes += sizes[srcs[i]] // moved by then
-}
-```
-
-A progress event that lands after its download resolves — a straggler over IPC, a queued microtask, an event flushed on close — sees the _next_ offset and double-counts. It won't reproduce locally, and clamping the output only hides it.
-
-- **Don't let a callback close over state that a later step mutates.** Pass the value the callback needs, or compute the whole table up front (see [Derived state](#derived-state)).
-- **`for (let i …)` is per-iteration; `let x` outside the loop is not.** The loop index is safe to capture, the accumulator beside it isn't.
-- **After every `await`, assume anything not local may have changed** — including fields on `this`, which is the same hazard the `closing` checks exist for.
-
-### Never sleep to synchronise
-
-**Zero `setTimeout` in product code.** No arbitrary delays, no sleep-polling. Wait on the signal, promise, event, or callback from the layer that actually knows when the thing is ready. A timeout that "usually works" is a race you've decided to ship — and it fails on the slowest machine, which is CI.
-
-If nothing exposes readiness, that's the bug: add the event or the promise to the layer that owns the state, and wait on it. Tests may use a bounded `setTimeout` only when exercising genuinely external timing with no deterministic primitive to wait on.
-
----
-
-## Buffers and wire formats (Bare + Node)
-
-### b4a everywhere
-
-**Don't use the `Buffer` global.** _Reason: it may not exist on Bare. `b4a` is identical behavior, runs on both._ This is the default precisely because we target Bare and Node from the same source.
-
-```js
-const b4a = require('b4a')
-
-b4a.from('hello') // not Buffer.from
-b4a.alloc(32) // not Buffer.alloc
-b4a.equals(a, b) // not a.equals(b)
-b4a.toString(buf, 'hex') // not buf.toString('hex')
-b4a.concat([a, b])
-```
-
-A single `Buffer.from` is a portability bug in code meant to run on Bare.
-
-### compact-encoding for the wire
-
-Wire and on-disk formats use `compact-encoding` — positional, length-prefixed, no field tags.
-
-```js
-const c = require('compact-encoding')
-
-const message = {
-  preencode(state, m) {
-    c.uint.preencode(state, m.seq)
-    c.string.preencode(state, m.name)
-  },
-  encode(state, m) {
-    c.uint.encode(state, m.seq)
-    c.string.encode(state, m.name)
-  },
-  decode(state) {
-    return { seq: c.uint.decode(state), name: c.string.decode(state) }
-  }
-}
-```
-
-Carved-in-stone rule: **fields are positional — new fields append at the END; existing fields are never removed, reordered, or retyped.** Any data already on disk or replicated to a peer is frozen. Plan the format before shipping. For typed records, prefer `hyperschema`/`hyperdb` codegen over hand-rolling (see the hyperdb-hyperschema skill).
-
----
-
-## Dependency discipline
-
-Each dependency is maintained forever — its bugs, breaking changes, security surface, and weight on Bare become yours.
-
-- **Prefer the small ecosystem primitive** first: `b4a`, `streamx`, `ready-resource`, `ready-guard`, `scope-lock`, `safety-catch`, `compact-encoding`, `hypercore-crypto`, `sodium-universal`. Small, audited, Bare-safe.
-- **A small dependency you understand beats a large one you don't.** Need 40 lines of behavior from a 4000-line library? Write the 40 lines.
-- **Vet for Bare-compatibility.** Anything touching the `Buffer` global, Node `stream`, raw `fs`, or unported native addons is suspect.
-- **Justify every `package.json` entry in one sentence.** If you can't, it shouldn't be there.
-- **Don't import to avoid an obvious function.** `isOdd` is the cautionary tale.
-
-The governing question is the complexity check again: _is there a simpler way to execute the ambition?_ Often it's no dependency at all.
-
----
-
-## Testing
-
-Tests are the contract. Because we don't program defensively, the test suite plus the README plus semver are what keep the API safe to depend on — there's no guard code doing it at runtime. So tests carry real weight: **test the API the way a dev actually uses it.**
-
-**Tests are as real as possible.** For anything P2P, bootstrap a real `hyperdht` testnet rather than mocking the transport — a mocked swarm proves your mock works. Don't assert that a function was called; assert the behavior it was supposed to produce. If a unit test can only verify a spy, it has no value and shouldn't exist.
-
-`brittle` is the standard — flat, assertion-driven, TAP-style. (Older repos use `tape`/`test`; match the repo.)
-
-```js
-const test = require('brittle')
-const Thing = require('./')
-
-test('basic append and read', async function (t) {
-  const thing = new Thing(store)
-  await thing.ready()
-  t.teardown(() => thing.close())
-
-  await thing.doWork('a')
-  t.is(thing.length, 1)
-  t.alike(await thing.get(0), expected)
-})
-```
-
-What "test the API" means here:
-
-- **Tests exercise the public surface as a consumer would call it** — construct, `ready()`, call the documented methods, assert the documented behavior. They're the executable version of the README's Usage section. If a method is documented, there's a test that uses it the documented way.
-- **Test how the thing is _meant_ to be used, not how it's built.** Assert behavior through the public API (`t.is`, `t.alike`, `t.ok`), never reach into internals. A refactor that keeps the API stable must keep the tests green — that's the whole point.
-- **You do not test misuse.** We don't program defensively, so there's nothing to assert about passing garbage in — that path is a native crash by design. Don't write tests that pin down the crash behavior of unsupported input; it isn't part of the contract and pinning it makes the contract accidentally wider.
-- **Test the real failure paths that _are_ part of the contract** — close-during-open, the race you just fixed, the documented bounds that legitimately return nothing, operational errors surfacing on the resource. These are behaviors you promise; prove them.
-- **`t.teardown()` for cleanup** — closes resources even when assertions fail. Use it for everything you open.
-- **Flat tests, one `test()` per behavior.** The name states the assertion. No deep describe/it nesting.
-- **Semver follows the tests.** A change that breaks an existing API test is a breaking change — major bump. Tests are how you know. Even small throwaway modules get CI, lint, and basic API tests; same checklist every time.
-- **Keep helpers out of the way.** A helper used by one test goes inside that test; a helper used by the file goes at the end of it. Big reusable ones move to `test/helpers/`. Never let scaffolding sit between the reader and the first assertion.
-
-For a suite that builds real multi-peer structure, put the setup behind one factory that owns the testnet and the teardown:
-
-```js
-const { things } = await create(t) // testnet + teardown registered
-const thing1 = await things.start() // takes opts, awaits ready, wires the testnet in
-const t1 = await things.restart(0) // close and re-open thing1
-```
-
-The test then reads as the scenario it describes, and lifecycle correctness lives in one place instead of being re-derived per test.
-
----
-
-## Review checklist
-
-Apply to any module, regardless of size or visibility. When reviewing, walk it and report violations tersely with the fix, in dependency order — don't rewrite wholesale unless asked. And remember the first rule: a flagged item is a prompt to think, not an automatic defect. If the code broke a default _for a good reason_, that's good code.
-
-- [ ] One responsibility, describable without "and"; built on the layer below, not reimplementing or reaching around it.
-- [ ] Composed by passing the lower primitive in (store/core/bee), not constructing it secretly; no layer depends upward.
-- [ ] File boundaries fall on domains — a long single-focus file left whole, a multi-domain one split; no split made on line count alone.
-- [ ] Exports match the kind of code (named for product source, one default for a publishable module); `(required, opts = {})` constructor; all fields declared.
-- [ ] Functions take one or two positional subjects and an object for the rest — no same-typed neighbours, no positional booleans, no loop-invariants re-passed per call.
-- [ ] TypeScript with no `as`, no `any`, `unknown` only at boundaries; `erasableSyntaxOnly` respected for anything Bare loads.
-- [ ] Comments: none unless they explain _why_, one line max, no comment blocks, no banner dividers.
-- [ ] Blank lines group the code into setup / action / assertion — neither an unbroken wall nor padding that groups nothing.
-- [ ] No conditional spreads — optional values assigned plainly and allowed to be `undefined`; no commented-out code or unused scaffolding.
-- [ ] One source of truth per value — nothing carried twice or computed twice in the same payload, and where two fields do hold the same value, each is in the channel its type documents.
-- [ ] Invariants precomputed rather than accumulated in a loop; no callback closing over state a later step mutates.
-- [ ] No `Math.max(x, 0)` / `?? 0` / `|| 0` laundering a value that should never be wrong.
-- [ ] No `setTimeout` to synchronise — waits on a real readiness signal.
-- [ ] Cheap construction, no async in constructor; lifecycle (ready/close) where resources warrant it, skipped where they don't.
-- [ ] `if (!this.opened) await this.ready()` on public async methods, not a bare await; `closing` checked at every suspension point; state set before awaiting.
-- [ ] `_close` releases everything `_open` took — no force-exit, kill timer, or stale-lock reaping standing in for a real teardown.
-- [ ] Root cause fixed, not the symptom — no retry, longer wait, or stabilisation sleep hiding a race.
-- [ ] `b4a` for buffers, no `Buffer` global; runs on Bare and Node.
-- [ ] `streamx` for flows; events for notifications; no defensive guards — caller bugs crash, operational failures surface on the resource; `safety-catch` where teardown rejections are expected.
-- [ ] Shared-resource concurrency serialized (scope-lock) where interleaving would corrupt; not over-applied.
-- [ ] Wire/disk format append-only and planned; codegen where it fits.
-- [ ] Every dependency justified in one sentence; ecosystem primitives preferred.
-- [ ] `brittle` tests that exercise the public API the way a consumer calls it, with `t.teardown`, covering the contracted failure paths; no tests pinning misuse behavior.
-- [ ] API documented in the README and versioned with semver; breaking an API test means a major bump.
-- [ ] README: install / usage (runnable) / API / license.
-- [ ] CI + lint wired, even if tiny.
-- [ ] Nothing generated that the author can't evaluate.
-
----
-
-## Sibling skills
-
-This skill governs the shape of the code. The others cover surfaces and workflow around it:
-
-- Writing the PR itself (title, body, type) → **pr-create**.
-- Reviewing a PR or a local diff against these rules → **pr-review**.
-- The KV cache, the context window and the overflow ladder → **kvcache**.
-
-Commit and branch rules live in [`CLAUDE.md`](../../../CLAUDE.md); how a PR itself is shaped and delivered is **pr-create**.