Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ contains only Python 3.11 and runs `--arm test-full`. The `gnn-conformance` job
(display name `gnn conformance (pinned)`) runs `--arm all`
on Python 3.12 with `GNN_RUNTIME_PYTHON` set to the separate runtime provisioned from `specs/gnn-pin.json`.
There is no separate `gate` job. Pinned conformance always runs in the `gnn`
arm; missing runtime dependencies must fail, never skip. PDF rendering remains
arm, where the shared `python -m gnn.importers check --repo .` reads the pin and
the pointer; missing runtime dependencies must fail, never skip. PDF rendering remains
an explicit local `--arm render` selection. The workflow uses pinned
`astral-sh/setup-uv` directly, not the Institute composite; see
[`../docs/gate.md`](../docs/gate.md) for the exact action and command map.
Expand Down
13 changes: 9 additions & 4 deletions .github/GNN.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,19 @@
`gnn conformance (pinned)` is the display name of job `gnn-conformance` in
`.github/workflows/ci.yml`. It reads `specs/gnn-pin.json` (schema
`gnn-importer-pin/v1`), which pins
`ActiveInferenceInstitute/Generalized_Notation_Notation` at `v5.0.3`
(`8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1`) and records SHA-256 digests for
`ActiveInferenceInstitute/Generalized_Notation_Notation` at `v5.1.0`
(`75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf`) and records SHA-256 digests for
the five parser files under `src/gnn/`.

The job installs that commit into a separate Python 3.12 runtime, then invokes
the canonical release gate with `--arm all` and `GNN_RUNTIME_PYTHON` set to that runtime. Its `gnn`
arm always performs both the offline drift check and real pinned validation;
a missing runtime fails instead of skipping conformance. See
arm runs the estate's shared reader,
`python -m gnn.importers check --repo . --require-pointer --workflow
.github/workflows/ci.yml --job gnn-conformance`, from that runtime, then the
offline drift check and the deep pinned-parser conformance check. The reader
owns pin discovery and validation, and reports a pointer that fails to name the
pin file, the pinned revision, the workflow or the job. A missing runtime
fails instead of skipping conformance. See
[`docs/gate.md`](../docs/gate.md) for the complete job and arm map, and
[`docs/gnn.md`](../docs/gnn.md) for standalone validation commands.

Expand Down
3 changes: 2 additions & 1 deletion .github/workflows/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ release gate in two jobs:

The second job retains the display name `gnn conformance (pinned)` and installs
the revision in [`../../specs/gnn-pin.json`](../../specs/gnn-pin.json) into a
separate runtime. The full suite runs on both Python versions; all other release
separate runtime; its `gnn` arm then calls the shared
`python -m gnn.importers check --repo .` from that runtime. The full suite runs on both Python versions; all other release
arms run with conformance on Python 3.12. Missing pinned-runtime validation
fails the gate. There is no separate `gate` job, and PDF rendering remains an
explicit local arm.
Expand Down
12 changes: 8 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,9 @@ jobs:
# Validates the committed GNN specification with the parser pinned in
# specs/gnn-pin.json. The pinned revision is installed into a separate runtime
# because the GNN distribution requires numpy>=2 while this package
# resolves numpy 1.x; the validator verifies the installed parser file
# digests against the pin record before parsing.
# resolves numpy 1.x. The gnn arm runs the shared `python -m gnn.importers
# check` from that runtime, and the validator verifies the installed parser
# file digests against the pin record before parsing.
name: gnn conformance (pinned)
runs-on: ubuntu-latest

