bounded-agent 0.1.0__tar.gz

bounded_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run pytest tests -q
+      # Known-answer drill: the sentinel ships with a deliberately broken service, and a
+      # non-clean verdict exits 1 (the headless surface). CI asserts the plant IS caught —
+      # an exit code of 0 here would mean the watchdog missed its own fixture.
+      - name: sentinel known-answer (must catch the planted failure)
+        run: |
+          set +e
+          uv run python examples/sentinel/sentinel.py
+          code=$?
+          set -e
+          [ "$code" -eq 1 ] || { echo "expected exit 1 (plant caught), got $code"; exit 1; }

bounded_agent-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/
+*.egg-info/
+examples/sentinel/run_ledger/

bounded_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hans Scholing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bounded_agent-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: bounded-agent
+Version: 0.1.0
+Summary: Contract-bounded autonomy for LLM agents: five small primitives that make an agent safe to leave alone.
+Project-URL: Repository, https://github.com/scholih/bounded-agent
+Project-URL: Manifesto, https://medium.com/@scholih/the-edge-is-the-harness-not-the-model-a543abade391
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pydantic-ai-slim[anthropic]>=2.22.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# bounded-agent
+
+**Contract-bounded autonomy for LLM agents: five small primitives that make an agent safe to
+leave alone.**
+
+The model is table stakes. The reliability of an autonomous agent lives in the **harness** —
+the deterministic structure around the LLM that decides what it may see, what it may say, what
+it may do, and what happens when it fails. This library is that harness, reduced to its five
+load-bearing primitives, each ~50 lines, each independently testable, built on top of
+[PydanticAI](https://ai.pydantic.dev) (which already solves the typed-LLM-call problem — we
+don't rebuild it, we add the autonomy layer it deliberately leaves to you).
+
+The design stance, in one sentence: **deterministic spine, agentic leaves** — code you can
+test decides the flow; the LLM reasons inside well-fenced steps and never pilots the loop.
+
+**The manifesto:** [The Edge Is the Harness, Not the Model](https://medium.com/@scholih/the-edge-is-the-harness-not-the-model-a543abade391) — the argument this library implements, and the start of a series that takes each primitive in depth.
+
+## The five primitives
+
+| Module | Primitive | The failure it prevents |
+|---|---|---|
+| `contracts.py` | **Contracts & gates** — a declared book of who may do what, at which autonomy tier (observe / propose / act) | an agent quietly acquiring capabilities nobody signed off on |
+| `leaf.py` | **The typed leaf & the escalate-only floor** — LLM output is a validated type or an error *value*; an LLM may raise an alarm, never silence one | a plausible-sounding model response lowering a deterministic alarm |
+| `actions.py` | **The double-closed action set** — an action runs only if it is both *contracted* and *implemented*; everything else is refused and recorded | prompt-injected or hallucinated actions; silent capability creep |
+| `ledgers.py` | **Evidence & idempotency ledgers** — append-only truth for every action and verdict; a finding alerts once per period, not forever | un-auditable agents; alert fatigue that trains humans to ignore the pager |
+| `envelope.py` | **The safety envelope** — ships disarmed, kill-switch checked before anything runs, a hard per-run breaker, and act-then-report (silence is impossible) | the runaway loop; the agent that did things nobody heard about |
+
+## Quickstart
+
+```bash
+uv add bounded-agent            # or: pip install bounded-agent
+```
+
+```python
+from bounded_agent import ContractBook, Gate, ActionSet, Envelope, EvidenceLedger
+
+book = ContractBook.load("contracts.yaml")            # raises loudly if missing/malformed
+gate = Gate(required_scope="checkout-stack", required_tier="act")
+granted = book.granted(gate)                          # {contract-name: (allowed actions,)}
+
+actions = ActionSet()
+actions.register("restart_worker", restart_worker)    # the implemented closed set
+
+env = Envelope(armed=True, kill_switch_path=Path("STOP"),
+               max_actions_per_run=2, notify=page_the_operator)
+outcome = actions.execute(list(granted.items()), env,
+                          ledger=EvidenceLedger(Path("ledger")), period=today)
+```
+
+An action fires only if it appears in **both** the contract's `allows` list **and** the
+registered set — and only inside an armed envelope with no kill-switch present and breaker
+budget remaining. Everything that happens (and everything refused) is one JSONL line.
+
+For the LLM side, see `examples/sentinel/` — a complete service-health watchdog: deterministic
+probes → an escalate-only LLM verdict → a typed diagnosis → contract-bounded remediation.
+It runs **offline with no API key** (PydanticAI's `TestModel`) so you can study the whole loop
+before connecting a real model.
+
+## What this deliberately is NOT
+
+Stating the non-goals is part of the teaching — most agent failures start with adopting more
+machinery than the problem earns:
+
+- **Not a planner.** No GOAP, no A*-search over preconditions. If you can hardcode the flow,
+  hardcode the flow.
+- **Not a durable-execution engine.** Design your steps idempotent and re-run from clean;
+  reach for Temporal/DBOS only when a mid-run crash would genuinely corrupt or double-charge.
+- **Not a graph framework.** Small fixed pipelines and explicit state machines in plain code
+  beat a graph DSL until your control flow is genuinely graph-shaped.
+- **Not a PydanticAI replacement.** The typed leaf is solved; this is the autonomy layer
+  above it. If PydanticAI grows this layer, this library should shrink.
+
+## Status
+
+A **teaching artifact**, maintained best-effort. The patterns here are extracted from a
+production system that runs unattended daily; the code is written fresh for clarity. Issues
+and discussion welcome; roadmap promises are not made.
+
+## License
+
+MIT

bounded_agent-0.1.0/README.md

@@ -0,0 +1,81 @@
+# bounded-agent
+
+**Contract-bounded autonomy for LLM agents: five small primitives that make an agent safe to
+leave alone.**
+
+The model is table stakes. The reliability of an autonomous agent lives in the **harness** —
+the deterministic structure around the LLM that decides what it may see, what it may say, what
+it may do, and what happens when it fails. This library is that harness, reduced to its five
+load-bearing primitives, each ~50 lines, each independently testable, built on top of
+[PydanticAI](https://ai.pydantic.dev) (which already solves the typed-LLM-call problem — we
+don't rebuild it, we add the autonomy layer it deliberately leaves to you).
+
+The design stance, in one sentence: **deterministic spine, agentic leaves** — code you can
+test decides the flow; the LLM reasons inside well-fenced steps and never pilots the loop.
+
+**The manifesto:** [The Edge Is the Harness, Not the Model](https://medium.com/@scholih/the-edge-is-the-harness-not-the-model-a543abade391) — the argument this library implements, and the start of a series that takes each primitive in depth.
+
+## The five primitives
+
+| Module | Primitive | The failure it prevents |
+|---|---|---|
+| `contracts.py` | **Contracts & gates** — a declared book of who may do what, at which autonomy tier (observe / propose / act) | an agent quietly acquiring capabilities nobody signed off on |
+| `leaf.py` | **The typed leaf & the escalate-only floor** — LLM output is a validated type or an error *value*; an LLM may raise an alarm, never silence one | a plausible-sounding model response lowering a deterministic alarm |
+| `actions.py` | **The double-closed action set** — an action runs only if it is both *contracted* and *implemented*; everything else is refused and recorded | prompt-injected or hallucinated actions; silent capability creep |
+| `ledgers.py` | **Evidence & idempotency ledgers** — append-only truth for every action and verdict; a finding alerts once per period, not forever | un-auditable agents; alert fatigue that trains humans to ignore the pager |
+| `envelope.py` | **The safety envelope** — ships disarmed, kill-switch checked before anything runs, a hard per-run breaker, and act-then-report (silence is impossible) | the runaway loop; the agent that did things nobody heard about |
+
+## Quickstart
+
+```bash
+uv add bounded-agent            # or: pip install bounded-agent
+```
+
+```python
+from bounded_agent import ContractBook, Gate, ActionSet, Envelope, EvidenceLedger
+
+book = ContractBook.load("contracts.yaml")            # raises loudly if missing/malformed
+gate = Gate(required_scope="checkout-stack", required_tier="act")
+granted = book.granted(gate)                          # {contract-name: (allowed actions,)}
+
+actions = ActionSet()
+actions.register("restart_worker", restart_worker)    # the implemented closed set
+
+env = Envelope(armed=True, kill_switch_path=Path("STOP"),
+               max_actions_per_run=2, notify=page_the_operator)
+outcome = actions.execute(list(granted.items()), env,
+                          ledger=EvidenceLedger(Path("ledger")), period=today)
+```
+
+An action fires only if it appears in **both** the contract's `allows` list **and** the
+registered set — and only inside an armed envelope with no kill-switch present and breaker
+budget remaining. Everything that happens (and everything refused) is one JSONL line.
+
+For the LLM side, see `examples/sentinel/` — a complete service-health watchdog: deterministic
+probes → an escalate-only LLM verdict → a typed diagnosis → contract-bounded remediation.
+It runs **offline with no API key** (PydanticAI's `TestModel`) so you can study the whole loop
+before connecting a real model.
+
+## What this deliberately is NOT
+
+Stating the non-goals is part of the teaching — most agent failures start with adopting more
+machinery than the problem earns:
+
+- **Not a planner.** No GOAP, no A*-search over preconditions. If you can hardcode the flow,
+  hardcode the flow.
+- **Not a durable-execution engine.** Design your steps idempotent and re-run from clean;
+  reach for Temporal/DBOS only when a mid-run crash would genuinely corrupt or double-charge.
+- **Not a graph framework.** Small fixed pipelines and explicit state machines in plain code
+  beat a graph DSL until your control flow is genuinely graph-shaped.
+- **Not a PydanticAI replacement.** The typed leaf is solved; this is the autonomy layer
+  above it. If PydanticAI grows this layer, this library should shrink.
+
+## Status
+
+A **teaching artifact**, maintained best-effort. The patterns here are extracted from a
+production system that runs unattended daily; the code is written fresh for clarity. Issues
+and discussion welcome; roadmap promises are not made.
+
+## License
+
+MIT

bounded_agent-0.1.0/examples/sentinel/contracts.yaml

@@ -0,0 +1,21 @@
+# The book of what the sentinel may do. A human edits this file; the agent only reads it.
+# tier: observe = read & report · propose = draft a fix, human executes · act = execute `allows`
+contracts:
+  - name: queue-worker
+    status: active
+    scope: checkout-stack
+    tier: act
+    allows: [restart_worker]
+    owner: platform-team          # extra fields are fine — the library ignores them
+
+  - name: cache
+    status: active
+    scope: checkout-stack
+    tier: propose                 # a human executes cache fixes; the sentinel may only draft
+    allows: [clear_cache]
+
+  - name: payments-db
+    status: proposed              # not yet signed off — grants NOTHING until status: active
+    scope: checkout-stack
+    tier: act
+    allows: [failover_replica]

bounded_agent-0.1.0/examples/sentinel/sentinel.py

@@ -0,0 +1,163 @@
+"""The sentinel — a service-health watchdog you can leave alone.
+
+The complete contract-bounded loop, end to end, in one file:
+
+    probes (deterministic)  →  floor verdict  →  LLM coherence verdict (escalate-only)
+    →  typed diagnosis      →  contract-bounded remediation (double-closed, enveloped)
+    →  everything ledgered
+
+Run it with NO API key (the LLM leaves use PydanticAI's TestModel, so you can study the
+whole control flow offline):
+
+    uv run python examples/sentinel/sentinel.py
+
+Run it against a real model (set ANTHROPIC_API_KEY):
+
+    uv run python examples/sentinel/sentinel.py --live
+
+The simulated stack ships with one deliberately broken service, so every run exercises the
+full path: floor catches it → leaf confirms → diagnosis names it → the contract book decides
+what may be done about it → the envelope bounds the doing → the ledger remembers all of it.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel
+from pydantic_ai import Agent
+from pydantic_ai.models.test import TestModel
+
+from bounded_agent import (
+    ActionSet, ContractBook, Envelope, EvidenceLedger, Gate, LeafError, TypedLeaf,
+    escalate_only,
+)
+
+HERE = Path(__file__).parent
+
+
+# ── 1. Probes — deterministic sensors over the (simulated) stack ─────────────────────────
+
+def run_probes() -> dict[str, dict]:
+    """In a real sentinel these hit HTTP health endpoints, disk, queue depth, container
+    states. Here they are simulated — with queue-worker deliberately unhealthy."""
+    return {
+        "checkout-api":  {"status": "ok",   "detail": "200 in 41ms"},
+        "cache":         {"status": "ok",   "detail": "hit-rate 0.94"},
+        "queue-worker":  {"status": "fail", "detail": "no heartbeat for 22 min; depth 14 302 and rising"},
+        "payments-db":   {"status": "ok",   "detail": "replica lag 0.4s"},
+    }
+
+
+# ── 2. The deterministic floor — the LLM never gets to overrule this ─────────────────────
+
+LEVELS = {"ok": 0, "cannot-assess": 1, "alert": 2}
+
+def floor_verdict(probes: dict[str, dict]) -> str:
+    statuses = {p["status"] for p in probes.values()}
+    if "fail" in statuses:
+        return "alert"
+    if "unavailable" in statuses:      # missing evidence is never "ok"
+        return "cannot-assess"
+    return "ok"
+
+
+# ── 3. Two typed leaves — the ONLY places a model runs ───────────────────────────────────
+
+class Coherence(BaseModel):
+    """Does the evidence cohere as a whole? The leaf may only ESCALATE the floor."""
+    level: Literal["ok", "alert"]
+    note: str
+
+class Diagnosis(BaseModel):
+    root_cause: str
+    evidence: list[str]
+    proposed_next_step: str
+    confidence: Literal["high", "medium", "low"]
+
+
+def build_leaves(live: bool) -> tuple[TypedLeaf, TypedLeaf]:
+    if live:
+        coherence = Agent("anthropic:claude-sonnet-4-6", output_type=Coherence,
+                          system_prompt="You review service-health evidence for cross-signal "
+                                        "contradictions the individual checks cannot see.")
+        diagnosis = Agent("anthropic:claude-sonnet-4-6", output_type=Diagnosis,
+                          system_prompt="Diagnose the most likely root cause from the "
+                                        "evidence alone. One concrete next step. Be terse.")
+    else:  # offline: scripted model outputs — the control flow is identical
+        coherence = Agent(TestModel(custom_output_args={
+            "level": "alert", "note": "queue depth rising while worker heartbeat silent"}),
+            output_type=Coherence)
+        diagnosis = Agent(TestModel(custom_output_args={
+            "root_cause": "queue-worker process wedged after cache failover",
+            "evidence": ["queue-worker heartbeat silent 22m", "depth 14302 rising"],
+            "proposed_next_step": "restart queue-worker; page if depth not draining in 10m",
+            "confidence": "high"}), output_type=Diagnosis)
+    return TypedLeaf(coherence), TypedLeaf(diagnosis)
+
+
+# ── 4. The run ───────────────────────────────────────────────────────────────────────────
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--live", action="store_true", help="use a real model (needs API key)")
+    ap.add_argument("--armed", action="store_true",
+                    help="arm remediation (ships disarmed, like everything should)")
+    args = ap.parse_args()
+
+    today = dt.date.today()
+    ledger = EvidenceLedger(HERE / "run_ledger")
+    notify = lambda msg: print(f"  [notify] {msg}")          # stand-in for a pager/Slack hook
+
+    # observe
+    probes = run_probes()
+    floor = floor_verdict(probes)
+    print(f"floor verdict: {floor}")
+
+    # reason (escalate-only: the leaf can raise the floor, never lower it)
+    coherence_leaf, diagnosis_leaf = build_leaves(args.live)
+    coh = coherence_leaf.run(json.dumps(probes))
+    proposed = None if isinstance(coh, LeafError) else coh.level
+    verdict = escalate_only(floor, proposed, rank=LEVELS.__getitem__)
+    if isinstance(coh, LeafError):                            # leaf failure is a VALUE:
+        verdict = escalate_only(verdict, "cannot-assess", rank=LEVELS.__getitem__)
+    print(f"merged verdict: {verdict}" + (f"  ({coh.note})" if isinstance(coh, Coherence) else ""))
+    ledger.append({"kind": "verdict", "floor": floor, "verdict": verdict}, period=today)
+
+    if verdict == "ok":
+        print("clean day — the sentinel goes back to sleep.")
+        return 0
+
+    # diagnose (typed, best-effort)
+    diag = diagnosis_leaf.run(json.dumps(probes))
+    if isinstance(diag, Diagnosis):
+        print(f"diagnosis [{diag.confidence}]: {diag.root_cause}")
+        print(f"  next step: {diag.proposed_next_step}")
+        ledger.append({"kind": "diagnosis", **diag.model_dump()}, period=today)
+
+    # act — only inside the book, only inside the envelope
+    book = ContractBook.load(HERE / "contracts.yaml")
+    granted = book.granted(Gate(required_scope="checkout-stack", required_tier="act"))
+    failing = [name for name, p in probes.items() if p["status"] == "fail"]
+    targets = [(n, granted[n]) for n in failing if n in granted]
+    print(f"contract book grants ACT on: {sorted(granted)} → actionable now: "
+          f"{[t[0] for t in targets] or 'nothing (alert-only)'}")
+
+    acts = ActionSet()
+    acts.register("restart_worker", lambda: (True, "worker restarted (simulated)"))
+    env = Envelope(armed=args.armed, kill_switch_path=HERE / "STOP",
+                   max_actions_per_run=1, notify=notify)
+    outcome = acts.execute(targets, env, ledger=ledger, period=today)
+    if outcome.blocked_reason:
+        print(f"remediation blocked: {outcome.blocked_reason} "
+              f"(run with --armed; `touch STOP` to kill-switch)")
+    print(f"ledger: {HERE / 'run_ledger'}")
+    return 1 if verdict != "ok" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bounded_agent-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "bounded-agent"
+version = "0.1.0"
+description = "Contract-bounded autonomy for LLM agents: five small primitives that make an agent safe to leave alone."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+    "pydantic>=2.7",
+    "pydantic-ai-slim[anthropic]>=2.22.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Repository = "https://github.com/scholih/bounded-agent"
+Manifesto = "https://medium.com/@scholih/the-edge-is-the-harness-not-the-model-a543abade391"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bounded_agent"]

bounded_agent-0.1.0/src/bounded_agent/__init__.py

@@ -0,0 +1,22 @@
+"""bounded-agent — contract-bounded autonomy for LLM agents.
+
+Five primitives that make an agent safe to leave alone. Deterministic spine, agentic
+leaves: code you can test decides the flow; the LLM reasons inside well-fenced steps and
+never pilots the loop. See README.md for the full argument; each module's docstring is a
+chapter.
+"""
+from __future__ import annotations
+
+from bounded_agent.actions import ActionRecord, ActionSet, ExecOutcome
+from bounded_agent.contracts import Contract, ContractBook, Gate
+from bounded_agent.envelope import Envelope
+from bounded_agent.leaf import LeafError, TypedLeaf, escalate_only
+from bounded_agent.ledgers import EvidenceLedger, IdempotencyLedger
+
+__all__ = [
+    "Contract", "ContractBook", "Gate",
+    "TypedLeaf", "LeafError", "escalate_only",
+    "ActionSet", "ActionRecord", "ExecOutcome",
+    "EvidenceLedger", "IdempotencyLedger",
+    "Envelope",
+]

bounded_agent-0.1.0/src/bounded_agent/actions.py

@@ -0,0 +1,110 @@
+"""Chapter 3 — The double-closed action set: agent actions safe by construction.
+
+An autonomous agent's actions must clear TWO independent closed sets before running:
+
+1. **Contracted** — the action name appears in a contract's ``allows`` list that a ``Gate``
+   granted (chapter 1). A human put that name in the book.
+2. **Registered** — the action name has an implementation registered here. An engineer wrote
+   and reviewed that handler.
+
+The intersection is the executable surface; everything else — a typo'd contract, a
+hallucinated action name, a prompt-injected "please also run …" — is **refused and
+recorded**, not an error path someone forgot. Capability creep now requires changing two
+artifacts, in two reviews.
+
+Execution runs inside the envelope (chapter 5) and journals to the evidence ledger
+(chapter 4). Two details that earn their keep:
+
+- **A raising handler is a recorded failure, not an escape.** After an action *starts*,
+  every outcome — success, failure, crash — must become a record that is ledgered and
+  notified. An exception unwinding through an unattended loop is an agent that stops
+  watching mid-run and tells nobody.
+- **Failed attempts spend breaker budget.** The breaker bounds *attempts*, not successes —
+  a handler that crashes N times in a loop is exactly the runaway the breaker exists for.
+"""
+from __future__ import annotations
+
+from typing import Callable, Literal, Sequence
+
+from pydantic import BaseModel, ConfigDict
+
+from bounded_agent.envelope import Envelope
+from bounded_agent.ledgers import EvidenceLedger, Period
+
+#: A handler does the work and reports (ok, detail). What "the work" is — a subprocess, an
+#: API call, a container restart — is its business; the set only knows names and outcomes.
+Handler = Callable[[], tuple[bool, str]]
+
+#: (contract_name, the action names that contract allows) — straight from ContractBook.granted.
+Target = tuple[str, Sequence[str]]
+
+Status = Literal["executed-ok", "executed-failed", "refused", "halted"]
+
+
+class ActionRecord(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    contract: str
+    action: str
+    status: Status
+    detail: str = ""
+
+
+class ExecOutcome(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    blocked_reason: str | None          # disarmed | kill-switch | None (ran)
+    records: tuple[ActionRecord, ...] = ()
+    executed: int = 0                   # attempts, successful or not
+
+
+class ActionSet:
+    """The registered half of the double-closed check, plus the execution loop."""
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, Handler] = {}
+
+    def register(self, name: str, handler: Handler) -> None:
+        self._handlers[name] = handler
+
+    def execute(self, targets: Sequence[Target], envelope: Envelope, *,
+                ledger: EvidenceLedger | None = None,
+                period: Period | None = None) -> ExecOutcome:
+        def emit(rec: ActionRecord) -> None:
+            if ledger is not None and period is not None:
+                ledger.append(rec, period=period)
+            envelope.notify(f"{rec.status}: {rec.action} on {rec.contract}"
+                            + (f" ({rec.detail})" if rec.detail else ""))
+
+        blocked = envelope.blocked_reason()
+        if blocked is not None:
+            rec = ActionRecord(contract="*", action="*", status="halted", detail=blocked)
+            emit(rec)
+            return ExecOutcome(blocked_reason=blocked, records=(rec,))
+
+        records: list[ActionRecord] = []
+        executed = 0
+        for contract, actions in targets:
+            for action in actions:
+                if envelope.breaker_tripped(executed):
+                    rec = ActionRecord(contract=contract, action=action, status="halted",
+                                       detail=f"breaker: {envelope.max_actions_per_run}/run")
+                    records.append(rec); emit(rec)
+                    return ExecOutcome(blocked_reason=None, records=tuple(records),
+                                       executed=executed)
+                handler = self._handlers.get(action)
+                if handler is None:              # contracted but not implemented → refused
+                    rec = ActionRecord(contract=contract, action=action, status="refused",
+                                       detail="not registered (closed set)")
+                    records.append(rec); emit(rec)
+                    continue
+                try:
+                    ok, detail = handler()
+                    status: Status = "executed-ok" if ok else "executed-failed"
+                except Exception as e:  # noqa: BLE001 — a crash is a RECORD, never an escape
+                    detail, status = f"{type(e).__name__}: {e}", "executed-failed"
+                rec = ActionRecord(contract=contract, action=action, status=status,
+                                   detail=detail)
+                records.append(rec); emit(rec)
+                executed += 1                    # attempts spend breaker budget
+        return ExecOutcome(blocked_reason=None, records=tuple(records), executed=executed)

bounded_agent-0.1.0/src/bounded_agent/contracts.py

@@ -0,0 +1,86 @@
+"""Chapter 1 — Contracts & gates: deciding who may do what, before any agent runs.
+
+The pattern: autonomy is granted by a **declared book of contracts**, never by code that
+happens to be reachable. A human edits the book (and signs off on new entries); the machine
+operates strictly inside it. Each contract names:
+
+- a ``scope`` — the blast-radius label ("checkout-stack", "reporting-db") the grant is
+  confined to;
+- a ``tier`` — how much autonomy: ``observe`` (read and report), ``propose`` (draft a fix a
+  human executes), ``act`` (execute its own ``allows`` list). Tiers are ORDERED: an ``act``
+  contract clears a ``propose`` gate, never the reverse;
+- an ``allows`` list — the CLOSED set of action names the contract permits (see
+  ``actions.py`` for the second half of the double-closed check).
+
+Two hard rules encoded here:
+
+1. **Absence is never authorization.** A missing or malformed book RAISES; an entry that is
+   not active, out of scope, or under-tiered grants nothing. There is no default-allow path.
+2. **The lifecycle vocabulary belongs to the caller.** Your workflow might call live entries
+   "active", "LIVE", or "ratified" — the gate's ``active_status`` is configurable rather than
+   baked into a type, because a library that hardcodes your status words will be wrong in
+   somebody's workflow.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict
+
+Tier = Literal["observe", "propose", "act"]
+
+#: The ordering that makes tiers meaningful: a gate requiring tier T grants any contract
+#: whose tier ranks >= T.
+_TIER_RANK: dict[str, int] = {"observe": 0, "propose": 1, "act": 2}
+
+
+class Contract(BaseModel):
+    """One declared grant. Extra YAML fields (owners, SLAs, notes) are ignored — the book
+    can carry your operational metadata without this library needing to model it."""
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    name: str
+    status: str = "active"
+    scope: str
+    tier: Tier = "observe"
+    allows: tuple[str, ...] = ()
+
+
+class Gate(BaseModel):
+    """A composable authorization predicate — the question "may this contract act here?"
+    asked the same way every time, instead of scattered ``if`` statements."""
+    model_config = ConfigDict(frozen=True)
+
+    required_scope: str | None = None       # None = any scope (rare; prefer naming one)
+    required_tier: Tier = "act"
+    active_status: str = "active"           # the caller's word for "live", verbatim
+
+    def permits(self, contract: Contract) -> bool:
+        if contract.status != self.active_status:
+            return False
+        if self.required_scope is not None and contract.scope != self.required_scope:
+            return False
+        return _TIER_RANK[contract.tier] >= _TIER_RANK[self.required_tier]
+
+
+class ContractBook(BaseModel):
+    """The parsed book. ``granted(gate)`` answers the only question the executor may ask:
+    which contracts may act, and what exactly does each allow."""
+    model_config = ConfigDict(frozen=True)
+
+    contracts: tuple[Contract, ...] = ()
+
+    @classmethod
+    def load(cls, path: Path | str) -> "ContractBook":
+        """Parse a ``contracts:`` YAML file. Raises on absence or malformation — the caller
+        decides whether that halts startup or degrades to observe-only, but it is never
+        silently treated as an empty (or worse, permissive) book."""
+        doc = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+        if not isinstance(doc, dict) or "contracts" not in doc:
+            raise ValueError(f"{path}: expected a top-level 'contracts' list")
+        return cls(contracts=tuple(Contract(**e) for e in doc["contracts"]))
+
+    def granted(self, gate: Gate) -> dict[str, tuple[str, ...]]:
+        return {c.name: c.allows for c in self.contracts if gate.permits(c)}