strathmark 2.0.0__tar.gz

strathmark-2.0.0/.gitattributes

@@ -0,0 +1,8 @@
+* text=auto eol=lf
+*.py text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.md text eol=lf
+*.txt text eol=lf
+*.json text eol=lf
+*.cfg text eol=lf

strathmark-2.0.0/.github/REPO_METADATA.md

@@ -0,0 +1,64 @@
+# GitHub Repository Metadata
+
+Paste the following into the repository **About** panel on GitHub
+(Settings tab is not required — use the cog icon next to *About* on the
+repo home page).
+
+## Repository description (one line, 350 char limit)
+
+> Woodchopping handicap engine — pip-installable calculation core for
+> timbersports tournaments. Computes Standing Block and Underhand marks
+> with a Manual > LLM > ML > Baseline > Panel cascade, 2-year time-decay
+> weighting, absolute ±3 s variance, and Monte Carlo fairness validation.
+> Extracted from STRATHEX.
+
+## Website
+
+```
+https://pypi.org/project/strathmark/
+```
+
+(leave blank until the first PyPI release; the source URL in
+`pyproject.toml` already points at the GitHub repo)
+
+## Topics / tags
+
+Apply these topic tags via the repo **About -> ⚙** settings. GitHub
+topics are lowercase, hyphen-separated, max 50 per repo. These are the
+tags that keep STRATHMARK discoverable to both the timbersports
+community and the Python/ML community:
+
+### Sport-domain tags
+
+- `timbersports`
+- `woodchopping`
+- `lumberjack`
+- `axemen`
+- `axe`
+- `chainsaw`
+- `tournament`
+- `handicap`
+- `handicapping`
+
+### Technical / discovery tags
+
+- `python`
+- `pandas`
+- `numpy`
+- `xgboost`
+- `machine-learning`
+- `monte-carlo`
+- `monte-carlo-simulation`
+- `fastapi`
+- `ollama`
+- `llm`
+- `sports-analytics`
+- `fairness`
+- `pip-package`
+- `calculation-engine`
+
+## Social preview image
+
+Use `assets/strathmark_logo.png` (already checked into the repo) as the
+social preview image under **Settings -> Social preview**. Recommended
+upload size is 1280x640; the current logo can be padded to that canvas.