Expand All @@ -83,8 +84,11 @@ jobs:
id: runtime
run: |
set -euo pipefail
REPO=$(uv run --no-sync python -c "from blockference.gnn import load_pin; print(load_pin()['repository'])")
COMMIT=$(uv run --no-sync python -c "from blockference.gnn import load_pin; print(load_pin()['commit'])")
# Provisioning needs only the two install coordinates. The pin itself is
# validated by the shared reader in the release arms below, so the
# workflow keeps no pin reader of its own.
REPO=$(uv run --no-sync python -c "import json; print(json.load(open('specs/gnn-pin.json', encoding='utf-8'))['repository'])")
COMMIT=$(uv run --no-sync python -c "import json; print(json.load(open('specs/gnn-pin.json', encoding='utf-8'))['commit'])")
uv venv --python 3.12 "$RUNNER_TEMP/gnn-runtime"
# The install follows specs/gnn-pin.json; a pin bump re-points it.
uv pip install --python "$RUNNER_TEMP/gnn-runtime/bin/python" \
Expand Down
10 changes: 6 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,12 @@ The grid-world model is declared in `specs/gridworld_3x3.gnn.md` (Generalized
Notation Notation) and generated from the implementation by
`blockference.gnn.render_spec`; `uv run python scripts/export_gnn_spec.py
--check` fails when the committed document drifts. The upstream parser is
pinned in `specs/gnn-pin.json` (GNN v5.0.3, commit `8f293d9ba`), and
`scripts/validate_gnn_spec.py` parses the document with that revision, builds
the runtime model from the declared parameters, and requires the declared
matrices to match. That check needs an external runtime (`GNN_ROOT` or
pinned in `specs/gnn-pin.json` (GNN v5.1.0, commit `75c834bd8`), and
`python -m gnn.importers check --repo .` reads that pin and the `.github/GNN.md`
pointer while `scripts/validate_gnn_spec.py` parses the document with that
revision, builds the runtime model from the declared parameters, and requires the
declared matrices to match. Do not add a second pin reader: the shared reader is
upstream. Both checks need an external runtime (`GNN_ROOT` or
`GNN_RUNTIME_PYTHON`); the required `gnn-conformance` CI job provisions one from
the pin and runs `scripts/release_check.py --arm gnn`. Do not
hand-edit `specs/gridworld_3x3.gnn.md`: change the model or fixture in
Expand Down
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,10 +113,11 @@ The grid-world generative model is declared in
[Generalized Notation Notation](https://github.com/ActiveInferenceInstitute/Generalized_Notation_Notation)
(GNN). The document is generated from the implementation and validated against
the upstream parser pinned in [`specs/gnn-pin.json`](specs/gnn-pin.json)
(schema `gnn-importer-pin/v1`, GNN v5.0.3, commit
`8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1`): the validator reads the declared parameters
back, builds the runtime model from them, and requires the declared matrices to
match exactly. See [`docs/gnn.md`](docs/gnn.md) for the commands and the
(schema `gnn-importer-pin/v1`, GNN v5.1.0, commit
`75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf`): the estate's shared reader
`gnn.importers` validates that pin and the [`.github/GNN.md`](.github/GNN.md)
pointer, and the validator reads the declared parameters back, builds the runtime
model from them, and requires the declared matrices to match exactly. See [`docs/gnn.md`](docs/gnn.md) for the commands and the
conformance contract.

GNN maintains a [downstream adoption
Expand Down
10 changes: 10 additions & 0 deletions TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,16 @@ Items are grouped by the size of the documentation change required:
- [x] Document receipt imports, including the failed offline package baseline
cache miss, without claiming a speedup; distinguish the declared NumPy
range from the actual lockfile resolution.
- [x] Cut over to the shared GNN pin reader. The pin moved from `v5.0.3` at
`8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1` — a revision that predates
`src/gnn/importers.py` — to `v5.1.0` at
`75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf`, and the interim local reader
(`blockference.gnn.load_pin` plus its pin-shape tests) is deleted. The
`gnn` arm now runs `python -m gnn.importers check --repo . --require-pointer
--workflow .github/workflows/ci.yml --job gnn-conformance` from the pinned
runtime, and the `gnn_*` manuscript variables come from
`gnn.importers.importer_variables` through
`scripts/gnn_importer_report.py`. No copy of the reader is vendored.

## Major

Expand Down
25 changes: 3 additions & 22 deletions blockference/gnn.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,13 @@
model *from* the parsed document and compare it with the declared matrices.

The pin record in ``specs/gnn-pin.json`` names the exact upstream revision whose
parser validates the document; see ``docs/gnn.md`` for the commands.
parser validates the document. The pin is read by the upstream
``gnn.importers`` reader, which this repository calls instead of keeping its own;
see ``docs/gnn.md`` for the commands.
"""

from __future__ import annotations

import json
import re
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path
Expand All @@ -34,13 +34,11 @@
from blockference.gridference import ActiveGridference, make_grid

__all__ = [
"GNN_PIN_PATH",
"GNN_SPEC_PATH",
"SPEC_DIR",
"GridWorldSpecParameters",
"build_spec_model",
"declared_arrays",
"load_pin",
"parameters_from_parsed",
"render_spec",
"spec_arrays",
Expand All @@ -50,7 +48,6 @@
ROOT = Path(__file__).resolve().parents[1]
SPEC_DIR = ROOT / "specs"
GNN_SPEC_PATH = SPEC_DIR / "gridworld_3x3.gnn.md"
GNN_PIN_PATH = SPEC_DIR / "gnn-pin.json"

#: GNN language revision declared by the document header.
GNN_LANGUAGE_VERSION = "GNN v1.1"
Expand Down Expand Up @@ -152,22 +149,6 @@ def spec_arrays(parameters: GridWorldSpecParameters | None = None) -> dict[str,
}


def load_pin(path: Path | None = None) -> dict[str, Any]:
"""Return the upstream pin, rejecting records outside the local pin contract."""

pin = json.loads((path or GNN_PIN_PATH).read_text(encoding="utf-8"))
if not isinstance(pin, dict):
raise ValueError("invalid GNN pin: expected a JSON object")
if pin.get("schema") != "gnn-importer-pin/v1":
raise ValueError("invalid GNN pin schema: expected gnn-importer-pin/v1")
if pin.get("tag") != "v5.0.3":
raise ValueError("invalid GNN pin tag: expected v5.0.3")
commit = pin.get("commit")
if not isinstance(commit, str) or re.fullmatch(r"[0-9a-fA-F]{40}", commit) is None:
raise ValueError("invalid GNN pin commit: expected a full 40-hex revision")
return pin


def _format_value(value: float) -> str:
return f"{float(value):.1f}"

Expand Down
30 changes: 15 additions & 15 deletions docs/_generated/gate-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

<!-- Generated by scripts/gate_metrics.py; edit the script, not this file. -->

Measured wall times from recorded canonical gate observations on `macOS-27.0.1-arm64-arm-64bit` with Python 3.12.16 at `2026-11-12T13:56:34Z`.
Measured wall times from recorded canonical gate observations on `macOS-27.0.1-arm64-arm-64bit` with Python 3.12.16 at `2026-11-12T16:30:49Z`.

First successful measurements retained for each arm. Package initially failed twice because offline pandas wheel metadata was unavailable; only package and the not-yet-run render arm were then run after SHA-256-verified acquisition of the exact pandas wheel in uv.lock. Those failures remain in this receipt’s runs. UV_FIND_LINKS pointed to that verified local wheelhouse for the successful package run. Baseline and after test selections differ by the new regression cases. No speedup is claimed. Audit refresh retains the earlier observations and two failed full-suite runs in runs; the notebook validator initially recursed into gitignored, untracked GNN migration build output. That output was moved aside without tracked changes for the successful 103-test run, then restored. Current lint, types, docs, GNN, render and full-suite observations are refreshed; other arm observations remain historical. The fresh render artifact was identified by the gate producer from source commit 2193be7b0be3fc429f4a8d159d4b96b249b12060.
First successful measurements retained for each arm. Package initially failed twice because offline pandas wheel metadata was unavailable; only package and the not-yet-run render arm were then run after SHA-256-verified acquisition of the exact pandas wheel in uv.lock. Those failures remain in this receipt’s runs. UV_FIND_LINKS pointed to that verified local wheelhouse for the successful package run. Baseline and after test selections differ by the new regression cases. No speedup is claimed. Audit refresh retains the earlier observations and two failed full-suite runs in runs; the notebook validator initially recursed into gitignored, untracked GNN migration build output. That output was moved aside without tracked changes for the successful 103-test run, then restored. Current lint, types, docs, GNN, render and full-suite observations are refreshed; other arm observations remain historical. The fresh render artifact was identified by the gate producer from source commit 2193be7b0be3fc429f4a8d159d4b96b249b12060. Recorded after the shared gnn.importers cutover: the gnn arm runs python -m gnn.importers check --repo . with --require-pointer, then the specification drift check and the deep pinned-parser conformance check, and the manuscript arm reads its gnn_* variables from the pinned runtime. GNN_RUNTIME_PYTHON pointed at the GNN v5.1.0 checkout's own virtual environment. No speedup is claimed.

Refresh with:

Expand All @@ -21,15 +21,15 @@ uv run python scripts/gate_metrics.py --record-timings /tmp/gate-after.json
| Arm | Before (s) | Before status | After (s) | After status | After command |
| --- | --- | --- | --- | --- | --- |
| `lint` | 0.11 | passed | 0.03 | passed | `uv run ruff check blockference tests GRTs scripts` |
| `types` | 0.61 | passed | 1.06 | passed | `uv run mypy blockference` |
| `test` | 33.27 | passed | 4.82 | passed | `uv run pytest -m not slow` |
| `test-full` | 55.38 | passed | 44.22 | passed | `uv run pytest --cov=blockference --cov-report=term --cov-report=xml --cov-fail-under=90` |
| `docs` | 7.45 | passed | 5.28 | passed | `uv run python scripts/check_docs_links.py` |
| `manuscript` | 6.04 | passed | 3.24 | passed | `uv run python scripts/manuscript_variables.py --check` |
| `gnn` | 2.78 | passed | 2.0 | passed | `uv run python scripts/export_gnn_spec.py --check` |
| `smoke` | 3.48 | passed | 2.55 | passed | `uv run blockference pipeline --config configs/smoke.yml --output-root /private/tmp/activeblockference-estate.8EbtJ4/tmp/activeblockference-gate-vx7lf7ds/output --run-name gate_smoke` |
| `package` | 0.08 | failed | 14.86 | passed | `uv build` |
| `render` | 4.04 | passed | 4.46 | passed | `uv run python scripts/build_manuscript.py --render pdf` |
| `types` | 0.61 | passed | 0.22 | passed | `uv run mypy blockference` |
| `test` | 33.27 | passed | 7.12 | passed | `uv run pytest -m not slow` |
| `test-full` | 55.38 | passed | 32.97 | passed | `uv run pytest --cov=blockference --cov-report=term --cov-report=xml --cov-fail-under=90` |
| `docs` | 7.45 | passed | 3.97 | passed | `uv run python scripts/check_docs_links.py` |
| `manuscript` | 6.04 | passed | 3.5 | passed | `uv run python scripts/manuscript_variables.py --check` |
| `gnn` | 2.78 | passed | 2.04 | passed | `uv run python scripts/export_gnn_spec.py --check` |
| `smoke` | 3.48 | passed | 2.72 | passed | `uv run blockference pipeline --config configs/smoke.yml --output-root /var/folders/qs/rxkntx5d4hlgz0c7x8v15gym0000gn/T/activeblockference-gate-xizbjknp/output --run-name gate_smoke` |
| `package` | 0.08 | failed | 8.91 | passed | `uv build` |
| `render` | 4.04 | passed | 3.59 | passed | `uv run python scripts/build_manuscript.py --render pdf` |

Baseline workloads that are not equivalent to their arms:

Expand All @@ -43,13 +43,13 @@ The baseline and current receipts are historical evidence. Timings include host

| Selection | Collected tests |
| --- | --- |
| full suite | 103 |
| fast (`-m "not slow"`) | 90 |
| full suite | 97 |
| fast (`-m "not slow"`) | 84 |
| slow (`-m slow`) | 13 |

Recorded run: 103 passed, 0 skipped.
Recorded run: 97 passed, 0 skipped.

`test-full` recorded 91.02% line coverage of `blockference` (floor 90%).
`test-full` recorded 90.96% line coverage of `blockference` (floor 90%).

## Receipts

Expand Down
Loading
Loading