@qvac/harness 0.2.6 → 0.2.8

package/.claude/skills/gh-stack/SKILL.md

@@ -7,7 +7,7 @@ description: >
   branch layers, dependent PRs, or gh stack; or when a stack is checked out.
 metadata:
   author: github
-  version: "0.1.0"
+  version: '0.1.0'
 ---
 
 # gh-stack
@@ -45,16 +45,16 @@ Agent harnesses differ, so always pass the flags below instead of relying on tha
 `--remote <name>` unless `remote.pushDefault` is configured. `checkout` and `trunk` have no
 `--remote` flag and require the config.
 
-| Always run | Never run bare | Why |
-|---|---|---|
-| `gh stack view --json` | `gh stack view` | opens a TUI under a PTY |
-| `gh stack submit --auto` | `gh stack submit` | prompts for a title per new PR |
-| `gh stack merge <target> --yes` | `gh pr merge` | `gh pr merge` cannot merge a stack |
-| `gh stack init <branch>...` | `gh stack init` | prompts for branch names |
-| `gh stack add <branch>` | `gh stack add` | prompts for a name, and fails even when piped |
-| `gh stack checkout <target>` | `gh stack checkout` | opens a selection menu |
-| `gh stack up` / `down` / `top` / `bottom` | `gh stack switch` | `switch` is menu-only |
-| — | `gh stack modify` | TUI-only, no non-interactive path |
+| Always run                                | Never run bare      | Why                                           |
+| ----------------------------------------- | ------------------- | --------------------------------------------- |
+| `gh stack view --json`                    | `gh stack view`     | opens a TUI under a PTY                       |
+| `gh stack submit --auto`                  | `gh stack submit`   | prompts for a title per new PR                |
+| `gh stack merge <target> --yes`           | `gh pr merge`       | `gh pr merge` cannot merge a stack            |
+| `gh stack init <branch>...`               | `gh stack init`     | prompts for branch names                      |
+| `gh stack add <branch>`                   | `gh stack add`      | prompts for a name, and fails even when piped |
+| `gh stack checkout <target>`              | `gh stack checkout` | opens a selection menu                        |
+| `gh stack up` / `down` / `top` / `bottom` | `gh stack switch`   | `switch` is menu-only                         |
+| —                                         | `gh stack modify`   | TUI-only, no non-interactive path             |
 
 - `view --short` is safe in both modes, but it is formatted for humans. Use `--json` to parse.
 - **`checkout <pr>` when a different local stack already covers those branches** cannot be forced.
@@ -138,19 +138,19 @@ an ancestor of the branch.
 
 ## Exit codes
 
-| Code | Meaning | Recovery |
-|---|---|---|
-| 0 | Success | — |
-| 1 | Generic error | Read stderr |
-| 2 | Not in a stack | `gh stack init`, or `gh stack checkout <target>` |
-| 3 | Rebase conflict | Follow the Exit 3 recovery below |
-| 4 | GitHub API failure | Check `gh auth status`, retry |
-| 5 | Invalid arguments | Fix the invocation; see `<command> --help` |
-| 6 | Disambiguation required | Branch is in several stacks; check out a non-shared branch |
-| 7 | Rebase already in progress | `gh stack rebase --continue` or `--abort` |
-| 8 | Stack file locked | Another `gh stack` process is writing; retry after ~5s |
-| 9 | Stacked PRs unavailable | Not enabled on the repository; tell the user |
-| 10 | Modify recovery required | `gh stack modify --abort` |
+| Code | Meaning                    | Recovery                                                   |
+| ---- | -------------------------- | ---------------------------------------------------------- |
+| 0    | Success                    | —                                                          |
+| 1    | Generic error              | Read stderr                                                |
+| 2    | Not in a stack             | `gh stack init`, or `gh stack checkout <target>`           |
+| 3    | Rebase conflict            | Follow the Exit 3 recovery below                           |
+| 4    | GitHub API failure         | Check `gh auth status`, retry                              |
+| 5    | Invalid arguments          | Fix the invocation; see `<command> --help`                 |
+| 6    | Disambiguation required    | Branch is in several stacks; check out a non-shared branch |
+| 7    | Rebase already in progress | `gh stack rebase --continue` or `--abort`                  |
+| 8    | Stack file locked          | Another `gh stack` process is writing; retry after ~5s     |
+| 9    | Stacked PRs unavailable    | Not enabled on the repository; tell the user               |
+| 10   | Modify recovery required   | `gh stack modify --abort`                                  |
 
 **Exit 3 recovery:**
 

