freeweight 1.0.0rc1__tar.gz

freeweight-1.0.0rc1/.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

freeweight-1.0.0rc1/.github/workflows/ci.yml

@@ -0,0 +1,199 @@
+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 -e ".[dev]"
+      - 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 -e ".[dev]"
+      - 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 -e ".[dev]"
+      - run: pytest -m "not live and not performance" --cov --cov-report=xml
+
+  postgresql-tests:
+    # Database standards §5.2: the migration suite runs on both supported dialects in CI, not
+    # just SQLite. FREEWEIGHT_REQUIRE_POSTGRES turns tests/integration/conftest.py's ordinary
+    # "skip if unreachable" behaviour into a failure here, so a broken service container fails
+    # the job instead of silently testing one dialect and calling it both.
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: freeweight
+          POSTGRES_PASSWORD: freeweight
+          POSTGRES_DB: freeweight_test
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      # Deliberately not the FREEWEIGHT_ prefix: tests/conftest.py strips those so no test reads
+      # the developer's environment, which would delete these before the fixture could read them.
+      FWTEST_REQUIRE_POSTGRES: "1"
+      FWTEST_POSTGRES_URL: postgresql+psycopg://freeweight:freeweight@localhost:5432/freeweight_test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      # pg_dump is what `freeweight db backup` shells out to on this dialect; without the client
+      # tools that branch skips itself and the job reports green having never run it.
+      - run: sudo apt-get update && sudo apt-get install -y postgresql-client
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not live and not performance" tests/integration
+
+  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" }
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not live and not performance"
+
+  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 -e ".[dev]"
+      - run: pytest -m "not live and not performance" --cov --cov-report=term-missing --cov-fail-under=85
+
+  diff-coverage:
+    # Testing standards §10 lists `diff-cover` among the gates required before merge: the
+    # repository-wide floor says nothing about whether *this change* was tested, and a large
+    # well-covered codebase absorbs an untested addition without the floor moving.
+    needs: [tests]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        # diff-cover compares against the merge base, so the base branch has to be in the object
+        # store; a depth-1 clone does not have it.
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not live and not performance" --cov --cov-report=xml
+      - run: diff-cover coverage.xml --compare-branch=origin/${{ github.base_ref }} --fail-under=90
+
+  contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -e ".[dev]"
+      - run: pytest -m contract
+
+  docs:
+    # Packaging standards §5's `docs` job: the generated documents must match what the code
+    # generates. `docs/configuration.md` is produced from the settings model (configuration
+    # standards §8) and `docs/openapi.json` from the served application (API standards §11); a
+    # field or a route changed without regenerating either fails here rather than drifting.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -e ".[dev]"
+      - run: python scripts/generate_config_reference.py --check
+      - run: python scripts/generate_openapi_snapshot.py --check
+
+  security:
+    # `pip-audit` audits the locked set, not the job's own environment: a bare `pip-audit` here
+    # inspects an environment containing only pip-audit itself and reports nothing (Security
+    # Standards §11). It audits `requirements/ci.lock` too once that file exists — it is blocked
+    # on `setspec 0.3.0` reaching PyPI, for the reason requirements/README.md gives.
+    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
+      - 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" }
+      # The same pinned build chain the release uses, so a wheel that builds here is the wheel
+      # that ships: `--no-isolation` takes the backend from this lock rather than re-resolving
+      # hatchling from the index at build time (requirements/README.md).
+      - 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 freeweight"

freeweight-1.0.0rc1/.github/workflows/nightly.yml

@@ -0,0 +1,41 @@
+# Testing Standards §10: the default suite runs on every push and must stay under three minutes,
+# so the two suites that cannot be fast run here instead — `live` needs real weights and `performance`
+# needs a machine whose timings mean something.
+#
+# On a GitHub-hosted runner the live suite **skips itself**: its provider fixture calls
+# `OllamaProvider.health()` and skips when nothing answers on 127.0.0.1:11434. That is deliberate
+# and is not a silent pass — the job prints the skip reasons with `-rs`, so "no Ollama here" is
+# visible rather than indistinguishable from "everything passed". Point a self-hosted runner with a
+# GPU at this workflow and the same job measures a real model.
+#
+# `performance` runs everywhere: its budgets are generous precisely so that shared CI hardware
+# produces information rather than flakes, and the query-plan assertions beside them are
+# hardware-independent.
+name: Nightly
+
+on:
+  schedule:
+    # 03:00 UTC — after any working day's pushes, before any working morning.
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+
+jobs:
+  performance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -e ".[dev]"
+      - run: pytest -m performance -rs
+
+  live:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -e ".[dev]"
+      # `-rs` reports every skip with its reason: a live suite that skipped because nothing was
+      # serving must not look like a live suite that passed.
+      - run: pytest -m live -rs