strathmark-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,250 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Ruff check
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+  test:
+    name: Test (${{ matrix.os }} / Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+
+      - name: Check dependency consistency
+        run: pip check
+
+      - name: Run pytest with coverage
+        # Supabase-backed db tests are gated behind STRATHMARK_TEST_DB and
+        # skip by default. ML predictor paths fall back to baseline when
+        # xgboost/lightgbm/sklearn are not installed (they live in the [ml]
+        # extra and are not pulled in by [dev]).
+        run: pytest tests/ -v --tb=short --cov=strathmark --cov-report=term-missing
+
+  api:
+    name: API contract (${{ matrix.compatible-set }})
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        compatible-set: [oldest, current]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install oldest compatible API dependency set
+        if: matrix.compatible-set == 'oldest'
+        run: pip install -e ".[dev,api]" -r requirements/api-oldest.txt
+
+      - name: Install current compatible API dependency set
+        if: matrix.compatible-set == 'current'
+        run: pip install -e ".[dev,api]" -r requirements/api-current.txt
+
+      - name: Check dependency consistency
+        run: pip check
+
+      - name: Run API contract tests
+        run: pytest tests/test_api.py tests/test_shadow_api.py tests/test_shadow_consumer_contract.py -v --tb=short
+
+  optional-ml:
+    name: Optional ML artifact and promotion gates (Ubuntu / Python 3.12)
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package with optional ML dependencies
+        run: pip install -e ".[dev,ml]"
+
+      - name: Check dependency consistency
+        run: pip check
+
+      - name: Run residual artifact and temporal validation tests
+        run: pytest tests/test_residual.py tests/test_validation.py -v --tb=short
+
+  validation-artifact:
+    name: Verify Prediction V2 release evidence (Ubuntu / Python 3.12)
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install core validation dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Check dependency consistency
+        run: pip check
+
+      - name: Verify persisted report and checksummed artifact
+        run: python scripts/validate_v2.py --verify-release
+
+      - name: Exercise release-gate contracts
+        run: pytest tests/test_validate_v2.py tests/test_validation.py -v --tb=short
+
+      - name: Verify runtime provider loads the packaged core
+        run: python -c "from datetime import date; from strathmark.predictor import FilePredictionProvider; b=FilePredictionProvider().snapshot(date(2026,8,11)); assert b.core is not None and b.source == 'package' and b.core.model_version == 'prediction-v2-core-20260207'"
+
+  golden:
+    name: Prediction V2 golden (${{ matrix.os }} / Python 3.12)
+    runs-on: ${{ matrix.os }}
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install core test dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Check dependency consistency
+        run: pip check
+
+      - name: Verify normalized public audit output
+        run: python scripts/verify_v2_golden.py
+
+  optimizer-capacity:
+    name: Optimizer capacity (Ubuntu / Python 3.12)
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install core dependencies
+        run: pip install -e .
+
+      - name: Check dependency consistency
+        run: pip check
+
+      - name: Enforce 64-competitor optimizer budget
+        run: python scripts/benchmark_mark_optimizer.py --output optimizer-capacity-ci.json
+
+      - name: Upload capacity measurement
+        uses: actions/upload-artifact@v4
+        with:
+          name: optimizer-capacity-ubuntu-python312
+          path: optimizer-capacity-ci.json
+
+  postgres-migration-rehearsal:
+    name: Disposable PostgreSQL migration rehearsal
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:18
+        env:
+          POSTGRES_USER: rehearsal
+          POSTGRES_PASSWORD: rehearsal-ci-only
+          POSTGRES_DB: strathmark_rehearsal_controller
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U rehearsal -d strathmark_rehearsal_controller"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+    env:
+      STRATHMARK_RUN_POSTGRES_REHEARSAL: "1"
+      STRATHMARK_REHEARSAL_DSN: postgresql://rehearsal:rehearsal-ci-only@127.0.0.1:5432/strathmark_rehearsal_controller
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install test dependencies and PostgreSQL client
+        run: |
+          pip install -e ".[dev]"
+          sudo apt-get update
+          sudo apt-get install --yes postgresql-client
+
+      - name: Exercise migrations 005 and 006 against disposable PostgreSQL
+        run: pytest tests/test_postgres_rehearsal.py -v --tb=short
+
+  build:
+    name: Installed ${{ matrix.kind }} (${{ matrix.os }} / Python 3.12)
+    runs-on: ${{ matrix.os }}
+    needs: [lint, test, api, optional-ml, validation-artifact, golden, optimizer-capacity, postgres-migration-rehearsal]
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        kind: [wheel, sdist]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Verify installed distribution outside checkout
+        run: python scripts/smoke_installed_distribution.py --kind ${{ matrix.kind }}

strathmark-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+# Manual-only for now. Alex triggers releases from the Actions tab.
+# To enable automatic publishing on tag push, uncomment the `push` block.
+on:
+  workflow_dispatch:
+  # push:
+  #   tags:
+  #     - "v*"
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    # PyPI trusted publishing requires this environment to be configured
+    # in the repo settings AND a matching publisher to be registered on
+    # PyPI for the strathmark project. See:
+    #   https://docs.pypi.org/trusted-publishers/
+    # Until that is wired up, this workflow will fail at the upload step.
+    environment: pypi
+    permissions:
+      # Required for PyPI trusted publishing (OIDC token exchange)
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

strathmark-2.0.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+develop-eggs/
+.installed.cfg
+lib/
+lib64/
+
+# Virtual environments
+.env
+.venv
+.venv*/
+env/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Distribution
+*.whl
+*.tar.gz
+.gstack/
+
+# Local secrets (env-var exports for Supabase, etc.) — never commit
+STRATHMARK API.txt
+*.secrets.txt
+
+# Local agent / editor config (per-developer, not portfolio content)
+CLAUDE.md
+.claude/
+AGENTS.md

strathmark-2.0.0/CHANGELOG.md

@@ -0,0 +1,194 @@
+# Changelog
+
+All notable changes to STRATHMARK will be documented in this file.
+
+## [Unreleased]
+
+## [2.0.0] - 2026-08-18
+
+Prediction Engine V2 replaces the numeric Manual/LLM/ML/baseline cascade with one
+reproducible, prior-only prediction system while retaining the five legacy result keys
+for compatibility.
+
+### Hardening
+
+- Added adversarial causal and artifact validation, trusted-ledger admission and
+  interval-aware drift checks, bounded mirror delivery, optimizer oracle/capacity
+  evidence, and stronger package/release verification.
+- Drift coverage for V2 is measured from each settled prediction's issued interval;
+  residual-quantile reconstruction remains historical behavior only.
+- Reconciled the retired pre-2.0 ensemble TODOs and corrected rounded-gap wording to
+  the implemented half-to-even behavior.
+- Excluded undated calibration rows and numeric pseudo-dates, normalized equivalent
+  species/gender identities before idempotency hashing, and kept an intentionally
+  inactive optional residual from degrading the promoted core.
+- Made active-v2 cloud payloads version-explicit, restored overflow/restart outbox
+  recovery, added a historical health cutoff, and guarded the 005-to-006 deploy window
+  plus rollback.
+- Preserved the public fairness-simulation admission limit at 4,000,000 cells and
+  limited it to one concurrent request per process pending a bounded-batch simulator.
+- Added migration 007's versioned, append-only shadow mirror for immutable receipt
+  cores and eligible numeric settle/void revisions. The cloud copy remains optional,
+  non-authoritative, stable-ID-only, and excludes operational context and free text.
+  The RPC recomputes each delivery digest from an explicit JSON body, validates the
+  frozen nested receipt contract, and requires receipt prediction identities to exactly
+  match the embedded ledger without duplicates.
+- Published the STRATHEX 7 consumer migration contract and reconciled maintained
+  deployment, REST, architecture, installation, and wiki guidance.
+
+### Added
+
+- Robust hierarchical log-time core with event and diameter effects, six species
+  physical properties, gender/missingness, recency-weighted competitor state, bounded
+  trend, cross-event borrowing, and partial pooling for zero/sparse history.
+- Chronological split-conformal 90% prediction intervals with calibration state and
+  scope, kept separate from race-performance `std_dev`.
+- Safe checksummed JSON core artifact with its canonical species-property lookup,
+  packaged with the wheel and one immutable
+  `PredictionBundle` snapshot per request.
+- Optional CatBoost residual artifact and strict rolling-origin promotion gate. No
+  residual candidate is promoted in the 2.0.0 release.
+- Deterministic joint mark optimizer using 2,048 common-random samples, exhaustive
+  global search for tractable small fields, and at most eight coordinate passes for
+  larger fields, with a bounded rounded-gap fallback.
+- Append-only local SQLite prediction ledger, authenticated REST ledger routes,
+  immutable settlement revisions, a replayable sanitized mirror outbox, and optional
+  best-effort Supabase mirroring through migrations
+  `20260811_005_prediction_v2.sql` and `20260813_006_prediction_hash_algorithm.sql`.
+- Frozen release evidence and a verify-only operator command: `python train_model.py`.
+
+### Changed
+
+- Numeric evidence is now restricted to stable identity/history, event, strictly prior
+  dated results, diameter, species physical properties, and gender including missing.
+- `get_all_predictions()` maps `baseline` to the V2 core, `ml` to a promoted residual
+  only, `panel` to the broad fallback, and `llm` to `None`.
+- `HandicapCalculator.calculate()` snapshots the engine once and chooses marks jointly.
+- REST responses include interval, engine/model/calibration, warning, optimizer,
+  prediction-ID, degradation, and ledger-state fields.
+- Public `/calculate` and `/predict` remain stateless. Trusted writes use
+  `/ledger/calculate` and require stable IDs, bearer authentication, and `request_id`.
+
+### Retired
+
+- Numeric LLM generation, selection, and adjustment. LLMs remain available only for
+  narrative features.
+- Numeric use of division, round/heat, venue, lane/stand, run order, exact material
+  identity, wood quality/moisture, weather, equipment, fatigue, penalty/DNF state,
+  same-tournament weighting, and field strength. Legacy inputs remain accepted as
+  documented no-ops for one migration release.
+
+### Validation
+
+- Frozen 128-row temporal test: MAE 16.1301 vs 20.5172 for the strict prior-only
+  incumbent (21.38% lower); RMSE 33.6904 vs 44.4791 (24.26% lower); 90% interval
+  coverage 94.53%. These results apply only to the checked-in workbook and split;
+  cohort samples are smaller and no universal accuracy or fairness claim is made.
+
+### Migration
+
+- Default engine is V2. Set `STRATHMARK_PREDICTION_ENGINE=legacy` for the temporary,
+  deterministic baseline-only rollback. The rollback never invokes an LLM numerically.
+- See `docs/PREDICTION_ENGINE_V2.md` and `docs/DEPLOYMENT.md` before upgrading a live
+  consumer.
+
+## [1.0.0] - 2026-05-08
+
+First public PyPI release. No API changes relative to 0.5.0; the 1.0.0 designation marks publication readiness, not a redesign. The library has been production-tested for multiple seasons across STRATHEX and the Missoula Pro-Am tournament manager.
+
+### Added
+- PyPI distribution metadata: `Development Status :: 5 - Production/Stable`, `License :: OSI Approved :: Apache Software License`, `Operating System :: OS Independent`, and `Topic :: Software Development :: Libraries` classifiers.
+- `[project.urls]` entries for Homepage, Issues, Documentation, and Changelog (in addition to the existing Source URL).
+- Author email field in `[project.authors]`.
+- Lower bound on the `ollama` optional dependency (`ollama>=0.3`) in the `[llm]` extra; previously unconstrained.
+
+### Changed
+- Version bumped from 0.5.0 to 1.0.0 to mark the first stable PyPI release. `__version__` in `strathmark/__init__.py` updated to match.
+- README image and inter-doc links rewritten as absolute GitHub URLs (`https://raw.githubusercontent.com/.../main/...` for the logo, `https://github.com/SquirmyWormy275/STRATHMARK/blob/main/...` and `.../tree/main/...` for documents and directories) so they render correctly on the PyPI project page.
+- README test-count figure updated from 708 to 759 to match the current suite.
+- `.gitignore` virtual-environment block extended with `.venv*/` so per-purpose venvs (e.g. `.venv-pypi-readiness`) are ignored without relying on Python's venv-internal `.gitignore`.
+
+### Fixed
+- README "Usage" prose claimed `HandicapCalculator().calculate()` returns `CalculationResult` objects with a `gap` attribute. The actual return type is `MarkResult` (defined in `strathmark.calculator`) with fields `name`, `mark`, `predicted_time`, `method_used`, `confidence`, `explanation`, `std_dev`. README rewritten to match the real API. Discovered by running the README example against the built wheel.
+
+### Removed
+- Placeholder LinkedIn line in the README "About the author" section.
+
+## [0.5.0] - 2026-05-08
+
+### Added
+- MNEMEX integration: STRATHMARK Supabase becomes a hydrated cache of canonical results held in a separate MNEMEX project. Sync runs in dry-run mode until `MNEMEX_SUPABASE_URL`/`MNEMEX_SUPABASE_KEY` are configured.
+- `strathmark/mnemex.py` — read-only MNEMEX client plus competitor registration helper. Reads canonical results, looks up canonical competitors, mints new ones via ULID.
+- `strathmark/sync.py` — three sync paths sharing one upsert core: `nightly_batch()` (cron at 03:00 UTC), `strathex_finalization(event_id)` (webhook), `manual_force_sync(show_name=None, since=None)` (admin button / CLI). Failures raise after writing an audit-trail row to `sync_log`.
+- `strathmark/drift.py` — calibration drift detection. `evaluate_drift(model_version_id, lookback_days=30)` returns a `DriftReport` with mean-shift, variance-ratio, and empirical-coverage alerts. Advisory only; never auto-deactivates a model.
+- `strathmark/db.py` ML state writes: `register_model_version()`, `set_active_model()`, `record_calibration()`, `store_features()`, `record_prediction()`, `settle_prediction()`. Best-effort vs raise-on-failure discipline matches the policy doc.
+- `_BiasCircuitBreaker` in `strathmark/predictor.py` — 60-second sliding window, 3-strike threshold, auto-reset. Replaces the prior session-level disable so transient Supabase blips don't permanently degrade bias correction.
+- Three SQL migrations under `strathmark/migrations/`: `001` adds source-tracking columns (`source_type`, `mnemex_id`), `002` creates ML state tables (`model_versions`, `calibration_tables`, `feature_store`, `predictions`, `prediction_residuals` extensions), `003` reframes RLS for controlled-write enforcement (FORCE ROW LEVEL SECURITY plus a dedicated `mnemex_sync` role plumbing checklist).
+- `scripts/rekey_against_mnemex.py` — idempotent re-keying script that fills in `mnemex_id` on existing STRATHMARK competitor rows from MNEMEX. Refuses to commit below the 95% match-rate threshold without `--force`.
+- `docs/ml-persistence-policy.md` — policy doc covering retraining cadence, model versioning, calibration drift, feature store, hot-path circuit breaker, non-blocking guarantee.
+- `docs/schema-reality-2026-05-04.md`, `docs/cleanup-candidates-2026-05-04.md`, `docs/ml-research-questions.md` — Phase 1 schema verification plus a cleanup audit confirming zero stray validation rows.
+- 65 new tests across `tests/test_mnemex.py`, `tests/test_sync.py`, `tests/test_drift.py`, `tests/test_circuit_breaker.py`, `tests/test_ml_state.py`, plus 277 lines of additions to `tests/test_db.py`.
+
+### Changed
+- `register_competitor()` rewrite: routes through MNEMEX when configured, falls back to STRATHMARK-local mint with a deprecation warning when MNEMEX is unset. Default `wait_for_sync=False`; opting in to blocking requires explicit kwarg.
+- `get_competitor_bias()` no longer swallows DB exceptions internally. Callers on the prediction hot path wrap in `_BiasCircuitBreaker`; the policy is documented in `docs/ml-persistence-policy.md` section 5.
+- `_do_sync` writes a failure sync_log row before re-raising on Supabase upsert error, so the audit trail is preserved AND callers see a non-zero exit (matches the module docstring).
+- Added `ulid-py>=1.1` to base dependencies.
+
+### Fixed
+- Cascade naming mismatch: `record_prediction` validator and the `predictions_cascade_level_check` constraint now accept `'panel'` instead of `'panel_fallback'`, matching the canonical emitter strings in `strathmark/predictor.py`.
+- Drift detection's coverage rule now compares empirical coverage of recent residuals against a 90% prediction interval derived from baseline residual quantiles, replacing a check that compared the static calibration-time `coverage_at_90` value against a fixed band.
+- RLS migration `003` now adds `FORCE ROW LEVEL SECURITY` to all governed tables, closing the BYPASSRLS bypass on `service_role`. Pre-application checklist expanded to require role plumbing AND `NOBYPASSRLS` rotation. The `wood_species_write_admin` policy no longer ORs in `service_role` (contradicted the header's "wood_admin only" intent).
+
+## [0.4.1] - 2026-04-21
+
+### Added
+- `ONBOARDING.md` at repo root — routing hub for new contributors by task (bug fix, feature, deployment debug, AI agent)
+- 7 new learning docs in `docs/solutions/`:
+  - `best-practices/llm-cascade-and-monte-carlo-tuning-2026-04-21.md` — cross-cutting v0.3.0 hardening narrative
+  - `best-practices/optional-dependency-gating-importorskip.md` — `[extras]` split + `pytest.importorskip` placement gotcha
+  - `best-practices/config-env-vars-importlib-reload-pattern.md` — test pattern for import-time env vars
+  - `architecture-decisions/dual-store-sqlite-supabase-split.md` — offline-first rationale for SQLite + Supabase
+  - `architecture-decisions/ensemble-predictor-design-decisions.md` — accepted design + deferred scope for TODO-001..011
+  - `test-failures/regression-test-must-include-triggering-input.md` — Codex-caught regression-coverage pattern
+  - `workflow-patterns/eng-review-cycle-and-todos-handoff.md` — plan-review → TODOS.md → impl → Codex → ship pattern
+
+### Changed
+- `docs/solutions/architecture-decisions/prediction-cascade-order.md` — added v0.3.0 provenance for JSON-schema / temp=0 / quality==5, cross-link to new hardening doc, `last_updated: 2026-04-21`
+- `docs/solutions/architecture-decisions/mark-floor-ceiling-invariants.md` — added pre-v0.3.0 ceiling-rounding historical note, cross-link to new hardening doc, `last_updated: 2026-04-21`
+- `strathmark/__init__.py` — `__version__` corrected from `0.3.1` (stale) to `0.4.1`
+- `README.md` — version string updated to 0.4.1 and onboarding pointer added
+
+## [0.4.0] - 2026-04-07
+
+### Added
+- Gemini cloud fallback (`google-generativeai`) in `llm.py` as a race-day fail-through when Ollama is unreachable
+- `_env_int`/`_env_str` helpers in `config.py` for safe env-var parsing with sensible fallbacks
+- `scripts/validate_deployment.py` — pre-event read-only deployment validation
+- `scripts/ingest_proam_results.py` — post-event Pro-Am result ingestion with dry-run / --commit modes
+- `push_results_dicts()` and `register_competitor()` public helpers for programmatic ingestion
+- `docs/DEPLOYMENT.md` — full deployment guide
+- `tests/test_deployment_fallbacks.py` — fail-fast cascade tests for unreachable Ollama / Supabase
+
+### Changed
+- Race-day Ollama defaults: `TIMEOUT_SECONDS` and `MAX_RETRIES` now env-overridable via `STRATHMARK_OLLAMA_*`; default `MAX_RETRIES=0` for fail-fast cascade behavior
+- `STRATHMARK_OLLAMA_URL` / `STRATHMARK_OLLAMA_TIMEOUT` / `STRATHMARK_OLLAMA_MAX_RETRIES` now documented as first-class operational knobs
+
+### Fixed
+- Ollama cascade hang on unreachable host (120s blocking per call) — fail-fast via reduced timeout + zero retries
+- Ollama status cache race condition under concurrent FastAPI requests — `threading.Lock` protecting cache reads/writes
+- `LLMConfig` env-var resolution now happens at call time (via helpers) for hot-swappable values, while import-time frozen dataclass is retained for stable params
+
+## [0.3.1] - 2026-03-24
+
+### Added
+- 221 new tests across 9 test files, bringing total from 446 to 667
+- Regression tests for fixed bugs: banker's rounding, decay weights, timeout filtering, absolute variance, mark floor/ceiling enforcement
+- Boundary tests for extreme values: 50-competitor fields, diameters 50-600mm, quality clamping, consistency rating thresholds
+- Config invariant tests: frozen dataclass enforcement, rules consistency, threshold ordering, ML/LLM config sanity
+- Extended decay tests: exponential precision, date type handling, adaptive vs fixed weighting, robust MAD clipping
+- Extended store tests: CRUD, duplicate detection, DataFrame round-trips, column aliases, date handling
+- Extended visualization tests: ASCII bar chart accuracy, line width, percentage sums, large field rendering
+- Predictor regression tests: cascade priority, tournament weighting with num_tournament_rounds, division fallback
+- Full pipeline integration tests: predict-calculate-simulate round-trips, multi-event days, store round-trips, simulation determinism
+- Wood boundary tests: species multipliers, Janka hardness monotonicity, event scaling exponents

strathmark-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to STRATHMARK
+
+STRATHMARK is the shared handicap calculation core for STRATHEX,
+Missoula-Pro-Am-Manager, and any future tournament manager built on the
+same engine. Changes here propagate downstream, so the bar for tests and
+lint is intentionally strict.
+
+## Development install
+
+```bash
+pip install -e ".[dev]"
+```
+
+Optional extras you may also want while working on specific subsystems:
+
+- `pip install -e ".[ml]"` — XGBoost / LightGBM / scikit-learn predictor
+- `pip install -e ".[db]"` — Supabase backend
+- `pip install -e ".[api]"` — FastAPI server
+- `pip install -e ".[llm]"` — optional narrative-analysis client
+
+## Running the test suite
+
+```bash
+pytest tests/ -v
+```
+
+Supabase-backed db tests are gated behind `STRATHMARK_TEST_DB=1` and skip
+by default. ML predictor paths fall back to baseline when the `[ml]` extras
+are not installed, so you do not need them to get a green run. Install
+`.[dev,api]` to run the REST API contract tests locally.
+
+## Linting and formatting
+
+```bash
+ruff check .
+ruff format --check .
+```
+
+To auto-fix and apply formatting:
+
+```bash
+ruff check . --fix
+ruff format .
+```
+
+## CI
+
+GitHub Actions runs lint, the full test matrix (Ubuntu + Windows across
+Python 3.10 through 3.13), oldest/current API dependency contracts, release and
+cross-platform golden verification, the optimizer capacity gate, and isolated wheel
+and source-distribution installs. **All PRs must pass CI before merge.** The workflow
+definitions live under [`.github/workflows/`](.github/workflows/).
+
+## Design rules (non-negotiable)
+
+These are enforced in code and in review. See the README's *Design rules*
+section for the full list, but the load-bearing ones are:
+
+- Mark floor: 3 seconds
+- Mark ceiling: 183 seconds system-wide
+- Variance: performance uncertainty is represented in absolute seconds; proportional
+  scaling is only a clamped no-history fallback
+- Prediction engine: manual override, otherwise the validated V2 posterior with deterministic fallback
+- Output: plain text only, no emojis, no ANSI color codes