package/.claude/skills/gh-stack/references/commands.md

@@ -67,7 +67,7 @@ first non-merged ancestor, then links them into a Stack on GitHub.
   the title and its body as the PR body. A branch with multiple commits humanizes the branch name
   (hyphens and underscores become spaces). There is no flag for a custom title or body; use
   `gh pr edit` afterwards.
-- `--open` marks new *and existing* PRs ready for review; without it new PRs are drafts.
+- `--open` marks new _and existing_ PRs ready for review; without it new PRs are drafts.
 - Requires stacked PRs to be enabled on the repository. If not, `submit` exits **9** when
   non-interactive (under a TTY it offers to create ordinary unstacked PRs instead).
 
@@ -172,6 +172,6 @@ Removes the stack **grouping** only. It never deletes pull requests or branches.
 
 `up`, `down`, `top`, `bottom`, and `trunk` are always non-interactive. `up` and `down` accept a
 count (`gh stack up 3`). Movement clamps at the stack bounds, and merged branches are skipped when
-navigating from an active branch, so `bottom` lands on the lowest *unmerged* branch.
+navigating from an active branch, so `bottom` lands on the lowest _unmerged_ branch.
 
 `gh stack switch` is a selection menu with no non-interactive path. Use the commands above instead.

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

@@ -12,7 +12,7 @@ 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.
+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:
 
@@ -34,7 +34,7 @@ It is **not** the place for workflow. Commit, branch-naming, and push/PR-deliver
 
 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:
+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.
@@ -46,16 +46,16 @@ When in doubt you are writing product source; the default export is for the modu
 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.
+- 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.
+- **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.
+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.
 
@@ -80,17 +80,17 @@ hypercore  →  hyperbee  →  hyperdb  →  autobee
                              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`.
+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.
+- **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?*
+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?_
 
 ---
 
@@ -102,17 +102,17 @@ A well-shaped module is a single default export, an options bag, cheap construct
 const b4a = require('b4a')
 
 module.exports = class Thing {
-  constructor (store, opts = {}) {
+  constructor(store, opts = {}) {
     this.store = store
     this.foo = opts.foo ?? defaultFoo
     this._internal = null // declare every field here, even if null
   }
 
-  async open () {
+  async open() {
     this._internal = await this.store.get()
   }
 
-  async doWork (arg) {
+  async doWork(arg) {
     // ...
   }
 }
@@ -120,13 +120,13 @@ module.exports = class Thing {
 
 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.*
+- **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 = {}) {
+  function aThing(somethingSuperImportantLikeACorestore, opts = {}) {
     const { signal } = opts
     this._otherThing = new OtherThing(opts)
   }
@@ -134,12 +134,12 @@ The conventions, each with its reason:
 - **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`'s `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:
+  `@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
+  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.
@@ -148,16 +148,17 @@ The conventions, each with its reason:
 
   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.
+  **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.
+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
@@ -175,7 +176,7 @@ frameProgress(update, {
 })
 ```
 
-**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.
+**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.
@@ -200,26 +201,32 @@ Types are the cheapest contract you get. Keep them honest at the boundary and th
 - **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.
+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.
+- **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.
+- **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.
+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 })
+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' })
@@ -230,7 +237,12 @@ t.absent(injection.enabled, 'injection mode still honors the toggle')
 // 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 })
