steadystate 0.1.0__py3-none-any.whl

steadystate/__init__.py

@@ -0,0 +1,7 @@
+"""steadystate.ai — stateful monitoring.
+
+Reconcile declared infrastructure state (Terraform, ArgoCD, ...) against observed
+reality, reason about the drift, and surface only what's actionable.
+"""
+
+__version__ = "0.1.0"

steadystate/_http.py

@@ -0,0 +1,33 @@
+"""Internal HTTP helper: every outbound request goes through one audited urlopen.
+
+steadystate opens URLs the operator configures -- chat webhooks, a Prometheus/Grafana base,
+the ArgoCD/Rancher APIs, an LLM endpoint. Routing them all through one place lets us enforce a
+single invariant: we only ever speak http(s). That rejects ``file://``, ``ftp://``, ``gopher://``
+and the other schemes ``urllib`` would otherwise honor (the local-file / SSRF surface), and it
+fails fast with a clear error on a mistyped URL -- instead of silently reading a local file.
+"""
+
+from __future__ import annotations
+
+import urllib.request
+from typing import Any
+from urllib.parse import urlparse
+
+_ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+
+def _url_of(target: str | urllib.request.Request) -> str:
+    return target.full_url if isinstance(target, urllib.request.Request) else target
+
+
+def safe_urlopen(target: str | urllib.request.Request, *, timeout: float | None = None) -> Any:
+    """``urllib.request.urlopen`` restricted to http(s).
+
+    Raises ``ValueError`` for any other scheme (or a schemeless URL) *before* a socket opens.
+    Callers keep their own timeout + error handling; this only narrows *which* URLs may open.
+    """
+    scheme = urlparse(_url_of(target)).scheme.lower()
+    if scheme not in _ALLOWED_SCHEMES:
+        raise ValueError(f"refusing to open a non-http(s) URL (scheme: {scheme or 'none'!r})")
+    # B310: scheme is allow-listed to http(s) immediately above, so this is the audited gate.
+    return urllib.request.urlopen(target, timeout=timeout)  # nosec B310

steadystate/act/__init__.py

