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
4 changes: 3 additions & 1 deletion .github/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@ contains only Python 3.11 and runs `--arm test-full`. The `gnn-conformance` job
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, 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
the pointer, and `scripts/validate_gnn_spec.py --verify-tag-remote` checks the
pinned v5.1.0 tag resolves to commit `75c834bd` and verifies the parser digests
before parsing; 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
4 changes: 2 additions & 2 deletions docs/_generated/gate-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ The baseline and current receipts are historical evidence. Timings include host

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

Recorded run: 97 passed, 0 skipped.
Expand Down
2 changes: 1 addition & 1 deletion docs/gate.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ measurements.
| `test-full` | `uv run pytest --cov=blockference --cov-report=term --cov-report=xml --cov-fail-under=90` | yes |
| `docs` | `scripts/check_docs_links.py`, `scripts/gate_metrics.py --check` | yes |
| `manuscript` | `scripts/manuscript_variables.py --check`, `scripts/validate_manuscript.py`, `scripts/build_manuscript.py`, `scripts/build_manuscript.py --check`; the `gnn_*` variables come from `gnn.importers` in the pinned runtime | yes |
| `gnn` | `scripts/export_gnn_spec.py --check`, the shared `python -m gnn.importers check --repo .` pin and pointer check, and real pinned `scripts/validate_gnn_spec.py` validation; missing runtime fails | yes |
| `gnn` | `scripts/export_gnn_spec.py --check`, the shared `python -m gnn.importers check --repo .` pin and pointer check, and real pinned `scripts/validate_gnn_spec.py --verify-tag-remote` validation (parser digests before parsing, the pin's tag resolved upstream to the pinned commit; needs network); missing runtime fails | yes |
| `smoke` | pipeline, validation, and standalone `run` JSON smoke checks in a temporary directory | yes |
| `package` | `uv build`, locked `uv export` constraints for clean-wheel dependencies, and isolated import outside the source tree | yes |
| `render` | `scripts/build_manuscript.py --render pdf` (Pandoc + XeLaTeX) | no |
Expand Down
24 changes: 19 additions & 5 deletions docs/gnn.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,17 +63,19 @@ GNN_ROOT=/path/to/Generalized_Notation_Notation \
GNN_PYTHON=/path/to/parser-runtime/bin/python \
uv run python scripts/validate_gnn_spec.py --json

# Installed pinned runtime (what CI uses)
uv run python scripts/validate_gnn_spec.py --gnn-runtime /path/to/venv/bin/python --json
# Installed pinned runtime (what CI uses); --verify-tag-remote resolves the
# pin's tag upstream with `git ls-remote` and needs network access
uv run python scripts/validate_gnn_spec.py --gnn-runtime /path/to/venv/bin/python \
--verify-tag-remote --json
```

`GNN_ROOT` is a `Generalized_Notation_Notation` checkout: the validator resolves
the pinned commit with `git archive`, verifies every recorded parser digest, and
runs the parser from that materialized tree, so a live working copy under
development is never imported. `GNN_PYTHON` (or `--gnn-runtime`) selects the
interpreter that has the parser dependencies; the GNN checkout's own `.venv`
works. Exit codes are `0` pass, `1` conformance failure, and `2` pinned runtime
or checkout unavailable — an unavailable run is reported as not run, never as a
works. Exit codes are `0` pass, `1` conformance failure, and `2` pinned runtime,
checkout, or requested remote tag resolution unavailable — an unavailable run is reported as not run, never as a
pass. With `GNN_ROOT` set and no runtime named, the gate uses the checkout's own
`.venv/bin/python` for both the reader and the pin.

Expand All @@ -94,7 +96,19 @@ and exact CI map.
revision, `.github/workflows/ci.yml`, and job `gnn-conformance`.
2. The document parses with the pinned `gnn` parser with no errors or warnings,
and the parser version equals the pinned tag; every recorded parser digest
matches the installed (or archived) parser files.
matches the installed (or archived) parser files, and for an installed
runtime that check runs *before* the document is parsed and the parser must be
imported from the verified package.
The pin's `tag` must resolve to the pinned `commit` (`tag-commit-mismatch`):
locally in a `GNN_ROOT` checkout, or upstream with `--verify-tag-remote`
(`git ls-remote`, the peeled commit of an annotated tag; the release gate's
`gnn` arm passes the flag, so it needs network access). The commit the
installer recorded for the runtime (`direct_url.json` `vcs_info.commit_id`)
must equal the pin's commit. Without a checkout or the flag, and for an
install with no recorded VCS commit, the receipt reports `tag_binding` /
`revision` as `unresolvable-offline` rather than a pass; with
`--verify-tag-remote`, a tag that cannot be resolved ends the run as *not
run* (exit `2`).
3. The declared `ModelParameters` are read back and used to build the runtime
model, whose `A`/`B`/`C`/`D`/`E` arrays must equal the declared matrices
exactly; declared `StateSpaceBlock` dimensions must match the array shapes.
Expand Down
2 changes: 1 addition & 1 deletion scripts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Repository gates and generators, all run from the repository root:
| `execute_notebooks.py` | Parses and executes every tracked notebook from the repository root. |
| `validate_notebooks.py` | Notebook hygiene checks before execution. |
| `export_gnn_spec.py` | Writes or verifies `specs/gridworld_3x3.gnn.md` from the implementation. |
| `validate_gnn_spec.py` | Validates the committed specification with the pinned parser, using a separate interpreter selected by `--gnn-runtime` or the documented environment variables. |
| `validate_gnn_spec.py` | Validates the committed specification with the pinned parser, using a separate interpreter selected by `--gnn-runtime` or the documented environment variables. Verifies the parser digests before parsing, binds the pin's tag to its commit (`--gnn-root` checkout or `--verify-tag-remote`; mismatch fails as `tag-commit-mismatch`), and compares the installed runtime's recorded commit with the pin. |
| `gnn_parser_probe.py` | Imports the upstream `gnn` parser; runs as a subprocess under the pin. |
| `gnn_importer_report.py` | Imports the upstream `gnn.importers` reader and prints this repository's normalized pin and `gnn-importer-variables/v1` map for the two scripts above. |

Expand Down
8 changes: 6 additions & 2 deletions scripts/release_check.py
Original file line number Diff line number Diff line change
Expand Up @@ -201,9 +201,13 @@ def _plan(
"--job", "gnn-conformance",
]
)
validator = ["uv", "run", "python", "scripts/validate_gnn_spec.py", "--json"]
# The pin's tag is resolved upstream (needs network), so a tag that was
# moved off the pinned commit fails the release gate.
validator = [
"uv", "run", "python", "scripts/validate_gnn_spec.py", "--verify-tag-remote", "--json",
]
if gnn_runtime:
validator[-1:-1] = ["--gnn-runtime", gnn_runtime]
validator[-2:-2] = ["--gnn-runtime", gnn_runtime]
commands.append(validator)
return commands
if arm == "smoke":
Expand Down
Loading
Loading