+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')
@@ -242,7 +254,7 @@ const missing = await ragSearch({ chatId: 'chat-404', query: 'alpha', mode: 'too
 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.
+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.
 
@@ -270,16 +282,16 @@ Every value that exists twice will eventually disagree. Most "impossible" bugs a
 
 **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.
+**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.
+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.
+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:
 
@@ -301,7 +313,7 @@ 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.
+**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.
 
@@ -342,7 +354,7 @@ The rules when you use it:
   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.
+  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:
 
@@ -386,32 +398,32 @@ Everything in [Buffers and wire formats](#buffers-and-wire-formats-bare--node) a
 
 ### 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`.
+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) {
+  constructor(db, range) {
     super()
     this.db = db
     this.range = range
     this._it = null
   }
 
-  _open (cb) {
+  _open(cb) {
     this._it = this.db.iterator(this.range)
     cb(null)
   }
 
-  async _read (cb) {
+  async _read(cb) {
     const { done, value } = await this._it.next()
     if (done) this.push(null)
     else this.push(value)
     cb(null)
   }
 
-  _destroy (cb) {
+  _destroy(cb) {
     this._it?.close().then(() => cb(null), cb)
   }
 }
@@ -425,17 +437,17 @@ EventEmitter (or streamx's emitter) for "something happened": `'close'`, `'updat
 
 ### 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.
+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.
+- **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.
+- **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.
 
@@ -450,7 +462,7 @@ const ScopeLock = require('scope-lock')
 
 const l = new ScopeLock()
 
-async function append (data) {
+async function append(data) {
   await l.lock()
   try {
     await reallyAppend(data)
@@ -467,8 +479,9 @@ It also has a **debounced** mode, for when you don't need every queued entry to
 ```js
 const d = new ScopeLock({ debounce: true })
 
-async function resync () {
-  if (await d.lock()) {   // only the entries that actually get the scope return true
+async function resync() {
+  if (await d.lock()) {
+    // only the entries that actually get the scope return true
     try {
       await doResync()
     } finally {
@@ -484,18 +497,18 @@ Use a plain lock when every call must run; use debounce when intermediate calls
 
 ### 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:
+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
+  const onProgress = (u) => report(completedBytes + u.downloaded) // reads it later
   await download(srcs[i], { onProgress })
-  completedBytes += sizes[srcs[i]]                                  // moved by then
+  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.
+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.
@@ -513,15 +526,15 @@ If nothing exposes readiness, that's the bug: add the event or the promise to th
 
 ### 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.
+**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.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])
 ```
 
@@ -535,9 +548,17 @@ Wire and on-disk formats use `compact-encoding` — positional, length-prefixed,
 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) } }
+  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) }
+  }
 }
 ```
 
@@ -555,7 +576,7 @@ Each dependency is maintained forever — its bugs, breaking changes, security s
 - **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.
+The governing question is the complexity check again: _is there a simpler way to execute the ambition?_ Often it's no dependency at all.
 
 ---
 
@@ -585,9 +606,9 @@ test('basic append and read', async function (t) {
 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.
+- **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.
+- **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.
@@ -596,9 +617,9 @@ What "test the API" means here:
 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
+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.
@@ -607,7 +628,7 @@ The test then reads as the scenario it describes, and lifecycle correctness live
 
 ## 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.
+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.
@@ -615,7 +636,7 @@ Apply to any module, regardless of size or visibility. When reviewing, walk it a
 - [ ] 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.
+- [ ] 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.
@@ -647,4 +668,4 @@ This skill governs the shape of the code. The others cover surfaces and workflow
 - Reviewing a PR or a local diff against these rules → **pr-review**.
 - The KV cache, the context window and the overflow ladder → **kvcache**.
 
-Commit, branch, and PR-delivery workflow lives in [`CLAUDE.md`](../../../CLAUDE.md).
+Commit and branch rules live in [`CLAUDE.md`](../../../CLAUDE.md); how a PR itself is shaped and delivered is **pr-create**.

package/.claude/skills/kvcache/SKILL.md

@@ -11,19 +11,19 @@ common wrong turns.
 
 This repo owns the cache: `lib/capabilities/completion.ts` (the `kvCache` key,
 the round loop, the overflow ladder), `lib/context-window.ts`,
-`lib/models/kv-cache.ts` and `lib/models/model-pool.ts`. The *prompt* side —
-folding a chat's history so it fits — is `@qvac/core`'s `lib/compaction.ts`;
+`lib/models/kv-cache.ts` and `lib/models/model-pool.ts`. The _prompt_ side —
+folding a chat's history so it fits — is `@qvac/core → lib/compaction.ts`;
 see its **compaction** skill before proposing anything that shrinks history.
 
 ## The one thing to internalise
 
 Three state sets exist and are **never reconciled**:
 
-| Layer | State | Keyed by |
-| --- | --- | --- |
-| caller (`@qvac/core`) | message **list** (shrinks only on an overflow retry) | chat |
-| SDK | message **count** (`savedCount`) | cache file path |
-| addon | token **positions** (`nPast`) + the on-disk `.bin` | cache key |
+| Layer                 | State                                                | Keyed by        |
+| --------------------- | ---------------------------------------------------- | --------------- |
+| caller (`@qvac/core`) | message **list** (shrinks only on an overflow retry) | chat            |
+| SDK                   | message **count** (`savedCount`)                     | cache file path |
+| addon                 | token **positions** (`nPast`) + the on-disk `.bin`   | cache key       |
 
 Almost every bug here is drift between those three, not context pressure.
 `savedCount` means "already sent", never "still resident": nothing below the