lockwire 0.2.0__tar.gz

lockwire-0.2.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: lockwire
+Version: 0.2.0
+Summary: The physical-assumption contract for robots: physics lockfile + preflight gate
+Keywords: robotics,urdf,ros,preflight,lockfile,ci,hardware,drone
+Author: Shivansh
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: numpy>=2.5.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: rich>=15.0.0
+Requires-Dist: ruamel-yaml>=0.19.1
+Requires-Dist: typer>=0.26.8
+Requires-Dist: mcp>=2.1.1 ; extra == 'mcp'
+Requires-Dist: fastapi>=0.141.1 ; extra == 'serve'
+Requires-Dist: uvicorn>=0.52.4 ; extra == 'serve'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/Shivansh2703/lockwire
+Project-URL: Repository, https://github.com/Shivansh2703/lockwire
+Project-URL: Issues, https://github.com/Shivansh2703/lockwire/issues
+Provides-Extra: mcp
+Provides-Extra: serve
+Description-Content-Type: text/markdown
+
+# lockwire
+
+**Find out your robot won't work before you buy the parts.**
+
+Every robot is a stack of numbers from a dozen datasheets: what each part weighs, what each power rail can supply, how much the bus can carry, how much torque each joint gets. Lockwire keeps those numbers in one file and tells you the moment they stop adding up. Use it while you're still planning a build, then keep it in CI so a part swap can't quietly break it later.
+
+Prefer clicking to typing? The free desktop app does the same visually: Open, Design, Declare, Plan, Check.
+
+## Plan a robot from scratch
+
+Start from a URDF (one line is enough), add the parts you're thinking of buying, and check:
+
+```bash
+pip install "git+https://github.com/Shivansh2703/lockwire@v0.2.0"   # not on PyPI
+echo '<robot name="rover"><link name="base_link"/></robot>' > robot.urdf
+lockwire start robot.urdf
+lockwire add rail   lockwire.yaml --id rail.5v --voltage "5 V" --capacity "15 W" --source "UBEC datasheet: 5 V 3 A" --witness Sam
+lockwire add device lockwire.yaml --id dev.pi5   --family fam.pi    --model mod.pi5    --rail rail.5v --draw "12 W" --mass "46 g" --mount-frame base_link --owner you --source "Raspberry Pi 5 product brief" --witness Sam
+lockwire add device lockwire.yaml --id dev.servo --family fam.servo --model mod.mg996r --rail rail.5v --draw "6 W"  --mass "55 g" --mount-frame base_link --owner you --source "MG996R datasheet" --witness Sam
+lockwire add budget lockwire.yaml --id bud.5v --kind rail_power --rail rail.5v --limit "15 W" --owner you --source "UBEC datasheet" --witness Sam
+lockwire check lockwire.yaml
+```
+
+`--witness` is the person who read the number off the datasheet; use a real name, not "you".
+
+```console
+VIOLATION budgets/bud.5v — observed 18.00 W, expected <= 15.00 W (Δ +3.00 W (+20%))
+  dependent: dev.pi5, dev.servo
+  owner: you
+  source: UBEC datasheet: 5 V 3 A
+  action: shed load on rail 'rail.5v' or raise its capacity with provenance
+warning model/links/base_link/mass — observed zero or missing mass, expected a positive mass with units
+  …
+scored 2: 0 add up, 1 do not · 0 not scored
+
+NO-GO — 1 violation(s), 1 warning(s)
+```
+
+The check exits 1. A Pi 5 and one servo on a common 3 A regulator: caught before you ordered either. Swap in a 5 A regulator and it passes.
+
+## A real-world example: the X500 drone
+
+```bash
+git clone https://github.com/Shivansh2703/lockwire && cd lockwire     # the X500 example lives in the repo, not the wheel
+lockwire check tests/fixtures/x500/contract.yaml
+```
+
+Output (trimmed):
+
+```console
+$ lockwire check tests/fixtures/x500/contract.yaml
+VIOLATION budgets/bud.power.pm02-5v — observed 35.20 W (draw mode: nominal), expected <= 15.60 W (Δ +19.60 W (+126%))
+  dependent: dev.camera.oak-d-lite, dev.companion.jetson-orin-nano, dev.radio.rfd900x
+  owner: power-integration
+  action: shed load on rail 'rail.pm02-5v' or raise its capacity with provenance
+VIOLATION budgets/bud.power.pm02-5v.7w-mode — observed 17.20 W (draw mode: 7W), expected <= 15.60 W (Δ +1.60 W (+10%))
+  … (same rail, Jetson in its 7 W mode: the radio's transmit peak still tips it over)
+not scored devices/dev.camera.oak-d-lite/physical/mass — observed mass not declared, expected a positive mass with units
+  … (more not-scored lines: things the lockfile does not declare yet, listed, never hidden)
+scored 10: 8 add up, 2 do not · 9 not scored
+
+NO-GO — 2 violation(s), 0 warning(s)
+$ echo $?
+1
+```
+
+## What just happened
+
+A Holybro PM02 power module publishes a regulated 5 V rail at 3 A: 15.6 W. An NVIDIA Jetson
+Orin Nano publishes a 25 W power mode at 5 V: 5 A. Put a camera on the same rail and the
+published parts **cannot power the published companion computer**. This is a custom
+integration of published parts, and the two vendors' own numbers still do not add up.
+
+Nobody printed "this build is broken". Nobody printed "5 A" either: that is 25 W / 5 V, a
+quotient of figures published on different pages. The records disagree with each other, and
+you find out before you apply power. Give the Jetson its own regulator
+(`tests/fixtures/x500/contract_corrected.yaml`) and the same check passes.
+
+## Your own robot
+
+`lockwire start` reads links, joints, masses and the structure hash from your URDF or SDF. A fresh
+lockfile knows the frame and nothing else; fill in devices, rails and buses as you go, and
+`check` lists what it still could not check.
+
+A lockfile whose `schema_version` this lockwire does not recognise is refused before any check runs.
+`check` prints `REFUSED — contract declares schema_version '0.99'; this lockwire supports 0.2, 0.3, 0.4` and exits 2.
+A lockfile at an older supported version is accepted as-is, with no automatic upgrade.
+
+Re-running `lockwire start --force` on the same URDF is destructive:
+re-declare every fact in the lockfile by hand, because no command carries those facts forward.
+Any field you hand-edited (including `robot.name`) is silently overwritten back to the URDF-derived value.
+
+## Exit codes
+
+| command | 0 | 1 | 2 | 3 |
+|---|---|---|---|---|
+| `check` | `GO`, `GO with notes` | `NO-GO` | a contract that could not be found, read, or parsed | `NOT SCORED` (nothing compared) |
+| `start` | the contract was written (or an existing one kept); no page is written | the URDF/SDF could not be parsed, or the contract could not be read or written | — | — |
+
+`NOT SCORED` (exit 3) means no comparison had both operands: it is not a pass and not a failure.
+The `scored N: …` line above the verdict is where a script should look.
+
+## In CI
+
+```yaml
+- uses: actions/checkout@v4
+- uses: Shivansh2703/lockwire@v0        # composite action: installs lockwire, runs the check, uploads an HTML report
+  with:
+    contract: lockwire.yaml
+```
+
+Inputs: `contract` (default `lockwire.yaml`), `version` (default latest), `python-version` (default 3.12).
+Or just `pip install "git+https://github.com/Shivansh2703/lockwire@v0.2.0" && lockwire check lockwire.yaml`.
+
+## Pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/Shivansh2703/lockwire
+    rev: v0.2.0
+    hooks:
+      - id: lockwire-check
+```
+
+Runs `lockwire check` (on `lockwire.yaml` in the repo root) whenever a lockfile changes.
+
+## What it checks
+
+Each check compares **two separately declared figures**, each with its own provenance line.
+It shows who said what; it cannot verify that a datasheet is true.
+
+| check | source A | source B |
+|---|---|---|
+| rail power budget | device draw (datasheet) | rail capacity (power module datasheet) |
+| rail tree rollup | child rail draw / efficiency | parent rail capacity |
+| torque budget | joint effort limit (URDF) | actuator continuous torque x gear ratio |
+| bus bandwidth | message rate x payload | bus bitrate x utilisation ceiling |
+| mass budget | per-device mass | declared total |
+| endurance | pack energy | summed draw |
+| voltage compatibility | rail voltage | device input voltage range |
+| reference integrity | every `bus_ref`, `mount_frame`, dependency edge | the thing it points at |
+
+No physics simulation, no machine learning, no network. The answer is the same twice.
+
+## Free and Pro
+
+- **Free forever (this repo):** the lockfile, all deterministic checks including
+  power/thermal/bus/link/torque budgets, edit / describe / plan / what-if, the MCP server, the
+  HTML report, and the desktop planning app (Open, Design, Declare, Plan, Check).
+- **Lockwire Pro** adds the powered-on preflight gate (Test, Run), recording analysis
+  (rosbag2 / ULog), and health.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Python 3.12 or newer; runtime dependencies are
+pydantic, typer, rich, ruamel.yaml and numpy.
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).

lockwire-0.2.0/README.md

@@ -0,0 +1,160 @@
+# lockwire
+
+**Find out your robot won't work before you buy the parts.**
+
+Every robot is a stack of numbers from a dozen datasheets: what each part weighs, what each power rail can supply, how much the bus can carry, how much torque each joint gets. Lockwire keeps those numbers in one file and tells you the moment they stop adding up. Use it while you're still planning a build, then keep it in CI so a part swap can't quietly break it later.
+
+Prefer clicking to typing? The free desktop app does the same visually: Open, Design, Declare, Plan, Check.
+
+## Plan a robot from scratch
+
+Start from a URDF (one line is enough), add the parts you're thinking of buying, and check:
+
+```bash
+pip install "git+https://github.com/Shivansh2703/lockwire@v0.2.0"   # not on PyPI
+echo '<robot name="rover"><link name="base_link"/></robot>' > robot.urdf
+lockwire start robot.urdf
+lockwire add rail   lockwire.yaml --id rail.5v --voltage "5 V" --capacity "15 W" --source "UBEC datasheet: 5 V 3 A" --witness Sam
+lockwire add device lockwire.yaml --id dev.pi5   --family fam.pi    --model mod.pi5    --rail rail.5v --draw "12 W" --mass "46 g" --mount-frame base_link --owner you --source "Raspberry Pi 5 product brief" --witness Sam
+lockwire add device lockwire.yaml --id dev.servo --family fam.servo --model mod.mg996r --rail rail.5v --draw "6 W"  --mass "55 g" --mount-frame base_link --owner you --source "MG996R datasheet" --witness Sam
+lockwire add budget lockwire.yaml --id bud.5v --kind rail_power --rail rail.5v --limit "15 W" --owner you --source "UBEC datasheet" --witness Sam
+lockwire check lockwire.yaml
+```
+
+`--witness` is the person who read the number off the datasheet; use a real name, not "you".
+
+```console
+VIOLATION budgets/bud.5v — observed 18.00 W, expected <= 15.00 W (Δ +3.00 W (+20%))
+  dependent: dev.pi5, dev.servo
+  owner: you
+  source: UBEC datasheet: 5 V 3 A
+  action: shed load on rail 'rail.5v' or raise its capacity with provenance
+warning model/links/base_link/mass — observed zero or missing mass, expected a positive mass with units
+  …
+scored 2: 0 add up, 1 do not · 0 not scored
+
+NO-GO — 1 violation(s), 1 warning(s)
+```
+
+The check exits 1. A Pi 5 and one servo on a common 3 A regulator: caught before you ordered either. Swap in a 5 A regulator and it passes.
+
+## A real-world example: the X500 drone
+
+```bash
+git clone https://github.com/Shivansh2703/lockwire && cd lockwire     # the X500 example lives in the repo, not the wheel
+lockwire check tests/fixtures/x500/contract.yaml
+```
+
+Output (trimmed):
+
+```console
+$ lockwire check tests/fixtures/x500/contract.yaml
+VIOLATION budgets/bud.power.pm02-5v — observed 35.20 W (draw mode: nominal), expected <= 15.60 W (Δ +19.60 W (+126%))
+  dependent: dev.camera.oak-d-lite, dev.companion.jetson-orin-nano, dev.radio.rfd900x
+  owner: power-integration
+  action: shed load on rail 'rail.pm02-5v' or raise its capacity with provenance
+VIOLATION budgets/bud.power.pm02-5v.7w-mode — observed 17.20 W (draw mode: 7W), expected <= 15.60 W (Δ +1.60 W (+10%))
+  … (same rail, Jetson in its 7 W mode: the radio's transmit peak still tips it over)
+not scored devices/dev.camera.oak-d-lite/physical/mass — observed mass not declared, expected a positive mass with units
+  … (more not-scored lines: things the lockfile does not declare yet, listed, never hidden)
+scored 10: 8 add up, 2 do not · 9 not scored
+
+NO-GO — 2 violation(s), 0 warning(s)
+$ echo $?
+1
+```
+
+## What just happened
+
+A Holybro PM02 power module publishes a regulated 5 V rail at 3 A: 15.6 W. An NVIDIA Jetson
+Orin Nano publishes a 25 W power mode at 5 V: 5 A. Put a camera on the same rail and the
+published parts **cannot power the published companion computer**. This is a custom
+integration of published parts, and the two vendors' own numbers still do not add up.
+
+Nobody printed "this build is broken". Nobody printed "5 A" either: that is 25 W / 5 V, a
+quotient of figures published on different pages. The records disagree with each other, and
+you find out before you apply power. Give the Jetson its own regulator
+(`tests/fixtures/x500/contract_corrected.yaml`) and the same check passes.
+
+## Your own robot
+
+`lockwire start` reads links, joints, masses and the structure hash from your URDF or SDF. A fresh
+lockfile knows the frame and nothing else; fill in devices, rails and buses as you go, and
+`check` lists what it still could not check.
+
+A lockfile whose `schema_version` this lockwire does not recognise is refused before any check runs.
+`check` prints `REFUSED — contract declares schema_version '0.99'; this lockwire supports 0.2, 0.3, 0.4` and exits 2.
+A lockfile at an older supported version is accepted as-is, with no automatic upgrade.
+
+Re-running `lockwire start --force` on the same URDF is destructive:
+re-declare every fact in the lockfile by hand, because no command carries those facts forward.
+Any field you hand-edited (including `robot.name`) is silently overwritten back to the URDF-derived value.
+
+## Exit codes
+
+| command | 0 | 1 | 2 | 3 |
+|---|---|---|---|---|
+| `check` | `GO`, `GO with notes` | `NO-GO` | a contract that could not be found, read, or parsed | `NOT SCORED` (nothing compared) |
+| `start` | the contract was written (or an existing one kept); no page is written | the URDF/SDF could not be parsed, or the contract could not be read or written | — | — |
+
+`NOT SCORED` (exit 3) means no comparison had both operands: it is not a pass and not a failure.
+The `scored N: …` line above the verdict is where a script should look.
+
+## In CI
+
+```yaml
+- uses: actions/checkout@v4
+- uses: Shivansh2703/lockwire@v0        # composite action: installs lockwire, runs the check, uploads an HTML report
+  with:
+    contract: lockwire.yaml
+```
+
+Inputs: `contract` (default `lockwire.yaml`), `version` (default latest), `python-version` (default 3.12).
+Or just `pip install "git+https://github.com/Shivansh2703/lockwire@v0.2.0" && lockwire check lockwire.yaml`.
+
+## Pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/Shivansh2703/lockwire
+    rev: v0.2.0
+    hooks:
+      - id: lockwire-check
+```
+
+Runs `lockwire check` (on `lockwire.yaml` in the repo root) whenever a lockfile changes.
+
+## What it checks
+
+Each check compares **two separately declared figures**, each with its own provenance line.
+It shows who said what; it cannot verify that a datasheet is true.
+
+| check | source A | source B |
+|---|---|---|
+| rail power budget | device draw (datasheet) | rail capacity (power module datasheet) |
+| rail tree rollup | child rail draw / efficiency | parent rail capacity |
+| torque budget | joint effort limit (URDF) | actuator continuous torque x gear ratio |
+| bus bandwidth | message rate x payload | bus bitrate x utilisation ceiling |
+| mass budget | per-device mass | declared total |
+| endurance | pack energy | summed draw |
+| voltage compatibility | rail voltage | device input voltage range |
+| reference integrity | every `bus_ref`, `mount_frame`, dependency edge | the thing it points at |
+
+No physics simulation, no machine learning, no network. The answer is the same twice.
+
+## Free and Pro
+
+- **Free forever (this repo):** the lockfile, all deterministic checks including
+  power/thermal/bus/link/torque budgets, edit / describe / plan / what-if, the MCP server, the
+  HTML report, and the desktop planning app (Open, Design, Declare, Plan, Check).
+- **Lockwire Pro** adds the powered-on preflight gate (Test, Run), recording analysis
+  (rosbag2 / ULog), and health.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Python 3.12 or newer; runtime dependencies are
+pydantic, typer, rich, ruamel.yaml and numpy.
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).

