alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/adapters/household/tapo_ecosystem/storage.py

@@ -0,0 +1,95 @@
+"""Tapo ecosystem storage layer — local SQLite, mode 600.
+
+Persists hub-scoped device events.  Room labels (member-authored at
+pairing) are deliberately NOT in the schema — they live at the bridge
+layer and never reach the daemon's storage boundary.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from alter_runtime.config import data_dir
+
+__all__ = ["TapoEcosystemStorage", "DB_FILENAME"]
+
+logger = logging.getLogger("alter_runtime.adapters.household.tapo_ecosystem.storage")
+
+DB_FILENAME: str = "tapo_ecosystem.db"
+
+_SCHEMA: str = """
+CREATE TABLE IF NOT EXISTS hub_device_events (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    hub_mac      TEXT    NOT NULL,
+    device_mac   TEXT    NOT NULL,
+    device_kind  TEXT    NOT NULL,
+    ts           TEXT,
+    created_at   TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_hub_events_hub
+    ON hub_device_events (hub_mac);
+CREATE INDEX IF NOT EXISTS idx_hub_events_device
+    ON hub_device_events (device_mac);
+"""
+
+
+class TapoEcosystemStorage:
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path = db_path or (data_dir() / DB_FILENAME)
+        self._lock = asyncio.Lock()
+        self._ensure_db()
+
+    @property
+    def db_path(self) -> Path:
+        return self._db_path
+
+    def _ensure_db(self) -> None:
+        self._db_path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if not self._db_path.exists():
+            self._db_path.touch(mode=0o600, exist_ok=True)
+        else:
+            try:
+                self._db_path.chmod(0o600)
+            except OSError as exc:  # pragma: no cover
+                logger.warning("tapo_ecosystem chmod 0o600 failed: %s", exc)
+        with sqlite3.connect(self._db_path) as conn:
+            conn.executescript(_SCHEMA)
+
+    async def record_event(
+        self,
+        *,
+        hub_mac: str,
+        device_mac: str,
+        device_kind: str,
+        ts: Any | None = None,
+    ) -> None:
+        async with self._lock:
+            await asyncio.to_thread(self._insert_event, hub_mac, device_mac, device_kind, ts)
+
+    def _insert_event(
+        self,
+        hub_mac: str,
+        device_mac: str,
+        device_kind: str,
+        ts: Any | None,
+    ) -> None:
+        with sqlite3.connect(self._db_path) as conn:
+            conn.execute(
+                "INSERT INTO hub_device_events "
+                "(hub_mac, device_mac, device_kind, ts) VALUES (?, ?, ?, ?)",
+                (hub_mac, device_mac, device_kind, str(ts) if ts is not None else None),
+            )
+            conn.commit()
+
+    async def event_count(self) -> int:
+        return await asyncio.to_thread(self._event_count_sync)
+
+    def _event_count_sync(self) -> int:
+        with sqlite3.connect(self._db_path) as conn:
+            cur = conn.execute("SELECT COUNT(*) FROM hub_device_events")
+            row = cur.fetchone()
+            return int(row[0]) if row else 0

alter_runtime/adapters/household/tapo_ecosystem/tests/test_adapter.py

@@ -0,0 +1,55 @@
+"""Tests for TapoEcosystemAdapter — hub-level event ingest."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from alter_runtime.adapters.household.tapo_ecosystem.adapter import (
+    TAPO_HUB_ENERGY_TOPIC,
+    TAPO_HUB_STATE_TOPIC,
+    TapoEcosystemAdapter,
+)
+from alter_runtime.adapters.household.tapo_ecosystem.storage import (
+    TapoEcosystemStorage,
+)
+from alter_runtime.config import DaemonConfig
+from alter_runtime.subscribers.bus import EventBus
+
+
+def test_two_topic_globs() -> None:
+    assert TAPO_HUB_STATE_TOPIC == "tapo/+/+/state"
+    assert TAPO_HUB_ENERGY_TOPIC == "tapo/+/+/energy"
+    assert set(TapoEcosystemAdapter.subscribe_topics) == {
+        TAPO_HUB_STATE_TOPIC,
+        TAPO_HUB_ENERGY_TOPIC,
+    }
+
+
+async def test_adapter_persists_hub_event(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    db_path = tmp_path / "tapo_ecosystem.db"
+    monkeypatch.setattr(
+        "alter_runtime.adapters.household.tapo_ecosystem.adapter.TapoEcosystemStorage",
+        lambda: TapoEcosystemStorage(db_path=db_path),
+    )
+    bus = EventBus()
+    adapter = TapoEcosystemAdapter(config=DaemonConfig(), bus=bus)
+    await adapter.handle_event(
+        {
+            "hub_mac": "AA:BB:CC:DD:EE:00",
+            "device_mac": "AA:BB:CC:DD:EE:01",
+            "device_kind": "plug",
+            "ts": "2026-05-27T00:00:00Z",
+        }
+    )
+    assert await TapoEcosystemStorage(db_path=db_path).event_count() == 1
+
+
+async def test_adapter_drops_incomplete_event() -> None:
+    bus = EventBus()
+    adapter = TapoEcosystemAdapter(config=DaemonConfig(), bus=bus)
+    # All three core fields missing — must not raise.
+    await adapter.handle_event({"device_kind": "plug"})
+    await adapter.handle_event({})
+    await adapter.handle_event("not a dict")

alter_runtime/adapters/household/tapo_ecosystem/tests/test_storage.py

@@ -0,0 +1,28 @@
+"""Tests for tapo_ecosystem SQLite storage — mode 600 + event insert."""
+
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+
+from alter_runtime.adapters.household.tapo_ecosystem.storage import (
+    TapoEcosystemStorage,
+)
+
+
+async def test_db_file_mode_is_600(tmp_path: Path) -> None:
+    db_path = tmp_path / "tapo_ecosystem.db"
+    TapoEcosystemStorage(db_path=db_path)
+    mode = stat.S_IMODE(db_path.stat().st_mode)
+    assert mode == 0o600, f"expected 0o600, got {oct(mode)}"
+
+
+async def test_record_event_persists_row(tmp_path: Path) -> None:
+    db_path = tmp_path / "tapo_ecosystem.db"
+    storage = TapoEcosystemStorage(db_path=db_path)
+    assert await storage.event_count() == 0
+    await storage.record_event(hub_mac="HUB:01", device_mac="DEV:01", device_kind="plug", ts=None)
+    await storage.record_event(
+        hub_mac="HUB:01", device_mac="DEV:02", device_kind="temp_humid", ts=None
+    )
+    assert await storage.event_count() == 2

alter_runtime/adapters/household/tapo_ecosystem/tests/test_traits.py

@@ -0,0 +1,45 @@
+"""Tests for tapo_ecosystem trait emitter — Clause-4 banlist + bands."""
+
+from __future__ import annotations
+
+import pytest
+
+from alter_runtime.adapters.household.tapo_ecosystem.traits import (
+    CLAUSE_4_BANLIST,
+    BannedTraitKindError,
+    TapoEcosystemTraits,
+)
+
+
+def test_banlist_contains_all_spec_kinds() -> None:
+    expected = {
+        "household-presence-inference",
+        "co-occupant-counting",
+        "bedroom-presence",
+        "sleep-cycle",
+        "motion-as-affect",
+        "classroom-Tapo-in-school-suitability",
+        "family-violence-stalker-hardware-detection",
+        "landlord-tenant-monitoring",
+    }
+    assert expected.issubset(CLAUSE_4_BANLIST)
+
+
+@pytest.mark.parametrize("banned_kind", sorted(CLAUSE_4_BANLIST))
+def test_banned_kinds_are_refused(banned_kind: str) -> None:
+    traits = TapoEcosystemTraits()
+    with pytest.raises(BannedTraitKindError):
+        traits.emit(banned_kind, band="moderate")
+
+
+def test_three_canonical_traits_emit() -> None:
+    traits = TapoEcosystemTraits()
+    a = traits.emit_household_appliance_stewardship("high")
+    b = traits.emit_household_routine_cadence("steady")
+    c = traits.emit_ambient_stewardship("tended")
+    assert a.kind == "household_appliance_stewardship" and a.band == "high"
+    assert b.kind == "household_routine_cadence" and b.band == "steady"
+    assert c.kind == "ambient_stewardship" and c.band == "tended"
+    for emission in (a, b, c):
+        assert emission.provenance == "passive_local_multi_parameter"
+        assert emission.stream == "tapo"

alter_runtime/adapters/household/tapo_ecosystem/traits.py

@@ -0,0 +1,97 @@
+"""Tapo ecosystem trait band emitters (Eco-14) with Clause-4 banlist.
+
+Three banded traits (stub spec §5):
+
+* ``household_appliance_stewardship``
+* ``household_routine_cadence``
+* ``ambient_stewardship``
+
+Clause-4 banlist (stub spec §5):
+
+* ``household-presence-inference``
+* ``co-occupant-counting``
+* ``bedroom-presence``
+* ``sleep-cycle``
+* ``motion-as-affect``
+* ``classroom-Tapo-in-school-suitability``
+* ``family-violence-stalker-hardware-detection``
+* ``landlord-tenant-monitoring``
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+__all__ = [
+    "AppliancesStewardshipBand",
+    "AmbientStewardshipBand",
+    "BannedTraitKindError",
+    "CLAUSE_4_BANLIST",
+    "RoutineCadenceBand",
+    "TapoEcosystemTraitEmission",
+    "TapoEcosystemTraits",
+]
+
+logger = logging.getLogger("alter_runtime.adapters.household.tapo_ecosystem.traits")
+
+CLAUSE_4_BANLIST: frozenset[str] = frozenset(
+    {
+        "household-presence-inference",
+        "co-occupant-counting",
+        "bedroom-presence",
+        "sleep-cycle",
+        "motion-as-affect",
+        "classroom-Tapo-in-school-suitability",
+        "family-violence-stalker-hardware-detection",
+        "landlord-tenant-monitoring",
+    }
+)
+
+AppliancesStewardshipBand = Literal["low", "moderate", "high", "exemplary"]
+RoutineCadenceBand = Literal["sparse", "uneven", "steady", "anchored"]
+AmbientStewardshipBand = Literal["volatile", "drifting", "tended", "well-tended"]
+
+
+class BannedTraitKindError(RuntimeError):
+    """Raised when a caller requests a Clause-4-banned trait kind."""
+
+
+class TapoEcosystemTraitEmission(BaseModel):
+    kind: str = Field(description="Trait kind, e.g. 'household_appliance_stewardship'")
+    band: str = Field(description="Banded label (never numeric)")
+    provenance: str = Field(default="passive_local_multi_parameter")
+    stream: str = Field(default="tapo")
+
+
+class TapoEcosystemTraits:
+    """Tapo ecosystem trait emitter with Clause-4 banlist enforcement."""
+
+    def emit(self, kind: str, band: str) -> TapoEcosystemTraitEmission:
+        self._refuse_if_banned(kind)
+        # TODO(clause-3-identity-income): return/x402 hook attaches here per
+        #   D-PROV-1 + clause-3 ratification.  Each emission upward is the
+        #   point at which Identity-Income return-flow is metered.  Hook
+        #   implementation lives outside this scaffold pass.
+        return TapoEcosystemTraitEmission(kind=kind, band=band)
+
+    def emit_household_appliance_stewardship(
+        self, band: AppliancesStewardshipBand
+    ) -> TapoEcosystemTraitEmission:
+        return self.emit("household_appliance_stewardship", band)
+
+    def emit_household_routine_cadence(
+        self, band: RoutineCadenceBand
+    ) -> TapoEcosystemTraitEmission:
+        return self.emit("household_routine_cadence", band)
+
+    def emit_ambient_stewardship(self, band: AmbientStewardshipBand) -> TapoEcosystemTraitEmission:
+        return self.emit("ambient_stewardship", band)
+
+    @staticmethod
+    def _refuse_if_banned(kind: str) -> None:
+        if kind in CLAUSE_4_BANLIST:
+            logger.warning("tapo_ecosystem refusing Clause-4-banned trait kind=%s", kind)
+            raise BannedTraitKindError(f"trait kind {kind!r} is Clause-4 banned for tapo_ecosystem")

alter_runtime/adapters/household/workshop_tools/__init__.py

@@ -0,0 +1,25 @@
+"""Workshop-tools substrate adapter (Eco-12).
+
+Subscribes to MQTT topic glob ``tapo/plug/+/energy`` (via the household
+event-bus bridge) and computes per-plug rolling-30-day Wh signature,
+diversity, and cadence band.  Persists to
+``~/.local/share/alter-runtime/workshop_tools.db`` (mode 600).  Emits
+trait bands only — never raw Wh.
+
+Spec: ``.repos/internal/02-Technical-Strategy/workshop-tool-substrate-adapter-2026-05-19.md``
+Stub: ``phase2-wave2-stub-specs-pack-2026-05-27.md`` (Eco-12 line).
+"""
+
+from alter_runtime.adapters.household.workshop_tools.adapter import (
+    WorkshopToolsAdapter,
+)
+from alter_runtime.adapters.household.workshop_tools.traits import (
+    CLAUSE_4_BANLIST,
+    WorkshopToolsTraits,
+)
+
+__all__ = [
+    "CLAUSE_4_BANLIST",
+    "WorkshopToolsAdapter",
+    "WorkshopToolsTraits",
+]

alter_runtime/adapters/household/workshop_tools/adapter.py

@@ -0,0 +1,77 @@
+"""Workshop-tools adapter (Eco-12) — EventBusSubscriber over MQTT.
+
+The household event-bus bridge republishes Home-Assistant /
+Mosquitto-relayed Tapo plug telemetry onto the in-process bus.  This
+adapter subscribes to the topic glob ``tapo/plug/+/energy``, normalises
+each event into a per-plug Wh sample, and feeds the trait band
+computation.
+
+Per the spec (§5) raw Wh traces, fingerprint vectors, and maker-authored
+plug labels never leave the daemon.  This module deliberately stops at
+sample-ingest + storage hand-off; the NILMTK signature classifier and
+the 30-day rolling fingerprint are downstream of the storage layer in a
+follow-up implementation pass.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from alter_runtime.adapters.household._base import EventBusSubscriberBase
+from alter_runtime.adapters.household.workshop_tools.storage import (
+    WorkshopToolsStorage,
+)
+from alter_runtime.adapters.household.workshop_tools.traits import (
+    WorkshopToolsTraits,
+)
+from alter_runtime.config import DaemonConfig
+from alter_runtime.subscribers.bus import EventBus
+
+__all__ = ["WorkshopToolsAdapter", "TAPO_PLUG_ENERGY_TOPIC"]
+
+#: MQTT topic glob bridged onto the in-process bus.
+TAPO_PLUG_ENERGY_TOPIC: str = "tapo/plug/+/energy"
+
+
+class WorkshopToolsAdapter(EventBusSubscriberBase):
+    """Workshop-tools (Eco-12) adapter."""
+
+    name: str = "workshop_tools"
+    subscribe_topics: tuple[str, ...] = (TAPO_PLUG_ENERGY_TOPIC,)
+
+    def __init__(self, config: DaemonConfig, bus: EventBus) -> None:
+        super().__init__(config, bus)
+        self._storage = WorkshopToolsStorage()
+        self._traits = WorkshopToolsTraits()
+
+    async def handle_event(self, payload: Any) -> None:
+        """Normalise one MQTT-bridged energy event and persist a sample.
+
+        Expected payload shape (best-effort)::
+
+            {"plug_mac": "AA:BB:...", "watt_hours": 12.3, "ts": "2026-..."}
+
+        Unknown fields are tolerated; missing core fields are dropped
+        with a warning.
+        """
+        if not isinstance(payload, dict):
+            self._logger.debug("workshop_tools ignoring non-dict payload")
+            return
+        plug_mac = payload.get("plug_mac") or payload.get("device_id")
+        wh = payload.get("watt_hours") or payload.get("wh")
+        ts = payload.get("ts") or payload.get("timestamp")
+        if not plug_mac or wh is None:
+            self._logger.debug(
+                "workshop_tools dropping incomplete event keys=%s", list(payload.keys())
+            )
+            return
+
+        # TODO(eco-12): validate plug_mac shape (AA:BB:CC:DD:EE:FF) before persist.
+        # TODO(eco-12): NILMTK fingerprint classification on rolling power-curve
+        #   window — current scaffold persists raw Wh samples only.
+        # TODO(eco-12): rolling-30-day diversity + cadence aggregation across
+        #   per-plug samples; downstream of storage layer.
+        # TODO(eco-12): emit trait bands via self._traits.emit_*() once a
+        #   classifier window closes; current scaffold writes samples and
+        #   stops — no upward emission yet.
+        await self._storage.record_sample(plug_mac=str(plug_mac), wh=float(wh), ts=ts)

alter_runtime/adapters/household/workshop_tools/storage.py

@@ -0,0 +1,92 @@
+"""Workshop-tools storage layer — local SQLite, mode 600.
+
+Persists per-plug Wh samples in
+``~/.local/share/alter-runtime/workshop_tools.db``.  The file is
+created mode ``0o600`` before SQLite ever opens it, so a same-host
+non-daemon user cannot read the trace.
+
+This is a stub: schema and write path land; the rolling-30-day
+aggregation, NILMTK fingerprint window, and trait-band derivation are
+``# TODO(eco-12)`` for the follow-up implementation pass.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from alter_runtime.config import data_dir
+
+__all__ = ["WorkshopToolsStorage", "DB_FILENAME"]
+
+logger = logging.getLogger("alter_runtime.adapters.household.workshop_tools.storage")
+
+DB_FILENAME: str = "workshop_tools.db"
+
+_SCHEMA: str = """
+CREATE TABLE IF NOT EXISTS plug_energy_samples (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    plug_mac    TEXT    NOT NULL,
+    wh          REAL    NOT NULL,
+    ts          TEXT,
+    created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_samples_plug_mac
+    ON plug_energy_samples (plug_mac);
+"""
+
+
+class WorkshopToolsStorage:
+    """Async-friendly wrapper around a tiny ``sqlite3`` store.
+
+    Stdlib ``sqlite3`` is sync; we run writes inside ``asyncio.to_thread``
+    so the supervisor loop is never blocked by disk IO.
+    """
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path = db_path or (data_dir() / DB_FILENAME)
+        self._lock = asyncio.Lock()
+        self._ensure_db()
+
+    @property
+    def db_path(self) -> Path:
+        return self._db_path
+
+    def _ensure_db(self) -> None:
+        """Touch the DB file mode 0o600 then init schema."""
+        self._db_path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if not self._db_path.exists():
+            self._db_path.touch(mode=0o600, exist_ok=True)
+        else:
+            try:
+                self._db_path.chmod(0o600)
+            except OSError as exc:  # pragma: no cover — best-effort tightening
+                logger.warning("workshop_tools chmod 0o600 failed: %s", exc)
+        with sqlite3.connect(self._db_path) as conn:
+            conn.executescript(_SCHEMA)
+
+    async def record_sample(self, *, plug_mac: str, wh: float, ts: Any | None = None) -> None:
+        """Persist one Wh sample.  Returns once the row is committed."""
+        async with self._lock:
+            await asyncio.to_thread(self._insert_sample, plug_mac, wh, ts)
+
+    def _insert_sample(self, plug_mac: str, wh: float, ts: Any | None) -> None:
+        with sqlite3.connect(self._db_path) as conn:
+            conn.execute(
+                "INSERT INTO plug_energy_samples (plug_mac, wh, ts) VALUES (?, ?, ?)",
+                (plug_mac, wh, str(ts) if ts is not None else None),
+            )
+            conn.commit()
+
+    async def sample_count(self) -> int:
+        """Test introspection — number of rows currently persisted."""
+        return await asyncio.to_thread(self._sample_count_sync)
+
+    def _sample_count_sync(self) -> int:
+        with sqlite3.connect(self._db_path) as conn:
+            cur = conn.execute("SELECT COUNT(*) FROM plug_energy_samples")
+            row = cur.fetchone()
+            return int(row[0]) if row else 0

alter_runtime/adapters/household/workshop_tools/tests/test_adapter.py

@@ -0,0 +1,48 @@
+"""Tests for WorkshopToolsAdapter — subscribe/handle round-trip."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from alter_runtime.adapters.household.workshop_tools.adapter import (
+    TAPO_PLUG_ENERGY_TOPIC,
+    WorkshopToolsAdapter,
+)
+from alter_runtime.adapters.household.workshop_tools.storage import (
+    WorkshopToolsStorage,
+)
+from alter_runtime.config import DaemonConfig
+from alter_runtime.subscribers.bus import EventBus
+
+
+def test_subscribe_topic_matches_tapo_glob() -> None:
+    assert TAPO_PLUG_ENERGY_TOPIC == "tapo/plug/+/energy"
+    assert TAPO_PLUG_ENERGY_TOPIC in WorkshopToolsAdapter.subscribe_topics
+
+
+async def test_adapter_persists_bridged_event(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    db_path = tmp_path / "workshop_tools.db"
+    # Stub the adapter's storage to our tmp DB without touching ~/.local/share.
+    monkeypatch.setattr(
+        "alter_runtime.adapters.household.workshop_tools.adapter.WorkshopToolsStorage",
+        lambda: WorkshopToolsStorage(db_path=db_path),
+    )
+
+    bus = EventBus()
+    adapter = WorkshopToolsAdapter(config=DaemonConfig(), bus=bus)
+
+    await adapter.handle_event({"plug_mac": "AA:BB:CC:DD:EE:01", "watt_hours": 42.0, "ts": None})
+    assert await WorkshopToolsStorage(db_path=db_path).sample_count() == 1
+
+
+async def test_adapter_drops_incomplete_event(tmp_path: Path) -> None:
+    bus = EventBus()
+    adapter = WorkshopToolsAdapter(config=DaemonConfig(), bus=bus)
+    # Missing plug_mac — should silently drop, no exception.
+    await adapter.handle_event({"watt_hours": 12.3})
+    await adapter.handle_event("not a dict")
+    await adapter.handle_event(None)

alter_runtime/adapters/household/workshop_tools/tests/test_storage.py

@@ -0,0 +1,26 @@
+"""Tests for workshop_tools SQLite storage — mode 0o600 + sample insert."""
+
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+
+from alter_runtime.adapters.household.workshop_tools.storage import (
+    WorkshopToolsStorage,
+)
+
+
+async def test_db_file_mode_is_600(tmp_path: Path) -> None:
+    db_path = tmp_path / "workshop_tools.db"
+    WorkshopToolsStorage(db_path=db_path)
+    mode = stat.S_IMODE(db_path.stat().st_mode)
+    assert mode == 0o600, f"expected mode 0o600, got {oct(mode)}"
+
+
+async def test_record_sample_persists_row(tmp_path: Path) -> None:
+    db_path = tmp_path / "workshop_tools.db"
+    storage = WorkshopToolsStorage(db_path=db_path)
+    assert await storage.sample_count() == 0
+    await storage.record_sample(plug_mac="AA:BB:CC:DD:EE:01", wh=12.3, ts=None)
+    await storage.record_sample(plug_mac="AA:BB:CC:DD:EE:02", wh=7.5, ts="2026-05-27")
+    assert await storage.sample_count() == 2

alter_runtime/adapters/household/workshop_tools/tests/test_traits.py

@@ -0,0 +1,45 @@
+"""Tests for workshop_tools trait emitter — Clause-4 banlist + band shape."""
+
+from __future__ import annotations
+
+import pytest
+
+from alter_runtime.adapters.household.workshop_tools.traits import (
+    CLAUSE_4_BANLIST,
+    BannedTraitKindError,
+    WorkshopToolsTraits,
+)
+
+
+def test_banlist_contains_all_spec_kinds() -> None:
+    expected = {
+        "workshop-affect",
+        "craft-burnout",
+        "focus-fatigue",
+        "production-pressure",
+        "flow-state-inference",
+        "classroom-workshop-suitability",
+    }
+    assert expected.issubset(CLAUSE_4_BANLIST)
+
+
+@pytest.mark.parametrize("banned_kind", sorted(CLAUSE_4_BANLIST))
+def test_banned_kinds_are_refused(banned_kind: str) -> None:
+    traits = WorkshopToolsTraits()
+    with pytest.raises(BannedTraitKindError):
+        traits.emit(banned_kind, band="deep")
+
+
+def test_focus_block_depth_emits_band() -> None:
+    traits = WorkshopToolsTraits()
+    emission = traits.emit_focus_block_depth("deep")
+    assert emission.kind == "focus_block_depth"
+    assert emission.band == "deep"
+    assert emission.provenance == "passive_local_sensor"
+    assert emission.stream == "workshop_tool"
+
+
+def test_workshop_steward_active_bool_to_band() -> None:
+    traits = WorkshopToolsTraits()
+    assert traits.emit_workshop_steward_active(True).band == "active"
+    assert traits.emit_workshop_steward_active(False).band == "inactive"