Skip to content

GNN: adopt the shared gnn.importers reader at v5.1.0 - #27

Merged
docxology merged 1 commit into
mainfrom
estate/gnn-importer-cutover
Nov 12, 2026
Merged

docxology merged 1 commit into
mainfrom
estate/gnn-importer-cutover

Conversation

@docxology

@docxology docxology commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

GNN: adopt the shared gnn.importers reader at v5.1.0

This is the GNN–FEP cutover for ActiveBlockference, the last step of the
staged adoption in
docs/workflows/gnn-fep.md.
The member contract row for this repository is: role importer, gate
uv run python scripts/release_check.py --arm all, docs index docs/README.md
and docs/documentation-index.md, manuscript producer
scripts/manuscript_variables.py, pin specs/gnn-pin.json, reader arm
python -m gnn.importers check --repo ..

Pin: old and new revision

Tag Commit
Before v5.0.3 8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1
After v5.1.0 75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf

v5.0.3 predates src/gnn/importers.py, so the previous pin could not run
python -m gnn.importers at all. v5.1.0 is the release that ships it
(git ls-tree -r v5.1.0 --name-only -- src/gnn/importers.py names the module).
The pin keeps its schema (gnn-importer-pin/v1), repository, recorded date and
parser_files custody digests; the five digests were recomputed from the
pinned tree (git cat-file -p v5.1.0:<path> | shasum -a 256), and
/src/gnn/parsers/markdown_parser_parameter.py happens to be byte-identical
between the two revisions.

What changed

  • Deleted the interim local reader. blockference.gnn.load_pin,
    blockference.gnn.GNN_PIN_PATH and the three tests whose only subject was
    that pin shape were removed. No copy of the reader is vendored, and the
    reader is not overlaid on an older parser: the pin and the parser are the
    same revision.
  • The gnn arm calls the shared reader from the pinned runtime, then the
    offline drift check, then the deep pinned-parser conformance check:
    python -m gnn.importers check --repo . --require-pointer --workflow .github/workflows/ci.yml --job gnn-conformance. --require-pointer is on
    because .github/GNN.md already names the pin file, the revision, the
    workflow and the job.
  • scripts/gnn_importer_report.py is the single bridge: it runs in an
    interpreter where gnn is importable and prints the normalized pin (via
    find_pin/read_pin) and the gnn-importer-variables/v1 map (via
    importer_variables). scripts/validate_gnn_spec.py and
    scripts/manuscript_variables.py consume that JSON, so both stop reading the
    pin JSON themselves.
  • The gnn_* manuscript variables come from importer_variables, keeping
    their key names. gnn_repository is now the reader's normalized org/name
    form rather than the pin's URL form; prose is unaffected.
  • CI provisioning reads the two install coordinates (repository,
    commit) with a plain JSON read; the workflow keeps no pin reader.
  • A leaked temp tree is fixed on the way through:
    validate_gnn_spec.materialize_pin no longer mkdtemps outside the run's
    temporary directory, so a GNN_ROOT run leaves nothing behind. (A stale
    docs/_build/gnn-fep-migration/tmp/ tree from the earlier blocked attempt
    was what made the notebook-hygiene test recurse into GNN build output; it is
    gitignored debris and was removed, with no tracked change.)
  • Docs rewritten from blocked to adopted, citing the old and new
    revisions: docs/gnn.md, docs/gate.md, docs/development.md,
    docs/manuscript/09_reproducibility.md, .github/GNN.md, .github/AGENTS.md,
    .github/workflows/README.md, AGENTS.md, README.md, specs/README.md,
    scripts/README.md, TODO.md.

The exact check command and its output

Run in the pinned runtime, which here is the GNN v5.1.0 checkout's own
environment (GNN_RUNTIME_PYTHON):

$ "$GNN_RUNTIME_PYTHON" -m gnn.importers check --repo . --require-pointer \
    --workflow .github/workflows/ci.yml --job gnn-conformance
importer: /Users/friedman/Documents/Git/gitvault/Username/ActiveInferenceInstitute/Public/ActiveBlockference
  pin: specs/gnn-pin.json -> v5.1.0 @ 75c834bd85 (schema gnn-importer-pin/v1)
  specs: 1
  pointer: .github/GNN.md -> ok
  verdict: ok

