awdecide 0.3.0__tar.gz

awdecide-0.3.0/LICENSE

@@ -0,0 +1,15 @@
+Apache License 2.0
+
+Copyright 2026 Aitherium
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

awdecide-0.3.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: awdecide
+Version: 0.3.0
+Summary: One typed-decision contract -- choice / score / bool with a probability -- fail-closed, with a Brier ledger. Aither World Decide.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Aitherium/awdecide
+Project-URL: Documentation, https://github.com/Aitherium/awdecide#readme
+Project-URL: Repository, https://github.com/Aitherium/awdecide.git
+Project-URL: Issues, https://github.com/Aitherium/awdecide/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# awdecide — Aither World Decide
+
+**One typed-decision contract — choice / score / bool with a probability — over the
+backends you already run, fail-closed, with a Brier ledger that resolves every
+decision against its outcome.**
+
+```bash
+pip install -e AitherOS/packages/awdecide      # monorepo; no public mirror yet
+awdecide --self-test
+```
+
+## The problem it exists for
+
+Software makes the same bounded decision millions of times a day and asks a text
+model each time, then parses prose. Hosted "decision models" fix the shape — a typed
+question in, a typed answer with a probability out — but they send your program state
+off-box on every call, emit a probability that is never resolved against what
+happened, and cannot say what happens next if you act on it.
+
+A decision is a function. The loop it sits in is the product. `awdecide` is the
+function, written so the loop can be closed on your own machine:
+
+- **the contract** — `choice` (one of N names), `score` (one of N *ordered* levels),
+  `bool`; every answer carries `probability`, `confidence`, `backend`, `decided`.
+- **the ladder** — rungs asked in order, first answer above `min_confidence` wins:
+  `RulesBackend` (a matched rule answers at 1.0; no match abstains, never guesses),
+  `CallableBackend` (any `fn(state, question) -> {option: weight}` — a nanoGPT, an
+  sklearn model, a classify surface), `LogprobBackend` (an OpenAI-wire server with
+  `logprobs`: the mass over the option labels *is* the distribution; no prose parsed).
+- **fail-closed** — `decided=False` is a first-class answer. `value` is `None`, the
+  reasons say which rung abstained and why, and the strongest sub-threshold evidence is
+  kept in `probabilities` so a reviewer can see what was *not* acted on.
+- **the ledger** — SQLite. `record` a decided answer, `resolve` it against the outcome,
+  `reliability()` reports overall Brier, the climatology (base-rate) Brier it must beat,
+  and the per-bucket table (mean confidence vs observed frequency). Gate **1zdca**
+  (`check_decision_calibration.py --awdecide-db`) reads this file and goes red when the
+  probabilities stop carrying information.
+
+## Use
+
+```python
+from awdecide import Question, Ladder, RulesBackend, LogprobBackend, Ledger
+
+questions = {
+    "category": Question.choice(["billing", "technical", "sales"]),
+    "urgency":  Question.score(["low", "medium", "high"]),
+    "escalate": Question.bool(min_confidence=0.7),
+}
+ladder = Ladder([
+    RulesBackend([(r"refund|invoice", "billing")]),
+    LogprobBackend("http://127.0.0.1:8150", "orchestrator"),   # your own MicroScheduler
+])
+answers = ladder.decide(state_text, questions)
+answers["category"].value            # "billing"
+answers["escalate"].decided          # False if no rung cleared 0.7 -- act on that in code
+
+led = Ledger()                        # ~/.aither/awdecide.db or $AWDECIDE_DB
+did = led.record("escalate", state_text, answers["escalate"])
+...
+led.resolve(did, correct=True)       # later, when you know
+led.reliability()                    # brier, climatology, beats_base_rate, buckets
+```
+
+```bash
+awdecide ask --state "Customer emailed twice about a failed refund" \
+    category:choice=billing,technical,sales urgent:bool@0.7 \
+    --rule 'refund|invoice=billing' --record
+# exit 0 = every question decided · 3 = at least one decided=False (the JSON says why)
+awdecide resolve <id> --correct
+awdecide reliability
+```
+
+## The loop: a decision you resolved is never paid for twice
+
+`Ladder` answers a question. `Loop` remembers how the answer turned out. Ask, act,
+resolve -- the next identical decision is answered from that evidence with no model
+call, and an answer that was resolved wrong is never given again.
+
+Add it to the agent harness you already use:
+
+```bash
+claude mcp add awdecide -- uvx awdecide mcp          # Claude Code
+```
+
+```toml
+# Codex: ~/.codex/config.toml
+[mcp_servers.awdecide]
+command = "uvx"
+args = ["awdecide", "mcp"]
+```
+
+Then one paragraph in your `CLAUDE.md` / `AGENTS.md`:
+
+> Before a bounded decision you make repeatedly here (which command, which branch, retry
+> or stop), call `decide` with a STABLE `state` string. Act on the answer, then ALWAYS call
+> `decide_outcome`. If it returns `decided=false`, decide yourself and `decide_teach` it.
+
+The harness's own model is the brain on the first sighting; the ledger is the memory on
+every one after. To give the loop its own brain, point it at any OpenAI-wire endpoint:
+`AWDECIDE_LLM_URL`, `AWDECIDE_LLM_MODEL`, optional `AWDECIDE_LLM_KEY`.
+
+```python
+from awdecide import Loop, Ladder, Ledger, Question, ChatBackend
+
+loop = Loop(Ladder([ChatBackend("http://127.0.0.1:11434", "qwen3:8b")]), Ledger())
+d = loop.decide("test-runner", "lang:py,changed:tests",
+                Question.choice(["pytest -x", "pytest -n8", "tox"]))
+loop.resolve(d.id, correct=run(d.value))     # d.backend is "evidence" next time
+```
+
+Measure it: `awdecide bench` runs one deliberately imperfect brain (right 70% of the
+time) over 40 situations seen 10 times each, two ways.
+
+| | accuracy | model calls |
+|---|---|---|
+| call the brain every time | 70.8% | 400 |
+| **behind the loop** | **97.0%** | **52** |
+
+Same brain. More accurate because a wrong answer is resolved and retired; cheaper
+because a right one is never asked for again. The run also reports Brier against the
+base rate, so the probabilities are graded too. Change `--seed` and rerun it.
+
+## The learning backend: the decision door
+
+A rung may be a door that LEARNS. `DoorBackend` asks a world-model decision door
+(engine -> neighbor -> neural -> llm -> prior), which answers with the probability its
+own posted outcomes earned; `resolve()` sends the outcome back, so the next time that
+state -- or one like it -- arrives, the answer comes from evidence instead of a model.
+
+```python
+from awdecide import DoorBackend, Ladder, Ledger, Question
+
+state = "kind:code,len:short"
+door = DoorBackend(url="http://127.0.0.1:8299/v1", token=TOKEN, fork="router")
+d = Ladder([door]).decide_one(state, Question.choice(["fast-local", "reasoner"]))
+d.backend          # 'door:engine' -- which rung of the door answered
+led = Ledger()
+door.resolve(led.record("route", state, d), correct=True, ledger=led)   # teaches both
+```
+
+The door's own journals become ledger rows, idempotently by decision id:
+
+```bash
+awdecide ingest-door /path/to/ckpt-dir          # journaled pairs + prequential replay
+awdecide ingest-door --generate                 # bench-generated pairs, labelled bench/
+awdecide reliability                            # brier vs base rate, broken out by backend
+```
+
+A decision the door made with no probability, or with `source=none`, is not a claim and
+never becomes a row.
+
+## What it is not
+
+It is not a model. It ships no weights and calls nothing you did not name; a
+`LogprobBackend` with no URL is a refusal, not a default. It does not explain — a
+probability is what you get, and the ledger is where you find out whether it meant
+anything. Predicting what happens *after* the decision is `awpredict`'s contract;
+classifying documents at the door is `awclassify`'s; proving a page did the right thing
+is `awprove`'s.
+
+## Self-test
+
+`awdecide --self-test` runs seven arms and exits 0 only when all pass: rules answer,
+an empty ladder fails closed, `min_confidence` demotes a weak answer and keeps the
+evidence, the logprob rung turns a real logprobs payload (served in-process) into a
+distribution over the option labels only, the ledger's calibrated set beats the base
+rate and its overconfident set does not, the CLI grammar rejects a malformed spec, and the
+door rung maps every primitive, keeps the door's calibrated probability unrenormalized,
+abstains when the door has nothing, and ingests a door journal exactly once.
+
+Apache-2.0. Python 3.10+. Standard library only.
+## Sources and prediction
+
+`awdecide.sources` adds where a decision's state comes from and a rung that tries to
+predict the answer. `ReplState(session)` turns a live `awrepl` session into a STABLE
+state descriptor -- variable names, types and bucketed sizes (`rows:list:1k-9k`), never
+a repr and never a value, so the descriptor is safe to hash, log and resolve in the
+ledger. `PredictBackend(env)` is a ladder rung that asks a value oracle what each option
+is worth and ABSTAINS unless the top two are further apart than `margin`; the oracle is
+anything exposing `value(state, option)`, including `AwpredictValueEnv`, which wraps an
+`awpredict` engine's reward or value head. **The shipped default
+(`default_predict_backend()`) is the self-updating last-outcome lookup, not the learned
+model, and that is a measurement rather than a preference.**
+A bench (`tool_outcome_predict_bench`) asked whether anything can predict
+that the next run of a command shape will pass, well enough to skip the call, over
+323,644 real tool outcomes (95.0% pass) with a temporal 80/20 split, scored on the
+UNSEEN bucket only -- novel command shapes -- because a self-updating dictionary already
+owns the seen rows and an aggregate is therefore structurally unable to move. On 37,668
+UNSEEN rows the lookup, the online majority and "always run it" all score 0.9571, and
+coarsening the key to the command family makes it worse (0.9291); on a 12,000-row window
+with the learned arms in (1,785 UNSEEN) `awpredict`'s token-hash arm ties the base rate
+exactly at 0.9434 and its whole-string arm loses to it at 0.9412 -- so the bench exits 1,
+and exit 1 IS the finding: on a novel shape there is nothing in the history to learn
+from, and every arm collapses onto the base rate. The number that decides the design is
+not accuracy but skip-precision: 0.9434 on UNSEEN means roughly one in eighteen skipped
+calls would really have failed, so the rung is wired to abstain by default and to answer
+only where it has seen the option before. Re-run it when an engine with a real value head
+is a candidate; the arm ships the day it beats the dictionary, not before.

