vledger 0.1.0__tar.gz

vledger-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Michael Lenz <michael.lenz@nullvector.org>, <michael.lenz@nullvector.space>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

vledger-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: vledger
+Version: 0.1.0
+Summary: Vehicle ledger: trips, charging, refuelling and cost, derived from a raw log of Home Assistant states
+Author-email: Michael Lenz <michael.lenz@nullvector.org>
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/michael-lenz/ha-vledger
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: ha
+Requires-Dist: pytest-homeassistant-custom-component; extra == "ha"
+Dynamic: license-file
+
+# ha-vledger
+
+> **Pre-alpha. Do not install this.** It captures a raw log and nothing
+> else yet: no trips, no charging sessions, no consumption, no cost. The
+> log format is decided and will be read by every later version, but the
+> integration has run on exactly one vehicle, the options may change
+> between releases, and there is no support. It is public so that the
+> author can test it through HACS and so that the design can be read.
+> When it is ready for other people, this notice goes away.
+
+A vehicle ledger for Home Assistant. It keeps a raw log of the handful of
+vehicle states that matter to a ledger — odometer, position, fuel level,
+state of charge, charging state — and derives from it what the vehicle's
+own app never tells you reliably: trips, charging sessions, refuellings,
+consumption and cost. Passively, from whatever integration already exposes
+the vehicle, without a line of manufacturer-specific code, and without
+touching anything else the vehicle reports: it is a ledger, not a monitor.
+
+**Status:** capture works. The integration sets up a vehicle or a charge
+point through the UI and writes its raw log — the format, and the
+`vledger l0` verbs that write, read, validate it and list its gaps, are the
+library's. Nothing derives from the log yet: no trips, no sessions, no
+metrics, no receipts. Every behaviour described below is the design, held
+as requirements in the project's register (`ha-vledger-pm`); a section is
+marked *(planned)* until it exists.
+
+## What it does *(planned)*
+
+- **Captures, losslessly.** Every change of a source entity you assign to
+  a role becomes one record in a raw log (L0): JSON Lines, append-only, one
+  stream per vehicle and per charge point, rotated monthly, kept outside
+  the Home Assistant recorder and its retention. Start, stop and heartbeat
+  markers make any capture gap visible; nothing is interpolated across one.
+- **Derives, deterministically.** Trips (between standstills), charging
+  sessions (from the charging state), refuellings (a fuel rise at unchanged
+  odometer) and metrics are computed from L0, receipts and configuration
+  (L1) — the same logic live in Home Assistant and in batch from the
+  command line, recomputable from scratch at any time. Every derived value
+  carries a quality flag: `measured`, `receipt`, `estimated` or
+  `incomplete`.
+- **Takes receipts.** Price and exact quantity come from you: a refuelling
+  or charging receipt, entered from a notification, a dashboard or an
+  action, matched to the detected event by time. Receipt values beat sensor
+  values; a detected event without a receipt stays visible as unconfirmed.
+- **Knows your charge points.** Home, work, anywhere fixed: position,
+  radius, tariff, optionally a meter. A charge point with a tariff but no
+  meter still yields cost, estimated through a charging loss factor; a
+  tariff of 0 is cost 0. Anything else is a foreign charge and asks for a
+  receipt.
+- **Reports.** Per month, year and rolling period: distance, litres and kWh,
+  fuel and electricity cost, €/100 km per energy carrier, the electric
+  share two ways (energy by heating value, and an estimated distance
+  share), charge cycles and tank-fill equivalents. Fuel consumption is
+  tank-to-tank between any two receipts, corrected by the fuel level sensor,
+  so a tank that is never filled up still gets a figure.
+
+## What it is built of
+
+One repository, two packages, one version number (ADR-0002):
+
+```
+src/vledger/               the library and the vledger CLI: all derivation
+                           logic, no Home Assistant, no dependencies;
+                           published to PyPI as `vledger`
+custom_components/vledger/ the Home Assistant integration, a shell over the
+                           library: capture, config and options flows,
+                           entities, actions, diagnostics; pins the library
+                           by the same version in manifest.json
+tests/                     pytest: library tests on L0 fixtures, integration
+                           tests with pytest-homeassistant-custom-component
+docs/                      design documentation
+```
+
+A vehicle is a config entry; its source entities are assigned to roles
+(`odometer`, `position`, `fuel_level`, `soc`, `charging_state`, …), and
+what the vehicle can do follows from the roles it has. Everything is
+configured in the UI; no YAML.
+
+## Documentation
+
+| Document | What it is |
+|---|---|
+| [docs/user-guide.md](docs/user-guide.md) | What a participant types: the `vledger` command, verb by verb |
+| [docs/l0-format.md](docs/l0-format.md) | The raw log's layout, version 1 — the specification a reader of their own files needs |
+| [docs/glossary.md](docs/glossary.md) | The one English spelling of every domain term, and what it means |
+| [docs/releasing.md](docs/releasing.md) | What the person cutting a release does, in order |
+
+Decisions, requirements and the work queue are records in the project's
+register, `ha-vledger-pm`, not prose here.
+
+## Installing
+
+Not yet — see the notice at the top. For the author's own test
+instances: in HACS, *Integrations → ⋮ → Custom repositories*, add
+`https://github.com/michael-lenz/ha-vledger` as an *Integration*, then
+install it and restart; or copy `custom_components/vledger` into the
+configuration directory by hand. Either way Home Assistant installs the
+library from PyPI (`vledger==<version>`, pinned in the manifest), so the
+version has to be published first — [docs/releasing.md](docs/releasing.md).
+Then *Settings → Devices & services → Add integration → Vehicle Ledger*:
+the [user guide](docs/user-guide.md) walks the four steps. The library on
+its own: `pip install vledger`, which brings the `vledger` command.
+
+## Developing
+
+```bash
+pip install -e ".[dev]"        # library and CLI
+pip install -e ".[dev,ha]"     # plus the Home Assistant test stack, for the integration
+python -m pytest
+ruff check src tests custom_components
+```
+
+The integration's manifest pins a library version that may not be on PyPI
+yet; Home Assistant skips the install when the package already imports, so
+a development instance needs the editable install above first.
+
+The `ha` extra pulls in a full Home Assistant core and its test plugin.
+On a Debian or Ubuntu system Python that install can fail to build one of
+its transitive dependencies against the distribution's patched
+setuptools; a virtual environment (`python3 -m venv .venv`) does not have
+that problem, and is the recommended place for it anyway. Without the
+extra, `python -m pytest` runs the library's tests and leaves `tests/ha`
+out. The library's own tests, the integration's against the oldest and
+the newest Home Assistant, and HACS's validation run on every push
+(`.github/workflows/tests.yml`); a tag `vX.Y.Z` publishes the release
+(`.github/workflows/release.yml`, [docs/releasing.md](docs/releasing.md)).
+
+## Privacy
+
+The position history is personal data. It stays on your instance — nothing
+is transmitted anywhere — and is redacted from logs and diagnostics, but
+the default storage path lies under the Home Assistant configuration
+directory and is therefore part of your backups.
+
+## License
+
+BSD-3-Clause — see [LICENSE](LICENSE).

