From 34a722cf6126b4c07f9decbac12d3c7f7d88a8fd Mon Sep 17 00:00:00 2001 From: Daniel Ari Friedman Date: Thu, 12 Nov 2026 03:30:30 -0800 Subject: [PATCH 1/7] docs(gnn): record where the pin and conformance job live --- .github/GNN.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 .github/GNN.md diff --git a/.github/GNN.md b/.github/GNN.md new file mode 100644 index 0000000..ce59bf2 --- /dev/null +++ b/.github/GNN.md @@ -0,0 +1,17 @@ +# GNN conformance + +`gnn conformance (pinned)` is defined in `.github/workflows/ci.yml` and reads +`specs/gnn-pin.json`, which pins +`ActiveInferenceInstitute/Generalized_Notation_Notation` at `v5.0.3` +(`8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1`) and records SHA-256 digests for +the five parser files under `src/gnn/`. + +The job installs that commit into a separate runtime, then runs +`python scripts/validate_gnn_spec.py --gnn-runtime --json` and checks +that the resolved `gnn.__version__` matches the pin tag. The validator verifies +the installed parser file digests, parses `specs/gridworld_3x3.gnn.md` with the +pinned `MarkdownGNNParser`, and compares the declared parameters and the `A`, +`B`, `C`, `D`, and `E` matrices against the runtime model built by +`blockference.gnn`; it also requires the pinned semantic validator, the +B-orientation check, and the consistency checker to report no errors or +warnings. It does not scan the rest of the repository for `*.gnn.md`. From d2f947dd8054c80da63b35911ca28639f8990520 Mon Sep 17 00:00:00 2001 From: Daniel Ari Friedman Date: Thu, 12 Nov 2026 05:15:08 -0800 Subject: [PATCH 2/7] gate: add composable arms, generated metrics, and fast selection --- .github/workflows/ci.yml | 59 ++-- docs/_generated/README.md | 12 + docs/_generated/gate-metrics.md | 44 +++ docs/_generated/gate-timings.json | 86 +++++ docs/_generated/manuscript-variables.json | 25 ++ pyproject.toml | 3 +- scripts/build_manuscript.py | 113 ++++++- scripts/gate_metrics.py | 167 ++++++++++ scripts/manuscript_variables.py | 128 ++++++++ scripts/release_check.py | 383 +++++++++++++++++----- scripts/validate_manuscript.py | 25 +- tests/test_cli.py | 2 + tests/test_notebooks.py | 3 + tests/test_pipeline_real.py | 3 + tests/test_publication.py | 3 + 15 files changed, 957 insertions(+), 99 deletions(-) create mode 100644 docs/_generated/README.md create mode 100644 docs/_generated/gate-metrics.md create mode 100644 docs/_generated/gate-timings.json create mode 100644 docs/_generated/manuscript-variables.json create mode 100644 scripts/gate_metrics.py create mode 100644 scripts/manuscript_variables.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6beb28f..7341525 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -41,11 +41,8 @@ jobs: - name: Install locked package and development dependencies run: uv sync --locked --extra dev --python ${{ matrix.python-version }} - - name: Run canonical release gate - run: uv run python scripts/release_check.py - - - name: Type-check the package against Python 3.11 stubs - run: uv run mypy --python-version 3.11 blockference + - name: Full test arm (coverage floor) + run: uv run python scripts/release_check.py --arm test-full - name: Upload coverage if: matrix.python-version == '3.11' @@ -55,6 +52,36 @@ jobs: path: coverage.xml if-no-files-found: ignore + gate: + timeout-minutes: 60 + # Lint, types, docs, manuscript, smoke, and package work runs once; the + # test matrix above repeats only the suite across supported Python versions. + name: gate (lint, types, docs, manuscript, smoke, package) + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install uv + # v10.3.3; setup-uv publishes no floating v10 major tag, so @v10 is unresolvable + uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 + with: + version: "0.13.7" + enable-cache: true + cache-dependency-glob: "uv.lock" + + - name: Set up Python 3.12 + run: uv python install 3.12 + + - name: Install locked package and development dependencies + run: uv sync --locked --extra dev --python 3.12 + + - name: Run the release arms + run: >- + uv run python scripts/release_check.py + --arm lint --arm types --arm docs --arm manuscript + --arm smoke --arm package + gnn-conformance: timeout-minutes: 120 # Validates the committed GNN specification with the parser pinned in @@ -79,10 +106,11 @@ jobs: - name: Set up Python 3.12 run: uv python install 3.12 - - name: Install locked package and development dependencies - run: uv sync --locked --extra dev --python 3.12 + - name: Install locked package without development extras + run: uv sync --locked --python 3.12 - name: Provision the pinned GNN parser runtime + id: runtime run: | set -euo pipefail PIN=specs/gnn-pin.json @@ -93,17 +121,10 @@ jobs: # The install follows specs/gnn-pin.json; a pin bump re-points it. uv pip install --python "$RUNNER_TEMP/gnn-runtime/bin/python" \ "generalized-notation-notation @ git+${REPO}@${COMMIT}" + echo "python=$RUNNER_TEMP/gnn-runtime/bin/python" >> "$GITHUB_OUTPUT" - - name: Validate the GNN specification against the pinned parser + - name: GNN conformance arm run: >- - uv run python scripts/validate_gnn_spec.py - --gnn-runtime "$RUNNER_TEMP/gnn-runtime/bin/python" --json - - - name: Report the resolved GNN version - run: | - PIN=specs/gnn-pin.json - VERSION=$("$RUNNER_TEMP/gnn-runtime/bin/python" -c 'import gnn; print(gnn.__version__)') - TAG=$(python3 -c "import json;print(json.load(open('$PIN'))['tag'])") - test -n "$VERSION" - test "$VERSION" = "${TAG#v}" - echo "gnn-version=${VERSION}" >> "$GITHUB_STEP_SUMMARY" + uv run python scripts/release_check.py + --arm gnn --gnn-runtime "${{ steps.runtime.outputs.python }}" + --require-gnn diff --git a/docs/_generated/README.md b/docs/_generated/README.md new file mode 100644 index 0000000..85e1c13 --- /dev/null +++ b/docs/_generated/README.md @@ -0,0 +1,12 @@ +# `docs/_generated/` + +Generated documentation. Every file here is written by a named script and +checked by a gate arm; do not edit these files by hand. + +| File | Producer | Check | +| --- | --- | --- | +| [`gate-metrics.md`](gate-metrics.md) | `scripts/gate_metrics.py` from [`gate-timings.json`](gate-timings.json) | `scripts/release_check.py --arm docs` | +| [`manuscript-variables.json`](manuscript-variables.json) | `scripts/manuscript_variables.py` | `scripts/release_check.py --arm manuscript` | + +`gate-timings.json` is a recorded receipt from one `--timings` run of the gate; +it is evidence for the measured numbers, not a claim about another host. diff --git a/docs/_generated/gate-metrics.md b/docs/_generated/gate-metrics.md new file mode 100644 index 0000000..399a4bf --- /dev/null +++ b/docs/_generated/gate-metrics.md @@ -0,0 +1,44 @@ +# Gate metrics + + + +Measured numbers from one recorded run of the canonical gate on `macOS-27.0.1-arm64-arm-64bit` with Python 3.12.16 at `2026-11-12T13:09:06Z`. + +Refresh with: + +```bash +uv run python scripts/release_check.py --arm all --arm test \ + --timings docs/_generated/gate-timings.json +uv run python scripts/gate_metrics.py +``` + +## Arm wall times + +| Arm | Wall seconds | Status | First command | +| --- | --- | --- | --- | +| `lint` | 0.07 | passed | `uv run ruff check blockference tests GRTs scripts` | +| `types` | 0.35 | passed | `uv run mypy blockference` | +| `test` | 12.88 | passed | `uv run pytest -m not slow` | +| `test-full` | 58.06 | passed | `uv run pytest --cov=blockference --cov-report=term --cov-report=xml --cov-fail-under=90` | +| `docs` | 11.02 | passed | `uv run python scripts/check_docs_links.py` | +| `manuscript` | 7.84 | passed | `uv run python scripts/manuscript_variables.py --check` | +| `gnn` | 5.61 | passed | `uv run python scripts/export_gnn_spec.py --check` | +| `smoke` | 5.23 | passed | `uv run blockference pipeline --config configs/smoke.yml --output-root /var/folders/qs/rxkntx5d4hlgz0c7x8v15gym0000gn/T/activeblockference-gate-avw6d67s/output --run-name gate_smoke` | +| `package` | 12.91 | passed | `uv build` | +| `render` | not recorded | — | — | + +## Test selection + +| Selection | Collected tests | +| --- | --- | +| full suite | 85 | +| fast (`-m "not slow"`) | 72 | +| slow (`-m slow`) | 13 | + +Recorded run: 85 passed, 0 skipped. + +`test-full` recorded 90.94% line coverage of `blockference` (floor 90%). + +## Receipt + +The source of these numbers is [`gate-timings.json`](gate-timings.json), written by `scripts/release_check.py --timings`. An arm absent from that receipt is reported as not recorded, never as passing. diff --git a/docs/_generated/gate-timings.json b/docs/_generated/gate-timings.json new file mode 100644 index 0000000..2bbdbd4 --- /dev/null +++ b/docs/_generated/gate-timings.json @@ -0,0 +1,86 @@ +{ + "arms": { + "docs": { + "commands": [ + "uv run python scripts/check_docs_links.py", + "uv run python scripts/gate_metrics.py --check" + ], + "seconds": 11.02, + "status": "passed" + }, + "gnn": { + "commands": [ + "uv run python scripts/export_gnn_spec.py --check", + "uv run python scripts/validate_gnn_spec.py --json" + ], + "seconds": 5.61, + "status": "passed" + }, + "lint": { + "commands": [ + "uv run ruff check blockference tests GRTs scripts" + ], + "seconds": 0.07, + "status": "passed" + }, + "manuscript": { + "commands": [ + "uv run python scripts/manuscript_variables.py --check", + "uv run python scripts/validate_manuscript.py", + "uv run python scripts/build_manuscript.py", + "uv run python scripts/build_manuscript.py --check" + ], + "seconds": 7.84, + "status": "passed" + }, + "package": { + "commands": [ + "uv build", + "uv venv --python /Users/friedman/Documents/Git/gitvault/Username/ActiveInferenceInstitute/Public/ActiveBlockference/.venv/bin/python /var/folders/qs/rxkntx5d4hlgz0c7x8v15gym0000gn/T/activeblockference-package-fn41c71n/venv", + "uv pip install --python /var/folders/qs/rxkntx5d4hlgz0c7x8v15gym0000gn/T/activeblockference-package-fn41c71n/venv/bin/python /Users/friedman/Documents/Git/gitvault/Username/ActiveInferenceInstitute/Public/ActiveBlockference/dist/active_blockference-1.0.0-py3-none-any.whl", + "/var/folders/qs/rxkntx5d4hlgz0c7x8v15gym0000gn/T/activeblockference-package-fn41c71n/venv/bin/python -c from blockference import GridWorld; assert GridWorld(2, {'agent': (0, 0)}).current_state == {'agent': (0, 0)}" + ], + "seconds": 12.91, + "status": "passed" + }, + "smoke": { + "commands": [ + "uv run blockference pipeline --config configs/smoke.yml --output-root /var/folders/qs/rxkntx5d4hlgz0c7x8v15gym0000gn/T/activeblockference-gate-avw6d67s/output --run-name gate_smoke", + "uv run blockference validation --run-dir /var/folders/qs/rxkntx5d4hlgz0c7x8v15gym0000gn/T/activeblockference-gate-avw6d67s/output/gate_smoke", + "uv run blockference run --config configs/smoke.yml --output /var/folders/qs/rxkntx5d4hlgz0c7x8v15gym0000gn/T/activeblockference-gate-avw6d67s/run.csv" + ], + "seconds": 5.23, + "status": "passed" + }, + "test": { + "commands": [ + "uv run pytest -m not slow" + ], + "seconds": 12.88, + "status": "passed" + }, + "test-full": { + "commands": [ + "uv run pytest --cov=blockference --cov-report=term --cov-report=xml --cov-fail-under=90" + ], + "seconds": 58.06, + "status": "passed" + }, + "types": { + "commands": [ + "uv run mypy blockference" + ], + "seconds": 0.35, + "status": "passed" + } + }, + "generated": "2026-11-12T13:09:06Z", + "host": "macOS-27.0.1-arm64-arm-64bit", + "python": "3.12.16", + "schema": "activeblockference-gate/v1", + "tests": { + "coverage_percent": 90.94, + "passed": 85, + "skipped": 0 + } +} diff --git a/docs/_generated/manuscript-variables.json b/docs/_generated/manuscript-variables.json new file mode 100644 index 0000000..ca3b579 --- /dev/null +++ b/docs/_generated/manuscript-variables.json @@ -0,0 +1,25 @@ +{ + "gate_entry_point": "scripts/release_check.py", + "gnn_commit": "8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1", + "gnn_job_key": "gnn-conformance", + "gnn_job_name": "gnn conformance (pinned)", + "gnn_pin_path": "specs/gnn-pin.json", + "gnn_pin_schema": "gnn-importer-pin/v1", + "gnn_repository": "https://github.com/ActiveInferenceInstitute/Generalized_Notation_Notation", + "gnn_tag": "v5.0.3", + "package_version": "1.0.0", + "python_requires": "3.11+", + "schema": "manuscript-variables/v1", + "sources": { + "gate_entry_point": "scripts/release_check.py", + "gnn_commit": "specs/gnn-pin.json commit", + "gnn_job_key": ".github/workflows/ci.yml GNN job key", + "gnn_job_name": ".github/workflows/ci.yml GNN job name", + "gnn_pin_path": "specs/gnn-pin.json", + "gnn_pin_schema": "specs/gnn-pin.json schema", + "gnn_repository": "specs/gnn-pin.json repository", + "gnn_tag": "specs/gnn-pin.json tag", + "package_version": "pyproject.toml [project].version", + "python_requires": "pyproject.toml [project].requires-python" + } +} diff --git a/pyproject.toml b/pyproject.toml index d84adb0..8cf1ca7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -86,6 +86,7 @@ testpaths = ["tests"] addopts = "-ra --strict-markers" markers = [ "gnn: requires the pinned GNN parser runtime (GNN_ROOT or GNN_RUNTIME_PYTHON)", + "slow: excluded from the fast gate arm (notebook execution, real-pipeline, CLI, and figure-byte checks)", ] filterwarnings = [ "ignore::DeprecationWarning", @@ -102,7 +103,7 @@ select = ["E", "F", "W", "I", "B", "UP"] ignore = ["E501"] [tool.mypy] -python_version = "3.12" +python_version = "3.11" ignore_missing_imports = true disable_error_code = ["import-untyped"] check_untyped_defs = true diff --git a/scripts/build_manuscript.py b/scripts/build_manuscript.py index 7988c8e..2d23e23 100644 --- a/scripts/build_manuscript.py +++ b/scripts/build_manuscript.py @@ -11,9 +11,11 @@ import argparse import ast +import json import os import re import shutil +import subprocess import sys from collections import defaultdict from pathlib import Path @@ -26,6 +28,9 @@ MANUSCRIPT_DIR = REPO_ROOT / "docs" / "manuscript" BUILD_DIR = REPO_ROOT / "docs" / "_build" / "manuscript" FIGURE_DIR = MANUSCRIPT_DIR / "figures" +VARIABLES_PATH = REPO_ROOT / "docs" / "_generated" / "manuscript-variables.json" + +TOKEN_RE = re.compile(r"\{\{(?P[A-Za-z_][A-Za-z0-9_]*)\}\}") LABEL_RE = re.compile(r"#(?Peq|def|prop|alg|fig|tbl|sec):(?P