awdecide-0.3.0/README.md

@@ -0,0 +1,198 @@
+# awdecide — Aither World Decide
+
+**One typed-decision contract — choice / score / bool with a probability — over the
+backends you already run, fail-closed, with a Brier ledger that resolves every
+decision against its outcome.**
+
+```bash
+pip install -e AitherOS/packages/awdecide      # monorepo; no public mirror yet
+awdecide --self-test
+```
+
+## The problem it exists for
+
+Software makes the same bounded decision millions of times a day and asks a text
+model each time, then parses prose. Hosted "decision models" fix the shape — a typed
+question in, a typed answer with a probability out — but they send your program state
+off-box on every call, emit a probability that is never resolved against what
+happened, and cannot say what happens next if you act on it.
+
+A decision is a function. The loop it sits in is the product. `awdecide` is the
+function, written so the loop can be closed on your own machine:
+
+- **the contract** — `choice` (one of N names), `score` (one of N *ordered* levels),
+  `bool`; every answer carries `probability`, `confidence`, `backend`, `decided`.
+- **the ladder** — rungs asked in order, first answer above `min_confidence` wins:
+  `RulesBackend` (a matched rule answers at 1.0; no match abstains, never guesses),
+  `CallableBackend` (any `fn(state, question) -> {option: weight}` — a nanoGPT, an
+  sklearn model, a classify surface), `LogprobBackend` (an OpenAI-wire server with
+  `logprobs`: the mass over the option labels *is* the distribution; no prose parsed).
+- **fail-closed** — `decided=False` is a first-class answer. `value` is `None`, the
+  reasons say which rung abstained and why, and the strongest sub-threshold evidence is
+  kept in `probabilities` so a reviewer can see what was *not* acted on.
+- **the ledger** — SQLite. `record` a decided answer, `resolve` it against the outcome,
+  `reliability()` reports overall Brier, the climatology (base-rate) Brier it must beat,
+  and the per-bucket table (mean confidence vs observed frequency). Gate **1zdca**
+  (`check_decision_calibration.py --awdecide-db`) reads this file and goes red when the
+  probabilities stop carrying information.
+
+## Use
+
+```python
+from awdecide import Question, Ladder, RulesBackend, LogprobBackend, Ledger
+
+questions = {
+    "category": Question.choice(["billing", "technical", "sales"]),
+    "urgency":  Question.score(["low", "medium", "high"]),
+    "escalate": Question.bool(min_confidence=0.7),
+}
+ladder = Ladder([
+    RulesBackend([(r"refund|invoice", "billing")]),
+    LogprobBackend("http://127.0.0.1:8150", "orchestrator"),   # your own MicroScheduler
+])
+answers = ladder.decide(state_text, questions)
+answers["category"].value            # "billing"
+answers["escalate"].decided          # False if no rung cleared 0.7 -- act on that in code
+
+led = Ledger()                        # ~/.aither/awdecide.db or $AWDECIDE_DB
+did = led.record("escalate", state_text, answers["escalate"])
+...
+led.resolve(did, correct=True)       # later, when you know
+led.reliability()                    # brier, climatology, beats_base_rate, buckets
+```
+
+```bash
+awdecide ask --state "Customer emailed twice about a failed refund" \
+    category:choice=billing,technical,sales urgent:bool@0.7 \
+    --rule 'refund|invoice=billing' --record
+# exit 0 = every question decided · 3 = at least one decided=False (the JSON says why)
+awdecide resolve <id> --correct
+awdecide reliability
+```
+
+## The loop: a decision you resolved is never paid for twice
+
+`Ladder` answers a question. `Loop` remembers how the answer turned out. Ask, act,
+resolve -- the next identical decision is answered from that evidence with no model
+call, and an answer that was resolved wrong is never given again.
+
+Add it to the agent harness you already use:
+
+```bash
+claude mcp add awdecide -- uvx awdecide mcp          # Claude Code
+```
+
+```toml
+# Codex: ~/.codex/config.toml
+[mcp_servers.awdecide]
+command = "uvx"
+args = ["awdecide", "mcp"]
+```
+
+Then one paragraph in your `CLAUDE.md` / `AGENTS.md`:
+
+> Before a bounded decision you make repeatedly here (which command, which branch, retry
+> or stop), call `decide` with a STABLE `state` string. Act on the answer, then ALWAYS call
+> `decide_outcome`. If it returns `decided=false`, decide yourself and `decide_teach` it.
+
+The harness's own model is the brain on the first sighting; the ledger is the memory on
+every one after. To give the loop its own brain, point it at any OpenAI-wire endpoint:
+`AWDECIDE_LLM_URL`, `AWDECIDE_LLM_MODEL`, optional `AWDECIDE_LLM_KEY`.
+
+```python
+from awdecide import Loop, Ladder, Ledger, Question, ChatBackend
+
+loop = Loop(Ladder([ChatBackend("http://127.0.0.1:11434", "qwen3:8b")]), Ledger())
+d = loop.decide("test-runner", "lang:py,changed:tests",
+                Question.choice(["pytest -x", "pytest -n8", "tox"]))
+loop.resolve(d.id, correct=run(d.value))     # d.backend is "evidence" next time
+```
+
+Measure it: `awdecide bench` runs one deliberately imperfect brain (right 70% of the
+time) over 40 situations seen 10 times each, two ways.
+
+| | accuracy | model calls |
+|---|---|---|
+| call the brain every time | 70.8% | 400 |
+| **behind the loop** | **97.0%** | **52** |
+
+Same brain. More accurate because a wrong answer is resolved and retired; cheaper
+because a right one is never asked for again. The run also reports Brier against the
+base rate, so the probabilities are graded too. Change `--seed` and rerun it.
+
+## The learning backend: the decision door
+
+A rung may be a door that LEARNS. `DoorBackend` asks a world-model decision door
+(engine -> neighbor -> neural -> llm -> prior), which answers with the probability its
+own posted outcomes earned; `resolve()` sends the outcome back, so the next time that
+state -- or one like it -- arrives, the answer comes from evidence instead of a model.
+
+```python
+from awdecide import DoorBackend, Ladder, Ledger, Question
+
+state = "kind:code,len:short"
+door = DoorBackend(url="http://127.0.0.1:8299/v1", token=TOKEN, fork="router")
+d = Ladder([door]).decide_one(state, Question.choice(["fast-local", "reasoner"]))
+d.backend          # 'door:engine' -- which rung of the door answered
+led = Ledger()
+door.resolve(led.record("route", state, d), correct=True, ledger=led)   # teaches both
+```
+
+The door's own journals become ledger rows, idempotently by decision id:
+
+```bash
+awdecide ingest-door /path/to/ckpt-dir          # journaled pairs + prequential replay
+awdecide ingest-door --generate                 # bench-generated pairs, labelled bench/
+awdecide reliability                            # brier vs base rate, broken out by backend
+```
+
+A decision the door made with no probability, or with `source=none`, is not a claim and
+never becomes a row.
+
+## What it is not
+
+It is not a model. It ships no weights and calls nothing you did not name; a
+`LogprobBackend` with no URL is a refusal, not a default. It does not explain — a
+probability is what you get, and the ledger is where you find out whether it meant
+anything. Predicting what happens *after* the decision is `awpredict`'s contract;
+classifying documents at the door is `awclassify`'s; proving a page did the right thing
+is `awprove`'s.
+
+## Self-test
+
+`awdecide --self-test` runs seven arms and exits 0 only when all pass: rules answer,
+an empty ladder fails closed, `min_confidence` demotes a weak answer and keeps the
+evidence, the logprob rung turns a real logprobs payload (served in-process) into a
+distribution over the option labels only, the ledger's calibrated set beats the base
+rate and its overconfident set does not, the CLI grammar rejects a malformed spec, and the
+door rung maps every primitive, keeps the door's calibrated probability unrenormalized,
+abstains when the door has nothing, and ingests a door journal exactly once.
+
+Apache-2.0. Python 3.10+. Standard library only.
+## Sources and prediction
+
+`awdecide.sources` adds where a decision's state comes from and a rung that tries to
+predict the answer. `ReplState(session)` turns a live `awrepl` session into a STABLE
+state descriptor -- variable names, types and bucketed sizes (`rows:list:1k-9k`), never
+a repr and never a value, so the descriptor is safe to hash, log and resolve in the
+ledger. `PredictBackend(env)` is a ladder rung that asks a value oracle what each option
+is worth and ABSTAINS unless the top two are further apart than `margin`; the oracle is
+anything exposing `value(state, option)`, including `AwpredictValueEnv`, which wraps an
+`awpredict` engine's reward or value head. **The shipped default
+(`default_predict_backend()`) is the self-updating last-outcome lookup, not the learned
+model, and that is a measurement rather than a preference.**
+A bench (`tool_outcome_predict_bench`) asked whether anything can predict
+that the next run of a command shape will pass, well enough to skip the call, over
+323,644 real tool outcomes (95.0% pass) with a temporal 80/20 split, scored on the
+UNSEEN bucket only -- novel command shapes -- because a self-updating dictionary already
+owns the seen rows and an aggregate is therefore structurally unable to move. On 37,668
+UNSEEN rows the lookup, the online majority and "always run it" all score 0.9571, and
+coarsening the key to the command family makes it worse (0.9291); on a 12,000-row window
+with the learned arms in (1,785 UNSEEN) `awpredict`'s token-hash arm ties the base rate
+exactly at 0.9434 and its whole-string arm loses to it at 0.9412 -- so the bench exits 1,
+and exit 1 IS the finding: on a novel shape there is nothing in the history to learn
+from, and every arm collapses onto the base rate. The number that decides the design is
+not accuracy but skip-precision: 0.9434 on UNSEEN means roughly one in eighteen skipped
+calls would really have failed, so the rung is wired to abstain by default and to answer
+only where it has seen the option before. Re-run it when an engine with a real value head
+is a candidate; the arm ships the day it beats the dictionary, not before.

