rustuya-local 0.1.0.dev7__tar.gz → 0.1.0.dev8__tar.gz

{rustuya_local-0.1.0.dev7 → rustuya_local-0.1.0.dev8}/CHANGELOG.md

@@ -3,11 +3,26 @@
 All notable changes to this project are documented in this file. A release's GitHub Release notes are its section
 here (the release workflow reads it, and refuses to publish a version without one).
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions are `0.0.x` until the first
-stable release.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The current development series uses
+`0.1.0.devN`; the earlier `0.0.x` releases remain below as history.
 
 ## [Unreleased]
 
+## [0.1.0.dev8] — 2026-10-13
+
+### Fixed
+- Always stop the embedded bridge during Home Assistant unload, including service-stop failure or cancellation.
+- Close MQTT callback tasks, ignore queued dispatch after shutdown, retrieve asynchronous handler errors and stop
+  the paho thread outside the event loop, including when a connection attempt fails.
+- Preserve concurrent partial Home Assistant settings/options saves by locking reads, merges and restart together.
+- Reject unsafe pack ownership paths, malformed hashes and bounds; preserve host settings and symlink targets.
+
+### Documentation
+- Separate current status, architecture and outstanding work from the historical redesign record.
+- Document the 2026-10-13 code review, verification results and remaining reliability issues.
+- Correct daemon setup, test prerequisites and saved cover settings precedence.
+- Translate all Korean Markdown documents into English, including archived design and roadmap history.
+
 ## [0.1.0.dev7] — 2026-10-12
 
 ### Changed