@@ -0,0 +1,57 @@
+"""Executor plugins + guardrails -- the act seam, keyed by source.
+
+Every remediation is apply-eligibility-checked, snapshotted, verified, and reversible; chat
+(or any trigger) is a convenience, never a bypass of those guardrails. Executors register
+here per source, mirroring DRIFT_SOURCES: a source with an executor can be *acted on*; a
+source with none is **observe-only** -- steadystate detects its drift but cannot remediate it,
+and build_executor returns None. Adding an in-tree backend's act half is one line in
+_BUILTIN_EXECUTORS.
+
+Out-of-tree executors register the same way without editing this file: a separately installed
+package declares a `steadystate.executors` entry point (a factory(path) -> Executor) and
+`merged()` overlays it on the built-ins (built-ins win a name clash). See plugins.py. A
+discovered executor is bound by source name, so it pairs with a discovered (or built-in) source.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from ..plugins import merged
+from .ansible import AnsibleExecutor
+from .base import Executor
+from .terraform import TerraformExecutor
+
+
+def _terraform(path: Path) -> Executor:
+    # A working dir can apply; a captured plan file can only plan (no dir to run in).
+    return TerraformExecutor(working_dir=None if path.is_file() else path)
+
+
+def _ansible(path: Path) -> Executor:
+    # The playbook + inventory come from env (STEADYSTATE_ANSIBLE_PLAYBOOK/_INVENTORY); a dir
+    # path is the working dir to run the playbook in (a captured-check file has none).
+    return AnsibleExecutor(working_dir=None if path.is_file() else path)
+
+
+# source name -> factory(path) -> Executor. Only sources listed here can act; everything
+# else is observe-only by omission. (k8s/compose are the next entries.)
+_BUILTIN_EXECUTORS: dict[str, Callable[[Path], Executor]] = {
+    "terraform": _terraform,
+    "ansible": _ansible,
+}
+
+# Built-ins overlaid with discovered `steadystate.executors` entry points.
+EXECUTORS: dict[str, Callable[[Path], Executor]] = merged("executors", _BUILTIN_EXECUTORS)
+
+__all__ = ["EXECUTORS", "Executor", "build_executor"]
+
+# Note: reflex/hold (the control loop) lives in act.reflex and is imported directly by callers --
+# kept out of this module's import graph to avoid a cycle (reflex -> approve -> act).
+
+
+def build_executor(source: str, path: Path) -> Executor | None:
+    """The registered Executor for ``source``, or None when the source is observe-only."""
+    factory = EXECUTORS.get(source)
+    return factory(path) if factory is not None else None

steadystate/act/ansible.py

@@ -0,0 +1,106 @@
+"""Ansible executor: reconcile a drifted host back to its playbook, with guardrails.
+
+A drift from the ansible source is `host:task` -- a task `ansible-playbook --check` said
+would change on a host. Remediation is the natural inverse: run the playbook for real,
+scoped to that host (`ansible-playbook --limit <host>`), which is reconcile-toward-declared
+(the safe self-heal direction -- Ansible doesn't destroy undeclared resources). Live apply is
+gated behind apply-eligibility AND `confirm=True`; nothing runs by default.
+
+Ansible is not transactional, so there is no clean snapshot/auto-revert (unlike terraform's
+plan). We're honest about that in the plan's revert guidance. Verify re-runs `--check` for the
+host and reports whether the drift cleared.
+
+The playbook + inventory are configured out of band (constructor or the env vars
+STEADYSTATE_ANSIBLE_PLAYBOOK / STEADYSTATE_ANSIBLE_INVENTORY), since the drift input the CLI
+passes is the captured check output, not the playbook itself.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+from ..model import Drift
+from .base import RemediationResult
+from .plan import RemediationPlan, Risk
+
+
+class AnsibleExecutor:
+    name = "ansible"
+
+    def __init__(
+        self,
+        playbook: str | None = None,
+        inventory: str | None = None,
+        working_dir: str | Path | None = None,
+    ) -> None:
+        self.playbook = playbook or os.environ.get("STEADYSTATE_ANSIBLE_PLAYBOOK")
+        self.inventory = inventory or os.environ.get("STEADYSTATE_ANSIBLE_INVENTORY")
+        self.working_dir = Path(working_dir) if working_dir else None
+
+    def _host(self, drift: Drift) -> str:
+        return drift.identity.split(":", 1)[0]
+
+    def plan_for(self, drift: Drift) -> RemediationPlan:
+        host = self._host(drift)
+        command = ["ansible-playbook", "--limit", host]
+        if self.inventory:
+            command += ["-i", self.inventory]
+        if self.playbook:
+            command.append(self.playbook)
+        return RemediationPlan(
+            drift_identity=drift.identity,
+            # Re-running the playbook reconciles the host to declared -- the safe self-heal
+            # direction. Always eligible: Ansible converges toward the playbook, it doesn't
+            # destroy resources the playbook doesn't mention.
+            eligible=True,
+            risk=Risk.MEDIUM,
+            reason="Re-running the playbook on the host reconciles it to the declared config.",
+            command=command,
+            blast_radius=f"Runs the playbook against host {host}.",
+            revert=(
+                "Ansible is not transactional -- there is no automatic revert; restore from a "
+                "known-good playbook state and re-run if needed."
+            ),
+        )
+
+    def remediate(self, drift: Drift, *, confirm: bool = False) -> RemediationResult:
+        plan = self.plan_for(drift)
+        if not confirm:
+            return RemediationResult(
+                plan=plan,
+                applied=False,
+                verified=False,
+                detail="Dry run: pass confirm=True (or --apply) to reconcile.",
+            )
+        if not self.playbook:
+            return RemediationResult(
+                plan=plan,
+                applied=False,
+                verified=False,
+                detail="No playbook configured; set STEADYSTATE_ANSIBLE_PLAYBOOK to apply.",
+            )
+        self._run(plan.command)
+        cleared = not self._still_drifting(drift)
+        return RemediationResult(
+            plan=plan,
+            applied=True,
+            verified=cleared,
+            detail="Applied and verified clear."
+            if cleared
+            else "Applied, but the host still drifts on re-check.",
+        )
+
+    # --- live ansible (guarded; not exercised by unit tests) ---
+
+    def _run(self, command: list[str]) -> None:
+        subprocess.run(command, cwd=self.working_dir, check=True, capture_output=True, text=True)
+
+    def _still_drifting(self, drift: Drift) -> bool:
+        from ..sources.ansible import AnsibleSource
+
+        residual = AnsibleSource(
+            playbook=self.playbook, inventory=self.inventory, working_dir=self.working_dir
+        ).collect_drift()
+        return any(d.identity == drift.identity for d in residual)

steadystate/act/approve.py

@@ -0,0 +1,144 @@
+"""Shared remediation-approval core -- the CLI verbs and the chat listener both call here.
+
+Approving rebuilds the source + executor from what the suggesting scan recorded, re-collects
+to match the *live* drift by fingerprint (so the executor's snapshot/verify run against
+reality, and an already-cleared drift is a clean no-op), then applies under the usual
+guardrails. Decline marks it so a re-scan won't re-offer it.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from ..sources import build_drift_source
+from ..state import (
+    APPLIED,
+    APPROVED,
+    BREAKGLASS,
+    DECLINED,
+    FAILED,
+    NOOP,
+    PENDING,
+    VERIFIED,
+    AuditEntry,
+    PendingAction,
+    StateStore,
+)
+from . import build_executor
+from .base import RemediationResult
+from .bounds import confirmation_tier
+from .breakglass import BREAKGLASS_SOURCE, breakglass_allowed
+from .catalog import action_for_command
+from .cleanup import CLEANUP_SOURCE, run_cleanup
+from .execute import CATALOG_SOURCE, run_catalog_action
+from .solution_remedy import SOLUTION_SOURCE, run_solution, solution_named
+
+
+def _audit(
+    action: PendingAction, actor: str, decision: str, outcome: str, detail: str | None
+) -> AuditEntry:
+    """Build the append-only audit record for a decision on ``action``."""
+    return AuditEntry(
+        fingerprint=action.fingerprint,
+        source=action.source,
+        drift_identity=action.drift_identity,
+        actor=actor,
+        decision=decision,
+        outcome=outcome,
+        environment=action.environment,
+        detail=detail,
+    )
+
+
+def apply_pending(
+    store: StateStore,
+    fingerprint: str,
+    actor: str,
+    now: datetime | None = None,
+    *,
+    token: str = "",
+) -> tuple[str, RemediationResult | None]:
+    """Approve + run the pending remediation for ``fingerprint``. Returns a human message and
+    the RemediationResult when one ran (None when there was nothing to do). Every decision that
+    reaches a real remediation point is recorded to the append-only audit log. ``token`` is the
+    break-glass confirmation (the target's name for a strong-tier override); ignored otherwise."""
+    now = now or datetime.now(UTC)
+    action = store.get_pending(fingerprint)
+    if action is None or action.status != PENDING:
+        return "no pending remediation for that fingerprint.", None
+    if action.source == BREAKGLASS_SOURCE:  # an out-of-bound action awaiting a human override
+        # Re-check the allowlist AT CONFIRM time, then the confirmation friction (strong tier: type
+        # the target's name, stored as drift_identity), then run with the bound overridden --
+        # audited as BREAKGLASS so `history` shows who overrode it.
+        if not breakglass_allowed(actor):
+            return (
+                f"break-glass not enabled for you ({actor}). Set STEADYSTATE_BREAKGLASS_USERS.",
+                None,
+            )
+        matched = action_for_command(action.command)
+        tier = confirmation_tier(matched.envelope) if matched is not None else 0
+        if tier >= 2 and token != action.drift_identity:
+            return (
+                f"break-glass: type the target to confirm -- "
+                f"approve {action.fingerprint} {action.drift_identity}",
+                None,
+            )
+        if not store.claim_pending(fingerprint, PENDING, APPROVED, actor):
+            return "no pending remediation for that fingerprint.", None
+        result = run_catalog_action(action, break_glass=True)
+        outcome = VERIFIED if result.verified else APPLIED if result.applied else FAILED
+        store.record_audit(_audit(action, actor, BREAKGLASS, outcome, result.detail), now)
+        return result.detail, result
+    if action.source == SOLUTION_SOURCE:  # an authored runbook command -- operator-vouched, gated
+        # Same race guard + audit as the cleanup, but no content allow-pattern: the operator wrote
+        # and vouched for this command (it's IaC-grade runbook intent). Recover the bound from the
+        # named solution for the plan; the audit records the solution + author (in drift_identity).
+        if not store.claim_pending(fingerprint, PENDING, APPROVED, actor):
+            return "no pending remediation for that fingerprint.", None
+        result = run_solution(action, solution_named(action.drift_identity))
+        outcome = VERIFIED if result.verified else APPLIED if result.applied else FAILED
+        store.record_audit(_audit(action, actor, APPROVED, outcome, result.detail), now)
+        return result.detail, result
+    if action.source in (CLEANUP_SOURCE, CATALOG_SOURCE):  # a direct, re-validated catalog command
+        # Claim before the irreversible step (same race guard as the drift path), then run the
+        # allow-listed command and audit it. No drift source/executor -- the command is it. Both
+        # the evicted cleanup and the general `fix`/`run` actions route here through the same gate.
+        if not store.claim_pending(fingerprint, PENDING, APPROVED, actor):
+            return "no pending remediation for that fingerprint.", None
+        result = (
+            run_cleanup(action) if action.source == CLEANUP_SOURCE else run_catalog_action(action)
+        )
+        outcome = VERIFIED if result.verified else APPLIED if result.applied else FAILED
+        store.record_audit(_audit(action, actor, APPROVED, outcome, result.detail), now)
+        return result.detail, result
+    executor = build_executor(action.source, Path(action.path))
+    if executor is None:
+        return f"source '{action.source}' is observe-only; cannot remediate.", None
+    # Atomically claim the action (pending -> approved) BEFORE anything irreversible. Two approvers
+    # racing the same fingerprint (two chat users) both read PENDING above; the conditional UPDATE
+    # lets exactly one win -- the loser bails here, so the remediation runs at most once.
+    if not store.claim_pending(fingerprint, PENDING, APPROVED, actor):
+        return "no pending remediation for that fingerprint.", None
+    drifts = build_drift_source(action.source, Path(action.path)).collect_drift()
+    drift = next((d for d in drifts if d.fingerprint == fingerprint), None)
+    if drift is None:
+        store.record_audit(_audit(action, actor, APPROVED, NOOP, "drift no longer present"), now)
+        return "drift no longer present; nothing to do.", None
+    result = executor.remediate(drift, confirm=True)
+    outcome = VERIFIED if result.verified else APPLIED if result.applied else FAILED
+    store.record_audit(_audit(action, actor, APPROVED, outcome, result.detail), now)
+    return result.detail, result
+
+
+def decline_pending(
+    store: StateStore, fingerprint: str, actor: str, now: datetime | None = None
+) -> str:
+    """Decline the pending remediation for ``fingerprint``. Returns a human message."""
+    now = now or datetime.now(UTC)
+    action = store.get_pending(fingerprint)
+    if action is None:
+        return "no pending remediation for that fingerprint."
+    store.set_pending_status(fingerprint, DECLINED, actor)
+    store.record_audit(_audit(action, actor, DECLINED, DECLINED, None), now)
+    return f"declined {fingerprint}"

steadystate/act/artifact.py

@@ -0,0 +1,94 @@
+"""Remediation artifacts -- a remediation expressed as a *code change*, not a live apply.
+
+The deterministic counterpart to the live executors. Where ``terraform.py`` reconciles by
+changing reality to match the repo (``terraform apply``), an artifact reconciles the *other*
+direction: it proposes a repo change a human reviews and merges. The canonical form is a
+**patch** (a git-apply-able unified diff) -- auth-free, VCS-agnostic, and a pure string, so it
+is fully testable and provably *not* model-authored. A branch / PR is a way to *deliver* a
+patch (see ``act/deliver/``), never the artifact itself.
+
+The artifact is honest about **state**: a code change for a resource that isn't in state can't
+just edit files -- it must import the resource (the safe, non-destructive direction) or destroy
+it (never automatic). ``state_ops`` records that effect in plain language and ``destructive``
+flags the dangerous direction, so the dimension the apply path glosses over is explicit here.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from ..model import ChangeType
+
+
+@dataclass
+class RemediationArtifact:
+    """A remediation rendered as a reviewable repo change.
+
+    ``patch`` is the deterministic fix (a unified diff); ``state_ops`` and ``destructive`` make
+    the state effect explicit (an import vs a destroy); ``title`` / ``body`` narrate it -- today
+    deterministic, later LLM-authored when reasoning is enabled (the seam is the same)."""
+
+    drift_identity: str  # the resource the change concerns, e.g. "aws_s3_bucket.logs"
+    change_type: ChangeType
+    path: str  # repo-relative file the patch creates or edits
+    patch: str  # git-apply-able unified diff -- the canonical, auth-free fix
+    state_ops: list[str] = field(default_factory=list)  # plain-language state effects (imports)
+    destructive: bool = False  # True only for a destroy variant; gates labeling + delivery
+    title: str = ""  # PR / commit title
+    body: str = ""  # PR body: what changes, why, and the import/destroy implication
+
+    @property
+    def slug(self) -> str:
+        """A filesystem-safe id for this artifact (used to name a delivered ``.patch``)."""
+        return re.sub(r"[^A-Za-z0-9._-]", "_", self.drift_identity)
+
+
+def files_from_patch(patch: str) -> dict[str, str]:
+    """Reconstruct ``{repo_path: full_file_content}`` from a **whole-file-addition** unified diff
+    (the form ``new_file_patch`` produces) -- what an API-based delivery (github-pr) needs, since
+    it builds a tree from file contents, not a diff. Only new-file hunks are recovered; an edit or
+    delete hunk contributes nothing for that path, so a caller can detect the gap and skip rather
+    than ship a partial change. Deterministic, no git invoked."""
+    files: dict[str, str] = {}
+    path: str | None = None
+    is_new_file = False
+    body: list[str] = []
+
+    def _flush() -> None:
+        if path is not None and is_new_file:
+            files[path] = "\n".join(body) + ("\n" if body else "")
+
+    for line in patch.splitlines():
+        if line.startswith("diff --git "):
+            _flush()
+            path, is_new_file, body = None, False, []
+        elif line == "--- /dev/null":
+            is_new_file = True
+        elif line.startswith("+++ b/"):
+            path = line[len("+++ b/") :]
+        elif line.startswith("+") and not line.startswith("+++"):
+            body.append(line[1:])
+    _flush()
+    return files
+
+
+def new_file_patch(path: str, content: str) -> str:
+    """A git-apply-able unified diff that *creates* ``path`` with ``content``.
+
+    The whole-file-addition form (``--- /dev/null`` -> ``+++ b/<path>``) -- what ``git apply``
+    expects for a new file. ``content`` is normalized to end in a newline so every added line,
+    including the last, terminates cleanly and no ``\`` marker is
+    needed. Pure string assembly: deterministic and unit-testable, no git invoked."""
+    if not content.endswith("\n"):
+        content += "\n"
+    lines = content.split("\n")[:-1]  # drop the empty trailing element from the final newline
+    hunk = "".join(f"+{line}\n" for line in lines)
+    return (
+        f"diff --git a/{path} b/{path}\n"
+        "new file mode 100644\n"
+        "--- /dev/null\n"
+        f"+++ b/{path}\n"
+        f"@@ -0,0 +1,{len(lines)} @@\n"
+        f"{hunk}"
+    )

steadystate/act/base.py

@@ -0,0 +1,45 @@
+"""The Executor plugin seam + its result type.
+
+Every remediation must be apply-eligibility-checked, snapshotted, verified, and
+reversible. Chat is a convenient trigger, never a bypass of these guardrails.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from ..model import Drift
+from .artifact import RemediationArtifact
+from .plan import RemediationPlan
+
+
+@dataclass
+class RemediationResult:
+    plan: RemediationPlan
+    applied: bool
+    verified: bool  # post-apply re-check: did the drift actually clear?
+    detail: str = ""
+    snapshot: dict | None = field(default=None)  # pre-change state, for the record / revert
+
+
+@runtime_checkable
+class Executor(Protocol):
+    name: str
+
+    def plan_for(self, drift: Drift) -> RemediationPlan: ...
+
+    def remediate(self, drift: Drift, *, confirm: bool = False) -> RemediationResult: ...
+
+
+@runtime_checkable
+class Proposer(Protocol):
+    """An *optional* executor capability: render a drift as a reviewable code change instead of a
+    live apply. Probed by ``isinstance(executor, Proposer)`` -- like the inbound adapters' optional
+    ``defer``/``complete`` -- so an executor that can express a fix as a patch implements it and one
+    that can only apply live simply doesn't, and the propose path degrades honestly for it.
+
+    ``propose`` returns ``None`` for a drift it has no code-change for (e.g. the apply direction is
+    the right fix), so a caller can offer artifacts only where one genuinely exists."""
+
+    def propose(self, drift: Drift) -> RemediationArtifact | None: ...

steadystate/act/bounds.py

@@ -0,0 +1,170 @@
+"""Action envelopes + the bound: one impact-and-reversibility calculus for *all* infrastructure.
+
+The decision a good operator makes before any change is always the same two questions -- *how much
+does this touch, and can I undo it?* -- and it does not depend on whether the change is a
+`kubectl delete`, a `terraform apply`, or an ansible play. So that calculus lives here, once,
+backend-agnostic: every action declares an ``Envelope`` (its reversibility and its blast radius on
+a generic scale), and a human declares the **bound** -- which envelopes may run unattended. The
+gate (``within_bounds``) sees only the envelope, never a backend.
+
+What the bound governs today: the autonomous paths -- reflexes (``hold``), the decider
+(``propose``), and the drift ``--autonomy auto`` path for any executor that declares an envelope
+(terraform does; ``can_run_unattended`` in act/plan.py is the gate). An executor that has not yet
+declared envelopes (ansible) falls back to the older ``eligible`` boolean -- the migration is
+incremental, and absence of an envelope only keeps prior behavior, never loosens it. So this is on
+its way to "one grid governs every source", and is honest that it is not all the way there yet.
+
+This is the spine the autonomy story stands on. A reflex today, an LLM tomorrow, decides *what to
+do*; the bound decides *how much it is ever allowed to break*. The decider proposes an action and
+its envelope; the gate checks that envelope against the human's bound; out-of-bound escalates no
+matter how confident the decider is. The one decision that never goes to the code or the model is
+the bound itself -- a human sets it (the conservative default, widened via ``STEADYSTATE_BOUND`` as
+trust grows), and flipping a reflex to ``auto`` can never cross it.
+
+The two axes are deliberately generic; each backend maps its own nouns onto them:
+
+    Impact         k8s              terraform              ansible            compose
+    ------         ---              ---------              -------            -------
+    ONE            a pod            one resource           one host/task      one container
+    SERVICE        a workload       a module               a role             a service
+    TENANT         a namespace      a workspace/state      an inventory group a project/stack
+    NODE           a node           --                     a managed host     the docker host
+    FLEET          the cluster      a root/account/region  the whole inventory the engine
+
+    Reversibility  example
+    -------------  -------
+    LOSSLESS       destroys nothing of value (delete an evicted pod, `docker rm` a dead container)
+    SELF_HEALING   the platform restores it (delete a Running pod, restart a service, cordon a node)
+    RECOVERABLE    a known inverse exists (scale down<->up, a re-appliable terraform change)
+    IRREVERSIBLE   real loss, no inverse (delete a PVC, `terraform destroy` a database)
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from enum import IntEnum
+
+# Both axes are ordinal (IntEnum), worst last -- so a policy is just "the highest tier still
+# allowed" and the gate is a comparison. Names render lowercased for humans; the order is the point.
+
+
+class Reversibility(IntEnum):
+    """Can the action be undone, and is anything of value lost if it can't? Ascending severity."""
+
+    LOSSLESS = 0
+    SELF_HEALING = 1
+    RECOVERABLE = 2
+    IRREVERSIBLE = 3
+
+
+class Impact(IntEnum):
+    """The blast radius on a generic, cross-backend scale (each backend maps its nouns). Rising."""
+
+    ONE = 0
+    SERVICE = 1
+    TENANT = 2
+    NODE = 3
+    FLEET = 4
+
+
+@dataclass(frozen=True)
+class Envelope:
+    """What an action would do, in the only two terms the bound cares about. Backend-agnostic: a
+    kubectl cleanup, a terraform apply, and an ansible play all describe themselves this way."""
+
+    reversibility: Reversibility
+    impact: Impact
+
+    @property
+    def label(self) -> str:
+        return f"{self.reversibility.name.lower()}/{self.impact.name.lower()}"
+
+
+# The bound: for each reversibility, the HIGHEST impact tier that may run unattended (None = never).
+# This is the human's 3am calculus, written down once. Conservative by default -- only a lossless or
+# self-healing action, and only within a small blast radius, runs without a human; anything
+# recoverable-or-worse, or anything reaching a node/the fleet, escalates. An operator widens it as
+# trust grows (the same graduation `hold`'s reflexes use), but it is ALWAYS a human's decision: the
+# bound is the one thing a decider -- reflex or model -- never sets for itself.
+BoundPolicy = dict[Reversibility, "Impact | None"]
+
+DEFAULT_BOUND: BoundPolicy = {
+    Reversibility.LOSSLESS: Impact.TENANT,  # lossless, up to a whole tenant (namespace/stack): auto
+    Reversibility.SELF_HEALING: Impact.SERVICE,  # self-healing up to one service -> auto
+    Reversibility.RECOVERABLE: None,  # a known inverse still needs a human, until trust is earned
+    Reversibility.IRREVERSIBLE: None,  # never autonomous, at any size
+}
+
+
+def within_bounds(envelope: Envelope, policy: BoundPolicy = DEFAULT_BOUND) -> bool:
+    """True iff ``envelope`` may run unattended under ``policy`` -- the gate every decider passes
+    through, seeing only the envelope, never a backend. Pure. ``False`` (escalate) is the safe
+    default for any reversibility the policy doesn't permit."""
+    ceiling = policy.get(envelope.reversibility)
+    return ceiling is not None and envelope.impact <= ceiling
+
+
+def confirmation_tier(envelope: Envelope, policy: BoundPolicy = DEFAULT_BOUND) -> int:
+    """How much confirmation friction an action needs, from its envelope alone. ``0`` = within the
+    bound -- autonomous-eligible, no confirmation (`fix`/`run` just runs it). Out of bound is
+    break-glass: ``2`` (STRONG -- type the target's name to confirm) when it's IRREVERSIBLE or
+    reaches a NODE/the FLEET; else ``1`` (light -- a plain confirm). So the most dangerous things
+    get the most friction, automatically. Pure."""
+    if within_bounds(envelope, policy):
+        return 0
+    if envelope.reversibility >= Reversibility.IRREVERSIBLE or envelope.impact >= Impact.NODE:
+        return 2
+    return 1
+
+
+_REVERSIBILITY_BY_NAME = {r.name.lower(): r for r in Reversibility}
+_IMPACT_BY_NAME = {i.name.lower(): i for i in Impact}
+
+
+def _config_bound_table() -> dict:
+    from ..config import config_table  # local import: keep bounds.py importable without the config
+
+    return config_table("bound")
+
+
+def _apply_bound_pair(policy: BoundPolicy, rev_name: str, impact_name: str) -> None:
+    """Overlay one ``reversibility=impact`` decision onto ``policy`` (in place). An unknown
+    reversibility or impact is **skipped**, never applied -- a typo can only leave the bound at the
+    conservative default, never silently widen it ('never escalate on uncertainty')."""
+    reversibility = _REVERSIBILITY_BY_NAME.get(rev_name.strip().lower())
+    if reversibility is None:
+        return
+    impact = impact_name.strip().lower()
+    if impact in ("none", "never", ""):
+        policy[reversibility] = None  # explicitly forbid auto for this reversibility
+    elif impact in _IMPACT_BY_NAME:
+        policy[reversibility] = _IMPACT_BY_NAME[impact]
+    # else: an unknown impact name -> skip (stay conservative; never widen on a typo)
+
+
+def bound_from_env(raw: str | None = None) -> BoundPolicy:
+    """The *active* bound: ``DEFAULT_BOUND`` overlaid with the committed ``[bound]`` table, then the
+    ``STEADYSTATE_BOUND`` env knob (env wins). The widen/narrow dial every autonomy gate reads, so
+    one source governs the whole tool: drift auto-apply, reflexes, solution auto-apply, the decider.
+
+    The bound is the one decision that should never be casual -- so it belongs in the **committed
+    config**, reviewed in PRs (`[bound]` with ``reversibility = "impact"`` keys), with the env var
+    the per-run override. Reversibility names: ``lossless`` / ``self_healing`` / ``recoverable`` /
+    ``irreversible``; impact names ``one`` / ``service`` / ``tenant`` / ``node`` / ``fleet`` (each
+    pair names the HIGHEST impact tier that may run unattended for that reversibility; ``none``
+    forbids it). Env format mirrors it: comma-separated ``reversibility=impact`` pairs, e.g.
+    ``STEADYSTATE_BOUND="recoverable=service"``.
+
+    Unparseable entries are skipped (never widen on a typo). Pure given ``raw``; with ``raw`` None
+    it reads the committed ``[bound]`` table then ``STEADYSTATE_BOUND``."""
+    policy = dict(DEFAULT_BOUND)
+    if raw is None:  # the live resolution: committed config first (baseline), then env (override)
+        for rev_name, impact in _config_bound_table().items():
+            _apply_bound_pair(policy, rev_name, str(impact))
+        raw = os.environ.get("STEADYSTATE_BOUND", "")
+    for token in raw.replace(";", ",").split(","):
+        key, sep, value = token.partition("=")
+        if sep:  # a `reversibility=impact` pair (a bare token is skipped)
+            _apply_bound_pair(policy, key, value)
+    return policy