@qvac/harness 0.2.8 → 0.2.10

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

@@ -1,171 +0,0 @@
----
-name: kvcache
-description: Reason about the QVAC SDK KV cache, the context window and ContextOverflow in @qvac/harness — including why the sliding window (n_discarded) and dynamic tools (toolsMode) were retired. Use when touching prompt-cache keys, the overflow ladder, TTFT regressions, context-overflow errors, cache invalidation on retry/regenerate, or when debugging "the model forgot the conversation". Read this BEFORE proposing any caller-side history eviction.
----
-
-# KV cache + context window
-
-Read **[docs/kvcache-reference.md](../../../docs/kvcache-reference.md)** — how it
-works and the rules for using it. The summary below is just enough to stop the
-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 → 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       |
-
-Almost every bug here is drift between those three, not context pressure.
-`savedCount` means "already sent", never "still resident": nothing below the
-SDK reports what it evicted. That is what made the retired sliding window and
-dynamic-tools trim fatal, and it is the test for any new eviction idea.
-
-## The knobs (two)
-
-- `history`: the full history goes to `completion()`; the SDK computes the delta.
-- `cacheKey: 'chat-<chatId>'` — set by the caller, consumed here at
-  [lib/capabilities/completion.ts](../../../lib/capabilities/completion.ts).
-  An accepted diagram repair primes under a child of it (`chat-<chatId>/r<n>`),
-  so deleting the chat key reclaims every generation.
-
-Nothing else. `n_discarded` and `toolsMode` are gone from the stack, not just
-unset.
-
-**No client-side token math, ever.** Use the SDK's real `cacheTokens` /
-`promptTokens` / `generatedTokens` from `completion()` stats, and react to the
-typed `ContextOverflowError`. Never estimate chars-per-token, never reserve a
-response budget. To A/B the cache, drop `cacheKey` locally.
-
-If you encounter `RESERVED_FOR_RESPONSE`, a chars-per-token estimator,
-`windowHistoryToFit`, or `toolsThatFit` anywhere, that is retired code — not the
-shipping path, and none of it should come back.
-
-## Retired knobs
-
-Both were dropped on 2026-08-20 and have since been deleted upstream. Kept here
-as bug shapes, not as options.
-
-- **Sliding window (`n_discarded`).** SDK 0.19 dropped it from the `loadModel`
-  schema (rejected at validation) and addon 0.48 removed sliding outright. Why
-  it had to go: a slide was invisible to the SDK — it recorded the turn's full
-  message count and next sent `history.slice(savedCount)`, so the discarded span
-  was gone from the KV, never re-sent, and the model silently lost the middle of
-  the chat. While sliding was possible the tool block also travelled with every
-  turn (`toolBlockEvictable`, ~331 tokens for a 4-tool agent). A full window is
-  now a normal end state, recovered by the ladder and by the caller's fold.
-- **Dynamic tools (`toolsMode: 'dynamic'`).** SDK 0.18 deleted the key (its
-  parser rejects it); the addon dropped `tools_compact` after 0.39.4. It was a
-  no-op on every shipped model — the addon gate is exact-arch `qwen3`, ours are
-  `qwen35`/`qwen36` — while the SDK still sliced as-if-dynamic: the previous
-  answer was duplicated into the KV every turn and, on a cold cache, only the
-  last exchange was sent instead of overflowing. Static placement is the only
-  mode: `history.slice(savedCount)`, full history on a cold cache at TTFT cost
-  only, which is also what makes the overflow ladder effective.
-
-Full history: [2026-08-20-kvcache-static-placement](https://github.com/tetherto/qvac-app/blob/main/docs/decisions/2026-08-20-kvcache-static-placement.md),
-still in `tetherto/qvac-app`.
-
-## Hard facts that trip people up
-
-- **A slice at or above `ctx_size` can never be admitted.** Nothing is decoded
-  yet, so there is nothing to evict — and nothing evicts anyway.
-- **Overflow is a normal end state:** every long chat legitimately reaches ctx,
-  recovered by the ladder and by the caller's fold for any window at or above
-  4,096. Also legitimate: the current prompt alone exceeds ctx, a tool result
-  alone exceeds ctx, or a device that has never run this chat getting the whole
-  history (the cache is **device-local**). Anything else is a drift bug.
-- **A thrown overflow keeps the cache** (SDK 0.19,
-  [qvac#4163](https://github.com/tetherto/qvac/pull/4163)): a prefill
-  `ContextOverflowError` or an addon pre-mutation refusal releases the turn and
-  the committed `.bin` survives. What still destroys it: a turn that hits the
-  ceiling **mid-generation** (addon `stopReason=contextOverflow`, surfaced as
-  `length`) is not committed — its file is unlinked and the next turn
-  cold-primes from history.
-- **The tool block is not in the primed prefix** (since 0.17.1): the prime is
-  the system prompt alone. The block travels with the first turn that renders it
-  (the SDK requires a user message before believing it landed) and is skipped
-  once `toolBlockCached` is recorded at commit. It is never trimmed back out, so
-  `configHash` hashes the system prompt **plus the full tool definitions** — any
-  tool-set, description, or parameter change re-keys the file and costs a cold
-  prime. A skill activation and a `disabledToolsets` edit each do that once and
-  then hold. The block is NOT a fixed size — it is whatever the agent's
-  `enabledTools` serializes to; read `round start { tools }` and
-  `round stats { promptTokens }` from the harness log, never assume a figure.
-- **`modelId` is identity-by-config**: `sha256(type:src:sortedConfig)[:16]`. ANY
-  `modelConfig` field change — including `verbosity` from `QVAC_LLM_VERBOSITY` —
-  is a new `modelId`, a new cache directory, and a cold prime for every chat.
-  Debug the cache with `QVAC_HARNESS_LOG`/`xxd`, never by raising addon
-  verbosity. The system prompt is NOT in `modelId` (it is in `configHash`, the
-  file name): a prompt edit cold-primes one chat, a config edit cold-primes all.
-- **The addon compacts reasoning out of the KV itself.**
-  `remove_thinking_from_context` defaults to `true` (addon 0.33.0); since 0.48 it
-  rewinds to the block boundary and re-decodes what it keeps. `cacheTokens`
-  after a turn excludes thinking, so nothing above has to strip it.
-- **`ContextOverflowError` carries sizes** (0.19): `requiredTokens`, `ctxSize`,
-  `cachedTokens` on the warm guard, and `promptTokens` only when the guard
-  counted tokens. The harness matches the error by `name` (`CONTEXT_OVERFLOW`)
-  and reads none of them.
-
-## Before proposing caller-side eviction
-
-Ask whether the SDK cache would already handle it. The answer is yes for
-ordinary history growth; the cases that genuinely need handling above the SDK
-are a message (or tool result) larger than `ctx_size`, plus the cross-device
-cold start. Anything else is re-implementing the cache badly.
-
-**Compaction is the one sanctioned exception, and it already exists in
-`@qvac/core` — do not build a second one here.** It evicts from the prompt,
-never from the KV; it uses the SDK's own `cacheTokens` rather than token math;
-and it invalidates the chat key when a fold lands. The floor is
-`COMPACTION_MIN_CTX_SIZE` (4,096): below it a fold cannot pay for the ~420-token
-prefix it shares the window with, so those chats stay on the ladder here.
-
-## Debugging
-
-- `round stats { round, wallMs, TTFT, TPS, cacheTokens, promptTokens }` and
-  `round start { round, turns, tools }` — the per-round `hlog` in
-  [lib/capabilities/completion.ts](../../../lib/capabilities/completion.ts).
-  `cacheTokens` dropping back to system-prompt size mid-chat = a re-prime.
-  `turns` shrinking across an overflow with an identical outcome = an inert
-  ladder.
-- SDK `logMessagesToAddon` tags: `PROMPT_SEND` / `CACHE_INIT` / `NO_CACHE`. A
-  `CACHE_INIT` mid-chat is a re-prime.
-- No addon line reports eviction any more: `discarded N tokens`,
-  `[ContextSlider]` and `runtimeStats().contextSlides` left with sliding in
-  addon 0.48. A log that shows them is an old build.
-- Cache files: `{kvCacheDir}/{cacheKey}/{modelId}/{configHash}.bin`. Two files
-  under one chat key means `configHash` changed — a volatile system prompt costs
-  one cold prime per turn.
-
-## Versions — check these first
-
-**This behaviour is version-specific and has changed before.** Start every task
-here:
-
-```bash
-grep '"@qvac/sdk"' package.json
-grep '"version"' node_modules/@qvac/inference/package.json node_modules/@qvac/llm-llamacpp/package.json
-```
-
-This repo pins **`@qvac/sdk` 0.19.0** → **`@qvac/inference` 0.19.0** →
-**`@qvac/llm-llamacpp` 0.49.1**. Since 0.19 `@qvac/sdk` is a thin re-export over
-`@qvac/inference`, and the `#sdk` import seam resolves to `@qvac/inference`
-in-process on Bare — so the cache code that runs is
-`node_modules/@qvac/inference/dist/plugins/builtin/llamacpp-completion/ops/`
-(`completion-stream.js`, `kv-cache-session.js`, `context-overflow.js`), not
-anything under `@qvac/sdk/dist`. If the shipped numbers move past these, re-read
-before acting.
-
-Whenever you re-verify something, update the Versions section in
-[docs/kvcache-reference.md](../../../docs/kvcache-reference.md) in the same
-commit.

package/.claude/skills/pr-create/SKILL.md

@@ -1,180 +0,0 @@
----
-name: pr-create
-description: Write the title, body and commits for a pull request in @qvac/harness, and decide the conventional-commit type for a change — `fix` is reserved for user-facing defects in a released version. Use when opening a PR here, splitting work into a stack, or choosing between `fix` and `chore`.
----
-
-# PR creation
-
-`@qvac/harness` is a published package. The log is the only durable record of intent,
-and for this repo it is also the changelog a consumer reads before upgrading.
-
-## Title
-
-```
-type(scope): subject
-```
-
-Imperative, lowercase after the colon, no trailing period. Scope optional, and
-only when it narrows something real. What and why, not how.
-
-```
-feat: publish the sidecar entry, so spawning it needs no bundle
-fix(publish): repoint dynamic imports at dist-lib too
-refactor: own the schema codegen tooling
-chore: regenerate the schema
-```
-
-There is no ticket prefix here, and no title validator in CI. That is not
-licence to be loose: nothing will catch a bad title but a reviewer.
-
-## Types
-
-```
-build  chore  ci  docs  style  refactor  perf  test  fix  feat
-```
-
-**`fix` is reserved for a defect a consumer of a released version could hit.**
-It is the line someone reads to decide whether to upgrade, so it claims real
-breakage in something already published.
-
-| The change                                                  | Type                                               |
-| ----------------------------------------------------------- | -------------------------------------------------- |
-| Breaks a consumer on a published version                    | `fix`                                              |
-| Repairs code that has never shipped (same release cycle)    | `chore`                                            |
-| Repairs the build, the bundle, or what lands in the tarball | `build` or `fix` if a published artifact was wrong |
-| Repairs CI, a workflow, an action pin                       | `ci`                                               |
-| Repairs or adds a test                                      | `test`                                             |
-| Repairs a lint/type error                                   | `chore`                                            |
-| Pure move or rename, no behaviour change                    | `refactor`                                         |
-| New capability, new export, new flag                        | `feat`                                             |
-| README, comments, docs                                      | `docs`                                             |
-
-When a repair is on unreleased code, check the last release tag: if the bug was
-never in a published version, it is `chore`, not `fix`.
-
-Never relabel a real defect as `chore` to make the log quieter, and never
-inflate a cleanup into `fix` to make it look urgent.
-
-## Scopes
-
-Optional, and taken from what the diff actually touches — `lib`, `worker`, `schema`, `spec`, `scripts`, `test`, `ci`, `publish`, or a capability name (`completion`, `tools`, `models`).
-A scope that restates the type (`fix(fix)`) or names the whole repo adds
-nothing; leave it off.
-
-## Decision records
-
-`docs/decisions/` holds the durable, non-obvious choices — why a boundary is
-where it is, why an approach was rejected. They are reference for a future
-reader, **not rules, and not to be loaded by default**.
-
-Add one when this PR settles something a later reader would otherwise have to
-reverse-engineer from the diff: a runtime or storage boundary, a wire-format or
-schema choice, a build or publish constraint, a rejected alternative that will
-look obvious later. Do not add one for a bug fix, a rename, or anything the code
-already says plainly.
-
-Copy `docs/decisions/TEMPLATE.md`, give it a `status`, list it once in
-`INDEX.md`, and name it in the PR's Decisions section. `node
-scripts/docs-audit.cjs` checks all of that, and CI runs it.
-
-An **active** record may cite only paths that exist here; a path in another
-repository is written `@qvac/harness → lib/x.ts` so the audit treats it as
-context rather than a local file. A superseded record is exempt — it describes
-how things used to be.
-
-### One PR, one type
-
-The commits carry conventional-commit types, so the mix of types _is_ the scope
-statement. `feat:`, `fix:` and `chore:` on one branch is not a well-rounded
-change, it is three changes sharing a branch, and a reviewer has to hold all
-three while judging any one of them.
-
-List them before writing the body:
-
-```bash
-git log --format='%s' main..HEAD | grep -oE '^[a-z]+' | sort -u
-```
-
-- **One type** is the PR's type.
-- **A dominant type plus its own tests or docs** (`feat` + `test`, `fix` +
-  `docs`) is fine; the dominant one wins.
-- **Unrelated types** means split the PR, or stack it.
-
-## Small PRs, stacked
-
-A PR is read by a human, so it has to fit in one head. Default to one concern.
-When a change decomposes into dependent steps, do not grow one PR to fit them —
-stack them, so each step is reviewable alone and lands in order.
-
-- A large refactor belongs on a `refactor/...` branch with `refactor:` commits.
-- **Refactor commits never live inside a non-refactor branch.** A `feat/` branch
-  that also reshuffles unrelated code is two PRs. Behaviour changes and pure
-  moves are reviewed differently, and mixing them hides both.
-- A pure rename or move lands _before_ the change that depends on it, as its own
-  commit or its own PR in the stack.
-
-Branch names must never contain `codex`, `cursor`, or `claude` (case
-insensitive). Use a neutral name before committing or pushing.
-
-## Body
-
-`.github/pull_request_template.md` pre-fills the headings. Keep its shape, fill
-what applies, and delete the sections that would be empty — an absent section
-says more than one saying "n/a". The template's own order is Why, What, Testing,
-Decisions; the expanded form below is what each should contain.
-
-```markdown
-## What
-
-One paragraph. The change, in the reviewer's terms.
-
-## Why
-
-The problem this solves, or the decision it implements. Link the issue,
-PR, or upstream change that forced it.
-
-## How
-
-Only the parts a reader would not infer from the diff: the seam that moved,
-the invariant being preserved, the thing that looks wrong but isn't.
-
-## Testing
-
-What you ran, and what it proved. ``bun run test` (node, bare and addon lanes)` at minimum.
-Say plainly when something could not be tested locally and why.
-```
-
-For a **breaking change**, say so in the body under its own `## Breaking`
-heading, with the migration a consumer has to perform. Published package —
-this is the only warning they get.
-
-## Before opening
-
-1. Check the branch is not `main` and the name is neutral.
-2. `git log --oneline main..HEAD` — every commit is a conventional commit, and
-   each one is a change you would defend on its own. A trail of `wip`,
-   `fixup` or `address review` commits is not history; reshape it before
-   opening.
-3. `bun run lint` and ``bun run test` (node, bare and addon lanes)` pass locally. CI runs the same lanes; a
-   red PR wastes a reviewer's round trip.
-4. Rebase on `main` rather than merging it in. A merge commit in the branch
-   makes the diff unreadable.
-5. Open as a **draft** unless you are asking for review right now.
-
-```bash
-gh pr create --repo tetherto/qvac-harness --draft --title "type(scope): subject" --body-file <path>
-```
-
-Never push to `main`, never force-push a branch someone else is reviewing, and
-never open a PR that carries commits you did not write without saying so.
-
-## Version bumps
-
-Release PRs in this repo are titled by version alone (`0.2.4 (#32)`,
-`release/0.1.4 (#40)`). They carry the version bump and nothing else — do not
-fold a bump into a feature PR, and do not fold a feature into a bump.
-
-## Sibling skills
-
-- Reviewing a PR or a local diff → **pr-review**.
-- How the code itself should be shaped → **js-house-style**.