{rustuya_local-0.1.0.dev7 → rustuya_local-0.1.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rustuya-local
-Version: 0.1.0.dev7
+Version: 0.1.0.dev8
 Summary: Local Tuya control: rustuya-bridge -> tuya-interpreter -> IL (ildevice). HA-independent core.
 Project-URL: Homepage, https://github.com/3735943886/rustuya-local
 Project-URL: Repository, https://github.com/3735943886/rustuya-local
@@ -46,11 +46,29 @@ rustuya-bridge ──MQTT──► rustuya-local ──MQTT (il/…)──► il
 
 ## Daemon
 
+```bash
+uv venv --python 3.13
+uv pip install -e .
+.venv/bin/rustuya-local run --config config.json
 ```
-uv venv && uv pip install -e .
-rustuya-local run --config config.json
+
+Create `config.json` beside the device file before running:
+
+```json
+{
+  "bridge": {"host": "localhost", "port": 1883, "root": "rustuya"},
+  "il": {"host": "localhost", "port": 1883, "prefix": "il", "source": "tuya"},
+  "devices": "tuyadevices.json",
+  "custom_converters": "custom_converters",
+  "pack": true,
+  "watch_interval": 5,
+  "options": {"allow_hazardous": false, "expose_unused": false}
+}
 ```
 
+The package requires Python 3.13 or newer. Device and converter paths are relative to the configuration file.
+`watch_interval: 0` disables polling; use a positive interval to apply file edits and downloaded rules while running.
+
 `config.json` (see `src/rustuya_local/config.py`): the bridge and IL brokers, the IL prefix, the device list, a
 `custom_converters` directory, and options for the Hub (`allow_hazardous`, `expose_unused`, `overrides`).
 The device list is the `tuyadevices.json` that [rustuya-manager](https://github.com/3735943886/rustuya-manager) keeps (its QR-login wizard writes
@@ -134,7 +152,9 @@ device settings are enabled, unless an override selects another source. A settin
 the setting is saved as the device's block in `zz_settings.json` in the converters directory and applied at once, so it
 survives a restart and can be edited there too. Without a converters directory (a daemon with no
 `custom_converters`) the switches are not offered; `"options": {"device_settings": false}` turns them off.
-A block with the same `cover` keys in your own file or the builtin rules sets a model's starting point; the saved settings win.
+A block with the same `cover` keys in your own file or the builtin rules sets a model's starting point.
+User files, including `zz_settings.json`, are applied in filename order; a later file can override saved settings.
+The daemon's inline `options.overrides` is applied after file layers.
 Older `cover.infer_motion` and `converters.cover_motion` blocks are upgraded on loading to `cover.state_source`
 (`inferred`, or `none` for `infer_motion: false`) and `cover.settle`; see [migration notes](docs/MIGRATING.md).
 
@@ -172,15 +192,22 @@ rustuya-local release (bump the patch version and tag; the manager's catalog fol
 
 ## Tests
 
-```
-.venv/bin/python -m pytest
+```bash
+uv venv --python 3.14
+uv pip install -e ../ildevice-homeassistant -e ".[test,test-ha,fullstack,manager]"
+.venv/bin/python -m pytest -q
+ruff check src tests custom_components scripts
 ```
 
-Everything here needs the sibling repos and, for the last two groups, `mosquitto`, `pyrustuya-bridge` and `tuyamock`
-(`pip install -e ".[test,fullstack]"`); those are skipped when missing. Parity with Home Assistant core's fixtures lives in
-`tuya-interpreter/tests/chain`, the wire and topic vectors in `ildevice/vectors`.
+The complete suite uses Python 3.14 because the consumer and Home Assistant test dependencies require it.
+Install `mosquitto` for broker tests and Node.js for panel JavaScript tests. The command above installs the consumer
+from a sibling checkout and other dependencies from the package index; CI follows the same approach.
+Missing base or test dependencies can fail collection; optional broker, emulator and fixture tests skip when their
+prerequisites are unavailable. The full-stack device comparison uses `../tuya-interpreter/tests/golden`; IL wire and
+topic vectors use `../ildevice/vectors` (or the `ILDEVICE` environment variable). Keep those checkouts for these checks.
 
-- `tests/unit/`: the configuration.
+- `tests/unit/`: configuration validation, host lifecycle, IL vectors, rule loading, settings persistence,
+  pack ownership, converter APIs, panel JavaScript and release packaging.
 - `tests/e2e/test_service.py`: the service on in-memory brokers (overrides directory, a failed start).
 - `tests/e2e/test_chain_*.py`, `test_daemon.py`: the runner with ildevice-homeassistant's consumer model on the other side, in one process
   and over a real broker; the daemon as a subprocess.
@@ -190,8 +217,14 @@ Everything here needs the sibling repos and, for the last two groups, `mosquitto
   (`tuyamock`) around the daemon: state, commands, rejections, a device dropping off and returning, a daemon restart, and a
   differential check that 38 real device shapes come out of the whole chain exactly as `tuya-interpreter` computes them.
 
-## Status
+## Documentation
 
-Planning, progress and open decisions: `docs/REDESIGN.md`.
+- [Current status](docs/STATUS.md): version, document index and verification boundaries.
+- [Architecture](docs/ARCHITECTURE.md): current components, lifecycle and rule precedence.
+- [Migration](docs/MIGRATING.md): upgrading old converters and rustuya-homeassistant installations.
+- [Code review](docs/REVIEW.md): findings and local verification from 2026-10-13.
+- [Roadmap](docs/ROADMAP.md): outstanding work and real-device checks.
+- [Design history](docs/REDESIGN.md): the September redesign record; historical APIs and versions.
+- [Changelog](CHANGELOG.md): changes grouped by release.
 
-Licence: `LICENSE` (MIT).
+Licence: [MIT](LICENSE).

{rustuya_local-0.1.0.dev7 → rustuya_local-0.1.0.dev8}/README.md

@@ -20,11 +20,29 @@ rustuya-bridge ──MQTT──► rustuya-local ──MQTT (il/…)──► il
 
 ## Daemon
 
+```bash
+uv venv --python 3.13
+uv pip install -e .
+.venv/bin/rustuya-local run --config config.json
 ```
-uv venv && uv pip install -e .
-rustuya-local run --config config.json
+
+Create `config.json` beside the device file before running:
+
+```json
+{
+  "bridge": {"host": "localhost", "port": 1883, "root": "rustuya"},
+  "il": {"host": "localhost", "port": 1883, "prefix": "il", "source": "tuya"},
+  "devices": "tuyadevices.json",
+  "custom_converters": "custom_converters",
+  "pack": true,
+  "watch_interval": 5,
+  "options": {"allow_hazardous": false, "expose_unused": false}
+}
 ```
 
+The package requires Python 3.13 or newer. Device and converter paths are relative to the configuration file.
+`watch_interval: 0` disables polling; use a positive interval to apply file edits and downloaded rules while running.
+
 `config.json` (see `src/rustuya_local/config.py`): the bridge and IL brokers, the IL prefix, the device list, a
 `custom_converters` directory, and options for the Hub (`allow_hazardous`, `expose_unused`, `overrides`).
 The device list is the `tuyadevices.json` that [rustuya-manager](https://github.com/3735943886/rustuya-manager) keeps (its QR-login wizard writes
@@ -108,7 +126,9 @@ device settings are enabled, unless an override selects another source. A settin
 the setting is saved as the device's block in `zz_settings.json` in the converters directory and applied at once, so it
 survives a restart and can be edited there too. Without a converters directory (a daemon with no
 `custom_converters`) the switches are not offered; `"options": {"device_settings": false}` turns them off.
-A block with the same `cover` keys in your own file or the builtin rules sets a model's starting point; the saved settings win.
+A block with the same `cover` keys in your own file or the builtin rules sets a model's starting point.
+User files, including `zz_settings.json`, are applied in filename order; a later file can override saved settings.
+The daemon's inline `options.overrides` is applied after file layers.
 Older `cover.infer_motion` and `converters.cover_motion` blocks are upgraded on loading to `cover.state_source`
 (`inferred`, or `none` for `infer_motion: false`) and `cover.settle`; see [migration notes](docs/MIGRATING.md).
 
@@ -146,15 +166,22 @@ rustuya-local release (bump the patch version and tag; the manager's catalog fol
 
 ## Tests
 
-```
-.venv/bin/python -m pytest
+```bash
+uv venv --python 3.14
+uv pip install -e ../ildevice-homeassistant -e ".[test,test-ha,fullstack,manager]"
+.venv/bin/python -m pytest -q
+ruff check src tests custom_components scripts
 ```
 
-Everything here needs the sibling repos and, for the last two groups, `mosquitto`, `pyrustuya-bridge` and `tuyamock`
-(`pip install -e ".[test,fullstack]"`); those are skipped when missing. Parity with Home Assistant core's fixtures lives in
-`tuya-interpreter/tests/chain`, the wire and topic vectors in `ildevice/vectors`.
+The complete suite uses Python 3.14 because the consumer and Home Assistant test dependencies require it.
+Install `mosquitto` for broker tests and Node.js for panel JavaScript tests. The command above installs the consumer
+from a sibling checkout and other dependencies from the package index; CI follows the same approach.
+Missing base or test dependencies can fail collection; optional broker, emulator and fixture tests skip when their
+prerequisites are unavailable. The full-stack device comparison uses `../tuya-interpreter/tests/golden`; IL wire and
+topic vectors use `../ildevice/vectors` (or the `ILDEVICE` environment variable). Keep those checkouts for these checks.
 
-- `tests/unit/`: the configuration.
+- `tests/unit/`: configuration validation, host lifecycle, IL vectors, rule loading, settings persistence,
+  pack ownership, converter APIs, panel JavaScript and release packaging.
 - `tests/e2e/test_service.py`: the service on in-memory brokers (overrides directory, a failed start).
 - `tests/e2e/test_chain_*.py`, `test_daemon.py`: the runner with ildevice-homeassistant's consumer model on the other side, in one process
   and over a real broker; the daemon as a subprocess.
@@ -164,8 +191,14 @@ Everything here needs the sibling repos and, for the last two groups, `mosquitto
   (`tuyamock`) around the daemon: state, commands, rejections, a device dropping off and returning, a daemon restart, and a
   differential check that 38 real device shapes come out of the whole chain exactly as `tuya-interpreter` computes them.
 
-## Status
+## Documentation
 
-Planning, progress and open decisions: `docs/REDESIGN.md`.
+- [Current status](docs/STATUS.md): version, document index and verification boundaries.
+- [Architecture](docs/ARCHITECTURE.md): current components, lifecycle and rule precedence.
+- [Migration](docs/MIGRATING.md): upgrading old converters and rustuya-homeassistant installations.
+- [Code review](docs/REVIEW.md): findings and local verification from 2026-10-13.
+- [Roadmap](docs/ROADMAP.md): outstanding work and real-device checks.
+- [Design history](docs/REDESIGN.md): the September redesign record; historical APIs and versions.
+- [Changelog](CHANGELOG.md): changes grouped by release.
 
-Licence: `LICENSE` (MIT).
+Licence: [MIT](LICENSE).

{rustuya_local-0.1.0.dev7 → rustuya_local-0.1.0.dev8}/custom_components/rustuya/__init__.py

@@ -252,13 +252,19 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     # setup that follows puts it back anyway; only disabling the entry (or deleting it, below) removes it
     if entry.disabled_by is not None:
         panel.async_remove(hass)
-    runtime: RuntimeData = hass.data[DOMAIN].pop(entry.entry_id)
+    runtime: RuntimeData = hass.data[DOMAIN][entry.entry_id]
     restarting = getattr(runtime, "restarting", False) and entry.disabled_by is None
-    await runtime.service.stop(offline=not restarting)
+    try:
+        await runtime.service.stop(offline=not restarting)
+    finally:
+        try:
+            if runtime.embedded_bridge:
+                await runtime.embedded_bridge.stop()
+        finally:
+            # A stopped service cannot be reused, even when draining its commands failed.
+            hass.data[DOMAIN].pop(entry.entry_id, None)
     if restarting:
         hass.data[RESUME] = True
-    if runtime.embedded_bridge:
-        await runtime.embedded_bridge.stop()
     return True
 
 

{rustuya_local-0.1.0.dev7 → rustuya_local-0.1.0.dev8}/custom_components/rustuya/manifest.json

@@ -13,8 +13,8 @@
     "paho-mqtt>=2.0",
     "rustuya-manager>=0.2.2",
     "pyrustuyabridge>=0.4",
-    "rustuya-local>=0.1.0.dev7"
+    "rustuya-local>=0.1.0.dev8"
   ],
   "single_config_entry": true,
-  "version": "0.1.0.dev7"
+  "version": "0.1.0.dev8"
 }

{rustuya_local-0.1.0.dev7 → rustuya_local-0.1.0.dev8}/custom_components/rustuya/panel.py

@@ -221,11 +221,12 @@ class OptionsView(_View):
                 or not all(isinstance(v, bool) for v in body.values())):
             return self.json_message(f"the options are {sorted(DEFAULT_OPTIONS)}, each true or false",
                                      HTTPStatus.BAD_REQUEST)
-        options = {**entry.options, **body}
-        if options == dict(entry.options):
-            return self.json({"restarting": False})
-        await _restart(request.app["hass"], entry, options=options)        # answered once it has restarted
-        return self.json({"restarting": True})
+        async with _settings_lock(request.app["hass"]):
+            options = {**entry.options, **body}
+            if options == dict(entry.options):
+                return self.json({"restarting": False})
+            await _restart(request.app["hass"], entry, options=options)        # answered once it has restarted
+            return self.json({"restarting": True})
 
 
 def settings_of(data: Any) -> dict[str, Any]:
@@ -275,24 +276,30 @@ class SettingsView(_View):
     @_entry_view
     async def put(self, request: web.Request, entry: Any, runtime: Any) -> web.Response:
         hass = request.app["hass"]
-        try:
-            new = validate_settings(hass, entry.data, await request.json())
-        except ValueError as e:
-            return self.json_message(str(e), HTTPStatus.BAD_REQUEST)
-        old = dict(entry.data)
-        if new == settings_of(old):
-            return self.json({"restarting": False})
-        external = old.get(CONF_BRIDGE_MODE) != BRIDGE_EMBEDDED
-        if external and new[CONF_BRIDGE_ROOT] != old[CONF_BRIDGE_ROOT]:
-            from .config_flow import _probe_bridge
-
-            error = await _probe_bridge(hass, {**old, **new})
-            if error is not None:
-                return self.json_message(
-                    f"no rustuya-bridge answers on {new[CONF_BRIDGE_ROOT]}" if error == "bridge_not_found"
-                    else "cannot connect to the broker", HTTPStatus.BAD_REQUEST)
-        await _apply(hass, entry, old, {**old, **new})                       # answered once it has restarted
-        return self.json({"restarting": True})
+        body = await _json_body(request)
+        async with _settings_lock(hass):
+            try:
+                new = validate_settings(hass, entry.data, body)
+            except ValueError as e:
+                return self.json_message(str(e), HTTPStatus.BAD_REQUEST)
+            old = dict(entry.data)
+            if new == settings_of(old):
+                return self.json({"restarting": False})
+            external = old.get(CONF_BRIDGE_MODE) != BRIDGE_EMBEDDED
+            if external and new[CONF_BRIDGE_ROOT] != old[CONF_BRIDGE_ROOT]:
+                from .config_flow import _probe_bridge
+
+                error = await _probe_bridge(hass, {**old, **new})
+                if error is not None:
+                    return self.json_message(
+                        f"no rustuya-bridge answers on {new[CONF_BRIDGE_ROOT]}" if error == "bridge_not_found"
+                        else "cannot connect to the broker", HTTPStatus.BAD_REQUEST)
+            await _apply(hass, entry, old, {**old, **new})                       # answered once it has restarted
+            return self.json({"restarting": True})
+
+
+def _settings_lock(hass: HomeAssistant) -> asyncio.Lock:
+    return hass.data.setdefault(f"{DOMAIN}_settings_lock", asyncio.Lock())
 
 
 async def _apply(hass: HomeAssistant, entry: Any, old: dict[str, Any], data: dict[str, Any]) -> None:
@@ -318,34 +325,33 @@ async def _restart(hass: HomeAssistant, entry: Any, *, data: dict[str, Any] | No
     """Stop the entry, run `between`, store the new data / options, start it again — all awaited, so the panel's save
     answers once the restart is over (the page then reloads onto the restarted entry, not onto one about to go).
     Stopped, the entry has no update listener, so storing does not start a second reload. An options-only restart
-    keeps the IL presence online across it (`mark_restart`); new data may move the broker or the IL topics."""
-    lock = hass.data.setdefault(f"{DOMAIN}_settings_lock", asyncio.Lock())
-    async with lock:
-        old_data, old_options = dict(entry.data), dict(entry.options)
-        if data is None:
-            from . import mark_restart
-
-            mark_restart(hass, entry)
-        if not await hass.config_entries.async_unload(entry.entry_id):
-            raise RestartFailed("Could not stop the integration; settings were not changed")
+    keeps the IL presence online across it (`mark_restart`); new data may move the broker or the IL topics.
+    The request handler holds `_settings_lock` from reading the current entry through this restart."""
+    old_data, old_options = dict(entry.data), dict(entry.options)
+    if data is None:
+        from . import mark_restart
+
+        mark_restart(hass, entry)
+    if not await hass.config_entries.async_unload(entry.entry_id):
+        raise RestartFailed("Could not stop the integration; settings were not changed")
+    try:
+        if between is not None:
+            await between()
+        changes = {k: v for k, v in (("data", data), ("options", options)) if v is not None}
+        hass.config_entries.async_update_entry(entry, **changes)
+        if not await hass.config_entries.async_setup(entry.entry_id):
+            raise RestartFailed("The integration could not start with these settings")
+    except Exception as e:
+        # Failed setup leaves SETUP_ERROR/SETUP_RETRY, which cannot be set up
+        # directly. Unload also cancels any scheduled retry with the bad data.
+        await hass.config_entries.async_unload(entry.entry_id)
+        hass.config_entries.async_update_entry(entry, data=old_data, options=old_options)
         try:
-            if between is not None:
-                await between()
-            changes = {k: v for k, v in (("data", data), ("options", options)) if v is not None}
-            hass.config_entries.async_update_entry(entry, **changes)
-            if not await hass.config_entries.async_setup(entry.entry_id):
-                raise RestartFailed("The integration could not start with these settings")
-        except Exception as e:
-            # Failed setup leaves SETUP_ERROR/SETUP_RETRY, which cannot be set up
-            # directly. Unload also cancels any scheduled retry with the bad data.
-            await hass.config_entries.async_unload(entry.entry_id)
-            hass.config_entries.async_update_entry(entry, data=old_data, options=old_options)
-            try:
-                restored = await hass.config_entries.async_setup(entry.entry_id)
-            except Exception:  # noqa: BLE001 -- keep the recovery API usable even if rollback startup fails
-                restored = False
-            suffix = "Previous settings restored" if restored else "Previous settings restored, but startup still fails"
-            raise RestartFailed(f"{e}. {suffix}; settings remain editable") from e
+            restored = await hass.config_entries.async_setup(entry.entry_id)
+        except Exception:  # noqa: BLE001 -- keep the recovery API usable even if rollback startup fails
+            restored = False
+        suffix = "Previous settings restored" if restored else "Previous settings restored, but startup still fails"
+        raise RestartFailed(f"{e}. {suffix}; settings remain editable") from e
 
 
 class PackView(_View):

rustuya_local-0.1.0.dev8/docs/ARCHITECTURE.md

@@ -0,0 +1,78 @@
+# Current architecture
+
+Baseline: 2026-10-13, `rustuya-local 0.1.0.dev8`.
+See [README](../README.md) for installation and [REDESIGN](REDESIGN.md) for earlier designs.
+
+```text
+Tuya LAN devices
+  ↕
+rustuya-bridge / embedded pyrustuyabridge
+  ↕ MQTT (topic and payload templates announced by the bridge)
+BridgeClient ↔ Runner ↔ Hub ↔ tuya-interpreter TuyaDriver
+                ↕
+          IL MQTT transport
+                ↕
+ildevice-homeassistant / other IL consumers
+```
+
+## Components
+
+| Location | Responsibility |
+|---|---|
+| `src/rustuya_local/service.py` | Shared assembly, startup/shutdown, pack updates, retained cleanup, raw DP commands |
+| `bridge_client.py` | Bridge templates, paginated registry snapshots, intersection of registered and configured devices |
+| `host/hub.py` | Driver registry, replacement/reload, native rule-pack reference management |
+| `host/runner.py` | IL subscriptions and publish queue, timers, presence/probes, settings callbacks |
+| `host/il.py` | Mapping driver outputs to IL MQTT topics and values |
+| `host/rules.py`, `overrides.py` | Rule discovery/merging, legacy cover keys, file watching and settings persistence |
+| `host/pack.py` | Official rule downloads, hash verification and ownership ledger |
+| `host/mqtt.py`, `memory.py` | paho MQTT and in-process test transports |
+| `cli.py`, `config.py` | Standalone daemon and configuration validation |
+| `manager_plugin/` | Supervision by the manager, settings/file APIs and web tab |
+| `custom_components/rustuya/` | HA config entry, embedded bridge, login/registration and administrator panel |
+| External `tuya-interpreter` | Single-device Tuya DP interpretation, command validation and rule composition |
+
+HA entity creation belongs to the IL consumer. The base package does not import Home Assistant.
+
+## Startup and shutdown
+
+`Service.start()` prepares the native library and rules in worker threads, then connects the bridge and IL transports
+and creates the Hub. It refuses startup if a producer with the same IL prefix/source answers a probe. This is a
+preflight check, not an atomic distributed lock. After a complete bridge registry snapshot, it advertises devices
+present in both the device file and registry and clears stale IL topics left by the previous run. Pages are checked
+for order, counts and duplicates, but the bridge has no request ID for complete correlation with other requests.
+
+Normal shutdown marks presence offline and leaves descriptors/state retained. Restarting within the same namespace
+preserves presence. Moving namespaces or running `purge` clears the previous retained topics. `AsyncExitStack` manages
+service resources. HA unload always attempts embedded-bridge shutdown, even if service shutdown fails or is cancelled,
+and then removes the unusable runtime. The resume marker is set only after successful cleanup.
+
+MQTT close blocks new dispatch, cancels and awaits asynchronous handlers, and stops the paho thread outside the event
+loop. Cancelling close still waits for its cleanup before propagating cancellation. Asynchronous handler errors are
+retrieved and logged. Closed transports cannot be connected, subscribed or published through again.
+
+## Rule and settings precedence
+
+1. Bundled `rules/builtin/*.json` from `tuya-interpreter`.
+2. Downloaded `rules/builtin/*.json` below the configured rule directories.
+3. JSON files from `TUYA_ENGINE_RULES` and user directories, merged by filename byte order.
+4. Inline service `hub_options.overrides`; the daemon calls this `options.overrides`.
+
+Later values override earlier ones. `manifest.json` is excluded from rule layers, and directory files starting with
+`.` or `_` are skipped. `zz_settings.json` is a normal user layer: later filenames or inline overrides can replace
+its settings. Invalid user layers are skipped with warnings. A rejected Hub reload preserves the existing drivers.
+
+Automatic pack updates run at startup and daily; manual updates also work when automatic updates are disabled.
+Only files with matching ownership hashes are replaced or removed; user edits are preserved. Manifest and ledger
+entries must have safe filenames and SHA-256 hashes. Host settings, manifests and symlink targets cannot be owned
+by the pack. Each managed file is checked against the directory boundary.
+
+The watcher must run to apply downloaded files to an active Hub. The daemon's `watch_interval: 0` disables polling.
+IL settings saves use a separate lock and atomic replacement, then reload immediately. HA settings/options API
+requests share a lock covering the current-entry read, patch merge, validation, probing and restart.
+
+## Verification and coupling
+
+Unit tests, in-process services, real MQTT brokers, Tuya emulators and HA integration tests verify different
+boundaries. They do not replace real LAN-device tests. Driver state internals and the manager's private registry API
+remain coupling points that need checking when dependencies change. See [REVIEW](REVIEW.md) for fixes and limits.

{rustuya_local-0.1.0.dev7 → rustuya_local-0.1.0.dev8}/docs/MIGRATING.md

@@ -1,4 +1,9 @@
-# Moving to tuya-interpreter
+# Migration guide
+
+For the current component boundaries and file precedence, see [Architecture](ARCHITECTURE.md).
+Use [README](../README.md) for installation and [Changelog](../CHANGELOG.md) for version-specific changes.
+
+## Moving to rustuya-local 0.1 / tuya-interpreter
 
 The device file, MQTT configuration and IL topics stay the same. Custom files in the converters directory now use
 the rule-layer format. Wrap an existing product/device override mapping in `{"overrides": ...}`. For example:
@@ -7,13 +12,15 @@ the rule-layer format. Wrap an existing product/device override mapping in `{"ov
 {"overrides": {"product_id": {"cover": {"invert_position": true}}}}
 ```
 
-Apply the same conversion to `zz_settings.json` to preserve cover settings saved by an older version. Leave
+Back up the converters directory before editing. Apply the same conversion to `zz_settings.json` to preserve cover settings saved by an older version. Leave
 `options.overrides` in the daemon configuration as a product/device mapping; the host still accepts that format.
 Rewrite Python converters as JSON programs under `converters.declarative`. Invalid JSON rule layers are reported
 and skipped, so check the logs after upgrading. The managed override pack updates automatically when enabled;
-files you edited remain yours to convert.
+files you edited remain yours to convert. JSON files use filename order, including `zz_settings.json`; check for later
+files or inline overrides that replace saved settings. See the cover compatibility details below for `infer_motion`
+and `converters.cover_motion`.
 
-# Moving from rustuya-homeassistant
+## Moving from rustuya-homeassistant
 
 rustuya-homeassistant (`rustuya-ha`) published Home Assistant MQTT discovery for your Tuya devices, as a CLI or a
 rustuya-manager plugin. It is retired. Its replacement is two pieces:
@@ -24,7 +31,7 @@ rustuya-manager plugin. It is retired. Its replacement is two pieces:
 - **[ildevice-homeassistant](https://github.com/3735943886/ildevice-homeassistant)** (HACS) turns IL devices
   into Home Assistant entities. MQTT discovery is no longer used.
 
-## What changes for you
+### What changes for you
 
 - **Entity ids change.** The old entities belonged to Home Assistant's `mqtt` integration; the new ones belong to
   `ildevice`, and Home Assistant keeps the two apart. Automations, scripts and dashboards that name the old entities
@@ -34,7 +41,7 @@ rustuya-manager plugin. It is retired. Its replacement is two pieces:
   with more, fewer or differently split entities than v1 made.
 - **Availability** comes from rustuya-local's presence: when it stops, its devices show unavailable.
 
-## Steps
+### Steps
 
 1. **Remove the old discovery** while `rustuya-ha` still runs, so Home Assistant drops those entities:
 
@@ -65,7 +72,7 @@ rustuya-manager plugin. It is retired. Its replacement is two pieces:
      A property the tables do not build is defined from its dp in `props`.
    - A curtain's `invert_position` / `invert_set_position`, reversed command words and derived state are not files any
      more: each cover has configuration switches for them (README, *Cover settings*).
-   - Rewrite Python converters as JSON programs under `converters.declarative`; Python plugins are not loaded in 0.4.
+   - Rewrite Python converters as JSON programs under `converters.declarative`; Python plugins are not loaded by rustuya-local 0.1.
    - `converters.cover_motion` and a cover's `infer_motion` are read as the cover's `state_source` (`inferred`, or
      `none` for `infer_motion: false`), and a `cover_motion` `settle` as the cover's `settle`; its other keys are
      dropped with a warning. `zz_settings.json` is rewritten in the new form the next time a setting is saved.