149 lines
8.5 KiB
Markdown
149 lines
8.5 KiB
Markdown
# ADR-165: HOMECORE-MIGRATE — Migration Tooling from Python Home Assistant
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Status** | Accepted — P1 scaffold (full conversion deferred to P2) |
|
|
| **Date** | 2026-05-25 |
|
|
| **Deciders** | ruv |
|
|
| **Codename** | **HOMECORE-MIGRATE** |
|
|
| **Crate** | `v2/crates/homecore-migrate` |
|
|
| **Relates to** | [ADR-126](ADR-126-ruview-native-ha-port-master.md) (HOMECORE master — series map row "ADR-134 HOMECORE-MIGRATE"), [ADR-127](ADR-127-homecore-state-machine-rust.md) (HOMECORE-CORE), [ADR-132](ADR-132-homecore-recorder-history-semantic-search.md) (HOMECORE-RECORDER — P2 side-by-side export target) |
|
|
| **Tracking issue** | [#800](https://github.com/ruvnet/RuView/pull/800) (HOMECORE intake) |
|
|
|
|
> **Number-collision resolution (2026-06-12).** The HOMECORE series in ADR-126 §4 planned
|
|
> "ADR-134 = HOMECORE-MIGRATE", and the `homecore-migrate` crate cites "ADR-134" throughout.
|
|
> But the on-disk `ADR-134-csi-to-cir-time-domain-multipath.md` is a **different, unrelated
|
|
> decision** (First-Class CIR Support, a signal-processing tier). The migrate crate was
|
|
> therefore governed by a phantom identity (ADR-164 Gap G3 / Coverage-Gaps Lens §A). This
|
|
> ADR takes the next free number (**165**) and becomes the real governing record for
|
|
> HOMECORE-MIGRATE; the `ADR-134` references inside `v2/crates/homecore-migrate/` are
|
|
> repointed to ADR-165. The real ADR-134 (CIR) is untouched. ADR-126's series-map row still
|
|
> labels the *role* "ADR-134 HOMECORE-MIGRATE" for historical traceability; that registry
|
|
> renumber is owner-gated and left for the follow-up. This ADR reverse-documents the shipped
|
|
> P1 scaffold; it introduces no new design.
|
|
|
|
---
|
|
|
|
## 1. Context
|
|
|
|
ADR-126 decided to reimplement Home Assistant (HA) natively in Rust. A user adopting
|
|
HOMECORE has an existing HA install whose configuration lives in two places on disk:
|
|
|
|
- `.storage/*.json` — versioned JSON envelopes (`{ version, minor_version, data }`) holding
|
|
the entity registry, device registry, and config entries;
|
|
- top-level YAML — `secrets.yaml`, `automations.yaml`.
|
|
|
|
To migrate, HOMECORE must read this foreign, **untrusted** on-disk state. It is untrusted in
|
|
the security sense: the schema can drift between HA releases, and silently mis-parsing a
|
|
registry would corrupt the imported home. ADR-164 flagged this as a CRITICAL coverage gap —
|
|
a data-integrity-sensitive importer governed by a non-existent ADR identity.
|
|
|
|
The decision an ADR must pin here is the **trust boundary and import contract**: which HA
|
|
files are read, how schema versions are validated, and what happens on an unknown version.
|
|
|
|
## 2. Decision
|
|
|
|
Ship `homecore-migrate` as a CLI + library that reads an existing HA filesystem and imports
|
|
its configuration into HOMECORE. P1 is a **scaffold**: it parses and inspects everything and
|
|
converts the entity registry; full conversion of the remaining artifacts is deferred to P2.
|
|
|
|
### 2.1 Storage reader + versioned format gate (P1, shipped)
|
|
|
|
- `HaStorageDir` / `HaStorageEnvelope` read HA's `.storage/` directory; `read_envelope(path)`
|
|
deserializes a `.storage/*.json` envelope (`src/storage.rs`).
|
|
- Versioned parsers live under `storage_format::v<N>` (e.g. `v13` for the entity registry)
|
|
(`src/storage_format/`).
|
|
- **Schema-version validation is the load-bearing safety rule (§6 Q5 of this ADR):** an
|
|
unknown `minor_version` is a **hard error** (`MigrateError::UnsupportedSchemaVersion`),
|
|
never a silent best-effort parse. Better to refuse than to corrupt.
|
|
|
|
### 2.2 Per-artifact parsers (P1, shipped)
|
|
|
|
- `entity_registry::load()` — `core.entity_registry` → `Vec<homecore::EntityEntry>`
|
|
(ready for import).
|
|
- `device_registry::load()` — `core.device_registry` → `Vec<DeviceImport>` (P1 diagnostic;
|
|
full conversion P2).
|
|
- `config_entries::load()` — `core.config_entries` → domain counts + integration names
|
|
(the format is undocumented per §6 Q5; treated diagnostically).
|
|
- `secrets::load_secrets()` — `secrets.yaml` → `HashMap<String, String>` (resolution P2).
|
|
- `automations::load()` — `automations.yaml` → count + ID/alias list (conversion P2).
|
|
|
|
### 2.3 CLI (P1, shipped)
|
|
|
|
- `homecore-migrate inspect <ha-dir>` previews what will be migrated (entity/device/config
|
|
counts, redacted secret/automation lists) (`src/cli.rs`, `src/main.rs`).
|
|
- `import-entities` and `export-for-sidecar` are declared but their full behaviour is P2.
|
|
|
|
### 2.4 Structured errors (P1, shipped)
|
|
|
|
- `MigrateError` carries context (`path`, line/field) for I/O, JSON, YAML, missing-field,
|
|
unsupported-schema-version, and entity-id parse failures (`src/lib.rs`).
|
|
- **Secret-leak hardening (security review, 2026-06).** `secrets.yaml` parse failures must
|
|
NOT use the generic `MigrateError::YamlParse { source }` variant: `serde_yaml`'s message
|
|
for a typed-tag coercion error (e.g. `port: !!int <value>`) embeds the offending scalar
|
|
verbatim (`invalid value: string "<the-secret-value>"`), and that error propagates through
|
|
the `InspectSecrets` CLI path to stderr — leaking a secret value despite the CLI's
|
|
deliberate `<redacted>` design. `read_secrets` now maps such failures to a dedicated
|
|
redacting variant `MigrateError::SecretsParse { path, line, column }` that carries only the
|
|
file path and a coarse location (`serde_yaml::Error::location()`), never the scalar content.
|
|
Pinned by `secrets::tests::malformed_secrets_error_never_contains_secret_value` (asserts the
|
|
rendered error **and its full `#[source]` chain** never contain the secret value).
|
|
**Review dimensions confirmed clean with evidence:** source is never mutated (no
|
|
`fs::write`/`remove`/`create` anywhere — P1 reads source, writes nothing); paths are
|
|
user-supplied dirs joined with fixed filenames (no `..`/absolute traversal beyond the
|
|
user's own privileges); malformed/typed/truncated `.storage` JSON and YAML **error, never
|
|
panic** (every production `unwrap`/`expect` is test-only); unknown schema `minor_version`
|
|
hard-errors fail-closed; no SQL/shell/path injection surface (the tool emits diagnostics
|
|
only, persists nothing in P1).
|
|
|
|
### 2.5 Deferred to P2+ (NOT built — honestly labelled)
|
|
|
|
- Convert `config_entries` → HOMECORE plugin manifests.
|
|
- Convert `automations.yaml` → `homecore-automation` YAML.
|
|
- Side-by-side runtime mode (requires `homecore-recorder`, ADR-132; behind the `recorder`
|
|
Cargo feature, currently a no-op stub).
|
|
- `!secret` reference resolution in non-secrets YAML files.
|
|
|
|
### 2.6 Test evidence (as shipped)
|
|
|
|
- 21 tests (`cargo test -p homecore-migrate`) — 19 as originally shipped plus 2 added by the
|
|
2026-06 security review (`secrets::tests::malformed_secrets_error_never_contains_secret_value`,
|
|
`malformed_secrets_error_reports_location`).
|
|
|
|
## 3. Consequences
|
|
|
|
**Positive.**
|
|
|
|
- The trust boundary is explicit: unknown HA schema versions are rejected, not guessed, so a
|
|
schema drift fails loudly instead of corrupting an imported home.
|
|
- Reusing HA's own `.storage` and YAML formats means no intermediate export step; the tool
|
|
reads a live HA install directly.
|
|
- P1 `inspect` gives users a no-risk dry run before any write.
|
|
|
|
**Negative / honest limits.**
|
|
|
|
- P1 is a **scaffold**: only the entity registry is conversion-ready. Device registry,
|
|
config-entry→plugin, automation, and secret-resolution conversions are P2 and **not yet
|
|
built** — the Status field and crate docs say so.
|
|
- The side-by-side recorder export depends on ADR-132 and is currently a feature-gated
|
|
no-op.
|
|
- Performance figures in the README (envelope parse < 5 ms, 1 000-entity load < 50 ms) are
|
|
estimates, **needs verification** with a benchmark.
|
|
|
|
**Neutral.**
|
|
|
|
- This resolves only the *identity* of the migrate decision (134→165). The broader 6-way
|
|
duplicate-number cleanup (incl. ADR-126's series-map registry row) is owner-gated.
|
|
|
|
## 4. Links
|
|
|
|
- Crate: `v2/crates/homecore-migrate/` — `Cargo.toml`, `README.md`, `src/lib.rs`,
|
|
`src/storage.rs`, `src/storage_format/`, `src/entity_registry.rs`,
|
|
`src/device_registry.rs`, `src/config_entries.rs`, `src/secrets.rs`,
|
|
`src/automations.rs`, `src/cli.rs`, `src/main.rs`.
|
|
- [ADR-126](ADR-126-ruview-native-ha-port-master.md) — HOMECORE master (series map: HOMECORE-MIGRATE).
|
|
- [ADR-132](ADR-132-homecore-recorder-history-semantic-search.md) — HOMECORE-RECORDER (P2 side-by-side export target).
|
|
- [ADR-134](ADR-134-csi-to-cir-time-domain-multipath.md) — First-Class CIR Support (the *unrelated* decision the crate was mistakenly citing).
|
|
- [ADR-164](ADR-164-adr-corpus-gap-analysis.md) — gap analysis that surfaced this collision (Gap G3).
|
|
- [Home Assistant `.storage` format](https://developers.home-assistant.io/docs/storage/).
|