loadledger 0.1.0__tar.gz

loadledger-0.1.0/.editorconfig

@@ -0,0 +1,23 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+indent_size = 4
+max_line_length = 100
+
+[*.{toml,yml,yaml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+max_line_length = off
+
+[Makefile]
+indent_style = tab

loadledger-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,167 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install ruff
+      - run: ruff format --check .
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install ruff
+      - run: ruff check .
+
+  types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: mypy src tests
+
+  boundaries:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: lint-imports
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python-version }}" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m "not live and not performance" --cov --cov-report=xml
+
+  tests-314-early-warning:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.14" }
+      # Deliberately unpinned: ci.lock is resolved on 3.13, and pinning a version that has no
+      # 3.14 wheels would defeat the purpose of an early warning.
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not live and not performance"
+
+  db-matrix:
+    name: tests (PostgreSQL)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        # Credentials and database name match `DEFAULT_POSTGRES_URL` in tests/conftest.py, so the
+        # service this job starts is the one the integration tests look for.
+        env:
+          POSTGRES_USER: loadledger
+          POSTGRES_PASSWORD: loadledger
+          POSTGRES_DB: loadledger_test
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U loadledger -d loadledger_test" --health-interval 5s --health-timeout 5s --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m "not live and not performance" tests/integration
+        env:
+          # Without this the PostgreSQL legs would *skip* here exactly as they do on a developer's
+          # machine, and the job would go green having tested one dialect twice. A skipped dialect
+          # is an untested dialect.
+          LOADLEDGER_REQUIRE_POSTGRES: "1"
+          # The tests read LOADLEDGER_POSTGRES_URL, not DATABASE_URL. Set explicitly rather than
+          # relying on the default, so the job states which server it is testing.
+          LOADLEDGER_POSTGRES_URL: postgresql+psycopg://loadledger:loadledger@localhost:5432/loadledger_test
+
+  coverage:
+    needs: [tests]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m "not live and not performance" --cov --cov-report=term-missing --cov-fail-under=95
+
+  contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m contract
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        # gitleaks scans *history*, and `actions/checkout` fetches a single commit by default.
+        # For a push it is handed `<first-pushed>^..<last-pushed>`, so the parent of the first
+        # pushed commit has to be in the object store; in a depth-1 clone it is not, and git
+        # answers "unknown revision", which the action reports as exit code 1. It fails the same
+        # way whether or not a secret exists, so a green run would not have meant anything either.
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install pip-audit
+      # Audit the locked sets, not the job's own environment: a bare `pip-audit` here would
+      # inspect an environment containing only pip-audit itself (Security Standards §11).
+      - run: pip-audit --require-hashes -r requirements/ci.lock
+      - run: pip-audit --require-hashes -r requirements/release.lock
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+
+  install-check:
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - run: pip install dist/*.whl
+      - run: python -c "import loadledger"

loadledger-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+  workflow_dispatch:   # manual TestPyPI dry run; see publish-testpypi below
+
+permissions:
+  id-token: write   # required for PyPI Trusted Publishing
+  contents: write   # required to create the GitHub release
+
+jobs:
+  release:
+    # Tag pushes only. Without this, clicking "Run workflow" for the TestPyPI dry run below would
+    # also fire this job and publish to real PyPI — the exact opposite of a dry run.
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment: pypi   # must match the Environment name set on the PyPI trusted publisher
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      # Byte-for-byte the dry run's build chain below. A real release that resolved `build` and
+      # `hatchling` fresh from PyPI would not be the artifact the dry run proved.
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - run: pip install "dist/$(ls dist | grep .whl)[dev]"
+      - run: pytest -m "not live and not performance"
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+  publish-testpypi:
+    # Manual only, via Actions -> Release -> Run workflow. Packaging and Release Standards §6
+    # requires a successful TestPyPI publish ahead of a package's first real release; 0.1.0 is
+    # this package's first published version, so run this once before tagging v0.1.0. Later
+    # releases may skip it, or use it again as a dry run.
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - run: pip install "dist/$(ls dist | grep .whl)[dev]"
+      - run: pytest -m "not live and not performance"
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

loadledger-0.1.0/.gitignore

@@ -0,0 +1,104 @@
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# ---- Packaging / build backends ----
+pip-wheel-metadata/
+share/python-wheels/
+
+# ---- Testing / coverage ----
+.pytest_cache/
+.cache
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+*.py,cover
+htmlcov/
+nosetests.xml
+.hypothesis/
+
+# ---- Type checking / linting ----
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.pytype/
+
+# ---- Virtual environments ----
+.venv/
+venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+.python-version
+
+# ---- Distribution / dependency locking ----
+# requirements/*.lock is deliberately NOT ignored. The lock files are committed
+# inputs: CI and release jobs install from them with --require-hashes (Packaging
+# and Release Standards §4, Security Standards §11), so an ignored lock file
+# means a checkout that cannot build.
+
+# ---- Editors / OS ----
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ---- Suite runtime state (this component's local data) ----
+# The application writes to XDG paths at runtime (~/.config, ~/.local/share,
+# ~/.local/state per Master Architecture §1.2), never inside the repository.
+# These entries only guard against a developer pointing XDG_* at the repo
+# during local testing.
+.local/
+.config/
+*.sqlite3
+*.sqlite3-journal
+*.sqlite3-wal
+*.sqlite3-shm
+/data/
+/logs/
+/backups/
+/artifacts/
+/exports/
+
+# ---- Secrets ----
+# Per Security Standards §8: secrets are never committed. Config files may
+# only name where a secret comes from (*_env / *_file), never the value.
+.env
+.env.*
+*.key
+*.pem
+secrets.toml
+
+# ---- Node-free JS assets (MirrorWall consumers may still use a local tool) ----
+node_modules/
+
+# ---- Build artifacts from docs generation ----
+docs/api/openapi-v1.json.tmp
+
+# ---- import-linter cache ----
+# `lint-imports` writes this on every gate run; it is a cache, never an input.
+.import_linter_cache/

loadledger-0.1.0/.importlinter

@@ -0,0 +1,51 @@
+[importlinter]
+root_package = loadledger
+include_external_packages = True
+
+[importlinter:contract:no-application-imports]
+name = LoadLedger must not import applications
+type = forbidden
+source_modules = loadledger
+forbidden_modules =
+    freeweight
+    loadcoach
+    ideapress
+    promptcadence
+
+# `commissioner` was called `spotcheck` until py/Commissioner's rename (7077cc4). Both spellings
+# are listed: a forbidden module that no longer exists forbids nothing, silently, so dropping the
+# old name would quietly stop guarding against an import written before the rename.
+[importlinter:contract:no-sibling-packages]
+name = LoadLedger must not import sibling capability packages
+type = forbidden
+source_modules = loadledger
+forbidden_modules =
+    setspec
+    modelrack
+    sweatmeter
+    weightsdb
+    mirrorwall
+    cutctx
+    toolyard
+    commissioner
+    spotcheck
+
+# Replaces `no-sql-in-phase-1`, which forbade `sqlalchemy` outright while `loadledger.sql` did not
+# exist. Same rule, with the one exemption Phase 2 earned, and it is the mechanical statement of
+# ADR-0050 decision 4: `sqlalchemy` is an optional extra (`loadledger[sql]`) so the pure-value core
+# stays installable with nothing but baseaicore. Weakening this contract — or deleting it, which
+# looks identical in a diff — makes `pip install loadledger` drag an ORM into every consumer that
+# only wanted to add up tokens.
+#
+# `alembic` has no exemption at all: the host owns every migration (ADR-0050 decision 5), so no
+# module in this package imports it, `loadledger.sql` included. It is a test dependency for the
+# miniature host and never a runtime one.
+[importlinter:contract:only-the-sql-module-imports-sqlalchemy]
+name = Only loadledger.sql may import SQLAlchemy, and nothing may import Alembic
+type = forbidden
+source_modules = loadledger
+forbidden_modules =
+    sqlalchemy
+    alembic
+ignore_imports =
+    loadledger.sql -> sqlalchemy

loadledger-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.4
+    hooks:
+      - id: gitleaks

loadledger-0.1.0/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to `loadledger` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
+[Semantic Versioning](https://semver.org/), pre-1.0 per
+packaging and release standards §3.
+
+## [0.1.0] — 2026-09-02
+
+### Added
+- Repository scaffold: toolchain copied from `py/WeightsDB` (hatchling, ruff, mypy strict,
+  import-linter, pytest with `pytest-randomly`, hash-pinned `requirements/` locks, CI and release
+  workflows), with the PostgreSQL matrix job dropped — this package touches no database.
+- Phase 1, the pure core: `CeilingScope`, `BudgetCeiling`, `Debit`, `CeilingVerdict`,
+  `LedgerEntry`, the `Ledger` protocol, `BalanceBook`, `InMemoryLedger`, `utc_day_start`,
+  `utc_day_key`, and the `LedgerError` / `CurrencyMismatch` / `InvalidCeiling` / `UnknownRun`
+  hierarchy. No I/O, no SQL, no logging, no environment reads.
+- `CeilingVerdict.unpriced_debit_count` and `CeilingVerdict.unmetered_debit_count`, beyond the
+  shape in spec §7: contract 2 requires the unpriced count to ride on the money verdict, and the
+  same honesty is owed to the token balance when a provider leaves a token class unreported.
+- `Ledger.declare_run`, beyond the protocol in spec §7: spec §13 defines a run as existing "once
+  debited **or declared**", and §7 gave no way to declare one.
+- `as_canonical()` on `BudgetCeiling`, `Debit`, `CeilingVerdict` and `LedgerEntry`, following
+  BaseAiCore's own pattern — spec contract 4 requires byte-identical verdict serializations, and
+  `baseaicore.canonical_json` needs a mapping form to produce them. `Debit.as_canonical` omits
+  the cost deliberately: usage and `pricing_hash` are the stored facts (ADR-0030 rule 1).
+- `PartialPricing` and the keyword-only `BudgetCeiling.partial_pricing` (default `FLOOR`;
+  `STRICT` requires a money bound, else `InvalidCeiling`), and `CeilingVerdict.untotalled_debit_count`
+  — the subset of the unpriced count that carried an estimate which did not total, which is what
+  a strict ceiling fires on. Both appear in the canonical forms, so the goldens changed (ADR-0069).
+
+### Changed
+- A debit whose estimate did not total now accumulates the components that *were* priced into the
+  money balance as a floor, instead of adding nothing (ADR-0069, reversing spec contract 2 as
+  first written). On a floor, `exceeded` is certain when `True` and not when `False`; a `STRICT`
+  ceiling treats an untotalled estimate in its window as exceeding, at pre-flight too. A debit
+  with no estimate still touches no money balance, and never trips a strict ceiling.
+
+- Phase 2, the durable half: `loadledger.sql` under the new `loadledger[sql]` extra (ADR-0050).
+  - `mount_ledger_tables(metadata, *, prefix="ledger_") -> LedgerTables` adds four tables —
+    `ledger_entries`, `ledger_balances`, `ledger_balance_money`, `ledger_runs` — to an
+    application's own `MetaData`, so they appear in the application's own Alembic autogenerate and
+    the application owns the rows, the backups and the retention. The package owns no engine, no
+    session, no URL, no environment variable, no file and no migration history; `create_all`
+    appears nowhere in `src/`, and nothing is created on import.
+  - `SqlLedger(session_factory, ceilings, *, clock, table_prefix="ledger_")` implements the whole
+    `Ledger` protocol, `declare_run` included, over one injected session factory. It evaluates
+    through the same `BalanceBook` as `InMemoryLedger`, so the arithmetic and the honesty rules
+    have one implementation and not one per backend.
+  - `LedgerTables`, a frozen handle with `prefix`, `entries`, `balances`, `balance_money`, `runs`,
+    `metadata` and `all_tables`.
+  - `UnsupportedDialect` (`LEDGER_UNSUPPORTED_DIALECT`): ADR-0006 admits SQLite and PostgreSQL, and
+    a third dialect is refused at the first statement rather than found as a syntax error inside a
+    money transaction. Now in spec §7's error list and §13's table.
+  - `loadledger.core` gains the seams a durable ledger needs, all documented: `DebitContribution`,
+    `contribution_of`, `BalanceBook.windows_touched` / `window_for` / `seed`, `resolved_debit` and
+    `is_unpriced`. The package's top-level `__all__` is unchanged.
+- `docs/quickstart.md` and the standalone `docs/quickstart.py` it publishes the output of (spec §20
+  acceptance criterion 2), with a test that runs the script so it cannot rot.
+- `docs/mounted-table-upgrades.md`: the upgrade-note template and migration recipe LoadLedger ships
+  when a mounted table changes shape, since the host owns every migration (spec §19, ADR-0050
+  decision 5), with one worked example.
+- CI gains a `db-matrix` job running the integration tests against PostgreSQL 16 with
+  `LOADLEDGER_REQUIRE_POSTGRES=1`, so a dialect cannot be skipped into a green run.
+
+### Changed
+- `.importlinter`'s `no-sql-in-phase-1` is **replaced** by
+  `only-the-sql-module-imports-sqlalchemy`: same forbidden modules, one ignored import for
+  `loadledger.sql -> sqlalchemy`, and no exemption at all for `alembic`. The `no-sibling-packages`
+  contract's `spotcheck` entry gains `commissioner`, the package's name since `7077cc4`; the old
+  spelling is kept, because a forbidden module that no longer exists forbids nothing.
+- `pytest` `addopts` gains `-ra`, so a skipped PostgreSQL leg always names itself in the summary.
+
+### Specification
+- Spec §7, §10, §11, §13 and §15 were amended to describe what Phase 2 built, and the amendments
+  were accepted before release:
+  - §7 gains `LedgerTables`'s field list and `UnsupportedDialect`, and states what a durable
+    ledger's `entries()` returns.
+  - §10 names the four mounted tables and their keys, says why money is a table rather than a
+    column, and makes the `BigInteger` width part of the mounted contract.
+  - §11 contract 1 states that a durable ledger does not persist the `CostEstimate` — the one
+    place a consumer swapping `InMemoryLedger` for `SqlLedger` sees a difference.
+  - §13 gains rows for the prefix `ValueError` and for `UnsupportedDialect`.
+  - §15's single `entries` budget is split: for `SqlLedger` on SQLite, the query is ≤ 100 ms and
+    full materialization ≤ 250 ms. `InMemoryLedger` keeps ≤ 100 ms. The old single figure was set
+    before `SqlLedger` existed and was never about constructing ten thousand value objects.
+
+### Performance, as measured
+- `debit` with three ceilings ~1.5 ms (budget 5 ms) and flat as history grows — balances are
+  maintained, not recomputed. `would_exceed` ~0.4 ms (budget 2 ms). `entries` over a 10 000-entry
+  run: ~17 ms for the query (budget 100 ms), ~155 ms fully materialized (budget 250 ms). All
+  inside the amended §15.

loadledger-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to LoadLedger
+
+This repository is one component of the Local AI Suite. Before changing anything, read
+`docs/packages/loadledger/spec.md` and the current
+phase in `development-plan.md` — both are in this repository's `docs/` folder, copied from the suite's
+central documentation set so this repository can be worked on independently.
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+```
+
+## Required reading, in order
+
+1. This component's spec — purpose, scope, non-goals, contracts.
+2. `development-plan.md` in the same folder — the phase you are implementing, its acceptance criteria and its tests.
+
+## Rules that apply to every change here
+
+* Follow the architecture's dependency direction.
+  This repository's `.importlinter` enforces it in CI; do not weaken that file to make an import work.
+* No business logic in a route handler or CLI command body — both call one service method and render
+.
+* An unavailable measurement is `Unsupported`, never zero, never `None` used as a substitute
+.
+* Prompts are versioned JSON records, not Python string literals.
+* Every phase's acceptance criteria in `development-plan.md` must be demonstrable, not merely
+  test-covered — the plan states what to run and what a person should see.
+
+## Before opening a pull request
+
+```bash
+ruff format --check .
+ruff check .
+mypy src tests
+lint-imports
+pytest -m "not live and not performance"
+```
+
+All of the above run in CI (`.github/workflows/ci.yml`); a red CI run blocks merge.
+
+## Commit style
+
+Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `perf:`, `build:`,
+`ci:`), with `!` or a `BREAKING CHANGE:` footer for breaking changes. Update `CHANGELOG.md` under
+`## [Unreleased]` for any user-visible change.