awdecide-0.3.0/awdecide/__init__.py

@@ -0,0 +1,38 @@
+"""awdecide -- Aither World Decide.
+
+One typed-decision contract -- choice / score / bool with a probability -- over
+a ladder of backends you already run (rules, any local model as a callable, an
+OpenAI-wire model's logprobs), fail-closed (decided=False is an answer), with a
+Brier ledger that resolves every decision against its outcome and reports
+whether the probabilities carry information beyond the base rate.
+
+    from awdecide import Question, Ladder, RulesBackend, Ledger
+
+    q = {"category": Question.choice(["billing", "technical", "sales"]),
+         "urgent": Question.bool(min_confidence=0.7)}
+    answers = Ladder([RulesBackend([(r"refund|invoice", "billing")])]).decide(state, q)
+    answers["category"].value, answers["category"].probability, answers["urgent"].decided
+
+Stdlib only. Nothing here sends the state anywhere you did not name.
+"""
+from .backends import (
+    Backend,
+    CallableBackend,
+    Ladder,
+    LogprobBackend,
+    RulesBackend,
+    default_ladder,
+    parse_question_spec,
+)
+from .contract import Decision, Question, from_probabilities, normalize, undecided
+from .door import DoorBackend, decision_from_door, door_request
+from .ledger import Ledger
+from .loop import ChatBackend, Loop
+
+__version__ = "0.3.0"
+__all__ = [
+    "Backend", "CallableBackend", "Ladder", "LogprobBackend", "RulesBackend",
+    "default_ladder", "parse_question_spec", "Decision", "Question",
+    "from_probabilities", "normalize", "undecided", "Ledger", "DoorBackend",
+    "decision_from_door", "door_request", "ChatBackend", "Loop", "__version__",
+]

