v0.1.1 — Test pyramid, API contracts, docs site

v0.1.1 — Test pyramid, API contracts, docs site

Quality-and-contracts release. No CLI behaviour changes for v0.1 users; this is the foundation v0.2 and v0.3 will build on.

Test pyramid (43 → 103 tests, 87% coverage)

Layer	Count	Trigger
Unit	~43	every push
E2E (subprocess CLI, every role × format × command)	39	every push
Schema (every --format json output validates against its schema)	7	every push
Scale (10k / 50k / 100k receipts, time + RSS budgets)	3	RUN_SCALE=1 or weekly CI
Chaos (Hypothesis fuzz + I/O failure injection)	11	RUN_CHAOS=1 or weekly CI

Real bugs the new fuzz tests caught and fixed:

• ucid.py was leaking yaml.YAMLError on malformed registries — now wrapped in UcidError.
• bundle.py was leaking UnicodeDecodeError on binary input — now wrapped in BundleError for both NDJSON and JSON-array loaders.

API definition

• /schemas — JSON Schema 2020-12 for read, diff, and explain JSON outputs. The CLI and the planned v0.2 web view return the same shapes.
• docs/api/openapi.yaml — DRAFT OpenAPI 3.1 spec for the v0.2 web view (5 endpoints, references the schemas via $ref).
• docs/api/data-model.md, docs/api/actions.md (event-type × role-lens matrix), docs/api/flows.md (5 Mermaid sequence diagrams).

The spec ships as DRAFT so downstream tooling (Beacon, the planned GitHub Action in #3, dashboards) can begin generating clients against a stable contract before v0.2 is implemented.

Docs site

• mkdocs.yml — Material theme, mkdocstrings Python handler, Mermaid via pymdownx.
• docs/{index,cli,roadmap}.md plus docs/python/{bundle,render,ucid,cli}.md for auto-generated Python API reference.

Install with pip install -e ".[docs]" and run mkdocs serve.

CI

• Default job now runs unit + E2E + schema with --cov-fail-under=80.
• New nightly-scale-chaos job: workflow_dispatch + weekly Mon 08:00 UTC cron, runs the gated scale and chaos suites.

Refs

• v0.2 web viewer: #2
• v0.3 GitHub Action: #3

---

DCO-signed. Beacon signs. Lantern reads.