vesma-cortex 0.2.1__tar.gz

vesma_cortex-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,134 @@
+# Merge-gate CI (ADR 0003 R6): lint + test matrix + smoke + deterministic
+# model invariants. All four gate jobs (lint, test, smoke, eval-sanity)
+# must be marked required in branch protection.
+name: ci
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  # Cancel superseded runs on PRs only; runs on main always complete.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+      - name: ruff check + ruff format --check
+        run: make lint
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: test suite (default env, no torch)
+        run: make test
+
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+      - name: CPU smoke over the full D contour
+        run: make smoke
+
+  # Path filter: does this PR touch the model-relevant surface at all?
+  changes:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      model: ${{ steps.filter.outputs.model }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: dorny/paths-filter@v4
+        id: filter
+        with:
+          filters: |
+            model:
+              - 'src/**'
+              - 'models/**'
+              - 'scripts/gen_model_card.py'
+
+  # Deterministic invariants (eval-methodology #4, gate_contract.json):
+  # they block merge. Thresholds live in gate_contract.json whose sha256
+  # is pinned in eval-methodology #6 (anti-HARKing) — verified below.
+  eval-sanity:
+    needs: changes
+    if: needs.changes.outputs.model == 'true' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+
+      - name: gate_contract.json sha256 == pin in eval-methodology #6
+        shell: bash
+        run: |
+          set -euo pipefail
+          pinned=$(grep -oE '[0-9a-f]{64}' docs/specs/eval-methodology.md | head -1)
+          actual=$(sha256sum gate_contract.json | cut -d' ' -f1)
+          echo "pinned: $pinned"
+          echo "actual: $actual"
+          if [ -z "$pinned" ]; then
+            echo "::error::could not extract the gate contract pin from docs/specs/eval-methodology.md"
+            exit 1
+          fi
+          if [ "$pinned" != "$actual" ]; then
+            echo "::error::gate_contract.json sha256 diverges from the pin in docs/specs/eval-methodology.md #6 (anti-HARKing contract). Thresholds change only via a pre-registered addendum PR that updates the pin — never silently."
+            exit 1
+          fi
+
+      - name: adversarial sanity suite on the registry bundle
+        shell: bash
+        run: |
+          set -euo pipefail
+          uv run python scripts/eval_sanity_suite.py --bundle models/vesma-cortex-v1
+
+      # Lightweight review guard: every weights revision ships with its
+      # machine-readable eval report (ADR 0003). PR-only — on push to main
+      # the same check already passed on the PR.
+      - name: model.onnx changed -> eval-results.json must change too
+        if: github.event_name == 'pull_request'
+        shell: bash
+        run: |
+          set -euo pipefail
+          base=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
+          changed=$(git diff --name-only "$base" HEAD)
+          echo "$changed"
+          if echo "$changed" | grep -q '^models/vesma-cortex-v1/model\.onnx$'; then
+            if ! echo "$changed" | grep -q '^models/vesma-cortex-v1/eval-results\.json$'; then
+              echo "::error::model.onnx changed without an updated eval-results.json — every weights revision ships with its eval report (ADR 0003)."
+              exit 1
+            fi
+          fi

vesma_cortex-0.2.1/.github/workflows/nightly.yml

@@ -0,0 +1,31 @@
+# Nightly deep suite (ADR 0003 R6): full tests with the train extra
+# (CPU torch; N tests active) + the N-ladder smoke. One axis, Python 3.12.
+name: nightly
+
+on:
+  schedule:
+    - cron: "30 2 * * *" # 02:30 UTC daily
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: nightly-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  nightly:
+    runs-on: ubuntu-latest
+    # The CPU torch wheel is ~200 MB and the N ladder is slow — allow an hour.
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: full suite with the train extra (N tests active)
+        run: make test-train
+      - name: smoke with the N ladder end-to-end
+        run: make smoke-n

vesma_cortex-0.2.1/.github/workflows/release-model.yml

@@ -0,0 +1,230 @@
+# Model release train (ADR 0003 R5/R6): tag model-v1-<fp8> -> verify the
+# bundle (digest, sanity suite, pin drift) -> GitHub Release with assets
+# model.onnx, model.manifest.json, SHA256SUMS.txt.
+#
+# Freeze: no model-v* tags before 2026-10-16 (end of the B0 window) unless
+# the tag carries an explicit -emergency suffix (ADR 0003 R3).
+name: release-model
+
+on:
+  push:
+    tags: ["model-v1-*"]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    outputs:
+      pins-changed: ${{ steps.pins.outputs.changed }}
+    env:
+      # Pinned expectations for the current production revision (B1).
+      # Bump BOTH values in the same PR that lands the retrained bundle;
+      # any other drift routes the release through manual approval
+      # (environment model-release).
+      EXPECTED_FEATURE_SET_SHA256: dd86228f8c634f28d8a15b2d8279da1b99735d68e309be02d30f1c24698fa6af
+      EXPECTED_EMBEDDER_PIN: "nano:sha256:3b752e0671a50da5c108cb50e49630a66c160f7683afedcf879e1880d84317ba"
+    steps:
+      # On a tag push this checks out the tagged commit.
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+
+      - name: freeze guard (B0 window, ADR 0003 R3)
+        shell: bash
+        run: |
+          set -euo pipefail
+          # epoch of 2026-10-16T00:00:00Z — end of the B0 telemetry window
+          freeze_epoch=1792108800
+          now=$(date -u +%s)
+          if [ "$now" -lt "$freeze_epoch" ] && [[ "${GITHUB_REF_NAME}" != *-emergency ]]; then
+            echo "::error::model-v* tags are FROZEN until 2026-10-16 (end of the B0 window, ADR 0003 R3)."
+            echo "::error::For a genuine field incident, re-tag with an explicit -emergency suffix (model-v1-<fp8>-emergency) and page the owner."
+            exit 1
+          fi
+          echo "freeze check: OK (now=$(date -u +%Y-%m-%dT%H:%M:%SZ))"
+
+      - name: bundle integrity — sha256(model.onnx) == manifest sha256
+        shell: bash
+        run: |
+          set -euo pipefail
+          python3 - <<'EOF'
+          import hashlib
+          import json
+          import pathlib
+          import sys
+
+          bundle = pathlib.Path("models/vesma-cortex-v1")
+          manifest = json.loads((bundle / "manifest.json").read_text())
+          actual = hashlib.sha256((bundle / "model.onnx").read_bytes()).hexdigest()
+          if manifest.get("sha256") != actual:
+              sys.exit(f"::error::digest mismatch: manifest sha256={manifest.get('sha256')} actual={actual}")
+          print(f"bundle integrity OK: {actual}")
+          EOF
+
+      - name: adversarial sanity suite on the tagged bundle
+        shell: bash
+        run: |
+          set -euo pipefail
+          uv run python scripts/eval_sanity_suite.py --bundle models/vesma-cortex-v1
+
+      # Hard fail: manifest and eval report are two views of ONE revision —
+      # they must agree. Soft route (manual approval): pins drifted from the
+      # expectations pinned in this workflow (feature_set_sha256 growth is a
+      # model-vN line event, ADR 0003 R3).
+      - name: pin consistency and drift check
+        id: pins
+        shell: bash
+        run: |
+          set -euo pipefail
+          set +e
+          python3 - <<'EOF'
+          import json
+          import os
+          import pathlib
+          import sys
+
+          bundle = pathlib.Path("models/vesma-cortex-v1")
+          manifest = json.loads((bundle / "manifest.json").read_text())
+          report = json.loads((bundle / "eval-results.json").read_text())
+
+          prov = report["provenance"]
+          if manifest["embedder_pin"] != prov.get("embedder_pin"):
+              sys.exit("::error::manifest.json and eval-results.json disagree on embedder_pin")
+          if manifest["feature_set_sha256"] != report["artifact"].get("feature_set_sha256"):
+              sys.exit("::error::manifest.json and eval-results.json disagree on feature_set_sha256")
+
+          changed = (
+              manifest["embedder_pin"] != os.environ["EXPECTED_EMBEDDER_PIN"]
+              or manifest["feature_set_sha256"] != os.environ["EXPECTED_FEATURE_SET_SHA256"]
+          )
+          sys.exit(42 if changed else 0)
+          EOF
+          rc=$?
+          set -e
+          if [ "$rc" -eq 0 ]; then
+            changed=false
+            echo "pins: consistent with pinned expectations"
+          elif [ "$rc" -eq 42 ]; then
+            changed=true
+            echo "::warning::embedder_pin/feature_set_sha256 drifted from pinned expectations — the release now requires explicit manual approval via the model-release environment."
+          else
+            exit "$rc"
+          fi
+          echo "changed=$changed" >> "$GITHUB_OUTPUT"
+
+      # Prepare everything the release job needs: staged assets (registry
+      # asset names, model-registry.md #1), SHA256SUMS over the staged names,
+      # and human-readable notes generated from eval-results.json.
+      - name: stage assets and generate release notes
+        shell: bash
+        run: |
+          set -euo pipefail
+          stage=release-stage
+          mkdir -p "$stage"
+          cp models/vesma-cortex-v1/model.onnx "$stage/model.onnx"
+          cp models/vesma-cortex-v1/manifest.json "$stage/model.manifest.json"
+          (cd "$stage" && sha256sum model.onnx model.manifest.json > SHA256SUMS.txt)
+          python3 - <<'EOF'
+          import json
+          import os
+          import pathlib
+
+          report = json.loads(pathlib.Path("models/vesma-cortex-v1/eval-results.json").read_text())
+          art = report["artifact"]
+          b = report["layers"]["B_calibration"]
+          prov = report["provenance"]
+          fp8 = art["weights_sha256"][:8]
+          repo = os.environ["GITHUB_REPOSITORY"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          report_url = f"https://github.com/{repo}/blob/{tag}/{b.get('report_ref', 'docs/experiments/')}"
+
+          notes = f"""# vesma-cortex model revision `{art['revision']}` ({fp8})
+
+          - decision: **{report['decision']}**
+          - candidate: `{art['candidate']}`
+          - weights sha256: `{art['weights_sha256']}`
+          - embedder_pin: `{prov['embedder_pin']}`
+          - trained_at: {prov['trained_at']}
+          - train corpus fingerprint: `{prov['train_corpus_fingerprint']}`
+          - gate contract sha256: `{report['gate_contract_sha256']}`
+
+          ## Calibration (Layer B, holdout single-shot)
+
+          | metric | value |
+          |---|---|
+          | corpus | {b.get('corpus', 'NO-DATA')} |
+          | balanced accuracy | {b.get('ba')} (baseline {b.get('baseline_ba')}) |
+          | sensitivity / specificity | {b.get('sensitivity')} / {b.get('specificity')} |
+          | Brier | {b.get('brier')} |
+          | typed output | {b.get('typed')} |
+
+          Calibration report: {report_url}
+          """
+          pathlib.Path("release-stage/notes.md").write_text(notes)
+          EOF
+          cat release-stage/notes.md
+          cat release-stage/SHA256SUMS.txt
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: release-bundle
+          path: release-stage/
+
+  # Pins unchanged: publish straight away.
+  release:
+    needs: verify
+    if: needs.verify.outputs.pins-changed == 'false'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: release-bundle
+          path: release-stage/
+      - name: create GitHub release
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          gh release create "${GITHUB_REF_NAME}" \
+            --title "vesma-cortex model ${GITHUB_REF_NAME}" \
+            --notes-file release-stage/notes.md \
+            release-stage/model.onnx \
+            release-stage/model.manifest.json \
+            release-stage/SHA256SUMS.txt
+
+  # Pins changed (embedder_pin or feature_set): the same release, but gated
+  # on an explicit manual approval in the model-release environment
+  # (required reviewer = owner).
+  release-reviewed:
+    needs: verify
+    if: needs.verify.outputs.pins-changed == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: model-release
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: release-bundle
+          path: release-stage/
+      - name: create GitHub release (manually approved)
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          gh release create "${GITHUB_REF_NAME}" \
+            --title "vesma-cortex model ${GITHUB_REF_NAME}" \
+            --notes-file release-stage/notes.md \
+            release-stage/model.onnx \
+            release-stage/model.manifest.json \
+            release-stage/SHA256SUMS.txt

vesma_cortex-0.2.1/.github/workflows/release-py.yml

@@ -0,0 +1,143 @@
+# Package release train (ADR 0003 R5/R6): tag py-vX.Y.Z -> build (version
+# assert, twine check, privacy check on dist archives) -> full test suite
+# on the tag -> publish to PyPI via trusted publishing (OIDC, NO API token
+# stored in GitHub).
+name: release-py
+
+on:
+  push:
+    tags: ["py-v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+
+      - name: assert pyproject version == tag (py-vX.Y.Z)
+        shell: bash
+        run: |
+          set -euo pipefail
+          expected="${GITHUB_REF_NAME#py-v}"
+          actual=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "tag version: $expected | pyproject version: $actual"
+          if [ "$expected" != "$actual" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} does not match pyproject.toml version ${actual} — cut the tag from a commit where both agree."
+            exit 1
+          fi
+
+      - name: build sdist and wheel
+        run: uv build
+
+      - name: twine check
+        run: uvx twine@7.0.0 check dist/*
+
+      # Privacy gate (charter §6, ADR 0003 R2; MR-1 lesson: hatchling's VCS
+      # pass misses root-anchored patterns). Match EXACT top-level directory
+      # segments of each dist archive: `data/` or `datasets/` at the top
+      # level must never ship; the library package `src/cortex/data/` is
+      # contract code and is allowed.
+      - name: privacy check — no training-side top-level dirs in dist
+        shell: bash
+        run: |
+          set -euo pipefail
+          python3 - <<'EOF'
+          import pathlib
+          import sys
+          import tarfile
+          import zipfile
+
+          forbidden = {"data", "datasets"}
+          failures = []
+
+          def top_dirs(names: list[str], strip_root: bool) -> set[str]:
+              tops = set()
+              for name in names:
+                  parts = name.split("/")
+                  if strip_root:  # sdist members start with <pkg>-<ver>/
+                      parts = parts[1:]
+                  if len(parts) >= 2 and parts[0]:
+                      tops.add(parts[0])
+              return tops
+
+          for archive in sorted(pathlib.Path("dist").iterdir()):
+              if archive.name.endswith(".tar.gz"):
+                  with tarfile.open(archive) as tf:
+                      tops = top_dirs(tf.getnames(), strip_root=True)
+              elif archive.name.endswith(".whl"):
+                  with zipfile.ZipFile(archive) as zf:
+                      tops = top_dirs(zf.namelist(), strip_root=False)
+              else:
+                  continue
+              leaked = tops & forbidden
+              print(f"{archive.name}: top-level dirs = {sorted(tops)}")
+              if leaked:
+                  failures.append(f"{archive.name}: leaked top-level dirs {sorted(leaked)}")
+
+          # Product requirement (0.2.0+): the wheel ships the model bundle.
+          with zipfile.ZipFile(next(pathlib.Path("dist").glob("*.whl"))) as zf:
+              names = set(zf.namelist())
+          for required in (
+              "cortex/models/vesma-cortex-v1/model.onnx",
+              "cortex/models/vesma-cortex-v1/manifest.json",
+          ):
+              if required not in names:
+                  failures.append(f"wheel is missing the model bundle file {required}")
+
+          if failures:
+              for failure in failures:
+                  print(f"::error::{failure}")
+              sys.exit(1)
+          print("privacy check OK: no data/ or datasets/ at dist top level; wheel carries the model bundle")
+          EOF
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  # Full suite re-run on the exact tag ref before anything is published.
+  test:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: make test
+
+  publish:
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      # Trusted publishing: short-lived OIDC token minted by GitHub, accepted
+      # by PyPI when the project's "trusted publisher" lists this repo +
+      # workflow + environment. NO PyPI API token is stored anywhere here.
+      id-token: write
+      contents: read
+    steps:
+      # Local fallback (owner-only, when trusted publishing is unavailable):
+      # from a host checkout of the tag run
+      #   uv build && uvx twine check dist/*
+      #   uvx twine upload --non-interactive --repository pypi dist/*
+      # authenticating via the API token kept ONLY in the host secrets store
+      # (~/.secrets). Never paste token values into this file, CI logs, or
+      # shell history.
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: publish to PyPI (trusted publishing, OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1

vesma_cortex-0.2.1/.gitignore

@@ -0,0 +1,41 @@
+# Data hygiene: no raw store content ever enters this repo (charter §6).
+# Root-anchored on purpose: a bare "data/" pattern would also ignore
+# src/cortex/data/ — the fingerprints/holdout CONTRACT code (A3a lesson).
+/data/
+*.db
+/datasets/*
+# Layer A frozen eval sets (eval-methodology §3; ADR 0003 R2: synthetic
+# probe content is committable — no store lines, fingerprinted). The
+# corpus-v4 authored batches ride the same rule (wave D4-1: synthetic,
+# fingerprinted, disjointness-tested). The rest of datasets/ stays closed.
+# Negations sit AFTER the blocking pattern (same idiom as models/ below).
+!/datasets/evalsets/
+!/datasets/evalsets/**
+!/datasets/corpus-v4/
+!/datasets/corpus-v4/**
+# Near-miss watchlist registry (la4: synthetic eval-surface provenance
+# summaries only — no store lines, same ADR 0003 R2 rule as evalsets).
+!/datasets/watchlist/
+!/datasets/watchlist/**
+/artifacts/weights/
+*.pt
+*.onnx
+*.safetensors
+
+# Model registry (ADR 0003): weights of ARTIFACT revisions are tracked
+# under models/ — the canonical artifact lives in git (HF-style, ~98 KB,
+# no LFS needed). Training-side weights above stay ignored. Negations sit
+# AFTER the blocking patterns to re-include the registry bundles.
+!models/
+!models/**
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+
+# Local env / scratch
+.local/
+.env

vesma_cortex-0.2.1/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/#semantic-versioning).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-06
+
+### Added
+
+- **Zoned monotonicity v2 in the evalsets gate** (PR #19, la4): the runner
+  now applies the ratified zoned rule (gate_contract v3 `monotonicity_v2`) —
+  the razor zone (0.95, 1.0) is two-valued, steps starting strictly above its
+  low edge are not asserted, outside the zone the non-increase holds.
+  Single source for the edge constant (`RAZOR_ZONE_COS_LOW` shared with the
+  sanity suite); `REPORT_SCHEMA_VERSION` 1 -> 2 (monotonicity detail
+  semantics changed).
+- **Near-0009 watchlist module** (`cortex.data.watchlist`, PR #19, la4):
+  near-miss observation quota per the calibration-b2p prereg §9 (SCOLET) and
+  the evalsets manifest; documented in the la4 zone-rule addenda.
+
+### Fixed
+
+- **sdist privacy gate pruned recursively** (PR #18): hatchling's bare
+  directory patterns (`/datasets`) match the directory entry but do not
+  prune its children — the 0.2.0 sdist leaked `datasets/` (22 files, the
+  training corpus). All four exclude patterns now carry explicit `/**`
+  forms. Root cause is the same as the earlier `data/stage2-dry` leak.
+  (ADR 0003 R2: training-side data never ship.)
+
+### Packaging
+
+- 0.2.0 shipped on PyPI as a **wheel-only** release: the sdist was caught by
+  the release-engineer privacy check (datasets leak above) and was never
+  published. 0.2.1 restores the full wheel + sdist pair from the clean
+  build with the recursive gate in place.
+
+## [0.2.0] - 2026-10-05
+
+Initial PyPI release (wheel-only; see the sdist note under 0.2.1).
+Decision-model development library: pair features, D/N training, selection,
+ONNX export, single-shot eval, machine bundle registry
+(`cortex/models/vesma-cortex-v1/`).
+
+[Unreleased]: https://github.com/vesmaro/vesma-cortex/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/vesmaro/vesma-cortex/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/vesmaro/vesma-cortex/releases/tag/v0.2.0