The deep conformance check run by the arm (receipt:
docs/_build/gnn/validation-receipt.json, ignored):

gnn validation passed: specs/gridworld_3x3.gnn.md parsed by gnn 5.1.0
(installed runtime .../src/gnn)
{"consistency_score": 1.0, "failures": [], "gnn_version": "5.1.0", "ok": true,
 "orientation": ["canonical"], "parser_success": true,
 "pin": {"commit": "75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf", ...}}

The reader also fails closed in the other direction: with the pointer still
naming the old revision it reported
[error] pointer-revision-unnamed: .github/GNN.md does not name the pinned revision 75c834bd8519 and exited 1, which is why the pointer is updated in the
same change.

Gate

uv run python scripts/release_check.py --arm all --arm test --arm render
with GNN_RUNTIME_PYTHON set to the pinned v5.1.0 runtime, on this tree at
9262dc3:

lint passed in 0.03s
types passed in 0.22s
test passed in 7.12s
... 97 passed in 32.22s ...
test-full passed in 32.97s     (90.96% line coverage of blockference, floor 90%)
docs passed in 3.97s
manuscript passed in 3.50s
gnn passed in 2.04s
smoke passed in 2.72s
package passed in 8.91s
render passed in 3.59s
release gate passed

tests/test_gnn_spec.py also runs its pinned-parser conformance test with the
runtime present (97 passed, 0 skipped). The generated artifacts were refreshed
through their producers, not by hand: scripts/manuscript_variables.py
(no drift on re-run) and scripts/gate_metrics.py with the recorded receipt
(--check passes, and a second generation is zero-diff).

Hosted Actions

No hosted evidence is claimed. Runs on this repository terminate before any step
executes — ci and CodeQL runs on main and on PR #26 report
conclusion: failure with 0 steps after ~4 s, consistent with the org-wide
Actions billing lock. The gate above is a local run on this workstation, quoted
with its host and interpreter in
docs/_generated/gate-metrics.md.

Merge

Squash-merged as b6211266fa8530b39c9c8f1e016744ed0f9d62fc on 2026-11-12.

The pin moves from v5.0.3 at 8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1 —
a revision that predates src/gnn/importers.py — to v5.1.0 at
75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf, the release that ships it.

The interim local reader goes away instead of being reimplemented:

* blockference.gnn.load_pin, GNN_PIN_PATH and their pin-shape tests are
  deleted; the shared reader owns pin discovery, shape normalization and
  the pointer check.
* the gnn arm runs `python -m gnn.importers check --repo .
  --require-pointer --workflow .github/workflows/ci.yml --job
  gnn-conformance` from the pinned runtime, then the drift check and the
  deep pinned-parser conformance check.
* scripts/gnn_importer_report.py is the only bridge: it prints the
  normalized pin and the gnn-importer-variables/v1 map from an
  interpreter where gnn is importable, which is what
  validate_gnn_spec.py and manuscript_variables.py consume.
* the gnn_* manuscript variables come from importer_variables, so the
  prose and the conformance job cannot disagree about the pinned
  revision.
* CI provisions the runtime from the two pin fields with a plain JSON
  read; the workflow keeps no pin reader.

Pin and pointer validation, spec parsing, the semantic validator, the
B-orientation check, the consistency checker and the recorded parser
digests all run against 75c834bd. The gate selection
`--arm all --arm test --arm render` passes on this tree.
@docxology
docxology merged commit b621126 into main Nov 12, 2026
0 of 2 checks passed
docxology added a commit that referenced this pull request Nov 12, 2026
…29)

The optional pymdp extra and its lock are recorded as done: the floor moved
from >=1.0.1 to >=1.0.5 and uv.lock resolves 1.0.5 (7f8469d, #28). The GNN
cutover item now cites its merge (b621126, #27), and the verification notes
record this pass: the docs arm and the gnn arm both passed at 7f8469d, with
gnn.importers reporting v5.1.0 @ 75c834bd85 and verdict ok.

One defect found while checking the tree is recorded as open: ignored.csv is a
cadCAD record dump committed by 574a5c1 and nothing references it; .gitignore
covers result.csv, results/ and output/ but not that name.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant