alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/adapters/household/self_hoster/storage.py

@@ -0,0 +1,83 @@
+"""Self-hoster storage layer — local SQLite, mode 600.
+
+Persists per-sub-trait observation rows.  Schema is deliberately
+coarse: ``kind`` + a short summary string + timestamp.  Detailed
+per-source values (package lists, snapshot mtimes, cert expiries) stay
+inside the adapter's poll cycle and never reach the storage layer.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sqlite3
+from pathlib import Path
+
+from alter_runtime.config import data_dir
+
+__all__ = ["SelfHosterStorage", "DB_FILENAME"]
+
+logger = logging.getLogger("alter_runtime.adapters.household.self_hoster.storage")
+
+DB_FILENAME: str = "self_hoster.db"
+
+_SCHEMA: str = """
+CREATE TABLE IF NOT EXISTS subtrait_observations (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    kind            TEXT    NOT NULL,
+    value_summary   TEXT    NOT NULL,
+    observed_at     TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_subtrait_kind
+    ON subtrait_observations (kind);
+"""
+
+
+class SelfHosterStorage:
+    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("self_hoster chmod 0o600 failed: %s", exc)
+        with sqlite3.connect(self._db_path) as conn:
+            conn.executescript(_SCHEMA)
+
+    async def record_observation(self, *, kind: str, value_summary: str) -> None:
+        async with self._lock:
+            await asyncio.to_thread(self._insert_observation, kind, value_summary)
+
+    def _insert_observation(self, kind: str, value_summary: str) -> None:
+        with sqlite3.connect(self._db_path) as conn:
+            conn.execute(
+                "INSERT INTO subtrait_observations (kind, value_summary) VALUES (?, ?)",
+                (kind, value_summary),
+            )
+            conn.commit()
+
+    async def observation_count(self, *, kind: str | None = None) -> int:
+        return await asyncio.to_thread(self._observation_count_sync, kind)
+
+    def _observation_count_sync(self, kind: str | None) -> int:
+        with sqlite3.connect(self._db_path) as conn:
+            if kind is None:
+                cur = conn.execute("SELECT COUNT(*) FROM subtrait_observations")
+            else:
+                cur = conn.execute(
+                    "SELECT COUNT(*) FROM subtrait_observations WHERE kind = ?",
+                    (kind,),
+                )
+            row = cur.fetchone()
+            return int(row[0]) if row else 0

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

@@ -0,0 +1,216 @@
+"""Tests for SelfHosterAdapter — poll_once invokes all five sub-observers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from alter_runtime.adapters.household.self_hoster.adapter import (
+    DEFAULT_POLL_INTERVAL_SECONDS,
+    AllowlistViolationError,
+    SelfHosterAdapter,
+    SelfHosterAllowlists,
+)
+from alter_runtime.adapters.household.self_hoster.storage import SelfHosterStorage
+from alter_runtime.config import DaemonConfig
+
+
+def test_default_poll_interval_is_6_hours() -> None:
+    assert DEFAULT_POLL_INTERVAL_SECONDS == 6 * 60 * 60
+    assert SelfHosterAdapter.poll_interval_seconds == 6 * 60 * 60
+
+
+def test_allowlists_default_to_empty_tuples() -> None:
+    allowlists = SelfHosterAllowlists()
+    assert allowlists.systemd_units == ()
+    assert allowlists.backup_repo_paths == ()
+    assert allowlists.letsencrypt_cert_dirs == ()
+
+
+async def test_poll_once_records_one_row_per_subtrait(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    db_path = tmp_path / "self_hoster.db"
+    monkeypatch.setattr(
+        "alter_runtime.adapters.household.self_hoster.adapter.SelfHosterStorage",
+        lambda: SelfHosterStorage(db_path=db_path),
+    )
+    adapter = SelfHosterAdapter(
+        config=DaemonConfig(),
+        allowlists=SelfHosterAllowlists(
+            systemd_units=("nginx.service",),
+            backup_repo_paths=(Path("/tmp/restic-fake"),),
+            letsencrypt_cert_dirs=(Path("/tmp/letsencrypt-fake/live/example"),),
+        ),
+    )
+    await adapter.poll_once()
+    storage = SelfHosterStorage(db_path=db_path)
+    # Five sub-trait observations recorded in one poll cycle.
+    assert await storage.observation_count() == 5
+    for kind in (
+        "os_update_discipline",
+        "backup_cadence",
+        "self_hosted_service_breadth",
+        "tls_hygiene",
+        "uptime_steward",
+    ):
+        assert await storage.observation_count(kind=kind) == 1
+
+
+# ----------------------------------------------------------------------
+# V&V hardening (2026-05-28): observer-execution allowlist guard tests
+# ----------------------------------------------------------------------
+
+
+def _adapter_with(
+    *,
+    systemd_units: tuple[str, ...] = (),
+    backup_repo_paths: tuple[Path, ...] = (),
+    letsencrypt_cert_dirs: tuple[Path, ...] = (),
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> SelfHosterAdapter:
+    db_path = tmp_path / "self_hoster.db"
+    monkeypatch.setattr(
+        "alter_runtime.adapters.household.self_hoster.adapter.SelfHosterStorage",
+        lambda: SelfHosterStorage(db_path=db_path),
+    )
+    return SelfHosterAdapter(
+        config=DaemonConfig(),
+        allowlists=SelfHosterAllowlists(
+            systemd_units=systemd_units,
+            backup_repo_paths=backup_repo_paths,
+            letsencrypt_cert_dirs=letsencrypt_cert_dirs,
+        ),
+    )
+
+
+def test_observer_refuses_out_of_allowlist_systemd_unit(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A systemd-unit target not in allowlists.systemd_units MUST be refused."""
+    adapter = _adapter_with(
+        systemd_units=("nginx.service",),
+        tmp_path=tmp_path,
+        monkeypatch=monkeypatch,
+    )
+    with pytest.raises(AllowlistViolationError) as exc:
+        adapter._check_allowlist(
+            kind="self_hosted_service_breadth",
+            target="sshd.service",
+            bucket="systemd_units",
+        )
+    msg = str(exc.value)
+    assert "sshd.service" in msg
+    assert "systemd_units" in msg
+
+
+def test_observer_refuses_out_of_allowlist_backup_path(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A backup-repo path not in allowlists.backup_repo_paths MUST be refused."""
+    adapter = _adapter_with(
+        backup_repo_paths=(Path("/tmp/restic-fake"),),
+        tmp_path=tmp_path,
+        monkeypatch=monkeypatch,
+    )
+    with pytest.raises(AllowlistViolationError) as exc:
+        adapter._check_allowlist(
+            kind="backup_cadence",
+            target=Path("/etc/shadow"),
+            bucket="backup_repo_paths",
+        )
+    msg = str(exc.value)
+    assert "/etc/shadow" in msg
+    assert "backup_repo_paths" in msg
+
+
+def test_observer_refuses_out_of_allowlist_letsencrypt_dir(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A LE-cert dir not in allowlists.letsencrypt_cert_dirs MUST be refused."""
+    adapter = _adapter_with(
+        letsencrypt_cert_dirs=(Path("/tmp/letsencrypt-fake/live/example"),),
+        tmp_path=tmp_path,
+        monkeypatch=monkeypatch,
+    )
+    with pytest.raises(AllowlistViolationError) as exc:
+        adapter._check_allowlist(
+            kind="tls_hygiene",
+            target=Path("/etc/letsencrypt/live/other.example.com"),
+            bucket="letsencrypt_cert_dirs",
+        )
+    msg = str(exc.value)
+    assert "other.example.com" in msg
+    assert "letsencrypt_cert_dirs" in msg
+
+
+def test_observer_proceeds_for_in_allowlist_target(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Positive control — in-allowlist targets across all three buckets pass."""
+    backup_path = Path("/tmp/restic-fake")
+    le_dir = Path("/tmp/letsencrypt-fake/live/example")
+    adapter = _adapter_with(
+        systemd_units=("nginx.service",),
+        backup_repo_paths=(backup_path,),
+        letsencrypt_cert_dirs=(le_dir,),
+        tmp_path=tmp_path,
+        monkeypatch=monkeypatch,
+    )
+    # None of these should raise.
+    adapter._check_allowlist(
+        kind="self_hosted_service_breadth",
+        target="nginx.service",
+        bucket="systemd_units",
+    )
+    adapter._check_allowlist(
+        kind="backup_cadence",
+        target=backup_path,
+        bucket="backup_repo_paths",
+    )
+    adapter._check_allowlist(
+        kind="tls_hygiene",
+        target=le_dir,
+        bucket="letsencrypt_cert_dirs",
+    )
+
+
+async def test_invoke_observer_runs_only_when_target_in_allowlist(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """_invoke_observer awaits the invocation only when allowlist passes."""
+    backup_path = Path("/tmp/restic-fake")
+    adapter = _adapter_with(
+        backup_repo_paths=(backup_path,),
+        tmp_path=tmp_path,
+        monkeypatch=monkeypatch,
+    )
+    invocations: list[str] = []
+
+    async def fake_read() -> str:
+        invocations.append("ran")
+        return "ok"
+
+    # In-allowlist: invocation runs.
+    result = await adapter._invoke_observer(
+        kind="backup_cadence",
+        target=backup_path,
+        bucket="backup_repo_paths",
+        invocation=fake_read,
+    )
+    assert result == "ok"
+    assert invocations == ["ran"]
+
+    # Out-of-allowlist: invocation MUST NOT run.
+    with pytest.raises(AllowlistViolationError):
+        await adapter._invoke_observer(
+            kind="backup_cadence",
+            target=Path("/etc/shadow"),
+            bucket="backup_repo_paths",
+            invocation=fake_read,
+        )
+    assert invocations == ["ran"], (
+        "_invoke_observer must not await the invocation when the allowlist refuses"
+    )

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

@@ -0,0 +1,25 @@
+"""Tests for self_hoster SQLite storage — mode 600 + observation insert."""
+
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+
+from alter_runtime.adapters.household.self_hoster.storage import SelfHosterStorage
+
+
+async def test_db_file_mode_is_600(tmp_path: Path) -> None:
+    db_path = tmp_path / "self_hoster.db"
+    SelfHosterStorage(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_observation_persists_row(tmp_path: Path) -> None:
+    db_path = tmp_path / "self_hoster.db"
+    storage = SelfHosterStorage(db_path=db_path)
+    assert await storage.observation_count() == 0
+    await storage.record_observation(kind="tls_hygiene", value_summary="2/2 valid")
+    await storage.record_observation(kind="backup_cadence", value_summary="last 1h ago")
+    assert await storage.observation_count() == 2
+    assert await storage.observation_count(kind="tls_hygiene") == 1

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

@@ -0,0 +1,55 @@
+"""Tests for self_hoster trait emitter — Clause-4 banlist + bands."""
+
+from __future__ import annotations
+
+import pytest
+
+from alter_runtime.adapters.household.self_hoster.traits import (
+    CLAUSE_4_BANLIST,
+    BannedTraitKindError,
+    SelfHosterTraits,
+)
+
+
+def test_banlist_contains_all_spec_kinds() -> None:
+    expected = {
+        "sysadmin-burnout",
+        "self-hoster-anxiety",
+        "patching-stress",
+        "tech-debt-shame",
+        "homelab-fatigue",
+        "CVE-panic",
+        "classroom-IT-administrator-suitability",
+        "employer-tier-engineering-grading",
+        "security-firm-risk-scoring",
+    }
+    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 = SelfHosterTraits()
+    with pytest.raises(BannedTraitKindError):
+        traits.emit(banned_kind, band="steady")
+
+
+def test_five_canonical_subtraits_emit() -> None:
+    traits = SelfHosterTraits()
+    emissions = [
+        traits.emit_os_update_discipline("regular"),
+        traits.emit_backup_cadence("daily"),
+        traits.emit_self_hosted_service_breadth("broad"),
+        traits.emit_tls_hygiene("compliant"),
+        traits.emit_uptime_steward("steady"),
+    ]
+    kinds = [e.kind for e in emissions]
+    assert kinds == [
+        "os_update_discipline",
+        "backup_cadence",
+        "self_hosted_service_breadth",
+        "tls_hygiene",
+        "uptime_steward",
+    ]
+    for e in emissions:
+        assert e.provenance == "passive_local_multi_parameter"
+        assert e.stream == "self_hoster"

alter_runtime/adapters/household/self_hoster/traits.py

@@ -0,0 +1,105 @@
+"""Self-hoster trait band emitters (Eco-15) with Clause-4 banlist.
+
+Five banded sub-traits (stub spec §6):
+
+* ``os_update_discipline``
+* ``backup_cadence``
+* ``self_hosted_service_breadth``
+* ``tls_hygiene``
+* ``uptime_steward``
+
+Clause-4 banlist (stub spec §6):
+
+* ``sysadmin-burnout``
+* ``self-hoster-anxiety``
+* ``patching-stress``
+* ``tech-debt-shame``
+* ``homelab-fatigue``
+* ``CVE-panic``
+* ``classroom-IT-administrator-suitability``
+* ``employer-tier-engineering-grading``
+* ``security-firm-risk-scoring``
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+__all__ = [
+    "BackupCadenceBand",
+    "BannedTraitKindError",
+    "CLAUSE_4_BANLIST",
+    "OsUpdateDisciplineBand",
+    "SelfHosterTraitEmission",
+    "SelfHosterTraits",
+    "ServiceBreadthBand",
+    "TlsHygieneBand",
+    "UptimeStewardBand",
+]
+
+logger = logging.getLogger("alter_runtime.adapters.household.self_hoster.traits")
+
+CLAUSE_4_BANLIST: frozenset[str] = frozenset(
+    {
+        "sysadmin-burnout",
+        "self-hoster-anxiety",
+        "patching-stress",
+        "tech-debt-shame",
+        "homelab-fatigue",
+        "CVE-panic",
+        "classroom-IT-administrator-suitability",
+        "employer-tier-engineering-grading",
+        "security-firm-risk-scoring",
+    }
+)
+
+OsUpdateDisciplineBand = Literal["lapsed", "irregular", "regular", "vigilant"]
+BackupCadenceBand = Literal["absent", "sporadic", "weekly", "daily"]
+ServiceBreadthBand = Literal["minimal", "narrow", "broad", "wide"]
+TlsHygieneBand = Literal["lapsed", "uneven", "compliant", "exemplary"]
+UptimeStewardBand = Literal["unstable", "intermittent", "steady", "exemplary"]
+
+
+class BannedTraitKindError(RuntimeError):
+    """Raised when a caller requests a Clause-4-banned trait kind."""
+
+
+class SelfHosterTraitEmission(BaseModel):
+    kind: str = Field(description="Sub-trait kind, e.g. 'tls_hygiene'")
+    band: str = Field(description="Banded label (never numeric)")
+    provenance: str = Field(default="passive_local_multi_parameter")
+    stream: str = Field(default="self_hoster")
+
+
+class SelfHosterTraits:
+    def emit(self, kind: str, band: str) -> SelfHosterTraitEmission:
+        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 SelfHosterTraitEmission(kind=kind, band=band)
+
+    def emit_os_update_discipline(self, band: OsUpdateDisciplineBand) -> SelfHosterTraitEmission:
+        return self.emit("os_update_discipline", band)
+
+    def emit_backup_cadence(self, band: BackupCadenceBand) -> SelfHosterTraitEmission:
+        return self.emit("backup_cadence", band)
+
+    def emit_self_hosted_service_breadth(self, band: ServiceBreadthBand) -> SelfHosterTraitEmission:
+        return self.emit("self_hosted_service_breadth", band)
+
+    def emit_tls_hygiene(self, band: TlsHygieneBand) -> SelfHosterTraitEmission:
+        return self.emit("tls_hygiene", band)
+
+    def emit_uptime_steward(self, band: UptimeStewardBand) -> SelfHosterTraitEmission:
+        return self.emit("uptime_steward", band)
+
+    @staticmethod
+    def _refuse_if_banned(kind: str) -> None:
+        if kind in CLAUSE_4_BANLIST:
+            logger.warning("self_hoster refusing Clause-4-banned trait kind=%s", kind)
+            raise BannedTraitKindError(f"trait kind {kind!r} is Clause-4 banned for self_hoster")

alter_runtime/adapters/household/tapo_ecosystem/__init__.py

@@ -0,0 +1,22 @@
+"""Tapo ecosystem adapter (Eco-14) — hub-level multi-parameter composition.
+
+Subscribes at hub level: N parameters at one logical location (the H100
+hub).  ``MultiParameterProvenanceRecord`` is composed across all paired
+Tapo devices.  Member-authored room-mapping (declared at pairing) stays
+LOCAL and is never surfaced upward.
+
+Three banded traits: ``household_appliance_stewardship``,
+``household_routine_cadence``, ``ambient_stewardship``.
+
+Spec: ``phase2-wave2-stub-specs-pack-2026-05-27.md`` §5.
+"""
+
+from alter_runtime.adapters.household.tapo_ecosystem.adapter import (
+    TapoEcosystemAdapter,
+)
+from alter_runtime.adapters.household.tapo_ecosystem.traits import (
+    CLAUSE_4_BANLIST,
+    TapoEcosystemTraits,
+)
+
+__all__ = ["CLAUSE_4_BANLIST", "TapoEcosystemAdapter", "TapoEcosystemTraits"]

alter_runtime/adapters/household/tapo_ecosystem/adapter.py

@@ -0,0 +1,98 @@
+"""Tapo ecosystem adapter (Eco-14) — H100/H200 hub-level composition.
+
+Subscribes to ``tapo/+/+/state`` and ``tapo/+/+/energy`` topic globs;
+all paired Tapo devices under one hub compose into a single
+``MultiParameterProvenanceRecord`` keyed by hub MAC.
+
+Per-device traces never leave the daemon; only hub-level fused band
+emits.  Room-mapping authored by the member at pairing stays LOCAL.
+
+Vendor-cloud posture (option b): TP-Link cloud REFUSED; python-kasa
+local API accepted at the LAN bridge layer; Tapo Cloud account-link
+REFUSED.  This adapter only consumes events the household-bridge
+republishes from the local LAN — it never originates cloud calls.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from alter_runtime.adapters.household._base import EventBusSubscriberBase
+from alter_runtime.adapters.household.tapo_ecosystem.storage import (
+    TapoEcosystemStorage,
+)
+from alter_runtime.adapters.household.tapo_ecosystem.traits import (
+    TapoEcosystemTraits,
+)
+from alter_runtime.config import DaemonConfig
+from alter_runtime.subscribers.bus import EventBus
+
+__all__ = [
+    "TAPO_HUB_ENERGY_TOPIC",
+    "TAPO_HUB_STATE_TOPIC",
+    "TapoEcosystemAdapter",
+]
+
+TAPO_HUB_STATE_TOPIC: str = "tapo/+/+/state"
+TAPO_HUB_ENERGY_TOPIC: str = "tapo/+/+/energy"
+
+
+class TapoEcosystemAdapter(EventBusSubscriberBase):
+    """Tapo ecosystem (Eco-14) hub-level adapter."""
+
+    name: str = "tapo_ecosystem"
+    subscribe_topics: tuple[str, ...] = (
+        TAPO_HUB_STATE_TOPIC,
+        TAPO_HUB_ENERGY_TOPIC,
+    )
+
+    def __init__(self, config: DaemonConfig, bus: EventBus) -> None:
+        super().__init__(config, bus)
+        self._storage = TapoEcosystemStorage()
+        self._traits = TapoEcosystemTraits()
+
+    async def handle_event(self, payload: Any) -> None:
+        """Normalise + persist one hub-level device event.
+
+        Expected payload shape (best-effort)::
+
+            {
+                "hub_mac": "AA:BB:...",
+                "device_mac": "CC:DD:...",
+                "device_kind": "plug" | "temp_humid" | "motion" | "door",
+                "value": <float or dict>,
+                "ts": "2026-..."
+            }
+
+        ``room`` may be present in the bridged payload but is dropped
+        before persistence — room-mapping stays at the bridge level.
+        """
+        if not isinstance(payload, dict):
+            self._logger.debug("tapo_ecosystem ignoring non-dict payload")
+            return
+        hub_mac = payload.get("hub_mac") or payload.get("hub")
+        device_mac = payload.get("device_mac") or payload.get("device_id")
+        device_kind = payload.get("device_kind") or payload.get("kind")
+        if not hub_mac or not device_mac or not device_kind:
+            self._logger.debug(
+                "tapo_ecosystem dropping incomplete event keys=%s",
+                list(payload.keys()),
+            )
+            return
+
+        # TODO(eco-14): MultiParameterProvenanceRecord composition keyed by
+        #   hub_mac — current scaffold persists per-device events flat.
+        # TODO(eco-14): compute household_appliance_stewardship band from
+        #   per-plug Wh fingerprint diversity × rolling-30-day cadence.
+        # TODO(eco-14): compute household_routine_cadence band from
+        #   T100/T110 event clustering against weekly self-baseline.
+        # TODO(eco-14): compute ambient_stewardship band from T310/T315
+        #   temp/humidity ranges against AU climate-zone reference.
+        # TODO(eco-14): strip `room` from payload at the daemon boundary
+        #   before any upward emit (room-mapping stays LOCAL).
+        await self._storage.record_event(
+            hub_mac=str(hub_mac),
+            device_mac=str(device_mac),
+            device_kind=str(device_kind),
+            ts=payload.get("ts") or payload.get("timestamp"),
+        )