mirror of https://github.com/ruvnet/RuView synced 2026-08-01 19:01:42 +00:00

Files

T

rUv 90b29595fb 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.

2026-07-29 19:51:21 -04:00

9.5 KiB

Raw Blame History

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:

explain current capabilities without overstating maturity;
lead contributors to the correct source, ADRs, and focused tests;
exercise Wasmtime and HAP feature gates deliberately;
expose a small MCP guidance surface;
delegate exploration to local Claude Code or Codex CLIs at least authority;
remain removable from the Homecore server runtime.

The requested user experience is the exact command:

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.

9.5 KiB Raw Blame History

ADR-285: WASM-first Homecore developer metaharness via npx homecore