refactor(evm-wallet-experiment): rename simulation.md→demo-local.md and interactive-*.mjs→demo-*.mjs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: grypez

PR.md

@@ -0,0 +1,67 @@
+# feat(evm-wallet): split coordinator-vat into home/away coordinators with semantic grant types
+
+## Summary
+
+Splits the monolithic 3,275-line `coordinator-vat` into four focused components — home coordinator, away coordinator, delegator vat, and redeemer vat — and replaces raw caveat bytes with a discriminated union of decoded semantic grant types.
+
+**Architecture before:**
+
+```
+coordinator-vat (3,275 lines)   — home and away concerns mixed together
+delegation-vat  (211 lines)     — limited grant handling
+delegation-grant.ts             — builds grants from raw CaveatSpec arrays
+```
+
+**Architecture after:**
+
+```
+home-coordinator (2,388 lines)  — keyring, signing, delegation building, peer-relay relay
+delegator-vat    (245 lines)    — caveat encoding, unsigned grant construction
+away-coordinator (1,999 lines)  — grant reception, typed delegation routing
+redeemer-vat     (57 lines)     — away-side grant storage
+delegation-twin                 — semantic execution wrapper per grant
+```
+
+## Commits
+
+### 1. refactor: replace DelegationGrant with discriminated union and slim method-catalog
+
+Removes `CaveatSpec` and the old `DelegationGrant` type (raw caveat bytes on the away side). Replaces with `TransferNativeGrant | TransferFungibleGrant` — a discriminated union where each variant carries pre-decoded semantic fields (`to`, `maxAmount`, `token`) alongside the signed `Delegation`. The away side never decodes caveat bytes; the home encodes once at grant-build time. Slims `method-catalog` to the two methods this refactor introduces.
+
+### 2. feat: add delegator-vat for home-side grant building
+
+Vat that encodes caveats and constructs unsigned grants on the home side. Exposes `buildTransferNativeGrant`, `buildTransferFungibleGrant`, `storeGrant`, `removeGrant`, `listGrants` — all persisted in baggage.
+
+### 3. feat: add redeemer-vat for away-side grant storage
+
+Minimal 55-line away-side store for `DelegationGrant` values received from home, keyed by `delegation.id` and persisted in baggage.
+
+### 4. feat: add home-coordinator as home-side split of coordinator-vat
+
+Owns all home-side wallet infrastructure: keyring, provider, external signer, ERC-20, smart accounts, and OcapURL issuance. Delegation building is a three-step flow via delegator-vat. Exposes `homeSection` (direct transfer fallback for the away coordinator) and `redeemDelegation` (delegation UserOp relay for peer-relay mode kernels that have no local bundler).
+
+### 5. feat: rewrite delegation-twin for semantic grant enforcement
+
+`makeDelegationTwin({ grant, redeemFn })` returns a discoverable exo that enforces the grant's constraints locally before submitting an `Execution`:
+
+- **transferNative**: recipient and amount guards via `M.interface`
+- **transferFungible**: token match, optional recipient, cumulative spend tracked with reserve-before-await rollback; concurrent calls cannot together exceed the budget
+
+`DelegationSection` is a discriminated union carrying `method` and (for fungible) `token` — used by the away coordinator to filter matching sections and propagate constraint errors rather than silently falling through to home.
+
+### 6. feat: add away-coordinator with delegation routing and peer-relay support
+
+Owns all away-side wallet infrastructure. Delegation routing:
+
+- `receiveDelegation(grant)` — persists to redeemer-vat, rebuilds delegation sections
+- `transferNative` / `transferFungible` — filter sections by method (and token); if any matched sections exist, errors propagate rather than falling back to `homeSection`; `homeSection` fallback only when no sections match
+- `makeRedeemFn` — submits locally when bundler/smart account available; relays to `homeCoordRef.redeemDelegation()` in peer-relay mode so budget tracking accumulates correctly even without a local bundler
+- `connectToPeer(ocapUrl)` — redeems URL, fetches `homeSection`, rebuilds routing
+
+### 7. refactor: remove coordinator-vat, delegation-vat, delegation-grant
+
+Deletes the monolithic coordinator-vat, the old delegation-vat superseded by delegator-vat/redeemer-vat, and `delegation-grant.ts` whose role belongs to delegator-vat.
+
+### 8. test: migrate Docker e2e tests to new coordinator API
+
+Migrates the Docker e2e suite from the old `createDelegation`/`provisionTwin`/`pushDelegationToAway`/`sendTransaction` API to the new `buildTransferNativeGrant`/`receiveDelegation`/`transferNative`/`transferFungible` API. Fixes `callVat` in the docker test helper to pass `--raw` to the CLI and decode smallcaps CapData inline, correcting BigInt values that arrived as `'1000000000000000000n'` strings.