lockwire-0.2.0/pyproject.toml

@@ -0,0 +1,103 @@
+[project]
+name = "lockwire"
+version = "0.2.0"
+description = "The physical-assumption contract for robots: physics lockfile + preflight gate"
+readme = "README.md"
+authors = [
+    { name = "Shivansh" }
+]
+requires-python = ">=3.12"
+license = "Apache-2.0"
+keywords = ["robotics", "urdf", "ros", "preflight", "lockfile", "ci", "hardware", "drone"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Intended Audience :: Manufacturing",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "numpy>=2.5.1",
+    "pydantic>=2.13.4",
+    "rich>=15.0.0",
+    "ruamel-yaml>=0.19.1",
+    "typer>=0.26.8",
+]
+
+[project.optional-dependencies]
+# Serving lockwire over MCP to an agent. Optional for the same reason as `ros2bag`:
+# a plain install must stay lean, and the SDK is only needed by `lockwire mcp`.
+mcp = [
+    "mcp>=2.1.1",
+]
+# The Electron app's sidecar: `lockwire serve` over local HTTP. Optional for the
+# same reason as `desktop`/`ros2bag`/`mcp` — a plain CLI install stays lean; only the
+# packaged app build and anyone running the sidecar by hand need these. Versions are
+# today's PyPI current stable (measured, E1-a).
+serve = [
+    "fastapi>=0.141.1",
+    "uvicorn>=0.52.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/Shivansh2703/lockwire"
+Repository = "https://github.com/Shivansh2703/lockwire"
+Issues = "https://github.com/Shivansh2703/lockwire/issues"
+
+[project.scripts]
+lockwire = "lockwire:main"
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+
+[dependency-groups]
+dev = [
+    "mcp>=2.1.1",
+    # tests/test_serve.py needs the sidecar (`lockwire serve`) importable and
+    # runnable as a subprocess. Same reasoning as `mcp`/`mcap` above: CI's
+    # `test` job runs a plain `uv sync --dev`, so without these here that
+    # whole test file would silently never run. Dev-only: the runtime `serve`
+    # extra above stays optional so a plain install stays lean.
+    "fastapi>=0.141.1",
+    "uvicorn>=0.52.4",
+    "httpx>=0.28.1",
+    # Freezing the sidecar binary: `uv run pyinstaller packaging/lockwire.spec`. Dev-only —
+    # it is a build tool, never imported at runtime — and `tests/test_cli.py` imports it to
+    # anchor the uvicorn hidden-import test against uvicorn's real module list (box e1-d2).
+    "pyinstaller>=6.21.0",
+    "pytest>=9.1.1",
+    "pytest-xdist>=3.6.1",
+    "ruff>=0.15.20,<0.16",  # 0.17 changes default rules
+    "pytest-cov>=7.1.0",
+]
+
+[tool.ruff]
+# This codebase is written to ~100 columns: schema.py and checks.py carry aligned
+# trailing comments naming each field's consumer, and wrapping at ruff's default 88
+# splits those annotations off the line they annotate. E501 is not in ruff's default
+# rule set, so before this block the two documented commands disagreed — `ruff check`
+# passed while `ruff format` wanted to rewrite 12 files. At 100 the sweep is a net
+# reduction (83 insertions / 105 deletions); at 88 it was +219/-80.
+line-length = 100
+
+# measure_stacked_gate.py bootstraps sys.path before imports (B76) — E402 is intentional there.
+[tool.ruff.lint.per-file-ignores]
+"scripts/measure_stacked_gate.py" = ["E402"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]
+# chrome: drives real headless Chrome (subprocess spawn). scripts/pytest_slot.sh
+# excludes this marker from every non-exclusive (targeted) run so workers' test
+# runs never spawn Chrome processes; the cadence Check (--exclusive) still runs
+# them. Registered here so --strict-markers, if ever turned on, does not bite.
+markers = [
+    "chrome: drives real headless Chrome; excluded from targeted runs by scripts/pytest_slot.sh",
+]

lockwire-0.2.0/src/lockwire/__init__.py

@@ -0,0 +1,9 @@
+"""Lockwire — the physical-assumption contract for robots, enforced in CI and at preflight."""
+
+__version__ = "0.2.0"
+
+
+def main() -> None:
+    from lockwire.cli import app
+
+    app()

lockwire-0.2.0/src/lockwire/__main__.py

@@ -0,0 +1,9 @@
+"""``python -m lockwire`` — the same CLI the ``lockwire`` script runs.
+
+Exists so ``jobs.py`` can start a run as an argv list against ``sys.executable``
+without depending on a console script being on PATH.
+"""
+
+from lockwire.cli import app
+
+app()

lockwire-0.2.0/src/lockwire/advice.py

@@ -0,0 +1,119 @@
+"""The alternatives half of the advice sentence.
+
+``check_budgets`` (``checks.py``) already knows a rail_power budget is over its
+limit; this module answers the second half of the sentence — "what else could
+carry it" — headroom on every OTHER rail_power budget, plus a projected
+regulator suggestion. It computes nothing about rail membership itself:
+Reuse means ``checks.power_rollup``'s own return values (rail totals, the
+per-rail unknown-consumer sets) are passed in as plain data, never re-walked.
+This module never imports ``checks`` — the call only ever goes the other way,
+so there is no cycle.
+
+Every number carries its ``kind`` (a catalog or projected
+figure is shown only with its own visual mark and word, never in the same
+style as a measured one): headroom is ``derived-by-<check>`` — the same
+rollup ``check_budgets`` itself scores against; a suggested regulator rating
+is ``projected``, a number this product is choosing, not measuring.
+
+**Raising the over-budget rail's own declared capacity is never offered**
+: that clears the finding by moving the limit rather than
+the draw, which leaves a standing mark. Offering it as
+advice would make the product recommend the exact thing that mark exists to flag.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from lockwire.schema import Contract
+
+
+class Alternative(BaseModel):
+    """One remedy suggestion, its number, and the kind that number carries."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    text: str
+    value: float
+    unit: str
+    kind: str  # "derived-by-<check>" | "projected" | "none"
+    #: The word for a ``projected`` figure. Required when ``kind ==
+    #: "projected"`` — a projected figure reaching a door carries its mark and
+    #: its word, not a corrected sentence saying it is unenforced.
+    mark: str | None = None
+
+    @model_validator(mode="after")
+    def _carries_its_word(self) -> Alternative:
+        if self.kind == "projected" and not self.mark:
+            raise ValueError("a 'projected' number must carry its own word, e.g. mark='projected'")
+        return self
+
+
+def build_rail_alternatives(
+    contract: Contract,
+    *,
+    over_rail_id: str,
+    deficit_w: float,
+    rail_totals: dict[str, float],
+    rail_unknown: dict[str, set[str]],
+    check_name: str = "check_budgets",
+) -> list[Alternative]:
+    """Alternatives for a rail_power budget over its limit on ``over_rail_id``.
+
+    ``rail_totals``/``rail_unknown`` must come from ``checks.power_rollup`` run
+    against the same contract and draw mode as the violation being explained —
+    the shared builder that every call site (and every mutation bite) goes
+    through, so a broken kind anywhere breaks every caller alike.
+    """
+    alternatives: list[Alternative] = []
+    for budget in contract.budgets:
+        if budget.kind != "rail_power" or budget.rail in (None, over_rail_id):
+            continue
+        if rail_unknown.get(budget.rail):
+            # a rail with any consumer of unknown draw cannot be summed,
+            # so it cannot be claimed to have headroom either.
+            continue
+        used = rail_totals.get(budget.rail, 0.0)
+        headroom_w = budget.limit.base() - used
+        if headroom_w > 0.0:
+            alternatives.append(
+                Alternative(
+                    text=(
+                        f"move the device to rail {budget.rail!r}, which has "
+                        f"{headroom_w:.2f} W free"
+                    ),
+                    value=headroom_w,
+                    unit="W",
+                    kind=f"derived-by-{check_name}",
+                )
+            )
+
+    over_rail = contract.rail(over_rail_id)
+    source_rail_id = "battery"
+    if over_rail is not None and over_rail.upstream is not None:
+        source_rail_id = over_rail.upstream
+    rating_w = max(deficit_w, 0.0)
+    if rating_w > 0.0:
+        alternatives.append(
+            Alternative(
+                text=f"add a {rating_w:.2f} W regulator fed from rail {source_rail_id!r}",
+                value=rating_w,
+                unit="W",
+                kind="projected",
+                mark="projected",
+            )
+        )
+
+    if not alternatives:
+        alternatives.append(
+            Alternative(
+                text=(
+                    f"no other rail has headroom for {over_rail_id!r} and no regulator "
+                    "rating could be projected"
+                ),
+                value=0.0,
+                unit="W",
+                kind="none",
+            )
+        )
+    return alternatives