vledger-0.1.0/README.md

@@ -0,0 +1,137 @@
+# ha-vledger
+
+> **Pre-alpha. Do not install this.** It captures a raw log and nothing
+> else yet: no trips, no charging sessions, no consumption, no cost. The
+> log format is decided and will be read by every later version, but the
+> integration has run on exactly one vehicle, the options may change
+> between releases, and there is no support. It is public so that the
+> author can test it through HACS and so that the design can be read.
+> When it is ready for other people, this notice goes away.
+
+A vehicle ledger for Home Assistant. It keeps a raw log of the handful of
+vehicle states that matter to a ledger — odometer, position, fuel level,
+state of charge, charging state — and derives from it what the vehicle's
+own app never tells you reliably: trips, charging sessions, refuellings,
+consumption and cost. Passively, from whatever integration already exposes
+the vehicle, without a line of manufacturer-specific code, and without
+touching anything else the vehicle reports: it is a ledger, not a monitor.
+
+**Status:** capture works. The integration sets up a vehicle or a charge
+point through the UI and writes its raw log — the format, and the
+`vledger l0` verbs that write, read, validate it and list its gaps, are the
+library's. Nothing derives from the log yet: no trips, no sessions, no
+metrics, no receipts. Every behaviour described below is the design, held
+as requirements in the project's register (`ha-vledger-pm`); a section is
+marked *(planned)* until it exists.
+
+## What it does *(planned)*
+
+- **Captures, losslessly.** Every change of a source entity you assign to
+  a role becomes one record in a raw log (L0): JSON Lines, append-only, one
+  stream per vehicle and per charge point, rotated monthly, kept outside
+  the Home Assistant recorder and its retention. Start, stop and heartbeat
+  markers make any capture gap visible; nothing is interpolated across one.
+- **Derives, deterministically.** Trips (between standstills), charging
+  sessions (from the charging state), refuellings (a fuel rise at unchanged
+  odometer) and metrics are computed from L0, receipts and configuration
+  (L1) — the same logic live in Home Assistant and in batch from the
+  command line, recomputable from scratch at any time. Every derived value
+  carries a quality flag: `measured`, `receipt`, `estimated` or
+  `incomplete`.
+- **Takes receipts.** Price and exact quantity come from you: a refuelling
+  or charging receipt, entered from a notification, a dashboard or an
+  action, matched to the detected event by time. Receipt values beat sensor
+  values; a detected event without a receipt stays visible as unconfirmed.
+- **Knows your charge points.** Home, work, anywhere fixed: position,
+  radius, tariff, optionally a meter. A charge point with a tariff but no
+  meter still yields cost, estimated through a charging loss factor; a
+  tariff of 0 is cost 0. Anything else is a foreign charge and asks for a
+  receipt.
+- **Reports.** Per month, year and rolling period: distance, litres and kWh,
+  fuel and electricity cost, €/100 km per energy carrier, the electric
+  share two ways (energy by heating value, and an estimated distance
+  share), charge cycles and tank-fill equivalents. Fuel consumption is
+  tank-to-tank between any two receipts, corrected by the fuel level sensor,
+  so a tank that is never filled up still gets a figure.
+
+## What it is built of
+
+One repository, two packages, one version number (ADR-0002):
+
+```
+src/vledger/               the library and the vledger CLI: all derivation
+                           logic, no Home Assistant, no dependencies;
+                           published to PyPI as `vledger`
+custom_components/vledger/ the Home Assistant integration, a shell over the
+                           library: capture, config and options flows,
+                           entities, actions, diagnostics; pins the library
+                           by the same version in manifest.json
+tests/                     pytest: library tests on L0 fixtures, integration
+                           tests with pytest-homeassistant-custom-component
+docs/                      design documentation
+```
+
+A vehicle is a config entry; its source entities are assigned to roles
+(`odometer`, `position`, `fuel_level`, `soc`, `charging_state`, …), and
+what the vehicle can do follows from the roles it has. Everything is
+configured in the UI; no YAML.
+
+## Documentation
+
+| Document | What it is |
+|---|---|
+| [docs/user-guide.md](docs/user-guide.md) | What a participant types: the `vledger` command, verb by verb |
+| [docs/l0-format.md](docs/l0-format.md) | The raw log's layout, version 1 — the specification a reader of their own files needs |
+| [docs/glossary.md](docs/glossary.md) | The one English spelling of every domain term, and what it means |
+| [docs/releasing.md](docs/releasing.md) | What the person cutting a release does, in order |
+
+Decisions, requirements and the work queue are records in the project's
+register, `ha-vledger-pm`, not prose here.
+
+## Installing
+
+Not yet — see the notice at the top. For the author's own test
+instances: in HACS, *Integrations → ⋮ → Custom repositories*, add
+`https://github.com/michael-lenz/ha-vledger` as an *Integration*, then
+install it and restart; or copy `custom_components/vledger` into the
+configuration directory by hand. Either way Home Assistant installs the
+library from PyPI (`vledger==<version>`, pinned in the manifest), so the
+version has to be published first — [docs/releasing.md](docs/releasing.md).
+Then *Settings → Devices & services → Add integration → Vehicle Ledger*:
+the [user guide](docs/user-guide.md) walks the four steps. The library on
+its own: `pip install vledger`, which brings the `vledger` command.
+
+## Developing
+
+```bash
+pip install -e ".[dev]"        # library and CLI
+pip install -e ".[dev,ha]"     # plus the Home Assistant test stack, for the integration
+python -m pytest
+ruff check src tests custom_components
+```
+
+The integration's manifest pins a library version that may not be on PyPI
+yet; Home Assistant skips the install when the package already imports, so
+a development instance needs the editable install above first.
+
+The `ha` extra pulls in a full Home Assistant core and its test plugin.
+On a Debian or Ubuntu system Python that install can fail to build one of
+its transitive dependencies against the distribution's patched
+setuptools; a virtual environment (`python3 -m venv .venv`) does not have
+that problem, and is the recommended place for it anyway. Without the
+extra, `python -m pytest` runs the library's tests and leaves `tests/ha`
+out. The library's own tests, the integration's against the oldest and
+the newest Home Assistant, and HACS's validation run on every push
+(`.github/workflows/tests.yml`); a tag `vX.Y.Z` publishes the release
+(`.github/workflows/release.yml`, [docs/releasing.md](docs/releasing.md)).
+
+## Privacy
+
+The position history is personal data. It stays on your instance — nothing
+is transmitted anywhere — and is redacted from logs and diagnostics, but
+the default storage path lies under the Home Assistant configuration
+directory and is therefore part of your backups.
+
+## License
+
+BSD-3-Clause — see [LICENSE](LICENSE).

