mirror of
https://github.com/ruvnet/RuView
synced 2026-07-30 18:41:42 +00:00
feat(homecore): add WASM-first developer metaharness (#1477)
Adds the accepted ADR-285 Homecore metaharness, WASM-first kernel, read-only MCP guidance, guarded local host adapters, reviewed memory, and provenance-only npm release gates.
This commit is contained in:
rUv
@@ -0,0 +1,230 @@
|
||||
# ADR-285: WASM-first Homecore developer metaharness via `npx homecore`
|
||||
|
||||
- **Status**: Accepted — implemented and validated
|
||||
- **Date**: 2026-07-29
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: homecore, metaharness, wasm, mcp, npm, codex, claude-code
|
||||
|
||||
## Context
|
||||
|
||||
Homecore is now a multi-crate Rust subsystem with a concurrent state machine,
|
||||
startup restore, recorder, automation engine, authenticated Home
|
||||
Assistant-compatible REST/WebSocket core, migration tooling, compiled-in and
|
||||
Wasmtime plugin paths, a network HAP server, and voice/satellite protocol
|
||||
contracts. The implementation is intentionally bounded: features are gated,
|
||||
several deployments require providers or backends, and core compatibility is
|
||||
not the same as parity with the entire Home Assistant integration ecosystem.
|
||||
|
||||
The existing `@ruvnet/ruview` contributor harness contains source-cited
|
||||
Homecore guidance, but it serves the whole RuView repository. Homecore needs a
|
||||
focused entry point that can:
|
||||
|
||||
1. explain current capabilities without overstating maturity;
|
||||
2. lead contributors to the correct source, ADRs, and focused tests;
|
||||
3. exercise Wasmtime and HAP feature gates deliberately;
|
||||
4. expose a small MCP guidance surface;
|
||||
5. delegate exploration to local Claude Code or Codex CLIs at least authority;
|
||||
6. remain removable from the Homecore server runtime.
|
||||
|
||||
The requested user experience is the exact command:
|
||||
|
||||
```bash
|
||||
npx homecore
|
||||
```
|
||||
|
||||
An npm package named `@ruvnet/homecore` can expose a `homecore` binary after it
|
||||
is installed, but `npx homecore` resolves an unscoped package named
|
||||
`homecore`. ADR-265 normally reserves new packages for the `@ruvnet` scope, so
|
||||
the executable naming decision requires an explicit, narrow exception.
|
||||
|
||||
## Decision
|
||||
|
||||
Create `harness/homecore/` as an independently testable npm package named
|
||||
`homecore`, with the `homecore` binary. This unscoped package is the executable
|
||||
front door only. Future import-oriented libraries remain under `@ruvnet/*`.
|
||||
When accepted, this ADR amends ADR-265 only for that one executable package;
|
||||
all other new RuView npm packages remain subject to ADR-265's scoped-name rule.
|
||||
|
||||
The package is developer tooling, not a second Homecore runtime. It may inspect
|
||||
a trusted RuView checkout and run fixed test commands, but it does not start
|
||||
the server, alter home state, migrate user data, modify pairing records,
|
||||
install plugins, or publish changes.
|
||||
|
||||
### 1. WASM-first metaharness kernel
|
||||
|
||||
Pin `@metaharness/kernel` exactly. Unless the operator explicitly chooses a
|
||||
backend with `METAHARNESS_KERNEL_BACKEND`, the harness requests the packaged
|
||||
WebAssembly backend first.
|
||||
|
||||
The loaded kernel validates the MCP server specification. The actual backend
|
||||
is always reported:
|
||||
|
||||
- `wasm` is the preferred result;
|
||||
- a native or JavaScript fallback is allowed for portability;
|
||||
- `homecore wasm status --strict` fails when WASM is unavailable;
|
||||
- fallback execution is never relabelled as WASM.
|
||||
|
||||
The kernel specification and generated host configuration pin the current
|
||||
package version. Packaged project templates invoke an already-installed
|
||||
`homecore` binary; no committed MCP configuration executes
|
||||
`homecore@latest`.
|
||||
|
||||
This kernel boundary is separate from application plugins. Homecore's plugin
|
||||
architecture remains:
|
||||
|
||||
- native plugins are compiled in and registered explicitly;
|
||||
- external packages are bounded, path-checked, signature-verified Wasm;
|
||||
- Wasmtime execution is opt-in through Cargo features;
|
||||
- arbitrary native dynamic libraries are not loaded.
|
||||
|
||||
The `wasm` verification profile runs the Wasmtime-specific plugin and server
|
||||
tests from fixed argument arrays with `shell: false`.
|
||||
|
||||
### 2. CLI and MCP surface
|
||||
|
||||
The CLI provides:
|
||||
|
||||
- source-cited `guidance` and `capabilities`;
|
||||
- reviewed local `brain search`, citation verification, and proposal output;
|
||||
- `doctor` and strict/non-strict WASM diagnostics;
|
||||
- fixed `core`, `wasm`, `hap`, and `full` verification profiles;
|
||||
- skills and tool-schema discovery;
|
||||
- an MCP stdio server;
|
||||
- configuration output for Claude Code and Codex;
|
||||
- guarded local host delegation.
|
||||
|
||||
The MCP server exposes only:
|
||||
|
||||
- `homecore_guidance`;
|
||||
- `homecore_wasm_status`;
|
||||
- `homecore_doctor`;
|
||||
- `homecore_memory_search`.
|
||||
|
||||
All MCP tools are read-only. The fixed verification profiles remain local CLI
|
||||
commands because Cargo writes build artifacts, executes repository code, and
|
||||
may consume substantial resources. There are no MCP tools for test execution,
|
||||
server start, migration writes, pairing, plugin installation, agent
|
||||
delegation, GitHub mutation, release, or publication.
|
||||
|
||||
JSON-RPC request size, queue depth, per-process tool-call budget, output, and
|
||||
tool/subprocess duration are bounded. Tool schemas reject unknown fields.
|
||||
Repository roots are realpath-verified against fixed RuView/Homecore markers.
|
||||
Child processes use argument arrays, `shell: false`, a scrubbed environment,
|
||||
bounded output, and secret redaction. MCP repository access is anchored once
|
||||
at server startup from the launch checkout or `HOMECORE_TRUSTED_REPO`; request
|
||||
arguments cannot self-declare a new trust root.
|
||||
|
||||
### 3. Local Claude Code and Codex adapters
|
||||
|
||||
Both adapters operate on an exact trusted checkout and consume prompts through
|
||||
stdin.
|
||||
|
||||
Codex uses:
|
||||
|
||||
- `codex exec -`;
|
||||
- `-C <trusted-root>`;
|
||||
- `--sandbox read-only` by default;
|
||||
- ephemeral JSONL output;
|
||||
- strict configuration parsing;
|
||||
- ignored user config while repository exec-policy rules remain active.
|
||||
|
||||
Claude Code uses:
|
||||
|
||||
- `claude -p --safe-mode`;
|
||||
- plan mode with read/search tools by default;
|
||||
- JSON output;
|
||||
- no session persistence.
|
||||
|
||||
Workspace writes require both `--allow-write` and `--confirm`. Neither adapter
|
||||
emits a permission or sandbox bypass. Host delegation is CLI-only and is not
|
||||
reachable through MCP, avoiding recursive agent authority.
|
||||
|
||||
### 4. Reviewed guidance and shared brain
|
||||
|
||||
Capability records carry:
|
||||
|
||||
- an honest maturity label;
|
||||
- repository source paths;
|
||||
- fixed validation commands;
|
||||
- explicit limitations.
|
||||
|
||||
Canonical brain records are committed, reviewed, bounded, evidence-labelled,
|
||||
source-relative, and digest-covered. Search is deterministic. `brain propose`
|
||||
prints an unreviewed JSONL candidate and never edits canonical knowledge.
|
||||
Retrieved content is evidence, not instruction or permission. Private vector
|
||||
indexes, overlays, and raw transcripts remain untracked and unpackaged.
|
||||
|
||||
No Darwin/Flywheel candidate can self-promote through this harness. A future
|
||||
learning loop requires a separate reviewed decision and the same frozen
|
||||
holdout, provenance, security, and maintainer gates as ADR-283.
|
||||
|
||||
### 5. Distribution and release
|
||||
|
||||
Extend the ADR-265 npm matrix and provenance-only release workflow to
|
||||
`harness/homecore`. The gate must run on supported Node versions and verify:
|
||||
|
||||
- exact lockfile installation;
|
||||
- tests and security tests;
|
||||
- package version single-sourcing;
|
||||
- an explicit unpacked-size budget and no source maps;
|
||||
- installation and execution from the real tarball;
|
||||
- the WASM backend from the installed tarball;
|
||||
- MCP initialization and exports;
|
||||
- README claim checking;
|
||||
- the package provenance manifest.
|
||||
|
||||
Publication remains CI-only with npm provenance. The release job runs on a
|
||||
trusted-publishing-compatible Node/npm runtime, accepts only `main`, uses the
|
||||
protected `npm-release` environment, and publishes the exact digest-checked
|
||||
tarball that passed smoke tests. The environment must restrict deployment to
|
||||
`main`, require review, and prevent self-review. The unscoped npm name being
|
||||
available during development is not treated as permanent ownership; release
|
||||
must still confirm registry access and package identity.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Contributors get a focused `npx homecore` entry point without coupling the
|
||||
Rust server to an agent framework.
|
||||
- WASM is used for the portable kernel and explicitly exercised for Homecore
|
||||
plugin verification.
|
||||
- Capability guidance can distinguish implemented code, feature gates,
|
||||
provider requirements, ecosystem limitations, and certification boundaries.
|
||||
- Local agent execution is portable across Claude Code and Codex while
|
||||
remaining read-only by default.
|
||||
- MCP authority is small enough to audit and contains no direct home, network,
|
||||
GitHub, or release mutation.
|
||||
|
||||
### Negative
|
||||
|
||||
- `homecore` is a narrow exception to the `@ruvnet/*` package namespace rule.
|
||||
- The package adds one exact runtime dependency for the WASM kernel.
|
||||
- The Wasmtime and HAP verification profiles can be expensive and write Cargo
|
||||
build artifacts.
|
||||
- A packaged guidance catalog can become stale; citation verification and
|
||||
reviewed updates are required.
|
||||
|
||||
### Neutral
|
||||
|
||||
- The harness does not change Homecore's protocol, persistence, migration,
|
||||
plugin, HAP, or voice implementation.
|
||||
- A passing software profile does not establish a production deployment,
|
||||
third-party ecosystem parity, Apple certification, or hardware behavior.
|
||||
- Ruflo remains an optional development coordinator and is not a runtime
|
||||
dependency of `homecore`.
|
||||
|
||||
## Links
|
||||
|
||||
- [ADR-126](ADR-126-ruview-native-ha-port-master.md) - Homecore master decision.
|
||||
- [ADR-128](ADR-128-homecore-integration-plugin-system.md) - plugin boundary.
|
||||
- [ADR-130](ADR-130-homecore-rest-websocket-api.md) - REST/WebSocket contract.
|
||||
- [ADR-133](ADR-133-homecore-assist-ruflo.md) - assist and agent bridge.
|
||||
- [ADR-161](ADR-161-homecore-server-layer-security.md) - server security.
|
||||
- [ADR-165](ADR-165-homecore-migrate-from-home-assistant.md) - migration trust boundary.
|
||||
- [ADR-182](ADR-182-npx-ruview-harness-via-metaharness.md) - RuView metaharness.
|
||||
- [ADR-263](ADR-263-ruview-npm-harness-deep-review.md) - harness hardening.
|
||||
- [ADR-265](ADR-265-ruview-npm-distribution-strategy.md) - npm distribution policy.
|
||||
- [ADR-283](ADR-283-ruview-community-metaharness-flywheel.md) - shared brain and learning gates.
|
||||
- `harness/homecore/`
|
||||
- `v2/docs/homecore-capabilities.md`
|
||||
+2
-1
@@ -9,7 +9,7 @@ Latest proposed decisions:
|
||||
- [ADR-264: Versioned wire protocol for RTL8720F CFR and Range-FFT reports](ADR-264-rtl8720f-radar-wire-protocol.md)
|
||||
- [ADR-263: Adopt RTL8720F 2.4 GHz FMCW radar as an optional RuView sensing platform](ADR-263-rtl8720f-2-4ghz-fmcw-radar-platform.md)
|
||||
|
||||
This folder contains 193 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project. (The index tables below list a curated subset per domain; see the directory listing for the full set.)
|
||||
This folder contains 208 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project. (The index tables below list a curated subset per domain; see the directory listing for the full set.)
|
||||
|
||||
## Why ADRs?
|
||||
|
||||
@@ -142,6 +142,7 @@ Statuses: **Proposed** (under discussion), **Accepted** (approved and/or impleme
|
||||
| [ADR-280](ADR-280-active-sensing-programmable-perception.md) | Active sensing & programmable perception control plane | Accepted (implemented) |
|
||||
| [ADR-281](ADR-281-ble-cs-delay-doppler-pose-factorization.md) | BLE Channel Sounding, delay-Doppler tensors, P3162 import, factorized pose | Accepted (implemented) |
|
||||
| [ADR-282](ADR-282-ruview-ecosystem-positioning.md) | Ecosystem positioning + mandatory L0–L5 evidence ladder | Accepted |
|
||||
| [ADR-285](ADR-285-homecore-wasm-first-metaharness.md) | WASM-first Homecore developer metaharness via `npx homecore` | Accepted (implemented and validated) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user