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.

v0.1.0-alpha — CLI scaffold (read, diff, explain)

AIGovOps Lantern v0.1.0-alpha — first cut of the CLI

Lantern is the human-readable companion to AIGovOps Beacon. Beacon signs evidence bundles; Lantern reads them.

This first alpha ships the CLI scaffold so engineers, compliance, auditors, and regulators can all open a Beacon bundle and get the same facts in the language they care about.

What's in the box

Three commands:

• lantern read BUNDLE — render a Beacon NDJSON/JSONL evidence bundle as a human summary
• lantern diff OLD NEW — compare two bundles with a role-targeted narrative of what changed
• lantern explain UCID — look up a Unified Control ID against the umbrella-govops registry

Four role lenses (--role):

• engineer — gate.failed callouts, unsigned receipts, CI signal
• compliance — UCID-mapping reminders, control coverage
• auditor — evidence completeness, signature presence, chain-of-custody hints
• regulator — plain-language framework crosswalk

Three output formats (--format):

• text — Rich panel for terminals
• markdown — drop straight into a PR comment
• json — machine readable for downstream tooling

Quality

• 43 tests passing, 89% coverage
• ruff clean, mypy --strict clean
• CI matrix on Python 3.11 and 3.12 (Node 24 runtime)
• Apache-2.0, DCO sign-off enforced
• Fixtures use real Beacon sample receipts (scoring/sample_receipts.ndjson) so the renderer stays faithful to the on-the-wire OVERT 1.0 envelope

Install

pip install git+https://github.com/bobrapp/aigovops-lantern.git@v0.1.0-alpha
lantern --version

What this is not (yet)

• No web viewer — that's v0.2
• No GitHub Action wrapper — that's v0.3
• No i18n — that's v1.0
• No cryptographic verification — that's Beacon's job; Lantern reports signature presence only

Trademark

AIGovOps Lantern™ is a common-law trademark of the AIGovOps Foundation. The bare word "Lantern" is not a Foundation mark; always use the compound form. See TRADEMARK.md in umbrella-govops.

Thanks

Built alongside aigovops-beacon and umbrella-govops. Issues and PRs welcome.