freeweight-1.0.0rc1/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+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:
+    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" }
+      # The pinned build chain, so the wheel that ships is built by the same backend CI checked:
+      # `--no-isolation` takes hatchling from this lock rather than re-resolving it at build time.
+      - 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, and
+    # `freeweight` is an unclaimed distribution name — v1.0.0rc1 is that first release, so run
+    # this once before tagging it. Later releases may skip it, or use it again as a dry run.
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    # No `environment:` here, matching the package repositories. The OIDC claim must match the
+    # trusted publisher exactly: declaring an environment the TestPyPI publisher was not
+    # configured with fails the exchange. Add one only alongside configuring it there.
+    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/

freeweight-1.0.0rc1/.gitignore

@@ -0,0 +1,100 @@
+# ---- 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

freeweight-1.0.0rc1/.gitleaks.toml

@@ -0,0 +1,38 @@
+# gitleaks configuration — see the `security` job in .github/workflows/ci.yml.
+#
+# The default rule set is kept in full. This file adds one allowlist and disables nothing: a rule
+# is never turned off, and a finding is never allowlisted by fingerprint, because a fingerprint
+# carries the commit SHA and stops matching the moment the file moves — which turns "a person
+# looked at this and it is not a secret" into a silently unscanned line later.
+
+title = "FreeWeight"
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "A metric key is vocabulary, not a credential."
+# `generic-api-key` fires on any `…key = <high-entropy value>` assignment, and this suite names
+# every measurement with a `metric_key` — 129 of them across 51 files, and one per new benchmark.
+# `inter_chunk_ms_p50` and `inter_chunk_ms_p95` clear the rule's entropy floor, so they are
+# reported as secrets; the rest are one lucky character away from joining them, which is why this
+# matches the *shape* of a metric key rather than listing the two names that happen to trip it
+# today.
+#
+# The scan is diff-scoped, so this fails only on a push whose commit touches one of those lines —
+# it has fired three times (a2a0ac5, 92f5602, e6d3c88, the last on the `key` → `metric_key`
+# rename) and passed on every commit that leaves them alone. A green run on an unrelated commit is
+# not evidence that it is fixed.
+#
+# What this permits is narrow: a `…key` field bound to a lowercase snake_case identifier, quoted
+# and ending the match. A real credential is excluded by any of the things it almost always has
+# and an identifier never does — an uppercase letter, a hyphen, a dot, a `+` or `/`, or no
+# underscore at all. Keywords other than `key` are untouched, so `password = "correct_horse_..."`
+# is still a finding.
+#
+# `regexTarget` must be `match`: in a history scan — the mode CI runs in — a finding's `line` is
+# empty, so an allowlist written against the source line matches nothing and silently does not
+# apply. The match text differs between the two modes as well (`metric_key="…"` scanning a working
+# tree, `key="…"` scanning a diff), so the pattern deliberately starts at `key`.
+regexTarget = "match"
+regexes = ['''key["']?\s*[:=]\s*["'][a-z][a-z0-9]*(?:_[a-z0-9]+)+["']$''']

freeweight-1.0.0rc1/.importlinter

@@ -0,0 +1,40 @@
+[importlinter]
+root_package = freeweight
+include_external_packages = True
+
+[importlinter:contract:layers]
+name = FreeWeight internal layering
+type = layers
+layers =
+    web
+    cli
+    services
+    domain
+containers = freeweight
+
+[importlinter:contract:web-cli-independence]
+name = Web and CLI never import each other
+type = independence
+modules =
+    freeweight.web
+    freeweight.cli
+
+[importlinter:contract:domain-purity]
+name = Domain imports no frameworks
+type = forbidden
+source_modules = freeweight.domain
+forbidden_modules =
+    fastapi
+    starlette
+    sqlalchemy
+    typer
+    httpx
+    jinja2
+
+[importlinter:contract:no-other-applications]
+name = FreeWeight must not import other applications
+type = forbidden
+source_modules = freeweight
+forbidden_modules =
+    loadcoach
+    ideapress

freeweight-1.0.0rc1/.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