Architecture

Package layout

repairledger/
  __init__.py        Package version
  constants.py       Shared constants and enums
  errors.py          Structured error types
  models.py          Dataclass models (Workspace, Repair, ComponentSpec)
  identity.py        ID formatting, ref derivation, selector normalization
  storage.py         Filesystem operations, CRUD, version snapshots
  guardrails.py      Validation for observed status
  render.py          Markdown rendering of repair artifacts
  report.py          Aggregate report generation
  bundle.py          Structured JSON bundle create/update
  cli.py             Typer CLI definition
  launcher.py        Entry point

Module dependencies

launcher → cli → { bundle, render, report, storage }
storage → { identity, constants, errors, models, guardrails }
bundle → { storage, identity, constants, errors }
render → { storage, identity, constants }
report → { storage, identity, constants }
identity → { constants } (via ledgercore refs)

Key design decisions

Flat package layout: No src/ directory. Package is directly under repo root.
Dynamic versioning: Via setuptools_scm from Git tags.
Atomic writes: All file mutations use ledgercore.atomic helpers.
Version snapshots: Complete post-mutation copies under versions/v000X/.
Derived refs: Global and file refs are generated at render time, not stored.
ledgercore integration: Uses ledgercore for atomic I/O, YAML, ref parsing, timestamps, and hashing.