vledger-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+# One repository, two packages (ADR-0002): this file builds only the library.
+# The integration under custom_components/ is shipped by HACS and pins the
+# library by the same version number.
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vledger"
+version = "0.1.0"
+description = "Vehicle ledger: trips, charging, refuelling and cost, derived from a raw log of Home Assistant states"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Michael Lenz", email = "michael.lenz@nullvector.org" }]
+requires-python = ">=3.13"
+# No runtime dependencies, by requirement (CLI-06): the standard library is
+# the whole platform the library runs on.
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Home Automation",
+]
+
+[project.urls]
+Repository = "https://github.com/michael-lenz/ha-vledger"
+
+[project.scripts]
+vledger = "vledger.cli:main"
+
+[project.optional-dependencies]
+# Two extras on purpose: the library's own loop needs no Home Assistant
+# (ARC-03), and the HA test stack is heavy. Integration tests (QUA-02)
+# install both.
+dev = ["pytest", "pytest-asyncio", "ruff"]
+ha = ["pytest-homeassistant-custom-component"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+src = ["src", "tests", "custom_components"]

vledger-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vledger-0.1.0/src/vledger/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: BSD-3-Clause
+"""vledger — the vehicle ledger library.
+
+Everything the integration derives is derived here, and only here
+(ARC-02). The library knows nothing of Home Assistant (ARC-03) and depends
+on nothing outside the standard library (CLI-06).
+"""
+
+#: One version number for the library, the integration and the derivation
+#: logic recorded in L1 (ADR-0002, ABL-07). pyproject.toml and
+#: custom_components/vledger/manifest.json carry the same string; a test
+#: keeps the three in step.
+__version__ = "0.1.0"

vledger-0.1.0/src/vledger/cli.py

@@ -0,0 +1,255 @@
+# SPDX-License-Identifier: BSD-3-Clause
+"""The ``vledger`` command line.
+
+Every operation the library offers is a verb here, grouped by noun
+(ADR-0005): ``vledger l0 …`` for the raw log. A verb reads and writes the
+directory layout under ``--base`` and prints what it did. The library does
+the work; this module parses arguments and spells results.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from vledger import __version__, clock, l0
+from vledger.layout import Subject
+
+ENV_BASE = "VLEDGER_BASE"
+
+
+class Usage(Exception):
+    """A complaint about the arguments, printed without a traceback."""
+
+
+# --- shared pieces ---------------------------------------------------------
+
+def _subject(args) -> Subject:
+    if args.vehicle and args.chargepoint:
+        raise Usage("--vehicle and --chargepoint exclude each other")
+    if args.vehicle:
+        return Subject("vehicle", args.vehicle)
+    if args.chargepoint:
+        return Subject("chargepoint", args.chargepoint)
+    raise Usage("name the stream: --vehicle ID or --chargepoint ID")
+
+
+def _base(args) -> Path:
+    return Path(args.base or os.environ.get(ENV_BASE) or ".")
+
+
+def _t(args) -> str:
+    return args.t or clock.to_text(clock.now())
+
+
+def _json_arg(text: str):
+    """JSON from the argument itself, from a file, or from stdin (``-``)."""
+    if text == "-":
+        return json.load(sys.stdin)
+    p = Path(text)
+    if p.is_file():
+        return json.loads(p.read_text(encoding="utf-8"))
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        raise Usage(f"neither JSON, a file nor '-': {text!r}") from None
+
+
+def _kv(pairs: list[str]) -> dict:
+    out = {}
+    for pair in pairs or []:
+        if "=" not in pair:
+            raise Usage(f"expected key=value, got {pair!r}")
+        k, v = pair.split("=", 1)
+        try:
+            out[k] = json.loads(v)
+        except json.JSONDecodeError:
+            out[k] = v
+    return out
+
+
+def _add_stream_args(sp: argparse.ArgumentParser) -> None:
+    sp.add_argument("--base", help=f"the data directory (default: ${ENV_BASE} or .)")
+    g = sp.add_mutually_exclusive_group()
+    g.add_argument("--vehicle", metavar="ID", help="the vehicle's subject id")
+    g.add_argument("--chargepoint", metavar="ID", help="the charge point's subject id")
+
+
+def _add_t(sp: argparse.ArgumentParser) -> None:
+    sp.add_argument("--t", help="the event's time, UTC ISO 8601 (default: now)")
+
+
+# --- l0 verbs --------------------------------------------------------------
+
+def cmd_l0_state(args) -> int:
+    subject = _subject(args)
+    line = l0.state(_t(args), subject, args.role, args.entity, args.state,
+                    unit=args.unit, attrs=_kv(args.attr), measured_at=args.measured_at)
+    path = l0.append(_base(args), subject, line)
+    print(f"{path.name}: {l0.encode(line)}")
+    return 0
+
+
+def cmd_l0_start(args) -> int:
+    subject = _subject(args)
+    snapshot = _json_arg(args.snapshot) if args.snapshot else []
+    line = l0.start(_t(args), subject, vledger=args.vledger or __version__,
+                    homeassistant=args.homeassistant, snapshot=snapshot)
+    path = l0.append(_base(args), subject, line)
+    print(f"{path.name}: start, {len(snapshot)} role(s) in the snapshot")
+    return 0
+
+
+def cmd_l0_stop(args) -> int:
+    subject = _subject(args)
+    line = l0.stop(_t(args), subject, reason=args.reason)
+    path = l0.append(_base(args), subject, line)
+    print(f"{path.name}: stop ({args.reason})")
+    return 0
+
+
+def cmd_l0_heartbeat(args) -> int:
+    subject = _subject(args)
+    line = l0.heartbeat(_t(args), subject, lines=args.lines)
+    path = l0.append(_base(args), subject, line)
+    print(f"{path.name}: heartbeat, {args.lines} line(s) since start")
+    return 0
+
+
+def cmd_l0_config(args) -> int:
+    subject = _subject(args)
+    line = l0.config(_t(args), subject, config=_json_arg(args.config))
+    path = l0.append(_base(args), subject, line)
+    print(f"{path.name}: config, {len(line['config'])} key(s)")
+    return 0
+
+
+def cmd_l0_read(args) -> int:
+    n = 0
+    for r in l0.read(_base(args), _subject(args), kind=args.kind, role=args.role,
+                     since=args.since, until=args.until):
+        print(l0.encode(r.line))
+        n += 1
+    print(f"{n} line(s)", file=sys.stderr)
+    return 0
+
+
+def cmd_l0_validate(args) -> int:
+    report = l0.validate(_base(args), _subject(args))
+    if args.json:
+        print(json.dumps({
+            "files": report.files, "lines": report.lines, "by_kind": report.by_kind,
+            "versions": sorted(report.versions),
+            "problems": [p.__dict__ for p in report.problems],
+        }, indent=2))
+    else:
+        kinds = ", ".join(f"{k} {n}" for k, n in sorted(report.by_kind.items()))
+        versions = ", ".join(str(v) for v in sorted(report.versions)) or "none"
+        print(f"{report.files} file(s), {report.lines} line(s): {kinds or 'nothing'}")
+        print(f"schema version(s): {versions}")
+        for p in report.problems:
+            print(f"  [{p.severity}] {p.where}: {p.what}")
+        print(f"{report.errors} error(s), {len(report.problems) - report.errors} warning(s)")
+    return 1 if report.errors else 0
+
+
+def cmd_l0_gaps(args) -> int:
+    found = l0.gaps(_base(args), _subject(args), tolerance_s=args.tolerance,
+                    now=args.now, min_s=args.min)
+    if args.json:
+        print(json.dumps([g.__dict__ for g in found], indent=2))
+    else:
+        for g in found:
+            print(f"{g.start}  {g.end}  {g.seconds:10.0f} s  {g.reason}")
+        print(f"{len(found)} gap(s)", file=sys.stderr)
+    return 0
+
+
+# --- the parser ------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="vledger", description="The vehicle ledger")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    nouns = parser.add_subparsers(dest="noun", metavar="<noun>", required=True)
+
+    p_l0 = nouns.add_parser("l0", help="the raw log: write, read, validate, gaps")
+    verbs = p_l0.add_subparsers(dest="verb", metavar="<verb>", required=True)
+
+    sp = verbs.add_parser("state", help="append one state change")
+    _add_stream_args(sp)
+    _add_t(sp)
+    sp.add_argument("--role", required=True, choices=l0.ROLES)
+    sp.add_argument("--entity", required=True, help="the entity id")
+    sp.add_argument("--state", required=True, help="the state string, as Home Assistant holds it")
+    sp.add_argument("--unit", help="unit_of_measurement, when the entity has one")
+    sp.add_argument("--attr", action="append", metavar="KEY=VALUE",
+                    help="an attribute; only the role-relevant ones are kept")
+    sp.add_argument("--measured-at", help="the source's own measurement time, if it gives one")
+    sp.set_defaults(func=cmd_l0_state)
+
+    sp = verbs.add_parser("start", help="capture begins: write the start marker and snapshot")
+    _add_stream_args(sp)
+    _add_t(sp)
+    sp.add_argument("--vledger", help="library version (default: this one)")
+    sp.add_argument("--homeassistant", required=True, help="Home Assistant version")
+    sp.add_argument("--snapshot", help="JSON list of {role, entity, state, unit?, since}; "
+                                       "inline, a file, or - for stdin")
+    sp.set_defaults(func=cmd_l0_start)
+
+    sp = verbs.add_parser("stop", help="capture ends orderly: write the stop marker")
+    _add_stream_args(sp)
+    _add_t(sp)
+    sp.add_argument("--reason", required=True, choices=l0.STOP_REASONS)
+    sp.set_defaults(func=cmd_l0_stop)
+
+    sp = verbs.add_parser("heartbeat", help="write a heartbeat")
+    _add_stream_args(sp)
+    _add_t(sp)
+    sp.add_argument("--lines", type=int, required=True, help="state lines since start")
+    sp.set_defaults(func=cmd_l0_heartbeat)
+
+    sp = verbs.add_parser("config", help="write the subject's complete configuration")
+    _add_stream_args(sp)
+    _add_t(sp)
+    sp.add_argument("--config", required=True, help="JSON object; inline, a file, or - for stdin")
+    sp.set_defaults(func=cmd_l0_config)
+
+    sp = verbs.add_parser("read", help="print a stream as JSON Lines, in order")
+    _add_stream_args(sp)
+    sp.add_argument("--kind", choices=l0.KINDS)
+    sp.add_argument("--role", choices=l0.ROLES)
+    sp.add_argument("--since", help="first time to print, inclusive")
+    sp.add_argument("--until", help="last time to print, inclusive")
+    sp.set_defaults(func=cmd_l0_read)
+
+    sp = verbs.add_parser("validate", help="check a stream against the schema and report")
+    _add_stream_args(sp)
+    sp.add_argument("--json", action="store_true", help="the report as JSON")
+    sp.set_defaults(func=cmd_l0_validate)
+
+    sp = verbs.add_parser("gaps", help="list the capture gaps the markers reveal")
+    _add_stream_args(sp)
+    sp.add_argument("--tolerance", type=float, default=300,
+                    help="seconds a heartbeat may be late (default 300)")
+    sp.add_argument("--now", help="the time the stream is judged against (default: now)")
+    sp.add_argument("--min", type=float, default=0, help="shortest gap to list, seconds")
+    sp.add_argument("--json", action="store_true", help="the gaps as JSON")
+    sp.set_defaults(func=cmd_l0_gaps)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except (Usage, ValueError, TypeError, l0.TornLine, FileNotFoundError) as e:
+        print(f"vledger: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())