docs/testing-overview.md

@@ -0,0 +1,182 @@
+# Monorepo testing overview
+
+This document maps **how tests are organized**, **which commands run what**, and **how CI fits in**. It is aimed at humans who want a single mental model—and at planning simplifications.
+
+---
+
+## Two different “default” test flows
+
+The repo effectively has **two parallel ways** to run automated tests:
+
+| Flow                  | Command               | Mechanism                                               | Typical use                                 |
+| --------------------- | --------------------- | ------------------------------------------------------- | ------------------------------------------- |
+| **CI / coverage**     | `yarn test`           | Root `vitest.config.ts` with `projects: ['packages/*']` | GitHub Actions “Test” job, local coverage   |
+| **Developer / Turbo** | `yarn test:dev:quiet` | `turbo run test:dev:quiet` (depends on `^build`)        | Fast feedback, per-package `test:dev:quiet` |
+
+They are **not** the same:
+
+- **`yarn test`** runs Vitest once at the repo root and discovers **all** `packages/*` as Vitest projects (each package’s own `vitest.config.ts` still applies as a **project** merge).
+- **`yarn test:dev:quiet`** runs **only** workspaces that define `test:dev:quiet`, after **building dependencies** via Turborepo (`turbo.json` lists `test:dev` / `test:dev:quiet` with `dependsOn: ["^build"]`).
+
+**Implication:** A package can pass in one flow and behave differently in the other if build artifacts or config merging differ. Prefer documenting “CI runs X, local fast loop runs Y” explicitly.
+
+---
+
+## Root scripts (cheat sheet)
+
+| Script                  | What it does                                                                                              |
+| ----------------------- | --------------------------------------------------------------------------------------------------------- |
+| `yarn test`             | Root Vitest, all workspace projects; coverage enabled per root config                                     |
+| `yarn test:dev`         | Turbo → each package’s `test:dev`                                                                         |
+| `yarn test:dev:quiet`   | Turbo → each package’s `test:dev:quiet` (silent reporter)                                                 |
+| `yarn test:integration` | `yarn workspaces foreach --all run test:integration` — **only workspaces that define** `test:integration` |
+| `yarn test:e2e`         | `foreach --all run test:e2e` — only workspaces that define `test:e2e`                                     |
+| `yarn test:e2e:ci`      | `foreach --all run test:e2e:ci` — CI-oriented entrypoints per package                                     |
+| `yarn test:e2e:local`   | `foreach --all run test:e2e:local` — today essentially **`@ocap/kernel-test-local` only**                 |
+
+Yarn **skips** workspaces that do not define the script (no failure).
+
+---
+
+## Vitest layout (global)
+
+- **Root** [`vitest.config.ts`](../vitest.config.ts): `projects: ['packages/*']`, `pool: 'threads'`, default `testTimeout: 2000`, **global** `setupFiles` including **`vitest-fetch-mock`** (via `@ocap/repo-tools/test-utils/fetch-mock`).
+- **Packages** usually use `@ocap/repo-tools/vitest-config` **`mergeConfig`** with the root config and `defineProject({ test: { name: '…' } })` to add package-specific `setupFiles`, `include`/`exclude`, timeouts, etc.
+
+### Global setup footguns
+
+1. **`vitest-fetch-mock`** (root) — Mocks **`fetch`**. Any test that needs a **real** HTTP client to `localhost` (Docker Anvil, local servers) will see empty or wrong bodies unless the test project **opts out** (separate Vitest config with `setupFiles: []`, or exclude those files from the default project). **`@ocap/evm-wallet-experiment`** Docker E2E is an example: excluded from the main project; run with `yarn test:e2e:docker` and `vitest.config.docker.ts`.
+2. **`endoify` vs `mock-endoify`** — Kernel-ish packages pick different setup files (`@metamask/kernel-shims/endoify-node`, `mock-endoify`, or real `endoify.js` for some E2E). Mixing these affects lockdown / SES behavior.
+3. **`testTimeout: 2000`** at root — Fine for unit tests; packages that need longer runs override in their project (e.g. kernel tests, E2E configs).
+
+---
+
+## Categories of tests (vocabulary)
+
+| Term in this repo                            | Meaning                                                                          | Examples                                                                                |
+| -------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| **Unit**                                     | Vitest, co-located `*.test.ts`, no external services                             | Most `packages/*/src/**/*.test.ts`                                                      |
+| **Integration** (script: `test:integration`) | Separate Vitest config, often `pool: 'forks'`, different `setupFiles` / env      | `kernel-cli`, `kernel-browser-runtime`, `evm-wallet-experiment` (`test/integration/**`) |
+| **E2E** (script: `test:e2e`)                 | **Not one technology**: Vitest extra config, **Playwright**, or **Node drivers** | See below                                                                               |
+| **Docker E2E**                               | Vitest against **Docker Compose** stack (Anvil, bundler, kernels)                | `evm-wallet-experiment` → `yarn test:e2e:docker`                                        |
+| **Local E2E**                                | Vitest, **external LMS** (Ollama / llama-cpp), not in default CI                 | `kernel-test-local` → `yarn test:e2e:local`                                             |
+| **KLMS E2E**                                 | Vitest hitting real **Ollama** / API                                             | `kernel-language-model-service` → `yarn test:e2e` in that package                       |
+
+---
+
+## Packages with non-standard test entrypoints
+
+### `@ocap/kernel-test`
+
+- **Role:** Kernel tests that **spin up / talk to vats** (see package description).
+- **Scripts:** Standard `test` / `test:dev` / `test:dev:quiet` only.
+- **Config:** `endoify-node` setup, longer `testTimeout`, coverage thresholds unless `development` mode.
+
+### `@ocap/kernel-test-local`
+
+- **Role:** **Local-only** flows (e.g. agents + **Ollama**); not assumed available in CI.
+- **Unit-ish Vitest:** `vitest.config.ts` — `include: ./src/**/*.test.ts`, **`exclude: **/\*.e2e.test.ts`\*\*.
+- **Local E2E:** `test:e2e:local` → `vitest.config.e2e.ts` — includes `*.e2e.test.ts` and `./test/**/*.test.ts`, long timeouts.
+- **Helpers:** `test:e2e:local:llama-cpp` sets `LMS_PROVIDER=llama-cpp`.
+
+### `@ocap/evm-wallet-experiment`
+
+| Script                     | Purpose                                                                                                  |
+| -------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `test` / `test:dev*`       | Main Vitest; **`test/integration/**` excluded**; **`test/e2e/docker/**` excluded** (fetch mock conflict) |
+| `test:integration`         | `vitest.config.integration.ts` → `test/integration/**`                                                   |
+| `test:e2e:docker`          | `vitest.config.docker.ts` — Docker Compose E2E, **no fetch mock**, `pool: 'forks'`                       |
+| `test:e2e` / `test:e2e:ci` | **Node** driver: `test/e2e/run-all-e2e.mjs` (after `yarn build`)                                         |
+| `test:node`, `test:node:*` | Additional **Node** integration/e2e scripts (wallet, peer, Sepolia, etc.)                                |
+
+CI **E2E matrix** runs `yarn workspace @ocap/evm-wallet-experiment test:e2e:ci` (the Node runner), **not** `test:e2e:docker`—Docker Compose is **manual / optional** unless added to CI.
+
+### `@ocap/kernel-language-model-service`
+
+- **Unit:** default `vitest.config.ts`.
+- **`test:e2e`:** `vitest.config.e2e.ts` — `include: test/e2e/**`, real **endoify** setup; hits real services (e.g. Ollama).
+
+### `@metamask/kernel-node-runtime`
+
+- **`test:e2e`:** Vitest `vitest.config.e2e.ts`.
+- **`test:e2e:ci`:** Shell script: bundle + serve test vats, then `yarn test:e2e`.
+
+### `@ocap/kernel-cli`
+
+- **`test:e2e` / `test:integration`:** Separate Vitest config files (`vitest.e2e.config.ts`, `vitest.integration.config.ts`).
+- **`test:e2e:ci`:** Same as `test:e2e`.
+
+### `@metamask/kernel-browser-runtime`
+
+- **`test:integration`:** `vitest.integration.config.ts` (browser-oriented integration).
+
+### `@ocap/extension` and `@ocap/omnium-gatherum`
+
+- **`test:e2e`:** **Playwright** (`yarn playwright test`).
+- **`test:e2e:ci`:** Extension uses a **wrapper script** (build, bundle kernel-test vats, serve, then Playwright). Omnium uses `yarn test:e2e` directly.
+
+### `@ocap/omnium-gatherum` / `@ocap/extension` (extra)
+
+- **`test:build`:** TSX build tests (distinct from Vitest unit tests).
+
+---
+
+## CI (`.github/workflows/lint-build-test.yml`)
+
+Rough pipeline:
+
+1. **Lint** — `yarn lint`
+2. **Build** — `yarn build`
+3. **Test** — `yarn build` then **`yarn test --coverage=…`** (root Vitest + projects)
+4. **Integration** — `yarn build` then **`yarn test:integration`** (only packages with that script)
+5. **E2E** — matrix on Node 24, `VITE_DB_FOLDER=e2e yarn build`, then **`yarn workspace <pkg> test:e2e:ci`** for:
+   - `@metamask/kernel-node-runtime`
+   - `@ocap/extension`
+   - `@ocap/omnium-gatherum`
+   - `@ocap/evm-wallet-experiment`
+
+**Not run in that workflow by default:**
+
+- **`yarn test:dev` / `yarn test:dev:quiet`** (Turbo)
+- **`kernel-test-local`** `test:e2e:local` (needs local Ollama / llama-cpp)
+- **`evm-wallet-experiment`** `test:e2e:docker` (needs Docker Compose stack)
+- **`kernel-language-model-service`** `test:e2e` against live Ollama (unless added elsewhere)
+- **`@metamask/kernel-cli`** `test:e2e` / `test:e2e:ci` — defined on the package but **not** in the E2E matrix; only runs if you invoke the workspace script or a future `yarn test:e2e` full foreach locally
+
+Playwright browsers: **playwright-install** action is used for the Test and E2E jobs.
+
+---
+
+## Turborepo
+
+[`turbo.json`](../turbo.json) only wires **`build`**, **`build:dev`**, **`test:dev`**, **`test:dev:quiet`**. Other scripts (`test`, `test:integration`, `test:e2e*`) are **not** Turbo tasks—run them via root `yarn …` or per workspace.
+
+---
+
+## Simplification ideas (for discussion)
+
+1. **Name alignment** — Today “E2E” means Vitest, Playwright, Node scripts, or Docker. Consider prefixes in docs/scripts: `test:e2e:vitest`, `test:e2e:playwright`, `test:e2e:node`, `test:e2e:docker` (even if kept as aliases).
+2. **Single “full local checklist” doc** — One section: “Before push: `yarn lint`, `yarn build`, `yarn test`, `yarn test:integration`”; optional: “With Docker: …”, “With Ollama: …”.
+3. **CI vs dev parity** — Decide whether **`yarn test:dev:quiet`** should mirror CI more closely (e.g. document that CI uses **`yarn test`**, not Turbo).
+4. **Fetch mock** — Document in contributor guide: “Tests that need real `fetch` must not inherit root `setupFiles`” (pattern: separate config + dedicated script, as with Docker E2E).
+5. **Consolidate `test:e2e` vs `test:e2e:ci`** — Where they are identical (e.g. omnium, kernel-cli), one script could delegate to the other to reduce duplication; where they differ (extension, kernel-node-runtime), keep both and document why.
+6. **Optional CI job** — `evm-wallet` Docker E2E as a manual or nightly workflow with compose, if the team wants regression coverage without slowing every PR.
+7. **`kernel-test` vs `kernel-test-local`** — Names are good; a one-line diagram in README (“kernel-test = in-process vats; kernel-test-local = needs Ollama”) helps onboarding.
+
+---
+
+## File index (quick)
+
+| Area                    | Config / driver                                               |
+| ----------------------- | ------------------------------------------------------------- |
+| Root Vitest             | `vitest.config.ts`                                            |
+| Turbo                   | `turbo.json`                                                  |
+| Docker E2E (evm-wallet) | `packages/evm-wallet-experiment/vitest.config.docker.ts`      |
+| Local agent E2E         | `packages/kernel-test-local/vitest.config.e2e.ts`             |
+| KLMS service E2E        | `packages/kernel-language-model-service/vitest.config.e2e.ts` |
+| evm-wallet integration  | `packages/evm-wallet-experiment/vitest.config.integration.ts` |
+| Fetch mock setup        | `packages/repo-tools/src/test-utils/env/fetch-mock.ts`        |
+
+---
+
+_Generated for navigation and planning; update when scripts or CI change._