docs/adr/ADR-285-homecore-wasm-first-metaharness.md
npx homecoreHomecore 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:
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.
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.
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;homecore wasm status --strict fails when WASM is unavailable;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:
The wasm verification profile runs the Wasmtime-specific plugin and server
tests from fixed argument arrays with shell: false.
The CLI provides:
guidance and capabilities;brain search, citation verification, and proposal output;doctor and strict/non-strict WASM diagnostics;core, wasm, hap, and full verification profiles;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.
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;Claude Code uses:
claude -p --safe-mode;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.
Capability records carry:
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.
Extend the ADR-265 npm matrix and provenance-only release workflow to
harness/homecore. The gate must run on supported Node versions and verify:
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.
npx homecore entry point without coupling the
Rust server to an agent framework.homecore is a narrow exception to the @ruvnet/* package namespace rule.homecore.harness/homecore/v2/docs/homecore-capabilities.md