awdecide-0.3.0/awdecide/__main__.py

@@ -0,0 +1,7 @@
+"""python -m awdecide"""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

awdecide-0.3.0/awdecide/_doctor.py

@@ -0,0 +1,190 @@
+"""Stack-aware `doctor` for awdecide.
+
+GENERATED BY gen_aw_doctor.py -- DO NOT EDIT.
+Regenerate it with the generator named above; a hand-edit here is reverted by
+the next run and fails the parity gate.
+
+Why a doctor exists at all: the aw* bricks are designed to COMPOSE, so the
+interesting failures live BETWEEN them. "awdecide is installed" is not the useful
+fact -- "awdecide is installed and the thing it pairs with is not" is. This reports
+the whole stack, not just itself.
+
+stdlib only, on purpose: a diagnostic that cannot run because a dependency is
+missing is worthless precisely when you need it.
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+
+#: Frozen from the Aither World registry at generation time. A shipped
+#: package cannot read the registry, and a doctor that guessed at the family
+#: would go stale in silence. Regenerate to update.
+SELF = 'awdecide'
+FAMILY = ['awask', 'awavatar', 'awbac', 'awbrain', 'awbrowse', 'awclassify', 'awdeck', 'awdelphi', 'awdit', 'awembed', 'awevolve', 'awfind', 'awflow', 'awfocus', 'awgit', 'awgraph', 'awgym', 'awiam', 'awkno', 'awm', 'awmail', 'awmine', 'awnboard', 'awnest', 'awnet', 'awnode', 'awpool', 'awpredict', 'awprism', 'awprove', 'awreason', 'awrecover', 'awrecurse', 'awrelay', 'awrena', 'awrepl', 'awreport', 'awresearch', 'awrise', 'awrouter', 'awrtifact', 'awrun', 'awscreen', 'awseal', 'awsettings', 'awshare', 'awsprite', 'awstorage', 'awswarm', 'awtax', 'awtoll', 'awtunnel', 'awvision', 'awvoice', 'awwall', 'gawbbonet']
+PAIRS_WITH = ['awclassify', 'adk', 'awgraph', 'awpredict', 'awprove', 'awrepl', 'awtoll']
+
+#: This brick's OWN config, read out of its source at generation time.
+#: ENV_REQUIRED is `os.environ["X"]` -- absent, that is a KeyError the moment
+#: the line runs. ENV_OPTIONAL is `os.getenv("X")`, which returns None and lets
+#: the caller cope. Only this brick's namespace is listed: reporting the
+#: platform-wide vars it also touches would be noise, and a doctor that floods
+#: gets ignored.
+ENV_REQUIRED = []
+ENV_OPTIONAL = ['AWDECIDE_DB']
+
+
+def _installed(mod: str) -> "str | None":
+    """Version if importable, else None. Never raises -- a broken sibling must
+    not take the diagnostic down with it."""
+    try:
+        if importlib.util.find_spec(mod) is None:
+            return None
+    except (ImportError, ValueError):
+        return None
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version(mod)
+        except PackageNotFoundError:
+            return "installed"
+    except Exception:
+        return "installed"
+
+
+def report(out=None) -> int:
+    """Print the stack picture. 0 = this brick and its pairs are present."""
+    out = out or sys.stdout
+    print(f"{SELF} doctor", file=out)
+
+    mine = _installed(SELF)
+    print(f"  self       {SELF} {mine or 'NOT IMPORTABLE'}", file=out)
+    shim = shutil.which(SELF)
+    print(f"  command    {shim or 'not on PATH'}", file=out)
+
+    # The stack. Siblings this brick pairs with are called out separately,
+    # because a missing pair is a REASON, while a missing unrelated brick is
+    # just a fact about your machine.
+    missing_pairs, present = [], []
+    for name in FAMILY:
+        v = _installed(name)
+        if v:
+            present.append(name)
+        elif name in PAIRS_WITH:
+            missing_pairs.append(name)
+    print(f"  stack      {len(present)}/{len(FAMILY)} aw* packages installed",
+          file=out)
+    if present:
+        print(f"             {' '.join(sorted(present))}", file=out)
+
+    missing_req = [v for v in ENV_REQUIRED if not os.environ.get(v)]
+    if ENV_REQUIRED or ENV_OPTIONAL:
+        have = sum(1 for v in ENV_REQUIRED + ENV_OPTIONAL if os.environ.get(v))
+        total = len(ENV_REQUIRED) + len(ENV_OPTIONAL)
+        print(f"  config     {have}/{total} of this brick's own vars set", file=out)
+        if missing_req:
+            # Not a preference. os.environ[...] raises the moment it runs.
+            print(f"             MISSING REQUIRED: {' '.join(missing_req)}", file=out)
+
+    local = _local_checks()
+    for line in local:
+        print(f"  {line}", file=out)
+    problems, unjudged = _local_verdict()
+
+    if mine is None:
+        print(f"\nverdict: {SELF} itself is not importable. Reinstall it before "
+              f"anything else here means much.", file=out)
+        return 1
+    if missing_req:
+        print(f"\nverdict: {SELF} is missing required config "
+              f"({', '.join(missing_req)}). Those are read with os.environ[...], "
+              f"so the code path that needs them raises rather than degrades.",
+              file=out)
+        return 1
+    # A measured NO outranks a missing optional pair: awrise printed
+    # "nothing wakes run-due" and still exited 0 because the missing-pairs
+    # branch returned first (measured 2026-09-20).
+    if problems:
+        for p in problems:
+            print(f"\nverdict: {p}", file=out)
+        return 1
+    if unjudged:
+        for u in unjudged:
+            print(f"\nverdict: UNJUDGED -- could not judge: {u}", file=out)
+        return 2
+    if missing_pairs:
+        print(f"\nverdict: {SELF} works, but pairs with "
+              f"{', '.join(sorted(missing_pairs))} which "
+              f"{'is' if len(missing_pairs) == 1 else 'are'} not installed. "
+              f"That is a capability you are missing, not an error.", file=out)
+        return 0
+    print(f"\nverdict: {SELF} and everything it pairs with are present.", file=out)
+    return 0
+
+
+def _local_verdict() -> tuple:
+    """The brick's OWN verdict, folded into the exit code.
+
+    Without this the local lines are DECORATION. Measured 2026-09-20: awrise
+    printed "hostclock NOT INSTALLED -- nothing wakes run-due" and "last tick
+    never", then exited 0 -- teaching an operator that a doctor exit code
+    carries no information. A brick opts in with `_doctor_local_verdict()`
+    returning (problems, unjudged); a brick without one is unaffected.
+    """
+    try:
+        mod = importlib.import_module(f"{SELF}.doctor_local")
+        problems, unjudged = mod._doctor_local_verdict()
+    except Exception:                              # noqa: BLE001
+        return [], []
+    return list(problems or []), list(unjudged or [])
+
+
+def _local_checks() -> "list[str]":
+    """Per-brick checks, if this package defines them.
+
+    Kept as a HOOK rather than generated guesses: the generator knows the family
+    from the registry, but it does not know what awdecide needs at runtime, and a
+    doctor that invented config requirements would be confidently wrong. A
+    package supplies `_doctor_local()` returning display lines; absent, the
+    stack picture above still stands on its own.
+    """
+    try:
+        mod = importlib.import_module(f"{SELF}.doctor_local")
+    except Exception:
+        return []
+    try:
+        return list(mod._doctor_local())
+    except Exception as exc:                       # noqa: BLE001
+        return [f"local     checks raised {type(exc).__name__}: {exc}"]
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    # --self-test delegates to a SIBLING module when one exists.
+    #
+    # This file is generated and a fresh run replaces it, so a self-test
+    # written HERE is deleted by the next regeneration. awdelphi learned that
+    # the expensive way: 125 lines exercising four real failure paths --
+    # convergence, roster anonymization, resume, gateway-down -- lived in this
+    # file and were destroyed by a routine regeneration, silently, leaving a
+    # --self-test flag that reported PASS while asserting nothing.
+    #
+    # So the seam is a separate module the generator never writes. A package
+    # with real machinery to prove puts it in _selftest.py; everything else
+    # keeps the honest answer below rather than a self-test that only ever
+    # passes.
+    argv = list(argv if argv is not None else __import__("sys").argv[1:])
+    if "--self-test" in argv:
+        try:
+            from . import _selftest as _st
+        except Exception:
+            print("no _selftest module: this doctor reports the stack, and has",
+                  "no machinery of its own to prove")
+            return 0
+        return int(_st.run())
+    return report()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())