From 7da818d14f367ebe4ee63c7ef97d2a2b3ca8b3ac Mon Sep 17 00:00:00 2001 From: Daniel Ari Friedman Date: Sat, 14 Nov 2026 18:23:02 -0800 Subject: [PATCH 1/4] Integrate qualified Blockference custody and package boundary repairs --- .github/AGENTS.md | 12 +- .github/GNN.md | 24 +- .github/README.md | 3 + .github/workflows/README.md | 12 +- .github/workflows/ci.yml | 7 +- .gitignore | 1 + AGENTS.md | 20 +- GRTs/README.md | 7 + GRTs/agents.py | 22 +- GRTs/data3/README.md | 29 +- README.md | 19 +- TODO.md | 73 +- blockference/config/README.md | 13 +- blockference/config/__init__.py | 2 + blockference/config/experiment.py | 22 +- blockference/envs/README.md | 14 +- blockference/envs/grid_world.py | 63 +- blockference/envs/protocol.py | 12 +- blockference/gnn.py | 21 +- blockference/gnn_runtime.py | 41 ++ blockference/gnn_source.py | 291 ++++++++ blockference/io/persist.py | 105 +-- blockference/io/validate.py | 650 ++++++++++++------ blockference/manuscript_links.py | 145 ++++ blockference/maths.py | 23 +- blockference/notebook_inventory.py | 124 ++++ blockference/pipeline.py | 116 ++-- blockference/viz/_common.py | 102 ++- blockference/viz/animation.py | 24 +- blockference/viz/plots.py | 54 +- docs/api.md | 54 ++ docs/design-contract.md | 16 +- docs/development.md | 16 +- docs/gate.md | 47 +- docs/gnn.md | 144 ++-- docs/manuscript/09_reproducibility.md | 17 +- docs/manuscript/README.md | 19 + docs/pipeline.md | 36 +- ignored.csv | 8 - notebooks/README.md | 14 + .../simple_gridworld/gridference_single.ipynb | 8 +- scripts/AGENTS.md | 7 +- scripts/README.md | 31 +- scripts/build_manuscript.py | 81 ++- scripts/execute_notebooks.py | 25 +- scripts/gnn_importer_report.py | 70 -- scripts/gnn_parser_probe.py | 105 --- scripts/manuscript_variables.py | 61 +- scripts/release_check.py | 70 +- scripts/validate_gnn_spec.py | 348 ++++------ scripts/validate_manuscript.py | 60 +- scripts/validate_notebooks.py | 46 +- specs/README.md | 11 +- specs/gridworld_3x3.gnn.md | 10 +- tests/test_configuration_files.py | 88 +++ tests/test_contracts_extended.py | 26 +- tests/test_core_hardening.py | 11 +- tests/test_environment_identity.py | 110 +++ tests/test_external_runtime_contracts.py | 204 ++++++ tests/test_gnn_pin_binding.py | 77 +-- tests/test_gnn_source_admission.py | 564 +++++++++++++++ tests/test_gnn_spec.py | 147 +++- tests/test_grts.py | 87 +++ tests/test_manuscript_resources.py | 196 ++++++ tests/test_notebook_contracts.py | 193 ++++++ tests/test_notebooks.py | 16 +- tests/test_pipeline_real.py | 31 +- tests/test_publication.py | 16 +- tests/test_release_gate.py | 77 +-- tests/test_run_artifact_boundaries.py | 380 ++++++++++ tests/utils/test_utils_math.py | 85 +++ 71 files changed, 4241 insertions(+), 1422 deletions(-) create mode 100644 blockference/gnn_runtime.py create mode 100644 blockference/gnn_source.py create mode 100644 blockference/manuscript_links.py create mode 100644 blockference/notebook_inventory.py delete mode 100644 ignored.csv delete mode 100644 scripts/gnn_importer_report.py delete mode 100644 scripts/gnn_parser_probe.py create mode 100644 tests/test_configuration_files.py create mode 100644 tests/test_environment_identity.py create mode 100644 tests/test_external_runtime_contracts.py create mode 100644 tests/test_gnn_source_admission.py create mode 100644 tests/test_manuscript_resources.py create mode 100644 tests/test_notebook_contracts.py create mode 100644 tests/test_run_artifact_boundaries.py diff --git a/.github/AGENTS.md b/.github/AGENTS.md index 384d70a..e804535 100644 --- a/.github/AGENTS.md +++ b/.github/AGENTS.md @@ -5,11 +5,13 @@ The workflow installs `uv.lock`, then calls the arms of 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, where the shared `python -m gnn.importers check --repo .` reads the pin and -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 +There is no separate `gate` job. The `gnn` arm checks exporter drift, then +`scripts/validate_gnn_spec.py --verify-tag-remote` owns deep conformance and the +shared pin/pointer/workflow/job check through qualified external workers. +Require independently reviewed `GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` job +inputs and complete content/module/installed-origin admission through exit. +Their hosted delivery remains a release prerequisite; never invent download +URLs or weaken admission. Missing prerequisites 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. diff --git a/.github/GNN.md b/.github/GNN.md index 2111b66..bd0c174 100644 --- a/.github/GNN.md +++ b/.github/GNN.md @@ -7,21 +7,21 @@ (`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 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 +The job selects the canonical release gate with `--arm all` and a separate +`GNN_RUNTIME_PYTHON`. It must also receive independently reviewed +`GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` resources before hosted acceptance. +Within the `gnn` arm, exporter drift is checked first; the project validator +then owns deep conformance and the producer's syntax/pointer/workflow/job +check in separate isolated qualified lifetimes. The shared producer remains +authoritative for pin discovery and validation. Missing resources, runtime, +installed provenance, or exit revalidation fail rather than skip. 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. -The validator checks that the resolved `gnn.__version__` matches the pin tag, -verifies the installed parser file digests, parses `specs/gridworld_3x3.gnn.md` -with the pinned `MarkdownGNNParser`, and compares the declared parameters and the `A`, +Independent full-package content and actual module ownership are admitted +before target GNN execution and revalidated at verdict exit. The validator +also checks version and recorded parser hashes, parses the committed document +with the pinned `MarkdownGNNParser`, and compares declared parameters and `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 diff --git a/.github/README.md b/.github/README.md index 3e239a5..2148e25 100644 --- a/.github/README.md +++ b/.github/README.md @@ -82,6 +82,9 @@ arms of the canonical gate in [`scripts/release_check.py`](../scripts/release_ch * the Python 3.12 `gnn-conformance` job (display name `gnn conformance (pinned)`) runs `--arm all` with `GNN_RUNTIME_PYTHON` set to a separate pinned runtime provisioned from `specs/gnn-pin.json`. + Independently reviewed `GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` inputs must + also be delivered before hosted acceptance; source-only local proof does + not establish installed provenance or provide those hosted artifacts. The arms cover Ruff linting, repository-wide Markdown link/anchor validation, mypy, the test suite, notebook hygiene and execution, real pipeline and CLI diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 309eea2..b0ec79d 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -10,11 +10,13 @@ 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; 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. +separate runtime. Its `gnn` arm invokes the project validator for guarded deep +conformance and the shared importer check. Independently reviewed bootstrap +and full-manifest job inputs must be delivered before hosted acceptance; +no machine-local path or invented publication URL substitutes for them. +The full suite is selected on both Python versions; other release arms run +on Python 3.12. Missing prerequisites fail. There is no separate `gate` job; +PDF rendering remains an explicit local arm. The workflow uses pinned `astral-sh/setup-uv` directly, not the Institute composite. [`../../docs/gate.md`](../../docs/gate.md) is authoritative for the diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 985d003..72e316d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -57,9 +57,10 @@ 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 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. + # resolves numpy 1.x. The project validator owns both guarded conformance + # and shared importer checks. Hosted acceptance also requires independently + # reviewed GNN_BOOTSTRAP/GNN_SOURCE_MANIFEST resource delivery; parser-file + # digests alone are not complete source or installed-origin admission. name: gnn conformance (pinned) runs-on: ubuntu-latest diff --git a/.gitignore b/.gitignore index fb787eb..f0f53b3 100644 --- a/.gitignore +++ b/.gitignore @@ -43,6 +43,7 @@ coverage.xml # Generated artefacts (commit on demand) result.csv +ignored.csv *.csv.bak results/ output/ diff --git a/AGENTS.md b/AGENTS.md index f86f0e2..6654e00 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,15 +24,17 @@ 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.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 +pinned in `specs/gnn-pin.json` (GNN v5.1.0, commit `75c834bd8`). +`scripts/validate_gnn_spec.py` owns both deep conformance and the shared +pin/pointer/workflow/job check through `blockference/gnn_source.py`. +Require the selected separate interpreter plus independently reviewed +`GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` resources. Complete source/module +admission must remain active through verdict exit; metadata inspection alone +is not qualification. Never add a local pin reader or an unchecked direct +`-m gnn.importers` path. Installed provenance and source-artifact proof remain +distinct. Hosted resource delivery is a release prerequisite, not an assumed +published artifact. The required `gnn-conformance` job runs the `gnn` arm. +Do not hand-edit `specs/gridworld_3x3.gnn.md`: change the model or fixture in `blockference/` and regenerate with `scripts/export_gnn_spec.py`. See `docs/gnn.md`. diff --git a/GRTs/README.md b/GRTs/README.md index c418103..96cc2da 100644 --- a/GRTs/README.md +++ b/GRTs/README.md @@ -15,3 +15,10 @@ The optional OpenAI provider is selected explicitly with `--provider openai` and configured by the caller; there are no implicit global paths or provider instances. Offline tests and release gates never make network requests. A provider response is research input, not a software-integrity or scientific-validity verdict; preserve its provenance separately. + +An explicit `Path` corpus means a readable regular UTF-8 file. It is admitted +before workspace preparation or optional provider construction; missing, +directory, broken-link, unreadable, and invalid-UTF-8 inputs fail without +changing request/data/report sentinels. `None` selects the built-in corpus. +Existing readable filename strings retain file behavior; other strings remain +literal text, including empty or long text. No provider fallback is inferred. diff --git a/GRTs/agents.py b/GRTs/agents.py index 43e5f38..039827a 100644 --- a/GRTs/agents.py +++ b/GRTs/agents.py @@ -52,19 +52,31 @@ def prepare(self) -> None: self.research_data.write_text("", encoding="utf-8") +def _read_corpus_file(path: Path) -> str: + if path.is_dir(): + raise IsADirectoryError(f"corpus must be a readable UTF-8 file: {path}") + if not path.is_file(): + raise FileNotFoundError(f"corpus file not found: {path}") + return path.read_text(encoding="utf-8") + + class OfflineCorpusProvider: - """Deterministic provider that answers from a local text corpus.""" + """Use readable explicit Paths, existing filename strings, or literal/default text.""" def __init__(self, corpus: str | Path | None = None) -> None: if corpus is None: self.corpus = ( "Active inference links observations, beliefs, actions, and expected free energy." ) + elif isinstance(corpus, Path): + self.corpus = _read_corpus_file(corpus) else: corpus_path = Path(corpus) - self.corpus = ( - corpus_path.read_text(encoding="utf-8") if corpus_path.is_file() else str(corpus) - ) + try: + is_file = corpus_path.is_file() + except (OSError, ValueError): + is_file = False + self.corpus = _read_corpus_file(corpus_path) if is_file else corpus def complete(self, prompt: str) -> str: """Return stable corpus sentences selected by prompt terms.""" @@ -182,6 +194,8 @@ def build_provider( if name == "offline": return OfflineCorpusProvider(corpus) if name == "openai": + if isinstance(corpus, Path): + _read_corpus_file(corpus) return OpenAIProvider(model=model, timeout=timeout) raise ValueError("provider must be 'offline' or 'openai'") diff --git a/GRTs/data3/README.md b/GRTs/data3/README.md index 119e436..130c493 100644 --- a/GRTs/data3/README.md +++ b/GRTs/data3/README.md @@ -1,19 +1,18 @@ # `GRTs/data3/` — shared working corpus -Files in this folder are **the agents' communication channel**. The -LangChain agents in `GRTs/agents.py` read and write here. +These checked-in files are retained historical corpus/workspace material, not +a live LangChain persona protocol. Current runtime locations come from an +explicit `ResearchWorkspace(root)`. -| File | Read by | Written by | Purpose | -|-------------------------------|-----------------|--------------------|--------------------------------------------| -| `O_Project_description.txt` | both | human (seed) | The original task description. | -| `requests.txt` | Research Joe | Professor Karl | Outstanding research questions. | -| `research_data.txt` | Professor Karl | Research Joe | Gathered evidence / sources. | -| `report.txt` | human | Professor Karl | The final write-up. | +| File | Current role | +| --- | --- | +| `O_Project_description.txt` | Optional prompt context. | +| `requests.txt` | Human input, seeded only when missing. | +| `research_data.txt` | Research data written by `ResearchOrchestrator`. | +| `report.txt` | Report written by `ResearchOrchestrator`. | -## Conventions - -* Files are plain UTF-8 text. -* The agents append/overwrite with `WriteFileTool`; treat any file as - potentially mutated by the next run. -* Keep the seed `O_Project_description.txt` checked in; treat the rest as - ephemeral artefacts (do not rely on their git history). +`OfflineCorpusProvider` is deterministic and network-free. OpenAI is an +explicit optional provider requiring external credentials. The implementation +has no Research Joe/Professor Karl agents or `WriteFileTool` calls. +Preserve the corpus, reports, and historical communication files; updating +this description does not authorize running a provider or rewriting them. diff --git a/README.md b/README.md index f2291a2..7f2792b 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,10 @@ uv run python scripts/release_check.py --arm all --gnn-runtime /path/to/gnn-runt uv run blockference pipeline --config configs/smoke.yml --output-root output ``` -The release gate requires a separate pinned GNN runtime; replace the example +The release gate requires a separate pinned GNN runtime and independently +reviewed `GNN_BOOTSTRAP`/`GNN_SOURCE_MANIFEST` resources; replace the example interpreter path above with yours. [`docs/gate.md`](docs/gate.md) defines the -arms and CI mapping, and [`docs/gnn.md`](docs/gnn.md) explains runtime setup. +arms and CI mapping, and [`docs/gnn.md`](docs/gnn.md) explains admission/setup. The CLI has three explicit commands: @@ -44,6 +45,11 @@ summary/model/policies, an NPZ model archive, PNG visualisations, a GIF, a log, `manifest.json`, and one aggregate `validation_report.json`. Parquet is an optional additional format; CSV and JSON remain required. A non-empty run directory is refused unless `--reuse` is supplied explicitly. +Models, policies, summaries, and visual histories retain `(run, agent)` +ownership; independent runs are not concatenated. Version-2 artifact layouts +and exact diagnostic/category checks are documented in +[`docs/pipeline.md`](docs/pipeline.md). Historical version-1 trees are not +silently migrated or re-certified. For single-agent runs, `simulation.initial_state` remains the compatibility default. For multi-agent runs (`n_agents > 1`) the simultaneous-transition @@ -115,10 +121,11 @@ The grid-world generative model is declared in the upstream parser pinned in [`specs/gnn-pin.json`](specs/gnn-pin.json) (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. +owns pin/pointer validation inside a fully admitted external worker. The +validator reads declared parameters back, builds the runtime model, and +requires exact matrices and policy cardinalities. Source execution, +installed provenance, and scientific adequacy are separate boundaries. +See [`docs/gnn.md`](docs/gnn.md) for the commands and conformance contract. GNN maintains a [downstream adoption guide](https://github.com/ActiveInferenceInstitute/Generalized_Notation_Notation/blob/main/docs/gnn/integration/downstream_adoption.md) diff --git a/TODO.md b/TODO.md index 0fe62e2..9665c42 100644 --- a/TODO.md +++ b/TODO.md @@ -1,7 +1,7 @@ # ActiveBlockference TODO Owner: Active Inference Institute -Last reviewed: 2026-11-12 +Last reviewed: 2026-11-14 This file records documentation findings from the 2026-08-02 DOCS-DEEP pass and the 2026-11-11 completeness pass, plus the subsequent estate alignment. @@ -82,19 +82,64 @@ an executable publication validator. ## Open / deferred -No unresolved documentation finding remains. The Python-floor and pymdp-floor -reconciliations under **Medium** are complete, not deferred. - -One repository defect found in the 2026-11-12 review is open: - -- [ ] Remove the stray tracked run dump `ignored.csv` at the repository root. - It was committed by 574a5c1 ("updates", 2026-05-10), is a cadCAD record - export whose cells hold `ActiveGridference` object reprs, and no file, - test, or page in the tree references it. `.gitignore` covers `result.csv`, - `results/`, and `output/` but not this name, which is how it was committed. - Deleting the file, or adding the matching ignore rule, is a one-file - change; git history keeps the content either way. Owner: the maintainer - who opens the hygiene PR. Nothing outside this repository blocks it. +The current candidate is not merged or release-qualified. The dated completed +items and verification notes below remain historical, not proof for this +source. Current scope: + +- [x] **B01:** retain per-run/per-agent models and policies; local real-backend + and refreshed-manifest association controls passed. +- [x] **B02:** separate histories, diagnostics, plots, and animation labels by + run/agent; real render and artist/data controls passed. +- [x] **B03:** reviewed artifact-validation controls passed, including six + string/float/boolean categorical attacks across actions and observations. + Refreshed manifests cannot hide these invalid categorical values. +- [x] **B04:** malformed artifacts and missing parsed prerequisites fail + validation rather than escaping or becoming successful skipped boundaries. +- [x] **B05:** regenerate only through the exporter; actual pinned-source + default, three-action, and singleton-policy parsing passed. Runtime action + labels remain distinct from declaration-only numeric policy priors. +- [ ] **B06:** research-maintainer decision on scientific prose/definitions. + Numerical definitions and the held proposed prose remain unchanged. +- [x] **B07:** one external interpreter-selection contract preserves venv + launchers and separate NumPy environments without project-Python fallback. +- [ ] **B08:** source and installed-origin/content admission controls plus + actual pinned parser/importer validation passed. Hosted reviewed-resource + delivery remains required; full native-ecosystem qualification is not claimed. +- [x] **B09:** retain actual policy caps and ordered allowed policies. +- [x] **B10:** preserve built-in integer/string identities, registry order, + and established conflict priority through typed serialization. +- [x] **B11:** normalize extreme finite weights without changing RNG ownership + or the EFE definition. +- [x] **B12:** reject nonmapping configuration roots before output setup, + retaining explicit null/default compatibility. +- [x] **B13:** fresh-wheel selection controls and the actual invocation-owned + wheel build, clean-environment installation and isolated import smoke passed. +- [x] **B14:** metadata-selected confined experiment configuration reaches + real dimension-aware rendering. +- [x] **B15:** relocated composition preserves and resolves local resources; + code, citations, external URLs, titles, queries, and fragments are retained. +- [x] **B16:** one tracked notebook inventory feeds validation/execution; + real prepared-kernel execution passed without source output refresh. +- [x] **B17:** the teaching example owns its seeded generator independently + of the global NumPy stream. +- [x] **B18:** explicit corpus paths are admitted before workspace/provider + mutation; offline/literal/default modes retain their existing contracts. +- [x] **BO1:** document independent graph worlds versus shared occupancy + without introducing graph-world collision resolution. +- [ ] **BO2:** elective optimization/benchmark work requires owner selection, + measured workloads, and RNG/invalid-input parity; no speedup claimed. +- [x] **BO3:** current documentation link/anchor validation passed after + replacing retired worker instructions and obsolete GRT descriptions. +- [ ] **BO4:** optional adapter qualification remains elective and unclaimed; + do not reopen its already-set floor or infer incompatibility. +- [x] **BT01:** retire only the lane's legacy `ignored.csv` with its matching + ignore rule. Original bytes remain under private owner-managed custody; + no canonical-original deletion or broader CSV cleanup is implied. + +Final quality, full required gates, exact-merge-head proof, hosted CI, review, +and ordinary governed integration remain open. Existing measurements are not +rewritten, scientific/owner approvals are not inferred, and canonical figures, +manuscript outputs, private evidence, and retained storage stay preserved. ## Verification notes diff --git a/blockference/config/README.md b/blockference/config/README.md index e024093..5743a26 100644 --- a/blockference/config/README.md +++ b/blockference/config/README.md @@ -28,11 +28,20 @@ Each dataclass enforces invariants in `__post_init__`: * `timesteps >= 1`, `runs >= 1`, `n_agents >= 1`. * List fields read from YAML are coerced to tuples where the schema expects coordinates. -* `simulation.initial_states`, when supplied, must contain exactly one - coordinate per configured agent; otherwise `initial_state` is broadcast. +* `simulation.initial_states` must contain one distinct coordinate per agent. + The `initial_state` compatibility default applies only to a single agent. If validation fails, the loader raises `ValueError` *immediately*; the caller never sees a partially-valid config. +YAML/TOML roots must be mappings. Empty/comment-only YAML and explicit `null` +retain default configuration; `false`, zero, empty-string and list roots do +not. Nested null compatibility does not weaken unknown-key rejection. + +`load_manuscript_experiment` resolves the metadata's nonempty +`experiment.config_path` inside the selected repository and uses this same +typed loader. Missing, absolute, or escaping selections fail without a +hardcoded manuscript-config fallback. + See [`AGENTS.md`](AGENTS.md) for editing rules and the [`configs/README.md`](../../configs/README.md) for the user-facing schema. diff --git a/blockference/config/__init__.py b/blockference/config/__init__.py index cb62074..5d9b9be 100644 --- a/blockference/config/__init__.py +++ b/blockference/config/__init__.py @@ -7,6 +7,7 @@ OutputConfig, SimulationConfig, load_experiment_config, + load_manuscript_experiment, ) __all__ = [ @@ -16,4 +17,5 @@ "SUPPORTED_ENGINES", "SimulationConfig", "load_experiment_config", + "load_manuscript_experiment", ] diff --git a/blockference/config/experiment.py b/blockference/config/experiment.py index c7fbaeb..ba83fcc 100644 --- a/blockference/config/experiment.py +++ b/blockference/config/experiment.py @@ -233,7 +233,9 @@ def load_experiment_config(path: str | Path) -> ExperimentConfig: raise FileNotFoundError(f"config file not found: {config_path}") if config_path.suffix.lower() in {".yml", ".yaml"}: with config_path.open("r", encoding="utf-8") as stream: - data = yaml.safe_load(stream) or {} + data = yaml.safe_load(stream) + if data is None: + data = {} elif config_path.suffix.lower() == ".toml": with config_path.open("rb") as stream: data = tomllib.load(stream) @@ -242,6 +244,23 @@ def load_experiment_config(path: str | Path) -> ExperimentConfig: return ExperimentConfig.from_dict(data) +def load_manuscript_experiment( + root: str | Path, metadata: Mapping[str, Any], +) -> tuple[Path, ExperimentConfig]: + """Load the metadata-selected, repository-confined typed experiment.""" + if not isinstance(metadata, Mapping): + raise TypeError("manuscript metadata must be a mapping") + experiment = _mapping(metadata.get("experiment"), "manuscript experiment") + selection = experiment.get("config_path") + if not isinstance(selection, str) or not selection.strip() or Path(selection).is_absolute(): + raise ValueError("experiment.config_path must be a non-empty repository-relative path") + repository = Path(root).resolve() + path = (repository / selection).resolve() + if not path.is_relative_to(repository): + raise ValueError("experiment.config_path escapes the repository") + return path, load_experiment_config(path) + + __all__ = [ "SUPPORTED_ENGINES", "ExperimentConfig", @@ -249,4 +268,5 @@ def load_experiment_config(path: str | Path) -> ExperimentConfig: "OutputConfig", "SimulationConfig", "load_experiment_config", + "load_manuscript_experiment", ] diff --git a/blockference/envs/README.md b/blockference/envs/README.md index 14fb20d..56e2641 100644 --- a/blockference/envs/README.md +++ b/blockference/envs/README.md @@ -1,5 +1,15 @@ # Environments `GridWorld` is the package environment. It uses `(y, x)` coordinates, validates -all positions and actions, and resolves simultaneous transitions -deterministically: occupied targets, competing targets, and swaps are rejected. +all positions and actions, and resolves simultaneous shared-world transitions. +Initially occupied targets and swaps are refused; free-cell conflicts retain +the deterministic `(type name, repr)` priority. + +Built-in `int` and `str` agent IDs retain their types and registry order in +version-2 serialization. Sequence actions follow that registry order; integer +`1` and string `"1"` do not collapse into one JSON key. Unsupported Hashables, +duplicate IDs, malformed typed records, and lossy legacy payloads are rejected. + +`p_actinf_dict` uses shared occupancy and realized-state priors. +`actinf_graph` nodes have independent worlds: equal coordinates across nodes +are not collisions. See [`../../docs/design-contract.md`](../../docs/design-contract.md). diff --git a/blockference/envs/grid_world.py b/blockference/envs/grid_world.py index 21ad938..4cf0b12 100644 --- a/blockference/envs/grid_world.py +++ b/blockference/envs/grid_world.py @@ -2,7 +2,7 @@ from __future__ import annotations -from collections.abc import Hashable, Mapping, Sequence +from collections.abc import Mapping, Sequence import numpy as np @@ -10,6 +10,22 @@ from blockference.gridference import _move +def _encode_identity(value: int | str) -> dict: + if type(value) not in (int, str): + raise TypeError("GridWorld agent identities must be built-in int or str") + return {"type": type(value).__name__, "value": value} + + +def _decode_identity(payload: object) -> int | str: + if not isinstance(payload, dict) or set(payload) != {"type", "value"}: + raise ValueError("agent identity must contain type and value") + value = payload["value"] + if payload["type"] not in ("int", "str") or type(value).__name__ != payload["type"]: + raise ValueError("agent identity tag does not match its int/str value") + _encode_identity(value) + return value + + def _coordinate(value: Sequence[int], field_name: str, dimension: int) -> tuple[int, int]: if isinstance(value, (str, bytes)) or len(value) != 2: raise ValueError(f"{field_name} must be a (y, x) coordinate") @@ -21,18 +37,18 @@ def _coordinate(value: Sequence[int], field_name: str, dimension: int) -> tuple[ return coordinate -def _agent_order(agent_ids: Sequence[Hashable]) -> list[Hashable]: - """Return a deterministic order that supports mixed identifier types.""" +def _agent_order(agent_ids: Sequence[int | str]) -> list[int | str]: + """Preserve existing type-name/repr conflict priority, not registry order.""" return sorted(agent_ids, key=lambda value: (type(value).__name__, repr(value))) def resolve_moves( - positions: Mapping[Hashable, Sequence[int]], - actions: Mapping[Hashable, int], + positions: Mapping[int | str, Sequence[int]], + actions: Mapping[int | str, int], dimension: int, affordances: Sequence[str] = DEFAULT_AFFORDANCES, -) -> dict[Hashable, tuple[int, int]]: +) -> dict[int | str, tuple[int, int]]: """Resolve simultaneous actions without order-dependent collisions. A target occupied at the beginning of a step remains unavailable, so @@ -44,6 +60,8 @@ def resolve_moves( if isinstance(dimension, bool) or not isinstance(dimension, int) or dimension < 2: raise ValueError("dimension must be an integer >= 2") action_labels = validate_affordances(affordances) + for agent_id in (*positions, *actions): + _encode_identity(agent_id) if set(actions) != set(positions): raise ValueError("actions must contain exactly one action for every agent") current = { @@ -72,12 +90,12 @@ def resolve_moves( class GridWorld: - """Mutable grid environment with deterministic simultaneous transitions.""" + """Mutable grid with ordered built-in int/str identities and shared occupancy.""" def __init__( self, dimension: int, - positions: Mapping[Hashable, Sequence[int]] | None = None, + positions: Mapping[int | str, Sequence[int]] | None = None, *, affordances: Sequence[str] = DEFAULT_AFFORDANCES, stochastic: bool = False, @@ -88,8 +106,9 @@ def __init__( self.border = dimension - 1 self.affordances = validate_affordances(affordances) self.stochastic = bool(stochastic) - self.positions: dict[Hashable, tuple[int, int]] = {} + self.positions: dict[int | str, tuple[int, int]] = {} for agent_id, position in (positions or {}).items(): + _encode_identity(agent_id) self.positions[agent_id] = _coordinate(position, f"positions[{agent_id!r}]", dimension) if len(set(self.positions.values())) != len(self.positions): raise ValueError("positions must contain a unique coordinate for every agent") @@ -101,12 +120,12 @@ def grid(self) -> tuple[tuple[int, int], ...]: return tuple((y, x) for y in range(self.dimension) for x in range(self.dimension)) @property - def current_state(self) -> dict[Hashable, tuple[int, int]]: + def current_state(self) -> dict[int | str, tuple[int, int]]: """Return a defensive copy of current agent positions.""" return dict(self.positions) - def step(self, actions: Mapping[Hashable, int] | Sequence[int]) -> dict[Hashable, tuple[int, int]]: + def step(self, actions: Mapping[int | str, int] | Sequence[int]) -> dict[int | str, tuple[int, int]]: """Apply one action per agent and return the updated positions.""" if isinstance(actions, Mapping): @@ -124,12 +143,16 @@ def step(self, actions: Mapping[Hashable, int] | Sequence[int]) -> dict[Hashable return self.current_state def serialize(self) -> dict: - """Return a JSON-safe, lossless description of the environment state.""" + """Encode typed identities in registry order; reject unsupported Hashables.""" return { + "version": 2, "dimension": self.dimension, "affordances": list(self.affordances), "stochastic": self.stochastic, - "positions": {str(agent_id): list(pos) for agent_id, pos in self.positions.items()}, + "positions": [ + {"agent_id": _encode_identity(agent_id), "position": list(position)} + for agent_id, position in self.positions.items() + ], } @classmethod @@ -137,9 +160,17 @@ def load(cls, payload: dict) -> GridWorld: """Reconstruct a :class:`GridWorld` from a :meth:`serialize` payload.""" if not isinstance(payload, dict): raise TypeError("GridWorld payload must be a mapping") - positions = { - key: value for key, value in payload.get("positions", {}).items() - } + records = payload.get("positions") + if payload.get("version") != 2 or not isinstance(records, list): + raise ValueError("GridWorld requires version-2 ordered typed position records") + positions = {} + for record in records: + if not isinstance(record, dict) or set(record) != {"agent_id", "position"}: + raise ValueError("invalid GridWorld position record") + agent_id = _decode_identity(record["agent_id"]) + if agent_id in positions: + raise ValueError("duplicate GridWorld agent identity") + positions[agent_id] = record["position"] return cls( payload["dimension"], positions, diff --git a/blockference/envs/protocol.py b/blockference/envs/protocol.py index 2ce4e7b..1a5bd76 100644 --- a/blockference/envs/protocol.py +++ b/blockference/envs/protocol.py @@ -5,7 +5,7 @@ persistence, and validation can treat every environment uniformly instead of special-casing the grid. The protocol deliberately covers: -* state identity (a ``positions`` mapping of agent → coordinate), +* state identity (built-in ``int``/``str`` agent IDs mapped to coordinates), * observations (the ``grid`` coordinate set and ``affordances`` vocabulary), * simultaneous actions and collision resolution (``step``), * a frozen ``current_state`` snapshot, @@ -15,7 +15,7 @@ from __future__ import annotations -from collections.abc import Hashable, Mapping, Sequence +from collections.abc import Mapping, Sequence from typing import Protocol, runtime_checkable @@ -31,18 +31,18 @@ class DiscreteEnvironment(Protocol): dimension: int border: int affordances: Sequence[str] - positions: Mapping[Hashable, tuple[int, int]] + positions: Mapping[int | str, tuple[int, int]] stochastic: bool @property def grid(self) -> Sequence[tuple[int, int]]: ... @property - def current_state(self) -> Mapping[Hashable, tuple[int, int]]: ... + def current_state(self) -> Mapping[int | str, tuple[int, int]]: ... def step( - self, actions: Mapping[Hashable, int] | Sequence[int] - ) -> Mapping[Hashable, tuple[int, int]]: ... + self, actions: Mapping[int | str, int] | Sequence[int] + ) -> Mapping[int | str, tuple[int, int]]: ... def serialize(self) -> dict: ... diff --git a/blockference/gnn.py b/blockference/gnn.py index c27f6a9..64d1b04 100644 --- a/blockference/gnn.py +++ b/blockference/gnn.py @@ -133,9 +133,9 @@ def build_spec_model(parameters: GridWorldSpecParameters) -> ActiveGridference: def spec_arrays(parameters: GridWorldSpecParameters | None = None) -> dict[str, np.ndarray]: """Return the declared ``A``/``B``/``C``/``D``/``E`` arrays. - ``E`` is the uniform policy prior over the declared affordances, which is - the GNN convention; the affordance *labels* are declared separately in the - document's ``ModelParameters`` section. + ``E`` is the declaration-only uniform prior over complete policy sequences. + Runtime ``ActiveGridference.E`` remains the ordered action-label vocabulary; + the document declares those labels separately in ``ModelParameters``. """ resolved = parameters or spec_parameters() @@ -145,16 +145,17 @@ def spec_arrays(parameters: GridWorldSpecParameters | None = None) -> dict[str, "B": np.asarray(model.B, dtype=float), "C": np.asarray(model.C, dtype=float), "D": np.asarray(model.D, dtype=float), - "E": np.full(resolved.n_actions, 1.0 / resolved.n_actions, dtype=float), + "E": np.full(resolved.n_policies, 1.0 / resolved.n_policies, dtype=float), } def _format_value(value: float) -> str: - return f"{float(value):.1f}" + return repr(float(value)) def _format_vector(values: Iterable[float]) -> str: - return "(" + ", ".join(_format_value(value) for value in values) + ")" + formatted = [_format_value(value) for value in values] + return "(" + ", ".join(formatted) + (",)" if len(formatted) == 1 else ")") def _format_matrix(matrix: np.ndarray) -> str: @@ -214,7 +215,7 @@ def render_spec(parameters: GridWorldSpecParameters | None = None) -> str: deterministic and column-stochastic: every column selects exactly one next cell, and moves outside the grid clamp to the border. - `C` is a one-hot preference over the preferred cell {preferred}; `D` is a one-hot prior over - the initial cell {initial}; `E` is the uniform policy prior over the {resolved.n_actions} affordances. + the initial cell {initial}; `E` is the uniform prior over the {resolved.n_policies} length-{horizon} policies. - `G` is the expected free energy per policy and `pi` the policy posterior; the pipeline persists both components (`update_efe_epistemic`, `update_efe_pragmatic`) for every step. @@ -225,14 +226,14 @@ def render_spec(parameters: GridWorldSpecParameters | None = None) -> str: B[{n},{n},{resolved.n_actions},type=float] # Transition: B[next_state,previous_state,action] C[{n},type=float] # Preference over observations D[{n},type=float] # Prior over hidden states -E[{resolved.n_actions},type=float] # Policy prior over affordances +E[{resolved.n_policies},type=float] # Uniform prior over complete policies s[{n},1,type=float] # Current hidden state distribution s_prime[{n},1,type=float] # Next hidden state distribution o[{n},1,type=int] # Current observation -pi[{resolved.n_actions},type=float] # Policy posterior over affordances +pi[{resolved.n_policies},type=float] # Posterior over complete policies u[1,type=int] # Sampled affordance index -G[{resolved.n_actions},type=float] # Expected free energy per affordance +G[{resolved.n_policies},type=float] # Expected free energy per policy t[1,type=int] # Discrete time step ## Connections diff --git a/blockference/gnn_runtime.py b/blockference/gnn_runtime.py new file mode 100644 index 0000000..67c6562 --- /dev/null +++ b/blockference/gnn_runtime.py @@ -0,0 +1,41 @@ +"""Select the separate GNN interpreter without importing its NumPy environment.""" + +from __future__ import annotations + +import os +from pathlib import Path + +__all__ = ["resolve_gnn_runtime"] + + +def resolve_gnn_runtime( + explicit: str | Path | None = None, + *, + checkout: str | Path | None = None, + python: str | Path | None = None, + required: bool = True, +) -> str | None: + """Select CLI runtime, runtime environment, legacy Python, then checkout venv. + + Explicitly selected missing files fail without substitution. Keep the venv + launcher path rather than resolving its symlink to a base interpreter. + """ + selected = explicit + if selected is None: + selected = os.environ.get("GNN_RUNTIME_PYTHON") or ( + python if python is not None else os.environ.get("GNN_PYTHON") or None + ) + root = checkout or os.environ.get("GNN_ROOT") + if selected is None and root: + relative = Path("Scripts/python.exe" if os.name == "nt" else "bin/python") + selected = Path(root) / ".venv" / relative + if selected is None: + if required: + raise FileNotFoundError( + "select --gnn-runtime/GNN_RUNTIME_PYTHON or a GNN_ROOT with its own .venv" + ) + return None + candidate = Path(selected).expanduser().absolute() + if not candidate.is_file(): + raise FileNotFoundError(f"selected GNN interpreter does not exist: {candidate}") + return str(candidate) diff --git a/blockference/gnn_source.py b/blockference/gnn_source.py new file mode 100644 index 0000000..21f3ba4 --- /dev/null +++ b/blockference/gnn_source.py @@ -0,0 +1,291 @@ +"""Run exact-pin GNN operations without importing the project NumPy environment. + +Execute this file directly with the selected external interpreter and ``-I -B``. +``GNN_BOOTSTRAP`` selects the independently reviewed producer bootstrap; +``GNN_SOURCE_MANIFEST`` selects its independently frozen complete v5.1.0 manifest. +Their expected hashes are source-owned constants, never target-derived inputs. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import os +import sys +from collections.abc import Iterator +from contextlib import contextmanager +from pathlib import Path +from types import ModuleType +from typing import Any + +__all__ = [ + "BOOTSTRAP_SHA256", + "SOURCE_MANIFEST_SHA256", + "PINNED_COMMIT", + "worker_command", + "pin_report", + "probe", + "check_importer", + "main", +] + +BOOTSTRAP_SHA256 = "f638d4c01fe7de31e43d793e59bf382d0c3d1a82f365c59238334a2b40adfb37" +SOURCE_MANIFEST_SHA256 = "43b33c0b2b40386afa3f306fec4cc13bc1fd7c3b570fbf11d5008bad5c8e6b51" +PINNED_COMMIT = "75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf" +_BOOTSTRAP_NAME = "_blockference_reviewed_gnn_bootstrap" + + +def worker_command(python: str, action: str, *arguments: str) -> list[str]: + """Build an isolated external invocation without resolving the venv launcher.""" + return [python, "-I", "-B", str(Path(__file__).resolve()), action, *arguments] + + +def _resource(name: str) -> Path: + value = os.environ.get(name) + if not value: + raise ValueError(f"{name} must select the independently reviewed producer resource") + return Path(value).expanduser().absolute() + + +@contextmanager +def _bootstrap() -> Iterator[ModuleType]: + # Check once, then compile precisely that buffer. A loader/file reread or + # cached bytecode must never choose the code that executes. + path = _resource("GNN_BOOTSTRAP") + data = path.read_bytes() + if hashlib.sha256(data).hexdigest() != BOOTSTRAP_SHA256: + raise ValueError("bootstrap-hash-mismatch: GNN_BOOTSTRAP is not the reviewed bootstrap") + if _BOOTSTRAP_NAME in sys.modules: + raise ValueError("a reviewed GNN bootstrap session is already active") + module = ModuleType(_BOOTSTRAP_NAME) + module.__file__ = str(path) + sys.modules[_BOOTSTRAP_NAME] = module + try: + exec(compile(data, str(path), "exec", dont_inherit=True), module.__dict__) + yield module + if path.read_bytes() != data: + raise ValueError("bootstrap-changed: reviewed bootstrap changed during the operation") + finally: + del sys.modules[_BOOTSTRAP_NAME] + + +def _read_pin(bootstrap: ModuleType, repo_root: Path) -> Any: + path = bootstrap.find_pin(repo_root) + if path is None: + raise ValueError(f"no GNN pin file found under {repo_root}") + pin = bootstrap.read_pin(path) + if ( + pin.commit != PINNED_COMMIT + or pin.tag != "v5.1.0" + or pin.repository != bootstrap.UPSTREAM_REPOSITORY + ): + raise ValueError("source-pin-mismatch: consumer pin differs from the reviewed v5.1.0 input") + return pin + + +@contextmanager +def _source_path(source_root: Path | None) -> Iterator[Path | None]: + # Source mode is explicit. Installed mode neither reads GNN_ROOT nor honors + # inherited PYTHONPATH in the isolated worker, and never retries as source. + previous = sys.path[:] + try: + package_root = None + if source_root is not None: + source_root = source_root.absolute() + sys.path.insert(0, str(source_root / "src")) + package_root = source_root / "src" / "gnn" + yield package_root + finally: + sys.path[:] = previous + + +def pin_report( + repo_root: Path, *, job: str | None = None, job_name: str | None = None +) -> dict[str, Any]: + """Read pin metadata with the checked producer reader, without importing GNN. + + This is inspection only, including for manuscript variables. Actual parser + and importer verdicts require complete source/origin admission separately. + """ + repo_root = repo_root.resolve() + with _bootstrap() as bootstrap: + pin = _read_pin(bootstrap, repo_root) + payload = { + "mode": "inspection", + "qualified": False, + "runtime_python": sys.executable, + "bootstrap_sha256": BOOTSTRAP_SHA256, + "pin": { + "path": pin.path.relative_to(repo_root).as_posix(), + "schema": pin.schema, + "repository": pin.repository, + "tag": pin.tag, + "commit": pin.commit, + "recorded": pin.recorded, + "spec_files": list(pin.spec_files), + "parser_files": dict(pin.raw.get("parser_files", {})), + }, + "variables": bootstrap.importer_variables( + pin, repo_root=repo_root, job=job, job_name=job_name, + ), + } + return payload + + +def _jsonable(value: Any) -> Any: + if isinstance(value, dict): + return {str(key): _jsonable(item) for key, item in value.items()} + if isinstance(value, (list, tuple)): + return [_jsonable(item) for item in value] + if isinstance(value, (str, int, float, bool)) or value is None: + return value + return str(value) + + +def probe(repo_root: Path, spec: Path, *, source_root: Path | None = None) -> dict[str, Any]: + """Parse and run all pinned validators inside one producer-qualified lifetime. + + Only JSON data escapes. Imports, parser objects, validators and conversions + all finish before the producer revalidates the complete inventory/origin. + """ + with _bootstrap() as bootstrap: + pin = _read_pin(bootstrap, repo_root.resolve()) + manifest = _resource("GNN_SOURCE_MANIFEST").read_bytes() + with _source_path(source_root) as package_root: + with bootstrap.qualified_source( + pin, + manifest=manifest, + manifest_sha256=SOURCE_MANIFEST_SHA256, + package_root=package_root, + origin_mode="source" if source_root is not None else "installed", + ) as qualification: + import gnn + from gnn.parsers.markdown_parser import MarkdownGNNParser + from gnn.validation.consistency_checker import check_consistency + from gnn.validation.orientation import check_b_orientation + from gnn.validation.semantic_validator import SemanticValidator + + result = MarkdownGNNParser().parse_file(str(spec)) + model = result.model + semantic = SemanticValidator().validate(spec.read_text(encoding="utf-8")) + orientation = check_b_orientation(spec) + consistency = check_consistency(spec) + payload = { + "runtime_python": sys.executable, + "gnn_version": gnn.__version__, + "gnn_module": gnn.__file__, + "parser": { + "success": bool(result.success), + "errors": list(result.errors), + "warnings": list(result.warnings), + "model_name": model.model_name, + "version": model.version, + "variables": [ + { + "name": variable.name, + "dimensions": list(variable.dimensions), + "data_type": str(variable.data_type), + } + for variable in model.variables + ], + "connections": [ + { + "sources": list(connection.source_variables), + "targets": list(connection.target_variables), + "type": str(connection.connection_type), + } + for connection in model.connections + ], + "ontology_mappings": [ + {"variable": mapping.variable_name, "term": mapping.ontology_term} + for mapping in model.ontology_mappings + ], + "parameters": { + parameter.name: _jsonable(parameter.value) + for parameter in model.parameters + }, + "sections": sorted(model.raw_sections), + "time_specification": _jsonable(model.time_specification), + }, + "semantic": _jsonable(semantic), + "orientation": _jsonable(orientation), + "consistency": _jsonable(consistency), + } + # Freeze primitive data while GNN-derived values are still in + # scope; no lazy objects/callables cross the admission boundary. + payload = json.loads(json.dumps(payload)) + payload["source_qualification"] = qualification + return payload + + +def check_importer( + repo_root: Path, *, source_root: Path | None = None, + workflow: str = ".github/workflows/ci.yml", job: str = "gnn-conformance", +) -> dict[str, Any]: + """Run the producer's real pin/pointer/syntax check with full source admission.""" + repo_root = repo_root.resolve() + with _bootstrap() as bootstrap: + _read_pin(bootstrap, repo_root) + manifest = _resource("GNN_SOURCE_MANIFEST").read_bytes() + with _source_path(source_root) as package_root: + payload = bootstrap.check_importer( + repo_root, + expected_commit=PINNED_COMMIT, + expected_tag="v5.1.0", + require_pointer=True, + pointer_workflow=workflow, + pointer_job=job, + source_manifest=manifest, + source_manifest_sha256=SOURCE_MANIFEST_SHA256, + package_root=package_root, + origin_mode="source" if source_root is not None else "installed", + ) + payload["runtime_python"] = sys.executable + # The producer refuses to call an empty/inspection-only result qualified. + # Preserve that distinction even when no syntax error was encountered. + payload["ok"] = bool(payload["ok"] and payload["qualified"]) + return payload + + +def main(argv: list[str] | None = None) -> int: + """Run one fresh-process operation and publish only after exit revalidation.""" + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("action", choices=("inspect", "probe", "check")) + parser.add_argument("--repo", type=Path, default=Path(__file__).resolve().parents[1]) + parser.add_argument("--spec", type=Path) + parser.add_argument("--source-root", type=Path) + parser.add_argument("--output", type=Path) + parser.add_argument("--workflow", default=".github/workflows/ci.yml") + parser.add_argument("--job") + parser.add_argument("--job-name") + args = parser.parse_args(argv) + if args.action == "probe" and args.spec is None: + parser.error("probe requires --spec") + try: + if args.action == "inspect": + payload = pin_report(args.repo, job=args.job, job_name=args.job_name) + elif args.action == "probe": + payload = probe(args.repo, args.spec, source_root=args.source_root) + else: + payload = check_importer( + args.repo, source_root=args.source_root, + workflow=args.workflow, job=args.job or "gnn-conformance", + ) + except (OSError, ValueError, ImportError) as exc: + code = getattr(exc, "code", "source-unavailable") + print(f"gnn operation not run: {code}: {exc}", file=sys.stderr) + return 2 + text = json.dumps(payload, indent=2, sort_keys=True) + "\n" + if args.output is not None: + args.output.parent.mkdir(parents=True, exist_ok=True) + args.output.write_text(text, encoding="utf-8") + sys.stdout.write(text) + if args.action == "check" and not payload["ok"]: + qualification = payload["source_qualification"] + return 1 if qualification["ok"] and qualification["imports_verified"] else 2 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/blockference/io/persist.py b/blockference/io/persist.py index c62f475..9fa3a14 100644 --- a/blockference/io/persist.py +++ b/blockference/io/persist.py @@ -77,20 +77,28 @@ def _write(target: Path) -> None: return atomic_replace(paths.config_path, _write) -def persist_dataframe(df: pd.DataFrame, paths: RunPaths) -> dict[str, Path]: - """Write a documented nested-value trajectory as CSV and optional Parquet.""" +def persist_dataframe( + df: pd.DataFrame, paths: RunPaths, *, models: dict[tuple[int, str], Any] +) -> dict[str, Path]: + """Write a trajectory whose agent references bind each run's immutable model.""" paths.require_tree() written: dict[str, Path] = {} serialised = df.copy() + references = { + key: {"agent_id": key[1], "model_sha256": _model_digest(_model_payload(agent))} + for key, agent in models.items() + } for column in ("agents", "priors", "env_states", "actions", "inferences", "efe", "efe_epistemic", "efe_pragmatic", "q_pi", "p_u", "obs_idx"): if column not in serialised: continue if column == "agents": - serialised[column] = serialised[column].map( - lambda value: {str(key): {"agent_id": str(key)} for key in value} - if isinstance(value, dict) - else value - ) + serialised[column] = [ + { + str(agent_id): references[(int(run), str(agent_id))] + for agent_id in agents + } + for run, agents in zip(df["run"], df["agents"], strict=True) + ] else: serialised[column] = serialised[column].map(_to_jsonable) atomic_replace(paths.trajectory_csv, lambda target: serialised.to_csv(target, index=False)) @@ -112,32 +120,39 @@ def persist_summary(summary: dict[str, Any], paths: RunPaths) -> Path: return _atomic_json(paths.summary_json, _to_jsonable(summary)) -def persist_generative_model(agents: dict, paths: RunPaths) -> Path: - """Persist each agent's A/B/C/D/E matrices to a single JSON file. +def _model_payload(agent: Any) -> dict[str, Any]: + return { + "n_states": int(getattr(agent, "n_states", 0)), + "n_observations": int(getattr(agent, "n_observations", 0)), + "border": int(getattr(agent, "border", 0)), + "policy_len": int(getattr(agent, "policy_len", 0)), + "max_policies": int(getattr(agent, "max_policies", 100_000)), + "E": list(getattr(agent, "E", [])), + **{name: _to_jsonable(getattr(agent, name, None)) for name in ("A", "B", "C", "D")}, + } - Parameters - ---------- - agents : - ``{agent_id: ActiveGridference}`` mapping. Only the public matrices - are serialised; per-step state is captured in :func:`persist_per_step_records`. - """ + +def _model_digest(payload: dict[str, Any]) -> str: + encoded = json.dumps(payload, sort_keys=True, separators=(",", ":"), allow_nan=False) + return hashlib.sha256(encoded.encode("utf-8")).hexdigest() + + +def _run_payload(values: dict[tuple[int, str], Any]) -> dict[str, Any]: + runs: dict[str, dict[str, Any]] = {} + for (run, agent_id), value in values.items(): + if type(run) is not int or run < 1 or not isinstance(agent_id, str) or not agent_id: + raise ValueError("model keys must be (positive run, non-empty agent ID string)") + runs.setdefault(str(run), {})[agent_id] = value + return {"version": 2, "runs": runs} + + +def persist_generative_model(agents: dict[tuple[int, str], Any], paths: RunPaths) -> Path: + """Persist immutable A/B/C/D/E and planning metadata by ``(run, agent)``.""" paths.require_tree() if not agents: raise ValueError("at least one agent is required to persist a generative model") - payload: dict[str, Any] = {} - for agent_id, agent in agents.items(): - payload[str(agent_id)] = { - "n_states": int(getattr(agent, "n_states", 0)), - "n_observations": int(getattr(agent, "n_observations", 0)), - "border": int(getattr(agent, "border", 0)), - "policy_len": int(getattr(agent, "policy_len", 0)), - "E": list(getattr(agent, "E", [])), - "A": _to_jsonable(getattr(agent, "A", None)), - "B": _to_jsonable(getattr(agent, "B", None)), - "C": _to_jsonable(getattr(agent, "C", None)), - "D": _to_jsonable(getattr(agent, "D", None)), - } - return _atomic_json(paths.matrices_json, payload) + payload = {key: _model_payload(agent) for key, agent in agents.items()} + return _atomic_json(paths.matrices_json, _run_payload(payload)) def persist_per_step_records(records: list[dict[str, Any]], paths: RunPaths) -> Path: @@ -159,20 +174,14 @@ def persist_per_step_records(records: list[dict[str, Any]], paths: RunPaths) -> return paths.per_step_csv -def persist_generative_model_npz(agents: dict, paths: RunPaths) -> Path: - """Persist each agent's A/B/C/D matrices to a single ``.npz`` archive. - - Keys are namespaced ``/`` so a single - ``np.load(...)`` call exposes every array losslessly (no JSON precision - drift). Useful when downstream consumers want to instantiate a pymdp - ``Agent`` from the persisted matrices. - """ +def persist_generative_model_npz(agents: dict[tuple[int, str], Any], paths: RunPaths) -> Path: + """Persist matrices with ``run_/agent_/`` archive keys.""" paths.require_tree() if not agents: raise ValueError("at least one agent is required to persist matrices") payload: dict[str, np.ndarray] = {} - for agent_id, agent in agents.items(): - prefix = f"agent_{agent_id}" + for (run, agent_id), agent in agents.items(): + prefix = f"run_{run}/agent_{agent_id}" for name in ("A", "B", "C", "D"): arr = getattr(agent, name, None) if arr is None: @@ -219,16 +228,16 @@ def _write(target: Path) -> None: return atomic_replace(paths.manifest_json, _write) -def persist_policies(policies: list, paths: RunPaths) -> Path: - """Persist the enumerated policy set.""" +def persist_policies(policies: dict[tuple[int, str], list], paths: RunPaths) -> Path: + """Persist each run/agent's actual allowed, ordered policy set.""" paths.require_tree() - if not policies: - raise ValueError("at least one policy is required") - payload = [_to_jsonable(p) for p in policies] - return _atomic_json( - paths.policies_json, - {"n_policies": len(policies), "policies": payload}, - ) + if not policies or any(not values for values in policies.values()): + raise ValueError("at least one policy per run/agent is required") + payload = { + key: {"n_policies": len(values), "policies": [_to_jsonable(p) for p in values]} + for key, values in policies.items() + } + return _atomic_json(paths.policies_json, _run_payload(payload)) def _to_jsonable(obj: Any) -> Any: diff --git a/blockference/io/validate.py b/blockference/io/validate.py index b34d37f..4c6df4b 100644 --- a/blockference/io/validate.py +++ b/blockference/io/validate.py @@ -9,6 +9,7 @@ from pathlib import Path from types import SimpleNamespace from typing import Any +from zipfile import BadZipFile import numpy as np import pandas as pd @@ -16,6 +17,8 @@ from blockference.config import load_experiment_config from blockference.io.layout import RunPaths +from blockference.io.persist import _model_digest +from blockference.maths import construct_policies REQUIRED_TRAJECTORY_COLUMNS: tuple[str, ...] = ( "agents", @@ -129,6 +132,86 @@ def _coordinate(value: Any) -> tuple[int, int] | None: return int(parsed[0]), int(parsed[1]) +def _index(value: Any, minimum: int = 0) -> int | None: + if isinstance(value, (bool, np.bool_)): + return None + try: + number = float(value) + except (TypeError, ValueError, OverflowError): + return None + if not np.isfinite(number) or not number.is_integer() or number < minimum: + return None + return int(number) + + +def _agent_id(value: Any) -> str | None: + if isinstance(value, (bool, np.bool_)) or not isinstance(value, (str, int, np.integer)): + return None + number = _index(value) + return str(number) if number is not None and str(value) == str(number) else None + + +def _row_identity(row: Any) -> tuple[int, int, int] | None: + run = _index(row.get("run"), 1) + time = _index(row.get("timestep")) + substep = _index(row.get("substep")) + if run is None or time is None or substep is None: + return None + return run, time, substep + + +def _trajectory_rows(trajectory: Any) -> dict | None: + if ( + not isinstance(trajectory, pd.DataFrame) or trajectory.empty + or any(column not in trajectory for column in REQUIRED_TRAJECTORY_COLUMNS) + ): + return None + rows = {} + for _, row in trajectory.iterrows(): + key = _row_identity(row) + if key is None or key in rows: + return None + rows[key] = row + return rows + + +def _expected_model_keys(config: Any) -> set[tuple[int, str]]: + return { + (run, str(agent)) for run in range(1, config.simulation.runs + 1) + for agent in range(config.simulation.n_agents) + } + + +def _expected_schedule(config: Any) -> set[tuple[int, int, int]]: + # Both adapters run the single canonical update block and retain its initial row. + return { + (run, time, int(time > 0)) + for run in range(1, config.simulation.runs + 1) + for time in range(config.simulation.timesteps + 1) + } + + +def _run_records(payload: Any) -> dict[tuple[int, str], Any]: + if not isinstance(payload, dict) or payload.get("version") != 2: + raise ValueError("expected a version-2 run/agent artifact") + runs = payload.get("runs") + if not isinstance(runs, dict) or not runs: + raise ValueError("runs must be a non-empty mapping") + records = {} + for run_label, agents in runs.items(): + run = _index(run_label, 1) + if run is None or str(run) != run_label or not isinstance(agents, dict) or not agents: + raise ValueError("invalid run registry") + for agent_label, value in agents.items(): + agent = _agent_id(agent_label) + if agent is None: + raise ValueError("invalid configured agent ID") + records[(run, agent)] = value + return records + + + + def validate_trajectory_dataframe(df: pd.DataFrame) -> ValidationReport: """Validate trajectory columns, row values, and nested state structure.""" @@ -205,11 +288,16 @@ def validate_trajectory_dataframe(df: pd.DataFrame) -> ValidationReport: except (TypeError, ValueError): finite_indices = False report.add("finite_row_indices", finite_indices, "row indices are not numeric") + report.add( + "unique_row_identities", _trajectory_rows(df) is not None, + "run/timestep/substep identities are invalid or duplicated", + ) return report def validate_per_step_records( - records: list[dict[str, Any]], *, n_states: int | None = None, n_actions: int | None = None + records: list[dict[str, Any]], *, n_states: int | None = None, + n_actions: int | None = None, n_policies: int | None = None, ) -> ValidationReport: """Validate complete per-agent diagnostics for every simulation step. @@ -282,12 +370,15 @@ def validate_per_step_records( posterior.shape != prior.shape or efe.shape != epistemic.shape or efe.shape != pragmatic.shape + or efe.shape != q_pi.shape ): bad_shapes += 1 if n_states is not None and (posterior.size != n_states or prior.size != n_states): bad_dimensions += 1 if n_actions is not None and p_u.size != n_actions: bad_dimensions += 1 + if n_policies is not None and (efe.size != n_policies or q_pi.size != n_policies): + bad_dimensions += 1 valid_action = isinstance(action, (int, np.integer)) and not isinstance(action, bool) valid_observation = isinstance(observation, (int, np.integer)) and not isinstance( observation, bool @@ -334,9 +425,9 @@ def _probability_matrix( except (TypeError, ValueError) as exc: return None, str(exc) if array.shape != shape: - return array, f"expected shape {shape}, got {array.shape}" + return None, f"expected shape {shape}, got {array.shape}" if not np.isfinite(array).all() or (array < 0).any(): - return array, "contains non-finite or negative probabilities" + return None, "contains non-finite or negative probabilities" return array, None @@ -489,7 +580,7 @@ def _validate_manifest(paths: RunPaths) -> ValidationReport: f"extra={sorted(listed - actual)}", ) report.add("digests", failures == 0, f"{failures} manifest entries do not match") - except (OSError, json.JSONDecodeError, AttributeError, TypeError): + except (OSError, UnicodeError, json.JSONDecodeError, AttributeError, TypeError): report.add("parses", False, "manifest is not valid JSON") return report @@ -576,91 +667,66 @@ def validate_trajectory_boundary( summary_payload is not None and {"n_rows", "n_agents", "grid_dimension"} <= set(summary_payload), ) - except (OSError, json.JSONDecodeError) as exc: + except (OSError, UnicodeError, json.JSONDecodeError) as exc: report.add("summary_parses", False, str(exc)) return report, trajectory, summary_payload def validate_model_boundary( paths: RunPaths, config: Any -) -> tuple[ValidationReport, dict[str, Any] | None]: - """Validate the persisted generative model JSON and its NPZ archive. - - Returns ``(report, model_payload)`` so the aggregator can run the - config-vs-model cross-checks against the parsed payload. - """ +) -> tuple[ValidationReport, dict[tuple[int, str], Any] | None]: + """Validate every run/agent model and exact JSON/NPZ correspondence.""" report = ValidationReport() - model_payload = None - if _file_nonempty(paths.matrices_json): - try: - model_payload = json.loads(paths.matrices_json.read_text(encoding="utf-8")) - valid_payload = isinstance(model_payload, dict) and bool(model_payload) - report.add("generative_model_parses", valid_payload) - if isinstance(model_payload, dict) and model_payload: - for agent_id, payload in model_payload.items(): - if not isinstance(payload, dict): - report.add( - f"model.{agent_id}.payload", - False, - "agent model payload must be a mapping", - ) - continue - report.merge( - f"model.{agent_id}", - validate_generative_model(_model_from_payload(payload)), + models: dict[tuple[int, str], Any] | None = None + try: + models = _run_records(json.loads(paths.matrices_json.read_text(encoding="utf-8"))) + report.add("generative_model_parses", True) + for (run, agent), payload in models.items(): + name = f"model.run_{run}.agent_{agent}" + if not isinstance(payload, dict): + report.add(f"{name}.payload", False, "agent model must be a mapping") + continue + report.merge(name, validate_generative_model(_model_from_payload(payload))) + except (OSError, UnicodeError, ValueError, TypeError) as exc: + report.add("generative_model_parses", False, str(exc)) + models = None + try: + with np.load(paths.matrices_npz, allow_pickle=False) as archive: + arrays = {key: np.asarray(archive[key]) for key in archive.files} + report.add("generative_model_npz_parses", True) + expected = { + f"run_{run}/agent_{agent}/{name}" + for run, agent in (models or {}) for name in ("A", "B", "C", "D", "E") + } + report.add( + "generative_model_npz_complete", bool(models) and set(arrays) == expected, + "NPZ keys must match every and only the JSON run/agent matrices", + ) + failures = 0 + for (run, agent), payload in (models or {}).items(): + if not isinstance(payload, dict): + failures += 1 + continue + for name in ("A", "B", "C", "D", "E"): + try: + wanted = np.asarray(payload[name]) + actual = arrays[f"run_{run}/agent_{agent}/{name}"] + equal = wanted.shape == actual.shape and ( + np.array_equal(wanted, actual) if name == "E" + else np.allclose(wanted, actual, atol=0.0, rtol=0.0) ) - if not valid_payload: - model_payload = None - except (OSError, AttributeError, json.JSONDecodeError, TypeError) as exc: - report.add("generative_model_parses", False, str(exc)) - model_payload = None + except (KeyError, TypeError, ValueError): + equal = False + failures += int(not equal) + report.add( + "generative_model_npz_values", bool(models) and failures == 0, + f"{failures} JSON/NPZ matrix values differ", + ) + except (OSError, ValueError, KeyError, TypeError, EOFError, BadZipFile) as exc: + report.add("generative_model_npz_parses", False, str(exc)) + return report, models + - if _file_nonempty(paths.matrices_npz): - try: - with np.load(paths.matrices_npz, allow_pickle=False) as archive: - keys = set(archive.files) - npz_arrays = {key: np.asarray(archive[key]) for key in archive.files} - expected = { - f"agent_{agent_id}/{name}" - for agent_id in (model_payload or {}) - for name in ("A", "B", "C", "D", "E") - } - report.add( - "generative_model_npz_complete", - expected <= keys, - f"missing keys: {sorted(expected - keys)}", - ) - value_failures = 0 - if isinstance(model_payload, dict): - for agent_id, payload in model_payload.items(): - if not isinstance(payload, dict): - continue - for name in ("A", "B", "C", "D", "E"): - key = f"agent_{agent_id}/{name}" - if key not in npz_arrays or name not in payload: - value_failures += 1 - continue - try: - json_array = np.asarray(payload[name]) - npz_array = npz_arrays[key] - equal = ( - np.array_equal(json_array, npz_array) - if name == "E" - else json_array.shape == npz_array.shape - and np.allclose(json_array, npz_array, atol=0.0, rtol=0.0) - ) - if not equal: - value_failures += 1 - except (TypeError, ValueError): - value_failures += 1 - report.add( - "generative_model_npz_values", - value_failures == 0, - f"{value_failures} JSON/NPZ matrix values differ", - ) - except (OSError, ValueError, KeyError) as exc: - report.add("generative_model_npz_parses", False, str(exc)) - return report, model_payload def validate_manifest_boundary(paths: RunPaths) -> ValidationReport: @@ -671,158 +737,345 @@ def validate_manifest_boundary(paths: RunPaths) -> ValidationReport: return report -def validate_policies_boundary(paths: RunPaths) -> ValidationReport: - """Validate the persisted policy set JSON.""" +def validate_policies_boundary( + paths: RunPaths, config: Any, models: dict | None +) -> ValidationReport: + """Require every run/agent's complete, ordered, actually allowed policies.""" report = ValidationReport() - if _file_nonempty(paths.policies_json): + try: + records = _run_records(json.loads(paths.policies_json.read_text(encoding="utf-8"))) + report.add("policies_parses", True) + except (OSError, UnicodeError, ValueError, TypeError) as exc: + report.add("policies_parses", False, str(exc)) + return report + ready = config is not None and models is not None + report.add("policies_prerequisites", ready) + if not ready: + return report + assert models is not None + report.add( + "policies_run_agent_coverage", set(records) == _expected_model_keys(config) == set(models), + "policy identities differ from configuration or models", + ) + try: + expected = construct_policies( + [config.grid.dimension**2], [len(config.grid.affordances)], + policy_len=config.grid.planning_length, max_policies=config.grid.max_policies, + ) + except (TypeError, ValueError, OverflowError) as exc: + report.add("policies_complete_ordered", False, str(exc)) + return report + failures = 0 + for record in records.values(): + if not isinstance(record, dict): + failures += 1 + continue + values = record.get("policies") + if not isinstance(values, list) or not values: + failures += 1 + continue + valid = ( + type(record.get("n_policies")) is int + and record["n_policies"] == len(values) == len(expected) + ) try: - policy_payload = json.loads(paths.policies_json.read_text(encoding="utf-8")) - policies = policy_payload.get("policies") if isinstance(policy_payload, dict) else None - report.add("policies_parses", isinstance(policies, list) and bool(policies)) - report.add( - "policies_count_consistent", - isinstance(policy_payload, dict) - and policy_payload.get("n_policies") == len(policies or []), - ) - except (OSError, json.JSONDecodeError) as exc: - report.add("policies_parses", False, str(exc)) + for value, policy in zip(values, expected, strict=True): + array = np.asarray(value) + valid = valid and array.dtype.kind in "iu" and np.array_equal(array, policy) + except (TypeError, ValueError): + valid = False + failures += int(not valid) + report.add("policies_complete_ordered", failures == 0, f"{failures} invalid policy sets") return report + + def validate_per_step_boundary( - paths: RunPaths, config: Any, trajectory: Any + paths: RunPaths, config: Any, trajectory: Any, models: dict | None ) -> ValidationReport: - """Parse and validate the persisted per-step diagnostics records.""" + """Require one correctly associated diagnostic per configured run/time/agent.""" report = ValidationReport() - if _file_nonempty(paths.per_step_csv): - try: - per_step_frame = pd.read_csv(paths.per_step_csv) - records = [ - {column: _literal(value) for column, value in row.items()} - for row in per_step_frame.to_dict(orient="records") - ] - report.merge( - "per_step", - validate_per_step_records( - records, - n_states=config.grid.dimension**2 if config is not None else None, - n_actions=len(config.grid.affordances) if config is not None else None, - ), - ) - if config is not None and trajectory is not None: - expected_records = sum( - int(float(value)) > 0 for value in trajectory["timestep"] - ) * config.simulation.n_agents - report.add( - "per_step_coverage", - len(records) == expected_records, - f"expected {expected_records} records, found {len(records)}", - ) - except (OSError, pd.errors.ParserError, ValueError) as exc: - report.add("per_step_csv_parses", False, str(exc)) + try: + frame = pd.read_csv(paths.per_step_csv) + records = [ + {column: _literal(value) for column, value in record.items()} + for record in frame.to_dict(orient="records") + ] + report.add("per_step_csv_parses", True) + except (OSError, UnicodeError, pd.errors.ParserError, ValueError) as exc: + report.add("per_step_csv_parses", False, str(exc)) + return report + rows = _trajectory_rows(trajectory) + ready = config is not None and rows is not None and models is not None + report.add("per_step_prerequisites", ready, "config, keyed trajectory and models are required") + if not ready: + return report + assert rows is not None and models is not None + expected = { + (*key, str(agent)) for key in _expected_schedule(config) if key[1] > 0 + for agent in range(config.simulation.n_agents) + } + seen = set() + bad_keys = bad_values = 0 + columns = { + "env_state": "env_states", "action": "actions", "obs_idx": "obs_idx", + "posterior": "inferences", "prior": "priors", "efe": "efe", + "efe_epistemic": "efe_epistemic", "efe_pragmatic": "efe_pragmatic", + "q_pi": "q_pi", "p_u": "p_u", + } + for index, record in enumerate(records): + identity = _row_identity(record) + agent = _agent_id(record.get("agent_id")) + key = (*identity, agent) if identity is not None and agent is not None else None + if key is None or key in seen or key not in expected: + bad_keys += 1 + if key is not None: + seen.add(key) + model = models.get((identity[0], agent)) if identity is not None else None + if not isinstance(model, dict): + report.add(f"per_step.{index}.model", False, "no model for this run/agent") + continue + report.merge( + f"per_step.{index}", validate_per_step_records( + [record], n_states=config.grid.dimension**2, + n_actions=len(config.grid.affordances), + n_policies=len(config.grid.affordances)**config.grid.planning_length, + ), + ) + row = rows.get(identity) + if row is None: + bad_values += 1 + continue + for diagnostic, column in columns.items(): + mapping = _literal(row[column]) + try: + value = next( + value for label, value in mapping.items() if _agent_id(label) == agent + ) if isinstance(mapping, dict) else None + actual = record.get(diagnostic) + if diagnostic in ("action", "obs_idx"): + equal = ( + isinstance(actual, (int, np.integer)) + and not isinstance(actual, (bool, np.bool_)) + and isinstance(value, (int, np.integer)) + and not isinstance(value, (bool, np.bool_)) + and actual == value + ) + else: + actual, wanted = np.asarray(actual, dtype=float), np.asarray(value, dtype=float) + equal = actual.shape == wanted.shape and np.allclose( + actual, wanted, atol=1e-12, rtol=1e-12, + ) + except (TypeError, ValueError, StopIteration): + equal = False + bad_values += int(not equal) + report.add( + "per_step_coverage", bad_keys == 0 and seen == expected and len(records) == len(expected), + "diagnostics must have unique, complete configured run/time/agent identities", + ) + report.add("per_step_trajectory_values", bad_values == 0, f"{bad_values} keyed diagnostics differ") return report + + def validate_config_trajectory_agreement( - config: Any, - trajectory: Any, - summary_payload: dict[str, Any] | None, + config: Any, trajectory: Any, summary_payload: dict[str, Any] | None, ) -> ValidationReport: - """Cross-check trajectory contents and summary against the persisted config.""" + """Check exact backend schedules, every run's starts and run-scoped summaries.""" report = ValidationReport() - if config is None or trajectory is None or "env_states" not in trajectory: + rows = _trajectory_rows(trajectory) + ready = config is not None and rows is not None + report.add("configured_trajectory_prerequisites", ready) + if not ready: return report - first_env = _literal(trajectory.iloc[0]["env_states"]) if not trajectory.empty else None - agent_ids = set(first_env) if isinstance(first_env, dict) else set() + assert rows is not None report.add( - "configured_agent_count", - len(agent_ids) == config.simulation.n_agents, - f"trajectory has {len(agent_ids)} agents; config expects {config.simulation.n_agents}", + "configured_schedule", set(rows) == _expected_schedule(config), + "trajectory must retain every run's initial row and configured single-block steps", ) - out_of_bounds = 0 - for value in trajectory["env_states"]: - states = _literal(value) + expected_agents = {str(index) for index in range(config.simulation.n_agents)} + bad_registries = out_of_bounds = 0 + for row in rows.values(): + states = _literal(row["env_states"]) if not isinstance(states, dict): + bad_registries += 1 continue - for coordinate in states.values(): - parsed = _coordinate(coordinate) - if parsed is None or not all( - 0 <= component < config.grid.dimension for component in parsed - ): - out_of_bounds += 1 - report.add( - "configured_coordinate_bounds", - out_of_bounds == 0, - f"{out_of_bounds} coordinates exceed the configured grid", - ) - expected_starts = { - index: coordinate - for index, coordinate in enumerate(config.simulation.resolved_initial_states) + bad_registries += int({_agent_id(agent) for agent in states} != expected_agents) + for value in states.values(): + coordinate = _coordinate(value) + out_of_bounds += int(coordinate is None or not all( + 0 <= component < config.grid.dimension for component in coordinate + )) + report.add("configured_agent_count", bad_registries == 0, "agent registry differs from config") + report.add("configured_coordinate_bounds", out_of_bounds == 0, "invalid configured coordinates") + starts = { + str(agent): coordinate + for agent, coordinate in enumerate(config.simulation.resolved_initial_states) } - actual_starts = { - int(agent_id): _coordinate(coordinate) - for agent_id, coordinate in (first_env or {}).items() - if isinstance(agent_id, (int, np.integer, str)) and str(agent_id).isdigit() + bad_starts = 0 + for run in range(1, config.simulation.runs + 1): + row = rows.get((run, 0, 0)) + states = _literal(row["env_states"]) if row is not None else None + actual = { + _agent_id(agent): _coordinate(value) for agent, value in states.items() + } if isinstance(states, dict) else None + bad_starts += int(actual != starts) + report.add("configured_initial_states", bad_starts == 0, "one or more run starts differ") + summary_ok = isinstance(summary_payload, dict) and summary_payload.get("version") == 2 + report.add("summary_run_contract", summary_ok, "version-2 run-scoped summary is required") + if not summary_ok: + return report + assert summary_payload is not None + report.add("summary_row_count", summary_payload.get("n_rows") == len(trajectory)) + report.add("summary_agent_count", summary_payload.get("n_agents") == len(expected_agents)) + report.add("summary_grid_dimension", summary_payload.get("grid_dimension") == config.grid.dimension) + report.add("summary_run_count", summary_payload.get("n_runs") == config.simulation.runs) + report.add("summary_max_timestep", summary_payload.get("max_timestep") == config.simulation.timesteps) + report.add("summary_max_run", summary_payload.get("max_run") == config.simulation.runs) + summaries = summary_payload.get("runs") + valid_runs = isinstance(summaries, dict) and set(summaries) == { + str(run) for run in range(1, config.simulation.runs + 1) } - report.add( - "configured_initial_states", - actual_starts == expected_starts, - "trajectory first-row positions do not match configured starts", - ) - if summary_payload is not None: - report.add( - "summary_row_count", - summary_payload.get("n_rows") == len(trajectory), - "summary n_rows does not match trajectory rows", - ) - report.add( - "summary_agent_count", - summary_payload.get("n_agents") == len(agent_ids), - "summary n_agents does not match trajectory agents", - ) - report.add( - "summary_grid_dimension", - summary_payload.get("grid_dimension") == config.grid.dimension, - "summary grid_dimension does not match configuration", - ) + report.add("summary_run_coverage", valid_runs) + if not valid_runs: + return report + assert isinstance(summaries, dict) + for run in range(1, config.simulation.runs + 1): + selected = [row for key, row in sorted(rows.items()) if key[0] == run] + value = summaries[str(run)] + valid = isinstance(value, dict) and bool(selected) + if valid: + final = _literal(selected[-1]["env_states"]) + finals = { + str(agent): list(coordinate) if coordinate is not None else None + for agent, coordinate in ( + (agent, _coordinate(position)) for agent, position in final.items() + ) + } if isinstance(final, dict) else None + lengths = {agent: len(selected) for agent in expected_agents} + beliefs = {agent: 0 for agent in expected_agents} + for row in selected: + mapping = _literal(row["inferences"]) + if isinstance(mapping, dict): + for agent, vector in mapping.items(): + label = _agent_id(agent) + if label in beliefs and _vector(vector, "posterior") is not None: + beliefs[label] += 1 + valid = ( + value.get("n_rows") == len(selected) + and value.get("n_agents") == len(expected_agents) + and value.get("final_positions") == finals + and value.get("trajectory_lengths") == lengths + and value.get("belief_history_lengths") == beliefs + and value.get("max_timestep") == max(key[1] for key in rows if key[0] == run) + ) + report.add(f"summary.run_{run}", valid, "run-scoped summary differs from trajectory") return report + + def validate_config_model_agreement( - config: Any, model_payload: dict[str, Any] | None + config: Any, model_payload: dict | None, trajectory: Any, ) -> ValidationReport: - """Cross-check the persisted generative model against the persisted config.""" + """Bind all run/agent models to config and immutable trajectory references.""" report = ValidationReport() - if config is None or not isinstance(model_payload, dict): + ready = config is not None and isinstance(model_payload, dict) and bool(model_payload) + report.add("configured_model_prerequisites", ready) + if not ready: return report - expected_agents = {str(index) for index in range(config.simulation.n_agents)} + assert isinstance(model_payload, dict) + expected_keys = _expected_model_keys(config) report.add( - "configured_model_agents", - set(model_payload) == expected_agents, - "generative model agent IDs do not match configuration", + "configured_model_agents", set(model_payload) == expected_keys, + "models must contain every configured run/agent pair", ) - expected_states = config.grid.dimension**2 - bad_dimensions = 0 - for payload in model_payload.values(): - if not isinstance(payload, dict): + states = config.grid.dimension**2 + failures = 0 + digests = {} + for key, payload in model_payload.items(): + valid = isinstance(payload, dict) + if valid: + valid = ( + key in expected_keys + and all(type(payload.get(name)) is int for name in ("border", "policy_len", "max_policies")) + and payload.get("n_states") == states and payload.get("n_observations") == states + and payload.get("border") == config.grid.dimension - 1 + and payload.get("policy_len") == config.grid.planning_length + and payload.get("max_policies") == config.grid.max_policies + and payload.get("E") == list(config.grid.affordances) + ) + try: + digests[key] = _model_digest(payload) + except (TypeError, ValueError): + valid = False + if key in expected_keys: + start = config.simulation.resolved_initial_states[int(key[1])] + prior = np.zeros(states) + prior[start[0] * config.grid.dimension + start[1]] = 1.0 + try: + valid = valid and np.array_equal(np.asarray(payload.get("D"), dtype=float), prior) + except (TypeError, ValueError): + valid = False + failures += int(not valid) + report.add("configured_model_dimensions", failures == 0, "model metadata/affordance order differs") + rows = _trajectory_rows(trajectory) + report.add("model_trajectory_prerequisites", rows is not None) + if rows is None: + return report + failures = 0 + initial_failures = 0 + observed = set() + for (run, _time, _substep), row in rows.items(): + references = _literal(row["agents"]) + if not isinstance(references, dict): + failures += 1 continue - try: - matches = ( - int(payload.get("n_states", -1)) == expected_states - and int(payload.get("n_observations", -1)) == expected_states - and len(payload.get("E", [])) == len(config.grid.affordances) + for label, reference in references.items(): + agent = _agent_id(label) + key = (run, agent) + observed.add(key) + valid = ( + isinstance(reference, dict) and reference.get("agent_id") == agent + and key in digests and reference.get("model_sha256") == digests[key] ) - except (TypeError, ValueError): - matches = False - bad_dimensions += int(not matches) + failures += int(not valid) + if _time == 0: + priors = _literal(row["priors"]) + vector = _vector(priors.get(label), "prior") if isinstance(priors, dict) else None + model = model_payload.get(key) + valid_prior = vector is not None and vector.size == states and isinstance(model, dict) + if valid_prior and vector is not None and isinstance(model, dict): + try: + wanted = np.asarray(model.get("D"), dtype=float) + valid_prior = vector.shape == wanted.shape and np.allclose(vector, wanted) + except (TypeError, ValueError): + valid_prior = False + initial_failures += int(not valid_prior) report.add( - "configured_model_dimensions", - bad_dimensions == 0, - f"{bad_dimensions} model payloads disagree with configuration", + "model_run_association", failures == 0 and observed == expected_keys, + "trajectory references do not match their own run/agent model", ) + report.add("model_initial_priors", initial_failures == 0, "initial trajectory priors differ from D") return report +def _validate_render_coverage(paths: RunPaths, config: Any) -> ValidationReport: + report = ValidationReport() + report.add("render_coverage_prerequisites", config is not None) + if config is None: + return report + for run, agent in sorted(_expected_model_keys(config)): + for label in ("first", "last"): + name = f"belief_heatmap_run_{run}_agent_{agent}_{label}.png" + report.add(f"render.{name}", _render_file_valid(paths.viz_dir / name), name) + return report + + + + def validate_run_outputs(paths: RunPaths) -> ValidationReport: """Parse and validate every required artefact in a run tree. @@ -845,10 +1098,11 @@ def validate_run_outputs(paths: RunPaths) -> ValidationReport: trajectory_report, model_report, validate_manifest_boundary(paths), - validate_policies_boundary(paths), - validate_per_step_boundary(paths, config, trajectory), + validate_policies_boundary(paths, config, model_payload), + validate_per_step_boundary(paths, config, trajectory, model_payload), validate_config_trajectory_agreement(config, trajectory, summary_payload), - validate_config_model_agreement(config, model_payload), + validate_config_model_agreement(config, model_payload, trajectory), + _validate_render_coverage(paths, config), ] for stage in stages: aggregate.merge("artefacts", stage) diff --git a/blockference/manuscript_links.py b/blockference/manuscript_links.py new file mode 100644 index 0000000..5e64051 --- /dev/null +++ b/blockference/manuscript_links.py @@ -0,0 +1,145 @@ +"""Relocate local Markdown resources while retaining source-document semantics.""" + +from __future__ import annotations + +import os +import re +import string +from collections.abc import Mapping +from pathlib import Path +from urllib.parse import quote, unquote, urlsplit + +__all__ = ["rebase_local_links"] + +REFERENCE_RE = re.compile(r"^ {0,3}\[(?!\^)[^\]]+\]:[ \t]*") +FENCE_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})") + + +def _unescape(value: str) -> str: + output = [] + index = 0 + while index < len(value): + if value[index] == "\\" and index + 1 < len(value) and value[index + 1] in string.punctuation: + index += 1 + output.append(value[index]) + index += 1 + return "".join(output) + + +def _destination_span(line: str, start: int) -> tuple[int, int]: + while start < len(line) and line[start] in " \t": + start += 1 + if start < len(line) and line[start] == "<": + end = start + 1 + while end < len(line): + if line[end] == "\\": + end += 2 + elif line[end] == ">": + return start + 1, end + else: + end += 1 + return start, start + end, depth = start, 0 + while end < len(line): + char = line[end] + if char == "\\": + end += 2 + continue + if char == "(": + depth += 1 + elif char == ")": + if depth == 0: + break + depth -= 1 + elif char.isspace() and depth == 0: + break + end += 1 + return start, end + + +def _relocate(value: str, source: Path, output_dir: Path, copied: Mapping[Path, Path]) -> str: + if not value: + return value + decoded = _unescape(value) + parsed = urlsplit(decoded) + if parsed.scheme or parsed.netloc or not parsed.path: + return value + target = (source.parent / unquote(parsed.path)).resolve() + if target not in copied and not target.exists(): + raise FileNotFoundError(f"missing manuscript resource {value!r} in {source}") + destination = copied.get(target, target) + # Explicit copied destinations are publication-owned plans; the builder + # generates/validates registered figures and copies resources before success. + relative = Path(os.path.relpath(destination, output_dir)).as_posix() + # Preserve the original query/fragment bytes; only the path changes location. + suffix = decoded[len(parsed.path):] + return quote(relative, safe="/-._~") + suffix + + +def rebase_local_links( + text: str, *, source: Path, output_dir: Path, copied: Mapping[Path, Path] | None = None, +) -> str: + """Rebase inline/image and reference-definition destinations, not code or URIs. + + Destination parsing retains balanced/escaped parentheses, angle delimiters, + optional titles and query/fragment suffixes. Fenced and inline code, scholarly + citations and same-document fragments are left intact. + """ + assets = {path.resolve(): destination for path, destination in (copied or {}).items()} + lines = [] + fence: str | None = None + fence_length = 0 + for original in text.splitlines(keepends=True): + marker = FENCE_RE.match(original) + if marker: + token = marker.group(1) + if fence is None: + fence, fence_length = token[0], len(token) + elif token[0] == fence and len(token) >= fence_length: + fence = None + lines.append(original) + continue + if fence is not None: + lines.append(original) + continue + line = original + definition = REFERENCE_RE.match(line) + if definition: + start, end = _destination_span(line, definition.end()) + line = line[:start] + _relocate(line[start:end], source, output_dir, assets) + line[end:] + lines.append(line) + continue + index = 0 + while index < len(line): + if line[index] == "\\": + index += 2 + continue + if line[index] == "`": + end = index + while end < len(line) and line[end] == "`": + end += 1 + closing = line.find(line[index:end], end) + index = len(line) if closing < 0 else closing + end - index + continue + if line[index] != "[": + index += 1 + continue + end, depth = index + 1, 1 + while end < len(line) and depth: + if line[end] == "\\": + end += 2 + continue + if line[end] == "[": + depth += 1 + elif line[end] == "]": + depth -= 1 + end += 1 + if depth or end >= len(line) or line[end] != "(": + index = end + continue + start, finish = _destination_span(line, end + 1) + replacement = _relocate(line[start:finish], source, output_dir, assets) + line = line[:start] + replacement + line[finish:] + index = start + len(replacement) + lines.append(line) + return "".join(lines) diff --git a/blockference/maths.py b/blockference/maths.py index 9bb43f0..398f380 100644 --- a/blockference/maths.py +++ b/blockference/maths.py @@ -56,36 +56,37 @@ def softmax(x: np.ndarray, axis: int = -1) -> np.ndarray: def norm_dist(x: np.ndarray, axis: int = 0) -> np.ndarray: - """Normalise non-negative values along ``axis``. + """Normalise finite, non-negative weights along ``axis`` without overflow. - Zero-sum slices are represented by a uniform distribution. + All-zero slices become uniform; input arrays and RNG state are unchanged. """ values = _as_probability_array(x, name="x") if values.ndim == 0: raise ValueError("norm_dist requires an array with at least one dimension") if not -values.ndim <= axis < values.ndim: raise ValueError(f"axis {axis} is out of bounds for an array with {values.ndim} dimensions") - total = values.sum(axis=axis, keepdims=True) size = values.shape[axis] if size == 0: raise ValueError("norm_dist cannot normalise an empty axis") - uniform = np.full_like(values, 1.0 / size) - with np.errstate(divide="ignore", invalid="ignore"): - normalised = np.divide(values, total, out=np.zeros_like(values), where=total > 0) - return np.where(total == 0, uniform, normalised) + maximum = values.max(axis=axis, keepdims=True) + scaled = np.divide(values, maximum, out=np.zeros_like(values), where=maximum > 0) + total = scaled.sum(axis=axis, keepdims=True) + return np.divide(scaled, total, out=np.full_like(values, 1.0 / size), where=total > 0) def sample(p: np.ndarray, rng: np.random.Generator | None = None) -> int: - """Sample one index from a non-empty one-dimensional distribution.""" + """Sample finite, non-negative weights using the supplied or global RNG. + + Unlike :func:`norm_dist`, zero-mass sampling is an error. + """ probabilities = _as_probability_array(p, name="p") if probabilities.ndim != 1: raise ValueError(f"sample expects a one-dimensional vector, got {probabilities.ndim} dimensions") if probabilities.size == 0: raise ValueError("sample requires at least one probability") - total = float(probabilities.sum()) - if total <= 0: + if probabilities.max() == 0: raise ValueError("sample requires a positive probability total") - probabilities = probabilities / total + probabilities = norm_dist(probabilities) if rng is None: return int(np.random.choice(probabilities.size, p=probabilities)) return int(rng.choice(probabilities.size, p=probabilities)) diff --git a/blockference/notebook_inventory.py b/blockference/notebook_inventory.py new file mode 100644 index 0000000..e387da6 --- /dev/null +++ b/blockference/notebook_inventory.py @@ -0,0 +1,124 @@ +"""Tracked-source notebook selection, hygiene and isolated-workspace execution.""" + +from __future__ import annotations + +import os +import re +import subprocess +from pathlib import Path + +__all__ = ["execute_notebooks", "tracked_notebooks", "validate_all", "validate_notebook"] + +ABSOLUTE_PATH_RE = re.compile(r"(?:/Users/|/home/|[A-Za-z]:[\\/])") +FORBIDDEN_COMPONENTS = frozenset({ + ".git", ".ipynb_checkpoints", ".venv", "venv", "env", "cad", "build", "dist", + "output", "results", "node_modules", +}) + + +def _git(root: Path, *arguments: str, data: bytes | None = None) -> subprocess.CompletedProcess[bytes]: + environment = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")} + environment.update({"GIT_OPTIONAL_LOCKS": "0", "GIT_TERMINAL_PROMPT": "0"}) + return subprocess.run( + ["git", "--no-optional-locks", "-c", "core.fsmonitor=false", "-C", str(root), *arguments], + capture_output=True, check=False, env=environment, + input=data, stdin=subprocess.DEVNULL if data is None else None, + ) + + +def tracked_notebooks(root: str | Path) -> tuple[Path, ...]: + """Return only present, non-ignored tracked notebooks at an exact Git root. + + A worktree .git file is valid. Git failure, missing tracked files and symlink + escapes are errors; none is an empty inventory or a reason to scan the disk. + """ + repository = Path(root).resolve(strict=True) + top = _git(repository, "rev-parse", "--show-toplevel") + if top.returncode or Path(os.fsdecode(top.stdout).removesuffix("\n")).resolve() != repository: + raise ValueError(f"not an exact Git repository root: {repository}") + tracked = _git(repository, "ls-files", "--cached", "-z", "--", "*.ipynb") + if tracked.returncode: + raise RuntimeError("cannot read tracked notebooks: " + os.fsdecode(tracked.stderr)) + names = set(name for name in tracked.stdout.split(b"\0") if name) + if not names: + return () + ignored = _git( + repository, "check-ignore", "--no-index", "--stdin", "-z", + data=b"\0".join(sorted(names)) + b"\0", + ) + if ignored.returncode not in (0, 1): + raise RuntimeError("cannot classify ignored notebooks: " + os.fsdecode(ignored.stderr)) + excluded = set(ignored.stdout.split(b"\0")) + selected = [] + for name in sorted(names - excluded): + relative = Path(os.fsdecode(name)) + if relative.is_absolute() or ".." in relative.parts: + raise ValueError(f"invalid tracked notebook path: {relative}") + if any(part.lower() in FORBIDDEN_COMPONENTS for part in relative.parts): + continue + candidate = repository / relative + if candidate.is_symlink() or not candidate.resolve().is_relative_to(repository): + raise ValueError(f"tracked notebook is a symlink or escapes the repository: {relative}") + if not candidate.is_file(): + raise FileNotFoundError(f"tracked notebook is missing: {relative}") + selected.append(candidate) + return tuple(selected) + + +def validate_notebook(path: str | Path) -> list[str]: + """Return teaching-summary, source-path, API and committed-output violations.""" + import nbformat + + notebook_path = Path(path) + notebook = nbformat.read(notebook_path, as_version=4) + errors = [] + cells = notebook.cells + if not cells or cells[0].cell_type != "markdown": + errors.append("first cell must be a teaching-summary markdown cell") + elif len(cells[0].source.split()) < 12: + errors.append("teaching-summary markdown cell is too short") + for index, cell in enumerate(cells): + source = cell.source if isinstance(cell.source, str) else "".join(cell.source) + if ABSOLUTE_PATH_RE.search(source): + errors.append(f"cell {index} contains an absolute filesystem path") + if cell.cell_type == "code": + if "GRTs" not in notebook_path.parts and "blockference" not in source: + errors.append(f"code cell {index} does not import the current package API") + if cell.outputs or cell.execution_count is not None: + errors.append(f"code cell {index} contains committed execution output") + return errors + + +def _validate_selection(root: Path, notebooks: tuple[Path, ...]) -> dict[Path, list[str]]: + failures = {} + for path in notebooks: + errors = validate_notebook(path) + if errors: + failures[path.relative_to(root)] = errors + return failures + + +def validate_all(root: str | Path) -> tuple[tuple[Path, ...], dict[Path, list[str]]]: + """Return the frozen tracked selection and its violations; empty is explicit.""" + repository = Path(root).resolve(strict=True) + notebooks = tracked_notebooks(repository) + return notebooks, _validate_selection(repository, notebooks) + + +def execute_notebooks(root: str | Path, *, workspace: str | Path) -> tuple[Path, ...]: + """Validate and execute one frozen tracked selection in the supplied workspace.""" + notebooks, failures = validate_all(root) + if failures: + raise ValueError(f"notebook hygiene violations: {failures}") + if not notebooks: + return notebooks + import nbformat + from nbclient import NotebookClient + + for path in notebooks: + notebook = nbformat.read(path, as_version=4) + NotebookClient( + notebook, timeout=120, kernel_name="python3", + resources={"metadata": {"path": str(Path(workspace).resolve())}}, + ).execute() + return notebooks diff --git a/blockference/pipeline.py b/blockference/pipeline.py index 28e083c..849380e 100644 --- a/blockference/pipeline.py +++ b/blockference/pipeline.py @@ -73,6 +73,7 @@ extract_agent_positions, extract_belief_history, infer_grid_dimension, + ordered_trajectory, ) __all__ = [ @@ -134,23 +135,34 @@ def ok(self) -> bool: def summarise_trajectory(df: pd.DataFrame) -> dict: - """Compute a JSON-friendly summary of an experiment run.""" + """Summarise each run/agent without concatenating independent histories.""" positions = extract_agent_positions(df) beliefs = extract_belief_history(df) - n = infer_grid_dimension(df) - summary = { + ordered = ordered_trajectory(df) + runs = {} + for run, rows in ordered.groupby("run", sort=False): + run_positions = {agent: history for (number, agent), history in positions.items() if number == run} + runs[str(run)] = { + "n_rows": int(len(rows)), + "n_agents": len(run_positions), + "final_positions": {str(agent): history[-1] for agent, history in run_positions.items()}, + "trajectory_lengths": {str(agent): len(history) for agent, history in run_positions.items()}, + "belief_history_lengths": { + str(agent): len(history) + for (number, agent), history in beliefs.items() if number == run + }, + "max_timestep": int(rows["timestep"].max()), + } + return { + "version": 2, "n_rows": int(len(df)), - "n_agents": int(len(positions)), - "grid_dimension": int(n), - "final_positions": {str(k): v[-1] if v else None for k, v in positions.items()}, - "trajectory_lengths": {str(k): len(v) for k, v in positions.items()}, - "belief_history_lengths": {str(k): len(v) for k, v in beliefs.items()}, + "n_runs": len(runs), + "n_agents": len({agent for _run, agent in positions}), + "grid_dimension": int(infer_grid_dimension(df)), + "max_timestep": int(ordered["timestep"].max()), + "max_run": int(ordered["run"].max()), + "runs": runs, } - if "timestep" in df.columns: - summary["max_timestep"] = int(df["timestep"].max()) - if "run" in df.columns: - summary["max_run"] = int(df["run"].max()) - return summary def _as_float_array(v: Any) -> np.ndarray | None: @@ -255,23 +267,12 @@ def render_visualisations( log.info("rendering persisted expected free energy") viz["efe"] = plot_efe(df, paths.viz_dir / "efe.png") - beliefs = extract_belief_history(df) - if beliefs: - first_agent = next(iter(beliefs)) - n_steps = len(beliefs[first_agent]) - if n_steps > 0: - log.info("rendering belief heatmaps for agent %s (first/last)", first_agent) - viz["belief_heatmap_first"] = plot_belief_heatmap( - df, - paths.viz_dir / "belief_heatmap_first.png", - agent_id=first_agent, - timestep=0, - ) - viz["belief_heatmap_last"] = plot_belief_heatmap( - df, - paths.viz_dir / "belief_heatmap_last.png", - agent_id=first_agent, - timestep=-1, + for run, agent_id in extract_belief_history(df): + for label, index in (("first", 0), ("last", -1)): + name = f"belief_heatmap_run_{run}_agent_{agent_id}_{label}" + viz[name] = plot_belief_heatmap( + df, paths.viz_dir / f"{name}.png", + run=run, agent_id=agent_id, timestep=index, ) log.info("rendering trajectory animation") @@ -279,29 +280,29 @@ def render_visualisations( return viz, anims -def _extract_agents_dict(df: pd.DataFrame) -> dict: - """Return the post-run ``agents`` dict from the final cadCAD row.""" - if df.empty or "agents" not in df.columns: - return {} - last_agents = df.iloc[-1]["agents"] - if isinstance(last_agents, dict): - return last_agents - return {} +def _extract_run_agents(df: pd.DataFrame) -> dict[tuple[int, str], Any]: + """Return each run's final agents, retaining its own immutable model.""" + models = {} + for run, rows in ordered_trajectory(df).groupby("run", sort=False): + agents = rows.iloc[-1]["agents"] + if not isinstance(agents, dict) or not agents: + raise ValueError(f"run {run} has no final agent registry") + for agent_id, agent in agents.items(): + models[(int(run), str(agent_id))] = agent + return models -def _extract_policies(agents: dict) -> list: - """Return the policy set the inference loop used.""" - from blockference.maths import construct_policies as _cp +def _extract_policies(agents: dict[tuple[int, str], Any]) -> dict[tuple[int, str], list]: + """Reconstruct each model's exact ordered policy set under its actual cap.""" + from blockference.maths import construct_policies - if not agents: - return [] - first = next(iter(agents.values())) - n_states = int(getattr(first, "n_states", 0)) - n_actions = len(getattr(first, "E", [])) - policy_len = int(getattr(first, "policy_len", 1)) - if n_states == 0 or n_actions == 0: - return [] - return _cp([n_states], [n_actions], policy_len=policy_len) + return { + key: construct_policies( + [agent.n_states], [len(agent.E)], policy_len=agent.policy_len, + max_policies=agent.max_policies, + ) + for key, agent in agents.items() + } # --------------------------------------------------------------------------- @@ -338,20 +339,20 @@ def persist( persist_config(cfg, paths) log.info("persisted config to %s", paths.config_path) - written = persist_dataframe(df, paths) + agents = _extract_run_agents(df) + written = persist_dataframe(df, paths, models=agents) log.info("persisted trajectory: %s", {k: str(v) for k, v in written.items()}) summary = summarise_trajectory(df) persist_summary(summary, paths) log.info("persisted summary: %d agents, %d rows", summary["n_agents"], summary["n_rows"]) - agents = _extract_agents_dict(df) persist_generative_model(agents, paths) persist_generative_model_npz(agents, paths) - log.info("persisted generative model (JSON + NPZ) for %d agent(s)", len(agents)) + log.info("persisted generative models (JSON + NPZ) for %d run/agent pairs", len(agents)) policies = _extract_policies(agents) persist_policies(policies, paths) - log.info("persisted %d policies of length %d", len(policies), policies[0].shape[0]) + log.info("persisted policy sets for %d run/agent pairs", len(policies)) per_step = build_per_step_records(df) persist_per_step_records(per_step, paths) @@ -385,9 +386,9 @@ def validate( log.info("trajectory schema OK") model_reports: dict[str, ValidationReport] = {} - for agent_id, agent in agents.items(): + for (run, agent_id), agent in agents.items(): rep = validate_generative_model(agent) - model_reports[str(agent_id)] = rep + model_reports[f"run_{run}/agent_{agent_id}"] = rep if not rep.ok: log.warning( "generative model invariant failures for agent %s: %s", agent_id, rep.issues @@ -400,6 +401,9 @@ def validate( per_step, n_states=getattr(first_agent, "n_states", None), n_actions=len(getattr(first_agent, "E", [])) if first_agent is not None else None, + n_policies=( + len(first_agent.E) ** first_agent.policy_len if first_agent is not None else None + ), ) if not per_step_report.ok: log.warning("per-step diagnostics issues: %s", per_step_report.issues) diff --git a/blockference/viz/_common.py b/blockference/viz/_common.py index 7bad10d..34bd70e 100644 --- a/blockference/viz/_common.py +++ b/blockference/viz/_common.py @@ -50,55 +50,80 @@ def coerce_cell(value: Any) -> Any: return value -def _mapping_series(df: pd.DataFrame, column: str) -> list[dict[Any, Any]]: +def ordered_trajectory(df: pd.DataFrame) -> pd.DataFrame: + """Return rows ordered by their unique, non-negative run/time identity.""" + columns = ["run", "timestep", "substep"] + if df.empty or any(column not in df for column in columns): + raise ValueError("trajectory requires non-empty run/timestep/substep columns") + try: + indices = df[columns].to_numpy(dtype=float) + except (TypeError, ValueError) as exc: + raise ValueError("trajectory indices must be integers") from exc + if ( + not np.isfinite(indices).all() + or (indices < 0).any() + or (indices[:, 0] < 1).any() + or not np.equal(indices, np.floor(indices)).all() + or any(isinstance(value, (bool, np.bool_)) for value in df[columns].to_numpy().flat) + ): + raise ValueError("trajectory indices must be non-negative integers with run >= 1") + ordered = df.assign(**{ + column: indices[:, index].astype(int) for index, column in enumerate(columns) + }).sort_values(columns, kind="stable") + if ordered.duplicated(columns).any(): + raise ValueError("trajectory contains duplicate run/timestep/substep identities") + return ordered + + +def _mapping_series(df: pd.DataFrame, column: str) -> list[tuple[tuple[int, int, int], dict]]: if column not in df.columns: raise ValueError(f"trajectory frame must contain {column!r}") - cells = [coerce_cell(value) for value in df[column]] + ordered = ordered_trajectory(df) + cells = [coerce_cell(value) for value in ordered[column]] if any(not isinstance(cell, dict) for cell in cells): raise ValueError(f"trajectory column {column!r} must contain mappings") - return cells - + indices = ordered[["run", "timestep", "substep"]].itertuples(index=False, name=None) + return list(zip(indices, cells, strict=True)) -def extract_agent_positions(df: pd.DataFrame) -> dict[Any, list[tuple[int, int]]]: - """Return ``{agent_id: [(y, x), ...]}`` from a trajectory frame.""" - cells = _mapping_series(df, "env_states") - if not cells: - raise ValueError("trajectory frame is empty") - out: dict[Any, list[tuple[int, int]]] = {} - for cell in cells: +def extract_agent_positions(df: pd.DataFrame) -> dict[tuple[int, Any], list[tuple[int, int]]]: + """Return coordinate histories keyed by ``(run, agent)`` in actual time order.""" + out: dict[tuple[int, Any], list[tuple[int, int]]] = {} + for (run, _time, _substep), cell in _mapping_series(df, "env_states"): for agent_id, value in cell.items(): if not isinstance(value, (list, tuple)) or len(value) != 2: raise ValueError(f"agent {agent_id!r} has an invalid coordinate") - if any(isinstance(component, bool) or not isinstance(component, (int, np.integer)) for component in value): + if any( + isinstance(component, bool) or not isinstance(component, (int, np.integer)) + for component in value + ): raise ValueError(f"agent {agent_id!r} has a non-integer coordinate") coordinate = (int(value[0]), int(value[1])) if min(coordinate) < 0: raise ValueError(f"agent {agent_id!r} has a negative coordinate") - out.setdefault(agent_id, []).append(coordinate) + out.setdefault((run, agent_id), []).append(coordinate) if not out: raise ValueError("trajectory contains no agent positions") - lengths = {len(history) for history in out.values()} - if len(lengths) != 1: - raise ValueError("agent trajectories have inconsistent lengths") + lengths: dict[int, set[int]] = {} + for (run, _agent), history in out.items(): + lengths.setdefault(run, set()).add(len(history)) + if any(len(values) != 1 for values in lengths.values()): + raise ValueError("agent trajectories have inconsistent lengths within a run") return out -def extract_action_history(df: pd.DataFrame) -> dict[Any, list[Any]]: - """Return ``{agent_id: [action, ...]}`` from a trajectory frame.""" - - cells = _mapping_series(df, "actions") - out: dict[Any, list[Any]] = {} - for cell in cells: +def extract_action_history(df: pd.DataFrame) -> dict[tuple[int, Any], list[Any]]: + """Return ordered action histories keyed by ``(run, agent)``.""" + out: dict[tuple[int, Any], list[Any]] = {} + for (run, _time, _substep), cell in _mapping_series(df, "actions"): for agent_id, value in cell.items(): - out.setdefault(agent_id, []).append(value) + out.setdefault((run, agent_id), []).append(value) return out -def _extract_vector_history(df: pd.DataFrame, column: str) -> dict[Any, list[np.ndarray]]: - cells = _mapping_series(df, column) - out: dict[Any, list[np.ndarray]] = {} - for cell in cells: +def _extract_vector_history(df: pd.DataFrame, column: str) -> dict[tuple[int, Any], list[np.ndarray]]: + out: dict[tuple[int, Any], list[np.ndarray]] = {} + for (run, _time, _substep), cell in _mapping_series(df, column): for agent_id, value in cell.items(): parsed = coerce_cell(value) if parsed is None or (isinstance(parsed, str) and parsed == ""): @@ -106,18 +131,29 @@ def _extract_vector_history(df: pd.DataFrame, column: str) -> dict[Any, list[np. array = np.asarray(parsed, dtype=float) if array.ndim != 1 or array.size == 0 or not np.isfinite(array).all(): raise ValueError(f"{column} for agent {agent_id!r} is not a finite vector") - out.setdefault(agent_id, []).append(array) + out.setdefault((run, agent_id), []).append(array) + return out + + +def extract_history_steps(df: pd.DataFrame, column: str) -> dict[tuple[int, Any], list[tuple[int, int]]]: + """Return actual timestep/substep labels aligned with non-empty history cells.""" + out: dict[tuple[int, Any], list[tuple[int, int]]] = {} + for (run, time, substep), cell in _mapping_series(df, column): + for agent_id, value in cell.items(): + parsed = coerce_cell(value) + if parsed is not None and not (isinstance(parsed, str) and parsed == ""): + out.setdefault((run, agent_id), []).append((time, substep)) return out -def extract_belief_history(df: pd.DataFrame) -> dict[Any, list[np.ndarray]]: - """Return persisted posterior vectors by agent.""" +def extract_belief_history(df: pd.DataFrame) -> dict[tuple[int, Any], list[np.ndarray]]: + """Return persisted posterior vectors by ``(run, agent)``.""" return _extract_vector_history(df, "inferences") -def extract_efe_history(df: pd.DataFrame) -> dict[Any, list[np.ndarray]]: - """Return persisted expected-free-energy vectors by agent.""" +def extract_efe_history(df: pd.DataFrame) -> dict[tuple[int, Any], list[np.ndarray]]: + """Return persisted expected-free-energy vectors by ``(run, agent)``.""" return _extract_vector_history(df, "efe") @@ -146,5 +182,7 @@ def infer_grid_dimension(df: pd.DataFrame) -> int: "extract_agent_positions", "extract_belief_history", "extract_efe_history", + "extract_history_steps", "infer_grid_dimension", + "ordered_trajectory", ] diff --git a/blockference/viz/animation.py b/blockference/viz/animation.py index df43ccd..61cff28 100644 --- a/blockference/viz/animation.py +++ b/blockference/viz/animation.py @@ -13,7 +13,11 @@ import pandas as pd from matplotlib.animation import FFMpegWriter, FuncAnimation, PillowWriter -from blockference.viz._common import extract_agent_positions, infer_grid_dimension +from blockference.viz._common import ( + extract_agent_positions, + extract_history_steps, + infer_grid_dimension, +) __all__ = ["animate_trajectory"] @@ -39,7 +43,8 @@ def animate_trajectory( n = inferred if grid_dim is None else grid_dim if isinstance(n, bool) or not isinstance(n, int) or n < 2 or n != inferred: raise ValueError(f"grid_dim must equal the trajectory dimension {inferred}") - n_frames = len(next(iter(positions.values()))) + steps = extract_history_steps(df, "env_states") + n_frames = max(len(history) for history in positions.values()) fig, ax = plt.subplots(figsize=(6, 6)) try: ax.set_xlim(-0.5, n - 0.5) @@ -53,7 +58,10 @@ def animate_trajectory( lines, dots, labels = {}, {}, {} for index, agent_id in enumerate(positions): color = cmap(index % 10) - (line,) = ax.plot([], [], "-", color=color, alpha=0.6, label=f"agent {agent_id}") + (line,) = ax.plot( + [], [], "-", color=color, alpha=0.6, + label=f"run {agent_id[0]} / agent {agent_id[1]}", + ) (dot,) = ax.plot([], [], "o", color=color, markersize=10) lines[agent_id] = line dots[agent_id] = dot @@ -76,9 +84,13 @@ def update(frame: int): lines[agent_id].set_data(xs, ys) dots[agent_id].set_data([xs[-1]], [ys[-1]]) labels[agent_id].set_position((xs[-1] + 0.05, ys[-1] - 0.1)) - labels[agent_id].set_text(str(agent_id)) - step_text.set_text(f"step {frame}") - return list(lines.values()) + list(dots.values()) + [step_text] + labels[agent_id].set_text(f"r{agent_id[0]} / a{agent_id[1]}") + run_labels = {} + for key, history in steps.items(): + time, substep = history[min(frame, len(history) - 1)] + run_labels[key[0]] = f"run {key[0]}: t={time}, substep={substep}" + step_text.set_text("\n".join(run_labels.values())) + return list(lines.values()) + list(dots.values()) + list(labels.values()) + [step_text] animation = FuncAnimation( fig, update, frames=n_frames, init_func=init, blit=False, interval=1000 / fps diff --git a/blockference/viz/plots.py b/blockference/viz/plots.py index 6d2b2e9..16c9fbd 100644 --- a/blockference/viz/plots.py +++ b/blockference/viz/plots.py @@ -19,6 +19,7 @@ extract_agent_positions, extract_belief_history, extract_efe_history, + extract_history_steps, infer_grid_dimension, ) @@ -64,9 +65,12 @@ def plot_trajectory(df: pd.DataFrame, out_path: str | Path, *, title: str = "Age ax.set_aspect("equal") ax.set_title(title) cmap = plt.get_cmap("tab10") - for index, (agent_id, trajectory) in enumerate(positions.items()): + for index, ((run, agent_id), trajectory) in enumerate(positions.items()): ys, xs = zip(*trajectory, strict=True) - ax.plot(xs, ys, "-o", color=cmap(index % 10), label=f"agent {agent_id}", alpha=0.8) + ax.plot( + xs, ys, "-o", color=cmap(index % 10), + label=f"run {run} / agent {agent_id}", alpha=0.8, + ) ax.scatter([xs[0]], [ys[0]], c="green", s=80, marker="s", zorder=5) ax.scatter([xs[-1]], [ys[-1]], c="red", s=80, marker="*", zorder=5) ax.legend(loc="best") @@ -77,24 +81,37 @@ def plot_trajectory(df: pd.DataFrame, out_path: str | Path, *, title: str = "Age return path -def plot_belief_heatmap(df: pd.DataFrame, out_path: str | Path, *, agent_id: object | None = None, timestep: int = -1, grid_dim: int | None = None, title: str | None = None) -> Path: - """Render one persisted posterior vector as a grid heatmap.""" +def plot_belief_heatmap( + df: pd.DataFrame, out_path: str | Path, *, run: int | None = None, + agent_id: object | None = None, timestep: int = -1, + grid_dim: int | None = None, title: str | None = None, +) -> Path: + """Render one run/agent's persisted posterior at an ordered history index.""" path = _target(out_path) beliefs = extract_belief_history(df) if not beliefs: raise ValueError("trajectory contains no posterior vectors") - selected = next(iter(beliefs)) if agent_id is None else agent_id - if selected not in beliefs or not beliefs[selected]: - raise ValueError(f"agent {selected!r} has no posterior history") + matches = [ + key for key in beliefs + if (run is None or key[0] == run) and (agent_id is None or key[1] == agent_id) + ] + if not matches: + raise ValueError("selected run/agent has no posterior history") + if len(matches) > 1 and (run is not None or agent_id is not None): + raise ValueError("ambiguous posterior history; select both run and agent") + selected = matches[0] vector = beliefs[selected][timestep] + time, substep = extract_history_steps(df, "inferences")[selected][timestep] n = _grid_size(df, grid_dim) if vector.size != n * n: raise ValueError("posterior vector size does not match the grid") fig, ax = plt.subplots(figsize=(5, 5)) try: image = ax.imshow(vector.reshape(n, n), cmap="viridis", vmin=0.0, vmax=max(float(vector.max()), 1.0)) - ax.set_title(title or f"q(s) for agent {selected} @ step {timestep}") + ax.set_title( + title or f"q(s) run {selected[0]} / agent {selected[1]} @ t={time}, substep={substep}" + ) ax.set_xticks(range(n)) ax.set_yticks(range(n)) fig.colorbar(image, ax=ax, fraction=0.046, pad=0.04) @@ -105,8 +122,8 @@ def plot_belief_heatmap(df: pd.DataFrame, out_path: str | Path, *, agent_id: obj return path -def plot_action_distribution(df: pd.DataFrame, out_path: str | Path, *, affordances=None, title: str = "Action frequency per agent") -> Path: - """Plot action frequencies using the configured action vocabulary.""" +def plot_action_distribution(df: pd.DataFrame, out_path: str | Path, *, affordances=None, title: str = "Action frequency per run/agent") -> Path: + """Plot separate run/agent frequencies using the configured action vocabulary.""" path = _target(out_path) labels = validate_affordances(DEFAULT_AFFORDANCES if affordances is None else affordances) @@ -115,11 +132,14 @@ def plot_action_distribution(df: pd.DataFrame, out_path: str | Path, *, affordan try: width = 0.8 / max(len(actions), 1) cmap = plt.get_cmap("tab10") - for index, (agent_id, history) in enumerate(actions.items()): + for index, ((run, agent_id), history) in enumerate(actions.items()): integers = [int(value) for value in history if isinstance(value, (int, np.integer))] counts = Counter(integers) offsets = np.arange(len(labels)) + index * width - ax.bar(offsets, [counts.get(action, 0) for action in range(len(labels))], width=width, label=f"agent {agent_id}", color=cmap(index % 10)) + ax.bar( + offsets, [counts.get(action, 0) for action in range(len(labels))], + width=width, label=f"run {run} / agent {agent_id}", color=cmap(index % 10), + ) ax.set_xticks(np.arange(len(labels)) + (len(actions) - 1) * width / 2) ax.set_xticklabels(labels) ax.set_ylabel("count") @@ -139,13 +159,17 @@ def plot_efe(df: pd.DataFrame, out_path: str | Path, *, title: str = "Expected f efe_history = extract_efe_history(df) if not efe_history: raise ValueError("trajectory contains no persisted EFE vectors") + steps = extract_history_steps(df, "efe") fig, ax = plt.subplots(figsize=(7, 4)) try: cmap = plt.get_cmap("tab10") - for index, (agent_id, history) in enumerate(efe_history.items()): + for index, (key, history) in enumerate(efe_history.items()): values = [float(vector.min()) for vector in history] - ax.plot(range(len(values)), values, "-o", color=cmap(index % 10), label=f"agent {agent_id}") - ax.set_xlabel("step") + ax.plot( + [time for time, _substep in steps[key]], values, "-o", + color=cmap(index % 10), label=f"run {key[0]} / agent {key[1]}", + ) + ax.set_xlabel("timestep") ax.set_ylabel("min G(π) (nats)") ax.set_title(title) ax.grid(True, alpha=0.3) diff --git a/docs/api.md b/docs/api.md index 48ab562..2a819bd 100644 --- a/docs/api.md +++ b/docs/api.md @@ -20,6 +20,18 @@ `parse_trajectory_records(df)` normalizes a trajectory into typed, ordered `TrajectoryRecord` values for backend/persistence parity. +Agent IDs are built-in `int` or `str`. Version-2 environment serialization +preserves typed IDs, insertion order, and positions: integer `1` and string +`"1"` remain distinct. Sequence actions follow registry order; conflict +priority remains `(type name, repr)`, not numeric or insertion order. +Unsupported Hashables, duplicate IDs, malformed typed records, and lossy +legacy string-key payloads are rejected. + +`norm_dist` and `sample` scale finite nonnegative weights before summation. +Normalization retains uniform zero slices; sampling rejects zero total +before consuming RNG. A supplied `Generator` owns sampling; omitted `rng` +retains the global NumPy stream. Neither helper mutates its input. + ## Execution ```python @@ -44,6 +56,45 @@ Run the complete local release gate with `uv run python scripts/release_check.py --arm all`; the no-argument default is the fast selection. See [`gate.md`](gate.md). +## Persistence and validation + +Persistence is run/agent keyed. Pass +`persist_dataframe(..., models={(run, agent_id_string): agent})`; use the +same keys for `persist_generative_model`, `persist_generative_model_npz`, +and `persist_policies`. Model records retain ordered action labels, +dimensions, border, policy length, and the actual policy cap. + +Focused model, policy, and per-step validators require their parsed +configuration/model/trajectory prerequisites. Missing prerequisites fail. +The version-2 artifact and summary layouts, schedules, and required renders +are defined in [`pipeline.md`](pipeline.md); refreshing hashes never replaces +identity or value validation. + +## GNN, manuscript, and notebook consumers + +`blockference.gnn.spec_arrays` exports a numeric uniform prior over complete +policies; runtime `ActiveGridference.E` remains the ordered action vocabulary. +For five actions and horizon two, exported `E`, `pi`, and `G` have 25 entries, +while `B` has five action slices. Float text preserves round-trip precision, +including one-element vectors. The pinned parser canonicalizes `pi` to `π`; +parsed-payload consumers use that canonical name. + +The external worker and independently reviewed resources are described in +[`gnn.md`](gnn.md). Pin inspection and `gnn_*` manuscript metadata do not +constitute source execution, installed-origin, or scientific qualification. + +`load_manuscript_experiment` reads the confined repository-relative +`experiment.config_path` in manuscript metadata through the typed YAML/TOML +loader. Missing or escaping selections do not fall back to a default file. +See [`manuscript/README.md`](manuscript/README.md) for relocated resources. + +`blockference.notebook_inventory` owns `tracked_notebooks`, +`validate_notebook`, `validate_all`, and `execute_notebooks`. +`validate_all` returns `(frozen_paths, failures)`; execution validates and +executes that frozen tracked selection in its supplied workspace. +See [`../notebooks/README.md`](../notebooks/README.md) for selection and kernel +boundaries. + ## CLI ```text @@ -57,3 +108,6 @@ blockference validation --run-dir RUN_DIRECTORY `plot_trajectory`, `plot_action_distribution`, `plot_belief_heatmap`, `plot_efe`, and `animate_trajectory` return the written path. `plot_efe` consumes the persisted `efe` vectors and plots the minimum policy EFE per step. +Histories are run/agent keyed. Select both `run` and `agent_id` for a heatmap +when an agent occurs in multiple runs. Its `timestep` argument indexes the +ordered history; titles and GIF labels report actual run/time/substep values. diff --git a/docs/design-contract.md b/docs/design-contract.md index 2751825..54aa055 100644 --- a/docs/design-contract.md +++ b/docs/design-contract.md @@ -29,8 +29,8 @@ the model itself: enumeration, action sampling, environment stepping, and plots. 3. Probability arrays are finite, non-negative, shape-compatible, and normalized wherever they represent a distribution. -4. A multi-agent step is simultaneous: every proposal is computed from the - same pre-step occupancy map and resolved deterministically. +4. A shared-world multi-agent step is simultaneous: every proposal is computed + from the same pre-step occupancy map and resolved deterministically. 5. A persisted prior describes the realized world transition. A rejected collision proposal therefore produces a one-hot prior at the agent's realized coordinate. @@ -39,6 +39,16 @@ the model itself: 7. A release verdict is meaningful only after parsing the persisted files independently of the producing objects. +`GridWorld.step` and `p_actinf_dict` share occupancy: initially occupied cells +remain unavailable, swaps are refused, and free-cell conflicts use the +established `(type name, repr)` identity order. `actinf_graph` instead gives +each graph node an independent world; matching coordinates across nodes are +not shared-world collisions. + +Built-in integer and string IDs are distinct. Version-2 typed serialization +preserves registry insertion order for sequence actions without changing +conflict priority (for example, integer `10` precedes integer `2` by `repr`). + ## Constraint classification | Item | Classification | Current decision | @@ -47,7 +57,7 @@ the model itself: | YAML and TOML input | Soft choice | Accept both through one strict dataclass schema. | | CSV and JSON required artefacts | Soft choice | Keep readable interchange formats as the minimum contract. | | Parquet output | Optional convenience | Write it only when a compatible writer exists. | -| One shared `initial_state` field | Compatibility assumption | Preserve it by broadcasting; add `initial_states` for explicit starts. | +| One `initial_state` field | Compatibility assumption | Retain for one agent; multiple agents require distinct `initial_states`. | | Fully observed identity `A` | Model scope | Keep as the control condition; partial observation is a new model feature. | | Deterministic square-grid `B` | Model scope | Do not imply stochastic or obstacle dynamics without new validation. | | Large policy horizons | Physical resource limit | Fail or redesign before exponential enumeration becomes accidental. | diff --git a/docs/development.md b/docs/development.md index 379b2b9..dffcac2 100644 --- a/docs/development.md +++ b/docs/development.md @@ -21,13 +21,15 @@ the `slow` marker and are excluded from `--arm test`. The recorded before/after arm times, including the render arm, are in [`_generated/gate-metrics.md`](_generated/gate-metrics.md). -The `gnn` arm always runs the shared `python -m gnn.importers check --repo .` -pin and pointer reader plus pinned parser conformance -(`scripts/validate_gnn_spec.py`); it fails without the external runtime rather -than skipping validation. Replace the runtime path above with an installed -pinned interpreter, or configure the source-checkout route in [`gnn.md`](gnn.md). -CI's `gnn-conformance` job runs `all` on Python 3.12 with that separate runtime; -the Python 3.11 `test` job runs `test-full`. There is no separate `gate` job. +The `gnn` arm performs exporter drift checks and invokes the project validator, +which owns deep conformance and the shared importer check inside independent +qualified external lifetimes. Select the separate runtime and reviewed +`GNN_BOOTSTRAP`/`GNN_SOURCE_MANIFEST` resources per [`gnn.md`](gnn.md). +Missing resources, installed provenance, or failed exit revalidation fail; +there is no unchecked direct-import or project-Python fallback. +CI's Python 3.12 `gnn-conformance` job selects `all`; reviewed resource delivery +must be provisioned before hosted acceptance. The Python 3.11 `test` job +selects `test-full`. There is no separate `gate` job. Markdown links and anchors across all tracked documentation are validated by `scripts/check_docs_links.py`, which is also part of the canonical release diff --git a/docs/gate.md b/docs/gate.md index e5dfe32..3b18055 100644 --- a/docs/gate.md +++ b/docs/gate.md @@ -14,6 +14,8 @@ uv run python scripts/release_check.py --list # arms and their commands Run `uv sync --locked --extra dev` before the gate. Its child commands set `UV_NO_SYNC=1` to reuse that prepared project environment instead of repeating dependency synchronization. +Release selections also require the independently reviewed `GNN_BOOTSTRAP` +and `GNN_SOURCE_MANIFEST` inputs described in [`gnn.md`](gnn.md). Measured wall times and test counts live in the generated [`_generated/gate-metrics.md`](_generated/gate-metrics.md), which shows the @@ -33,10 +35,10 @@ measurements. | `test` | `uv run pytest -m "not slow"` | no | | `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`, then pinned `scripts/validate_gnn_spec.py --verify-tag-remote` conformance (parser digests verified before anything parses, the pin's tag resolved upstream to the pinned commit; needs network), then the shared `python -m gnn.importers check --repo .` pin and pointer check; missing runtime fails | yes | +| `manuscript` | `scripts/manuscript_variables.py --check`, `scripts/validate_manuscript.py`, `scripts/build_manuscript.py`, `scripts/build_manuscript.py --check`; `gnn_*` metadata comes from checked producer inspection, not a qualification verdict | yes | +| `gnn` | `scripts/export_gnn_spec.py --check`, then `scripts/validate_gnn_spec.py --verify-tag-remote`, which owns both guarded deep conformance and the shared syntax/pointer/workflow/job check; remote tag verification needs network | 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 | +| `package` | invocation-owned `uv build --wheel --out-dir`, locked dependency constraints, and an isolated installed-wheel import outside the source tree | yes | | `render` | `scripts/build_manuscript.py --render pdf` (Pandoc + XeLaTeX) | no | `--arm` is repeatable and arms always run in the canonical order above. `fast` @@ -58,22 +60,23 @@ job parses. The conformance job's key is `gnn-conformance` and its display name is `gnn conformance (pinned)`. -The pin, the pointer and the specification are read by the estate's shared -reader, `gnn.importers`, so this repository carries no copy of the pin shape. The -`gnn` arm runs the offline drift check, then real pinned-parser conformance, then -`python -m gnn.importers check --repo . --require-pointer ---workflow .github/workflows/ci.yml --job gnn-conformance` from the pinned -runtime. Conformance precedes that reader check because `gnn.importers check` -parses the document with the installed parser, while the validator verifies the -pin's parser digests before it parses anything: no arm command reaches the -parser before its digests are verified. - -Select an installed pinned runtime with `--gnn-runtime` or -`GNN_RUNTIME_PYTHON`, or supply a pinned source checkout via `GNN_ROOT` as -described in [`gnn.md`](gnn.md); with `GNN_ROOT` and no runtime named, the -checkout's own `.venv/bin/python` is used. Missing or invalid runtime -dependencies fail the arm and therefore `all`; conformance is never silently -skipped. +The `gnn` arm checks exporter drift, then invokes the project validator with +the selected external runtime and remote-tag request. The validator owns +deep conformance and the producer's shared syntax/pointer/workflow/job check +in separate isolated, qualified lifetimes. No trailing unchecked +`python -m gnn.importers` command bypasses admission. + +Select the external interpreter and independently reviewed bootstrap/full +manifest as described in [`gnn.md`](gnn.md). Admission binds complete content +and actual module ownership through verdict exit; five parser hashes alone +are insufficient. Installed mode additionally needs real canonical PEP610 Git +provenance. Source-artifact proof is separately labelled and never becomes an +installed-origin or scientific verdict. Missing resources, origin, runtime, +or failed revalidation fails the arm and therefore `all`, never silently skips. + +The package arm accepts exactly one fresh regular, non-symlink wheel from its +own build directory. It neither installs nor deletes stale repository `dist` +contents. Protocol unit controls are not an actual build/install smoke. ## GitHub Actions @@ -91,6 +94,12 @@ runtime remains separate from the locked library environment because their NumPy requirements differ. PDF rendering is an explicit local `--arm render` selection, not part of `all` or CI. +Hosted resource delivery is still a release prerequisite: the workflow must +receive the reviewed bootstrap and exact full manifest as explicit +`GNN_BOOTSTRAP`/`GNN_SOURCE_MANIFEST` inputs. Do not insert machine-local +campaign paths, invent a published artifact URL, or waive admission when +these inputs are unavailable. + The workflow installs uv directly with `astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2` (`v10.3.3`, pinned by commit because setup-uv publishes no floating `v10` tag). It does not diff --git a/docs/gnn.md b/docs/gnn.md index d5be30a..df17f5b 100644 --- a/docs/gnn.md +++ b/docs/gnn.md @@ -11,7 +11,7 @@ Python code and are checked against it. * `specs/gridworld_3x3.gnn.md` — the GNN document for the canonical 3x3 fixture: identity likelihood `A`, deterministic boundary-clamped transition `B[next_state, previous_state, action]`, one-hot preference `C`, one-hot - prior `D`, and the uniform policy prior `E` over the five affordances. + prior `D`, and a numeric uniform policy prior `E` over 25 length-two policies. * `specs/gnn-pin.json` — the pin record (schema `gnn-importer-pin/v1`): upstream repository, tag `v5.1.0`, commit `75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf`, recorded date, and SHA-256 @@ -22,20 +22,37 @@ The document is generated from the implementation by `ActiveGridference`, so the document cannot describe a model the package does not build. -## The pin is read by `gnn.importers`, not here +Exported `E`, `pi`, and `G` have complete-policy cardinality; `B` retains +action cardinality. Runtime `ActiveGridference.E` remains the ordered action +labels. Three actions at horizon two produce nine policies. Float text keeps +round-trip precision, and a singleton vector remains a tuple rather than a +scalar. The pinned parser canonicalizes source `pi` to `π`; parsed-payload +dimension checks use `π`. -The pin record is read and validated by the estate's shared reader, -`gnn.importers` in the pinned upstream revision. This repository keeps no copy -of that logic: +## Shared producer admission -* the artifact uses `read_pin`, `find_pin`, `check_pointer` and - `importer_variables` from that module; -* the release gate's `gnn` arm calls `python -m gnn.importers check --repo .` - from the pinned runtime; -* `scripts/gnn_importer_report.py` is the only bridge: it runs in an - interpreter where `gnn` is importable and prints the normalized pin and the - `gnn-importer-variables/v1` map as JSON for - `scripts/validate_gnn_spec.py` and `scripts/manuscript_variables.py`. +`blockference/gnn_source.py` is a stdlib-only external worker, launched directly +with `-I -B` in the selected GNN interpreter. It first checks and executes the +independently reviewed producer bootstrap, without importing target `gnn`. +The bootstrap owns pin discovery, reading, and manuscript metadata inspection; +inspection reports `qualified=false` and is not a parser verdict. + +Every actual parser, semantic, orientation, consistency, and shared +`gnn.importers` check runs inside producer admission through final import/content +revalidation. The project validator owns these separate guarded lifetimes. +There is no direct unchecked `-m gnn.importers` gate command, copied local pin +reader, or surviving `gnn_importer_report.py`/`gnn_parser_probe.py` entry point. + +Supply `GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` from independently reviewed +producer artifacts. The source-owned expected SHA-256 values are: + +* bootstrap: `f638d4c01fe7de31e43d793e59bf382d0c3d1a82f365c59238334a2b40adfb37`; +* full v5.1.0 manifest: `43b33c0b2b40386afa3f306fec4cc13bc1fd7c3b570fbf11d5008bad5c8e6b51`. + +Do not derive expected identity from the target package or replace complete +content/module ownership with a version string or the five parser digests. +Artifact publication/acquisition is release-owner work; no public download +location is assumed here. The cutover replaced the interim local reader. Until this change `specs/gnn-pin.json` pinned `v5.0.3` at `8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1`, a revision that @@ -50,71 +67,63 @@ adoption follows the pin and not the contract date. ## Commands ```bash -# The shared reader, from the pinned runtime (release gate, `gnn` arm) -"$GNN_RUNTIME_PYTHON" -m gnn.importers check --repo . --require-pointer \ - --workflow .github/workflows/ci.yml --job gnn-conformance +# Select existing independently reviewed resources and a prepared interpreter. +export GNN_BOOTSTRAP=/reviewed/gnn_bootstrap.py +export GNN_SOURCE_MANIFEST=/reviewed/v5.1.0-source-manifest.json +export GNN_RUNTIME_PYTHON=/prepared/gnn/bin/python # Regenerate the document, or verify it is current (release gate) uv run python scripts/export_gnn_spec.py uv run python scripts/export_gnn_spec.py --check -# Validate with the pinned upstream parser (requires a GNN source or runtime) -GNN_ROOT=/path/to/Generalized_Notation_Notation \ -GNN_PYTHON=/path/to/parser-runtime/bin/python \ -uv run python scripts/validate_gnn_spec.py --json +# Explicit source checkout: materialize the exact pin, then validate. +uv run python scripts/validate_gnn_spec.py \ + --gnn-root /path/to/Generalized_Notation_Notation --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 +# Installed mode: requires real matching PEP610 Git origin and full content. +# --verify-tag-remote additionally needs network access. +uv run python scripts/validate_gnn_spec.py --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, -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. - -CI's `gnn-conformance` job (display name `gnn conformance (pinned)`) runs the -full `all` selection on Python 3.12, provisioning a separate pinned runtime -because GNN requires NumPy 2.x while the library's committed lock resolves -NumPy 1.x. That runtime is also what the `manuscript` arm uses for the `gnn_*` -documented variables, whose values come from `gnn.importers.importer_variables`. -An unavailable runtime fails the `gnn` arm and `all`; no opt-in requirement flag -or skip mode is needed. See [`gate.md`](gate.md) for the canonical gate commands -and exact CI map. +Interpreter precedence is explicit `--gnn-runtime`, `GNN_RUNTIME_PYTHON`, +explicit legacy `--python`, `GNN_PYTHON`, then the selected `GNN_ROOT/.venv` +launcher. A missing explicit selection fails; it never substitutes project +Python. Venv launcher paths are preserved. The project and GNN NumPy +environments remain separate. + +For a Git checkout, the project validator resolves and archives the exact pin +before execution. A separately admitted plain source tree is explicitly +source-only: complete-content/import proof does not invent Git or installed +provenance, and plain-artifact receipts retain `vcs_verified=false`. +Installed mode requires actual distribution ownership, canonical PEP610 Git +origin with the pinned commit, and complete package content. An editable-local +installation or missing origin is not an installed pass and cannot fall back +to source. + +Exit codes are `0` pass, `1` conformance failure, and `2` unavailable required +runtime/resources/origin or requested tag resolution. Missing prerequisites +are not passes. CI must separately provision the reviewed bootstrap and full +manifest alongside its pinned runtime before hosted acceptance; local source +proof does not supply those hosted inputs. See [`gate.md`](gate.md). ## What the validation checks -1. The pin and the pointer: `gnn.importers` reports the pin file, its schema, - `repository`, `tag` and 40-hex `commit`, and requires - [`.github/GNN.md`](../.github/GNN.md) to name the pin file, the pinned - 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, 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 upstream answer is - authoritative: when the flag is given, upstream is always queried, so a tag - that moved after a checkout fetched it fails even though the local tag still - names the pinned commit. 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`). +1. The shared producer reports the pin and requires + [`.github/GNN.md`](../.github/GNN.md) to name its file, revision, workflow + `.github/workflows/ci.yml`, and job `gnn-conformance`. +2. Independent bootstrap/full-manifest admission precedes all target GNN + execution. Actual imported modules and verdict exit revalidation must + remain qualified. Parsing has no errors or warnings and the version + matches the pinned tag. + The tag must resolve to the pinned commit: locally for a Git checkout, or + upstream when `--verify-tag-remote` is requested. Remote verification + always queries upstream rather than trusting a stale local tag. Missing + offline tag/revision observations remain `unresolvable-offline`; they are + not invented VCS proof or a substitute for installed-origin admission. 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. + exactly; state-space dimensions and redundant action/policy counts must + agree. Parsed `π` and `G` have complete-policy cardinality. 4. The pinned semantic validator accepts the document, the B-tensor orientation diagnostic reports `canonical`, and the consistency checker reports a complete score. @@ -134,8 +143,9 @@ The receipt is written to `docs/_build/gnn/validation-receipt.json` * `parameters_from_parsed(payload)` / `declared_arrays(payload)` — read a pinned parser payload back into parameters and matrices. -Reading the pin is not part of this package: `gnn.importers` owns that, and the -gate calls it from the pinned runtime. +The producer owns pin inspection and execution admission. Manuscript `gnn_*` +metadata is inspection only, not an installed, source-execution, or scientific +qualification result. ## Scope diff --git a/docs/manuscript/09_reproducibility.md b/docs/manuscript/09_reproducibility.md index 875b764..b515b4c 100644 --- a/docs/manuscript/09_reproducibility.md +++ b/docs/manuscript/09_reproducibility.md @@ -6,14 +6,17 @@ uses `uv sync --locked --extra dev` for development. The release procedure is: ```bash uv sync --locked --extra dev GNN_RUNTIME_PYTHON="${GNN_RUNTIME_PYTHON:?Set the external pinned GNN runtime Python}" \ +GNN_BOOTSTRAP="${GNN_BOOTSTRAP:?Set the independently reviewed producer bootstrap}" \ +GNN_SOURCE_MANIFEST="${GNN_SOURCE_MANIFEST:?Set the independently reviewed full manifest}" \ uv run python {{gate_entry_point}} --arm all ``` The release selection requires a separately configured external GNN runtime at the pinned revision, named by `GNN_RUNTIME_PYTHON` (or a pinned checkout named by -`GNN_ROOT`); see [`../gnn.md`](../gnn.md) for setup. The `gnn` arm always performs -real pinned validation and fails when that runtime is unavailable. The gate has -separately runnable arms (`--list` shows them); `--arm all` is the release +`GNN_ROOT`), plus the independently reviewed bootstrap and full manifest; +see [`../gnn.md`](../gnn.md). The `gnn` arm performs real qualified validation +and fails when required resources, provenance, or exit revalidation are unavailable. +The gate has separately runnable arms (`--list` shows them); `--arm all` is the release selection and the fast default is used while editing. The generative-model declaration is checked against the pinned upstream parser: @@ -21,10 +24,10 @@ The generative-model declaration is checked against the pinned upstream parser: commit `{{gnn_commit}}`. The conformance job key is `{{gnn_job_key}}` with display name `{{gnn_job_name}}`; the pointer [`../../.github/GNN.md`](../../.github/GNN.md) records exactly what that job -parses. The pin and the pointer are validated by the estate's shared reader, -`python -m gnn.importers check --repo .`, which the `gnn` arm runs from the -pinned runtime; those same `gnn.importers` facts are what the variables above -declare, so prose and conformance cannot disagree about the pinned revision. +parses. The project validator runs the shared producer's pin/pointer check +and deep conformance in separate qualified external lifetimes. The variables +above come from checked producer metadata inspection, which is explicitly +not a source-execution, installed-origin, or scientific qualification verdict. The canonical command emits a run tree whose completed `manifest.json` and independently written `validation_report.json` agree. `PipelineResult.ok` and diff --git a/docs/manuscript/README.md b/docs/manuscript/README.md index 1249d27..0f39c24 100644 --- a/docs/manuscript/README.md +++ b/docs/manuscript/README.md @@ -39,6 +39,25 @@ the rendered PDF/HTML live under `docs/_build/`, which is reproducible and excluded from version control. Change the ordered source, then rerun the builder and validation commands. +The metadata's `experiment.config_path` must be a nonempty repository-relative +path confined to the selected root. Figures, variables, and validation share +the typed YAML/TOML loader; there is no hardcoded `manuscript.yml` fallback. +Seeded paths and EFE curves retain run/agent histories and actual times, and +plot bounds follow the selected grid dimension. + +Composition rebases local inline, image, and reference-definition destinations +from each source document into the actual output directory, including +`99_references.md`. Queries, fragments, titles, encoded/escaped parentheses, +external URLs, code, and scholarly citations are preserved. Ordinary missing +resources fail. Registered figures have explicit output destinations; +bibliography and metadata are copied alongside them and rendering consumes +those copies. A relocated GNN link still points to its actual source document. + +Generating variables requires the reviewed external GNN resources in +[`../gnn.md`](../gnn.md). Metadata inspection is not a conformance verdict. +Software composition/render tests do not authorize changing scientific +definitions, accepting manuscript claims, or refreshing canonical figures. + ## Figure bytes `figures/` keeps both an SVG and a PNG for every figure. Both formats are diff --git a/docs/pipeline.md b/docs/pipeline.md index 3110961..f8d14f7 100644 --- a/docs/pipeline.md +++ b/docs/pipeline.md @@ -32,6 +32,10 @@ list are rejected. A multi-agent run (`n_agents > 1`) requires one distinct broadcast default is valid only for a single agent and otherwise fails fast with an explicit error before any simulation backend runs. +File roots must be mappings. Empty/comment-only YAML and explicit YAML `null` +retain the default-configuration contract; `false`, zero, an empty string, and +lists are not treated as omitted configuration. They fail before output setup. + ## Required run tree ```text @@ -49,7 +53,9 @@ RUN/ ├── viz/ │ ├── trajectory.png │ ├── action_distribution.png -│ └── efe.png +│ ├── efe.png +│ ├── belief_heatmap_run__agent__first.png +│ └── belief_heatmap_run__agent__last.png ├── animations/trajectory.gif └── validation_report.json ``` @@ -57,12 +63,40 @@ RUN/ Parquet files may be added when an installed parquet engine supports the serialised schema. They are never used in place of required CSV/JSON files. +## Run and agent identity + +Model and policy JSON use version 2: +`{"version": 2, "runs": {"": {"": ""}}}`. +Every configured `(run, agent)` owns its model and ordered policy set. NPZ +keys are `run_/agent_/`. Trajectory agent records bind +`agent_id` and `model_sha256` to that same immutable model; a refreshed +manifest cannot certify swapped JSON/NPZ models. + +Summary version 2 retains aggregate row/agent/grid/run counts and places +`final_positions`, `trajectory_lengths`, and `belief_history_lengths` under +`runs[]`. Old flat summary fields and version-1 model/policy artifacts +are not silently migrated. Preserve historical trees and generate a new run. + +Each run contains `(timestep=0, substep=0)` followed by +`(timestep=1..T, substep=1)`. Every run retains its configured starts, complete +unique per-agent diagnostics, ordered affordances, and actual planning cap. +Actions and observation indices are integer categories, not numeric strings, +floats, or booleans. Policy diagnostics have `actions**planning_length` +entries; action distributions have action cardinality. + +Plots, heatmaps, and animation histories are keyed by `(run, agent)` and +ordered by actual time/substep. Independent runs are not concatenated. +Both heatmaps shown above are required for every configured pair. + ## Validation The aggregate `ValidationReport.ok` is the conjunction of trajectory schema, generative-model invariants, complete per-step diagnostics, parsed artefacts, and rendered files. `PipelineResult.ok` returns that value, and the `pipeline` CLI exits with status 1 when it is false. +Missing parsed prerequisites, malformed policies or matrices, invalid UTF-8, +and mismatched keyed diagnostics produce failed reports, not successful +skipped boundaries. The validation CLI emits its JSON report and status 1. These verdicts certify software and artefact integrity only. They do not — and cannot — certify the empirical adequacy of a scientific hypothesis. Any diff --git a/ignored.csv b/ignored.csv deleted file mode 100644 index 4a386fc..0000000 --- a/ignored.csv +++ /dev/null @@ -1,8 +0,0 @@ -,agents,priors,env_states,actions,inferences,efe,efe_epistemic,efe_pragmatic,q_pi,p_u,obs_idx,simulation,subset,run,substep,timestep -0,{0: },"{0: array([1., 0., 0., 0., 0., 0., 0., 0., 0.])}","{0: (0, 0)}",{0: ''},{0: ''},{0: ''},{0: ''},{0: ''},{0: ''},{0: ''},{0: ''},0,0,1,0,0 -1,{0: },"{0: array([1.e+00, 1.e-32, 0.e+00, 2.e-32, 1.e-32, 0.e+00, 2.e-32, 1.e-32, - 0.e+00])}","{0: (0, 0)}",{0: 2},"{0: array([1.e+00, 1.e-32, 1.e-32, 1.e-32, 1.e-32, 1.e-32, 1.e-32, 1.e-32, - 1.e-32])}","{0: array([36.84136149, 36.84136149, 36.84136149, 36.84136149, 36.84136149])}","{0: array([0., 0., 0., 0., 0.])}","{0: array([36.84136149, 36.84136149, 36.84136149, 36.84136149, 36.84136149])}","{0: array([0.2, 0.2, 0.2, 0.2, 0.2])}","{0: array([0.2, 0.2, 0.2, 0.2, 0.2])}",{0: 0},0,0,1,1,1 -2,{0: },"{0: array([0.e+00, 1.e+00, 2.e-32, 0.e+00, 1.e-32, 2.e-32, 0.e+00, 1.e-32, - 2.e-32])}","{0: (0, 1)}",{0: 3},"{0: array([1.e+00, 1.e-32, 1.e-32, 1.e-32, 1.e-32, 1.e-32, 1.e-32, 1.e-32, - 1.e-32])}","{0: array([36.84136149, 36.84136149, 36.84136149, 36.84136149, 36.84136149])}","{0: array([0., 0., 0., 0., 0.])}","{0: array([36.84136149, 36.84136149, 36.84136149, 36.84136149, 36.84136149])}","{0: array([0.2, 0.2, 0.2, 0.2, 0.2])}","{0: array([0.2, 0.2, 0.2, 0.2, 0.2])}",{0: 0},0,0,1,1,2 diff --git a/notebooks/README.md b/notebooks/README.md index 4db66c7..01660d8 100644 --- a/notebooks/README.md +++ b/notebooks/README.md @@ -3,3 +3,17 @@ Every notebook is a small executable example of the current package API. The examples cover the model, environment transitions, collision resolution, and the optional local research workflow. + +`blockference.notebook_inventory` owns selection, validation, and execution. +The scripts and slow tests consume one frozen tracked selection from an exact +Git root, including worktrees. Ignored/untracked files, administrative/build +trees, checkpoints, missing tracked files, and symlink escapes cannot enter +execution. Git errors fail rather than trigger a recursive-scan fallback; +a valid empty selection remains empty. + +Execution uses the supplied workspace and an independently prepared +`python3` kernel. Source selection alone is not kernel qualification. +The single-agent gridference example owns `np.random.default_rng(17)` and +passes it to planning, independently of the global NumPy stream. Executing +examples does not authorize committing refreshed outputs, metadata, or +scientific claims. diff --git a/notebooks/simple_gridworld/gridference_single.ipynb b/notebooks/simple_gridworld/gridference_single.ipynb index 5ff1e62..1aa016b 100644 --- a/notebooks/simple_gridworld/gridference_single.ipynb +++ b/notebooks/simple_gridworld/gridference_single.ipynb @@ -7,7 +7,7 @@ "source": [ "# Single-agent inference model\n", "\n", - "This notebook demonstrates the current ActiveBlockference API with deterministic local data and no external services." + "This notebook demonstrates the current ActiveBlockference API with deterministic local data and no external services. One notebook-owned seeded NumPy Generator keeps planning independent of the process-global random stream." ] }, { @@ -17,13 +17,15 @@ "metadata": {}, "outputs": [], "source": [ + "import numpy as np\n", "from blockference import ActiveGridference, make_grid\n", "from blockference.gridference import actinf_planning_single\n", "\n", + "rng = np.random.default_rng(17)\n", "agent = ActiveGridference(make_grid(3), planning_length=1)\n", "agent.get_C((2, 2))\n", "agent.get_D((0, 0))\n", - "update = actinf_planning_single(agent, agent.env_state, agent.A, agent.B, agent.C, agent.D)\n", + "update = actinf_planning_single(agent, agent.env_state, agent.A, agent.B, agent.C, agent.D, rng=rng)\n", "print(update[\"update_action\"], update[\"update_env\"])" ] } @@ -41,4 +43,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md index 708e218..eb33536 100644 --- a/scripts/AGENTS.md +++ b/scripts/AGENTS.md @@ -2,9 +2,10 @@ - These are thin entry points over `blockference.*`; new computation belongs in the package and gets a test under `tests/`. -- Keep `gnn_parser_probe.py` the only importer of the upstream `gnn` package. - The validator runs it in a subprocess with the pinned tree first on - `PYTHONPATH`. +- Target GNN imports belong only inside the fully qualified external + `blockference/gnn_source.py` worker, launched directly with `-I -B`. + Project orchestration and checked metadata inspection do not bypass + independent bootstrap/full-manifest admission or merge NumPy environments. - Do not add a file to `docs/manuscript/figures/`. `build_manuscript.py` requires every file there to be produced by a fresh build, so a guide in that directory fails the release gate. diff --git a/scripts/README.md b/scripts/README.md index e0105d1..3169e71 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -6,27 +6,32 @@ Repository gates and generators, all run from the repository root: |---|---| | `release_check.py` | The canonical gate: composable arms for lint, types, fast/full tests, docs, manuscript, GNN, smoke, package, and render. | | `gate_metrics.py` | Imports disjoint baseline receipts with repeatable `--record-baseline PATH` and one current receipt with `--record-timings PATH`, writes `docs/_generated/gate-metrics.md`, and checks drift with `--check`. | -| `manuscript_variables.py` | Derives `docs/_generated/manuscript-variables.json` from `pyproject.toml`, CI, and the `gnn_*` keys that `gnn.importers.importer_variables` produces in the pinned runtime; `--check` gates drift. | +| `manuscript_variables.py` | Derives variables from project/CI metadata, the metadata-selected experiment, and checked producer pin inspection; `--check` gates drift. Inspection is not GNN execution qualification. | | `check_docs_links.py` | Validates internal Markdown links and anchors across tracked documentation. | | `build_manuscript.py` | Builds the manuscript and its figures, injects declared variables, and renders with Pandoc (`--render pdf\|html`). | | `validate_manuscript.py` | Fail-closed manuscript validation, including declared variables. | -| `execute_notebooks.py` | Parses and executes every tracked notebook from the repository root. | -| `validate_notebooks.py` | Notebook hygiene checks before execution. | +| `execute_notebooks.py` | Executes the frozen tracked selection owned by `blockference.notebook_inventory` in a temporary workspace. | +| `validate_notebooks.py` | Uses the same tracked inventory and hygiene producer; successful empty selection remains explicitly empty. | | `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. Verifies the parser digests before parsing, binds the pin's tag to its commit (`--gnn-root` checkout or `--verify-tag-remote`, which always queries upstream, so a stale local tag cannot pass; 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. | +| `validate_gnn_spec.py` | Owns deep model conformance and shared importer checks through isolated, fully admitted external workers, with separate source/installed provenance and optional remote tag verification. | -Run the release selection with a pinned GNN runtime configured before -publishing; the no-argument default is the fast selection. The `gnn` arm always -runs the shared `python -m gnn.importers check --repo .` and real pinned -conformance, and fails if its runtime is unavailable. +The external worker is `blockference/gnn_source.py`, invoked directly with +`-I -B` rather than importing the project into the GNN NumPy environment. +`gnn_parser_probe.py` and `gnn_importer_report.py` are retired. Select the +prepared interpreter and reviewed bootstrap/full manifest per +[`../docs/gnn.md`](../docs/gnn.md) before release. Missing inputs fail. [`../docs/gate.md`](../docs/gate.md) owns the arm commands, CI mapping, `--timings PATH` recording and metrics-import workflow. The gate reuses the already-synced locked project environment by setting -`UV_NO_SYNC=1` for its commands. Its package check constrains clean-wheel -dependencies using a locked `uv export` and imports the installed wheel from -outside the source checkout. PDF rendering remains an explicit local +`UV_NO_SYNC=1` for its commands. Its package check builds into an invocation-owned +directory, requires exactly one fresh regular wheel, constrains dependencies +with locked `uv export`, and imports outside the source checkout. Repository +`dist` is neither installed from nor cleaned. PDF rendering remains an explicit local `--arm render` selection of `build_manuscript.py --render pdf`; it is not part of `all` or CI. + +Manuscript configuration comes from the confined `experiment.config_path`, +not a hardcoded fallback. Composition rebases source-relative links into the +selected output directory and renders using copied bibliography, metadata, +and registered figures; missing ordinary resources fail. diff --git a/scripts/build_manuscript.py b/scripts/build_manuscript.py index da88d59..38a379d 100644 --- a/scripts/build_manuscript.py +++ b/scripts/build_manuscript.py @@ -10,7 +10,6 @@ from __future__ import annotations import argparse -import ast import json import os import re @@ -20,6 +19,11 @@ from collections import defaultdict from pathlib import Path +import yaml + +from blockference.config import load_manuscript_experiment +from blockference.manuscript_links import rebase_local_links + if __package__: from scripts.validate_manuscript import figure_registry_errors else: @@ -230,8 +234,22 @@ def replace(match: re.Match[str]) -> str: return resolved -def compose_manuscript() -> tuple[str, dict[str, dict[str, int]]]: +def compose_manuscript(*, output_dir: Path | None = None) -> tuple[str, dict[str, dict[str, int]]]: variables = _manuscript_variables() + destination = BUILD_DIR if output_dir is None else output_dir + errors = figure_registry_errors(MANUSCRIPT_DIR, check_files=False) + if errors: + raise ValueError("; ".join(errors)) + registry = json.loads((MANUSCRIPT_DIR / "figure-registry.json").read_text(encoding="utf-8")) + copied = { + (FIGURE_DIR / entry[kind]).resolve(): destination / "figures" / entry[kind] + for entry in registry["figures"] for kind in ("svg", "png") + } + for name in ("references.bib", "config.yaml"): + resource = MANUSCRIPT_DIR / name + if not resource.is_file(): + raise FileNotFoundError(f"missing manuscript resource: {resource}") + copied[resource.resolve()] = destination / name sources = [ (path, _substitute_variables(text, path, variables)) for path, text in _read_sources() @@ -243,6 +261,9 @@ def compose_manuscript() -> tuple[str, dict[str, dict[str, int]]]: "", ] for path, source in sources: + source = rebase_local_links( + source, source=path, output_dir=destination, copied=copied, + ) if path.name == "99_references.md": sections.append(source.strip()) continue @@ -357,6 +378,9 @@ def build_figures(output_dir: Path = FIGURE_DIR) -> list[Path]: import matplotlib.pyplot as plt from matplotlib.patches import FancyArrowPatch, Rectangle + metadata = yaml.safe_load((MANUSCRIPT_DIR / "config.yaml").read_text(encoding="utf-8")) + _selected, cfg = load_manuscript_experiment(REPO_ROOT, metadata) + output_dir.mkdir(parents=True, exist_ok=True) paths: list[Path] = [] @@ -444,41 +468,39 @@ def build_figures(output_dir: Path = FIGURE_DIR) -> list[Path]: _save_figure(fig, path) paths.append(path) - from blockference.config import load_experiment_config from blockference.simulations.grid_sim import run_experiment + from blockference.viz._common import ( + extract_agent_positions, + extract_efe_history, + extract_history_steps, + ) - cfg = load_experiment_config(REPO_ROOT / "configs" / "manuscript.yml") frame = run_experiment(cfg) - def as_mapping(value): - return value if isinstance(value, dict) else ast.literal_eval(str(value)) fig, axes = plt.subplots(1, 2, figsize=(10, 4)) try: - positions = [as_mapping(value) for value in frame["env_states"]] - for agent_id in sorted(positions[0], key=repr): - ys = [state[agent_id][0] for state in positions] - xs = [state[agent_id][1] for state in positions] - axes[0].plot(xs, ys, "-o", label=f"agent {agent_id}") - axes[0].set_xlim(-0.25, 2.25) - axes[0].set_ylim(2.25, -0.25) - axes[0].set_xticks(range(3)) - axes[0].set_yticks(range(3)) + for (run, agent_id), positions in extract_agent_positions(frame).items(): + ys, xs = zip(*positions, strict=True) + axes[0].plot(xs, ys, "-o", label=f"run {run} / agent {agent_id}") + border = cfg.grid.dimension - 1 + axes[0].set_xlim(-0.25, border + 0.25) + axes[0].set_ylim(border + 0.25, -0.25) + axes[0].set_xticks(range(cfg.grid.dimension)) + axes[0].set_yticks(range(cfg.grid.dimension)) axes[0].grid(True, alpha=0.3) axes[0].set_title("Seeded paths") axes[0].set_xlabel("x") axes[0].set_ylabel("y") axes[0].legend() - efe_values: dict[object, list[float]] = defaultdict(list) - for value in frame["efe"]: - parsed = as_mapping(value) - for agent_id, vector in parsed.items(): - if vector is not None: - efe_values[agent_id].append(min(map(float, vector))) - for agent_id, values in efe_values.items(): - axes[1].plot(range(len(values)), values, "-o", label=f"agent {agent_id}") + steps = extract_history_steps(frame, "efe") + for key, history in extract_efe_history(frame).items(): + axes[1].plot( + [time for time, _substep in steps[key]], [float(vector.min()) for vector in history], + "-o", label=f"run {key[0]} / agent {key[1]}", + ) axes[1].set_title("Persisted policy EFE") - axes[1].set_xlabel("step") + axes[1].set_xlabel("timestep") axes[1].set_ylabel("min G(π) (nats)") axes[1].grid(True, alpha=0.3) axes[1].legend() @@ -535,6 +557,8 @@ def _write_outputs(compiled: str) -> Path: shutil.copy2(figure, build_figures_dir / figure.name) for figure in FIGURE_DIR.glob("*.png"): shutil.copy2(figure, build_figures_dir / figure.name) + for name in ("references.bib", "config.yaml"): + shutil.copy2(MANUSCRIPT_DIR / name, BUILD_DIR / name) return output @@ -672,11 +696,11 @@ def render_manuscript(compiled: Path, fmt: str, output: Path | None = None) -> P "--standalone", "--citeproc", "--bibliography", - str(MANUSCRIPT_DIR / "references.bib"), + str(compiled.parent / "references.bib"), "--metadata-file", - str(MANUSCRIPT_DIR / "config.yaml"), + str(compiled.parent / "config.yaml"), "--resource-path", - str(BUILD_DIR), + str(compiled.parent), "-o", str(target), ] @@ -715,9 +739,6 @@ def main(argv: list[str] | None = None) -> int: if args.check and args.render != "none": parser.error("--check cannot be combined with --render") try: - registry_errors = figure_registry_errors(MANUSCRIPT_DIR, check_files=False) - if registry_errors: - raise ValueError("; ".join(registry_errors)) compiled, labels = compose_manuscript() if not args.check: if not args.no_figures: diff --git a/scripts/execute_notebooks.py b/scripts/execute_notebooks.py index 906a1dd..f99c071 100644 --- a/scripts/execute_notebooks.py +++ b/scripts/execute_notebooks.py @@ -5,33 +5,16 @@ import tempfile from pathlib import Path -import nbformat -from nbclient import NotebookClient +from blockference.notebook_inventory import execute_notebooks def main() -> int: root = Path(__file__).resolve().parents[1] - try: - from .validate_notebooks import validate_all - except ImportError: - from validate_notebooks import validate_all - - failures = validate_all(root) - if failures: - raise ValueError(f"notebook hygiene violations: {failures}") with tempfile.TemporaryDirectory(prefix="activeblockference-notebooks-") as workspace: - workspace_path = Path(workspace) - for path in sorted(root.rglob("*.ipynb")): - if ".venv" in path.parts or ".git" in path.parts or ".ipynb_checkpoints" in path.parts: - continue - notebook = nbformat.read(path, as_version=4) - NotebookClient( - notebook, - timeout=120, - kernel_name="python3", - resources={"metadata": {"path": str(workspace_path)}}, - ).execute() + notebooks = execute_notebooks(root, workspace=workspace) + for path in notebooks: print(path.relative_to(root)) + print(f"executed {len(notebooks)} tracked notebooks") return 0 diff --git a/scripts/gnn_importer_report.py b/scripts/gnn_importer_report.py deleted file mode 100644 index dc93182..0000000 --- a/scripts/gnn_importer_report.py +++ /dev/null @@ -1,70 +0,0 @@ -"""Print the upstream ``gnn.importers`` reading of this repository's GNN pin. - -``gnn.importers`` is the estate's single reader for a GNN pin (discovery, shape -normalization, pointer checks and the ``gnn-importer-variables/v1`` map). This -module is the bridge that calls it from a Python process: it runs in an -interpreter where ``gnn`` is importable, and prints the normalized pin plus the -GNN-derived manuscript variables as JSON. Neither this repository nor its -scripts re-implement the pin shape. - -Run it with the pinned runtime (``GNN_RUNTIME_PYTHON``), or with a pinned source -checkout first on ``PYTHONPATH``. ``scripts/validate_gnn_spec.py`` and -``scripts/manuscript_variables.py`` invoke it; the release gate's ``gnn`` arm -calls ``python -m gnn.importers check`` directly and does not need this bridge. - -Usage (normally invoked by those scripts, not by hand): - - GNN_RUNTIME_PYTHON/bin/python scripts/gnn_importer_report.py --repo . -""" - -from __future__ import annotations - -import argparse -import json -import sys -from pathlib import Path -from typing import Any - -from gnn.importers import find_pin, importer_variables, read_pin - - -def report( - repo_root: Path, *, job: str | None = None, job_name: str | None = None -) -> dict[str, Any]: - """Return the shared reader's pin record and manuscript variables.""" - - pin_path = find_pin(repo_root) - if pin_path is None: - raise SystemExit(f"no GNN pin file found under {repo_root}") - pin = read_pin(pin_path) - parser_files = pin.raw.get("parser_files") - return { - "pin": { - "path": pin.path.relative_to(repo_root).as_posix(), - "schema": pin.schema, - "repository": pin.repository, - "tag": pin.tag, - "commit": pin.commit, - "recorded": pin.recorded, - "spec_files": list(pin.spec_files), - "parser_files": parser_files if isinstance(parser_files, dict) else {}, - }, - "variables": importer_variables(pin, repo_root=repo_root, job=job, job_name=job_name), - } - - -def main(argv: list[str] | None = None) -> int: - """Print the report for one repository checkout.""" - - parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument("--repo", type=Path, default=Path(".")) - parser.add_argument("--job", help="conformance job key the pointer and variables name") - parser.add_argument("--job-name", help="display name of that job") - args = parser.parse_args(argv) - payload = report(args.repo.resolve(), job=args.job, job_name=args.job_name) - sys.stdout.write(json.dumps(payload, indent=2, sort_keys=True) + "\n") - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/scripts/gnn_parser_probe.py b/scripts/gnn_parser_probe.py deleted file mode 100644 index 83e9d9b..0000000 --- a/scripts/gnn_parser_probe.py +++ /dev/null @@ -1,105 +0,0 @@ -"""Extract one GNN document with the pinned upstream parser and print JSON. - -This module is the only place that imports the upstream ``gnn`` package. It is -executed as a subprocess by ``scripts/validate_gnn_spec.py`` with the pinned -source tree first on ``PYTHONPATH``, so the parser that runs is always the -revision recorded in ``specs/gnn-pin.json`` and never a live checkout. - -Usage (normally invoked by the validator, not by hand): - - PYTHONPATH=/src python scripts/gnn_parser_probe.py --spec -""" - -from __future__ import annotations - -import argparse -import json -import sys -from pathlib import Path -from typing import Any - -from gnn import __version__ as gnn_version -from gnn.parsers.markdown_parser import MarkdownGNNParser -from gnn.validation.consistency_checker import check_consistency -from gnn.validation.orientation import check_b_orientation -from gnn.validation.semantic_validator import SemanticValidator - - -def _jsonable(value: Any) -> Any: - if isinstance(value, dict): - return {str(key): _jsonable(item) for key, item in value.items()} - if isinstance(value, (list, tuple)): - return [_jsonable(item) for item in value] - if isinstance(value, (str, int, float, bool)) or value is None: - return value - return str(value) - - -def probe(spec: Path) -> dict[str, Any]: - """Parse and validate ``spec`` with the imported (pinned) parser.""" - - parser = MarkdownGNNParser() - result = parser.parse_file(str(spec)) - model = result.model - semantic = SemanticValidator().validate(spec.read_text(encoding="utf-8")) - orientation = check_b_orientation(spec) - consistency = check_consistency(spec) - return { - "gnn_version": gnn_version, - "gnn_module": __import__("gnn").__file__, - "parser": { - "success": bool(result.success), - "errors": list(result.errors), - "warnings": list(result.warnings), - "model_name": model.model_name, - "version": model.version, - "variables": [ - { - "name": variable.name, - "dimensions": list(variable.dimensions), - "data_type": str(variable.data_type), - } - for variable in model.variables - ], - "connections": [ - { - "sources": list(connection.source_variables), - "targets": list(connection.target_variables), - "type": str(connection.connection_type), - } - for connection in model.connections - ], - "ontology_mappings": [ - {"variable": mapping.variable_name, "term": mapping.ontology_term} - for mapping in model.ontology_mappings - ], - "parameters": { - parameter.name: _jsonable(parameter.value) for parameter in model.parameters - }, - "sections": sorted(model.raw_sections), - "time_specification": _jsonable(model.time_specification), - }, - "semantic": _jsonable(semantic), - "orientation": _jsonable(orientation), - "consistency": _jsonable(consistency), - } - - -def main(argv: list[str] | None = None) -> int: - """Parse one specification and print the JSON payload.""" - - parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument("--spec", type=Path, required=True) - parser.add_argument("--output", type=Path) - args = parser.parse_args(argv) - payload = probe(args.spec) - text = json.dumps(payload, indent=2, sort_keys=True) + "\n" - if args.output: - args.output.parent.mkdir(parents=True, exist_ok=True) - args.output.write_text(text, encoding="utf-8") - sys.stdout.write(text) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/scripts/manuscript_variables.py b/scripts/manuscript_variables.py index 087e2f6..589055e 100644 --- a/scripts/manuscript_variables.py +++ b/scripts/manuscript_variables.py @@ -13,7 +13,6 @@ import argparse import json -import os import subprocess import sys import tomllib @@ -21,10 +20,13 @@ import yaml +from blockference.config import load_manuscript_experiment +from blockference.gnn_runtime import resolve_gnn_runtime +from blockference.gnn_source import worker_command + ROOT = Path(__file__).resolve().parents[1] VARIABLES_PATH = ROOT / "docs" / "_generated" / "manuscript-variables.json" WORKFLOW_PATH = ROOT / ".github" / "workflows" / "ci.yml" -REPORT = ROOT / "scripts" / "gnn_importer_report.py" SCHEMA = "manuscript-variables/v1" MANUSCRIPT_CONFIG_PATH = ROOT / "docs" / "manuscript" / "config.yaml" @@ -49,26 +51,18 @@ def _gnn_job() -> tuple[str, str]: raise ValueError("no GNN conformance job in .github/workflows/ci.yml") -def _gnn_interpreter() -> str: - """Return the interpreter that has the pinned GNN distribution installed.""" - - runtime = os.environ.get("GNN_RUNTIME_PYTHON") - if runtime and Path(runtime).is_file(): - return runtime - return sys.executable -def _gnn_variables(job_key: str, job_name: str) -> dict[str, str]: +def _gnn_variables( + job_key: str, job_name: str, *, gnn_runtime: str | None = None, +) -> dict[str, str]: """Return the ``gnn_*`` keys from ``gnn.importers.importer_variables``.""" completed = subprocess.run( - [ - _gnn_interpreter(), - str(REPORT), - "--repo", str(ROOT), - "--job", job_key, - "--job-name", job_name, - ], + worker_command( + resolve_gnn_runtime(gnn_runtime), "inspect", + "--repo", str(ROOT), "--job", job_key, "--job-name", job_name, + ), cwd=ROOT, stdin=subprocess.DEVNULL, capture_output=True, @@ -78,34 +72,34 @@ def _gnn_variables(job_key: str, job_name: str) -> dict[str, str]: if completed.returncode != 0: detail = (completed.stderr or completed.stdout).strip().splitlines() raise ValueError( - "the shared gnn.importers reader could not produce the gnn_* variables: " + "the checked producer reader could not produce the gnn_* metadata variables: " + (" | ".join(detail[-3:]) if detail else "no output") - + "; set GNN_RUNTIME_PYTHON to the pinned GNN runtime" + + "; select the external GNN runtime and reviewed GNN_BOOTSTRAP" ) variables = dict(json.loads(completed.stdout)["variables"]) variables.pop("schema", None) # gnn-importer-variables/v1 names the map, not this file return variables -def build() -> dict[str, object]: +def build(*, gnn_runtime: str | None = None) -> dict[str, object]: """Return the declared manuscript variables and their sources.""" project = _project() job_key, job_name = _gnn_job() - gnn = _gnn_variables(job_key, job_name) metadata = yaml.safe_load(MANUSCRIPT_CONFIG_PATH.read_text(encoding="utf-8")) - config_path = metadata["experiment"]["config_path"] - config = yaml.safe_load((ROOT / config_path).read_text(encoding="utf-8")) + selected, config = load_manuscript_experiment(ROOT, metadata) + config_path = selected.relative_to(ROOT.resolve()).as_posix() + gnn = _gnn_variables(job_key, job_name, gnn_runtime=gnn_runtime) experiment_values = { "experiment_config_path": config_path, - "experiment_engine": config["engine"], - "experiment_dimension": config["grid"]["dimension"], - "experiment_agents": config["simulation"]["n_agents"], - "experiment_planning_length": config["grid"]["planning_length"], - "experiment_timesteps": config["simulation"]["timesteps"], - "experiment_seed": config["seed"], - "experiment_affordance_count": len(config["grid"]["affordances"]), - "experiment_affordances": ", ".join(f"`{value}`" for value in config["grid"]["affordances"]), + "experiment_engine": config.engine, + "experiment_dimension": config.grid.dimension, + "experiment_agents": config.simulation.n_agents, + "experiment_planning_length": config.grid.planning_length, + "experiment_timesteps": config.simulation.timesteps, + "experiment_seed": config.seed, + "experiment_affordance_count": len(config.grid.affordances), + "experiment_affordances": ", ".join(f"`{value}`" for value in config.grid.affordances), } experiment_sources = { "experiment_config_path": "docs/manuscript/config.yaml experiment.config_path", @@ -162,10 +156,11 @@ def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--check", action="store_true", help="fail when the file is stale") + parser.add_argument("--gnn-runtime", help="external GNN interpreter; otherwise shared selection") args = parser.parse_args(argv) try: - content = render(build()) - except (OSError, ValueError, KeyError, yaml.YAMLError) as exc: + content = render(build(gnn_runtime=args.gnn_runtime)) + except (OSError, ValueError, TypeError, KeyError, yaml.YAMLError) as exc: print(f"manuscript variables failed: {exc}", file=sys.stderr) return 1 if args.check: diff --git a/scripts/release_check.py b/scripts/release_check.py index 01e454d..edb3bc0 100644 --- a/scripts/release_check.py +++ b/scripts/release_check.py @@ -40,6 +40,8 @@ import time from pathlib import Path +from blockference.gnn_runtime import resolve_gnn_runtime + if __package__: from scripts.build_manuscript import RENDER_TARGETS else: @@ -122,22 +124,6 @@ def _changed_paths() -> set[str]: } -def _checkout_runtime() -> str | None: - """Return the interpreter of the GNN checkout named by ``GNN_ROOT``, if any. - - A source checkout is an alternative to an installed pinned runtime. The - reader has to run in the same environment as the pinned parser, so the - checkout's own virtual environment supplies it. - """ - - root = os.environ.get("GNN_ROOT") - if not root: - return None - relative = Path("Scripts" if os.name == "nt" else "bin") / ( - "python.exe" if os.name == "nt" else "python" - ) - candidate = Path(root) / ".venv" / relative - return str(candidate) if candidate.is_file() else None def _assert_json(command: list[str]) -> None: @@ -185,33 +171,25 @@ def _plan( ] if arm == "manuscript": return [ - ["uv", "run", "python", "scripts/manuscript_variables.py", "--check"], + [ + "uv", "run", "python", "scripts/manuscript_variables.py", "--check", + *(["--gnn-runtime", gnn_runtime] if gnn_runtime else []), + ], ["uv", "run", "python", "scripts/validate_manuscript.py"], ["uv", "run", "python", "scripts/build_manuscript.py"], ["uv", "run", "python", "scripts/build_manuscript.py", "--check"], ] if arm == "gnn": commands = [["uv", "run", "python", "scripts/export_gnn_spec.py", "--check"]] - # The validator verifies the pinned parser file digests before it parses - # anything, so it runs before the shared reader's specification check: - # ``gnn.importers check`` parses the document with the installed parser - # and must not reach it before the digests are verified. It also resolves - # the pin's tag upstream, so a tag moved off the pinned commit fails. + # The validator owns both the deep parser verdict and the producer's + # syntax/pointer check. Each runs in its own fully qualified external + # lifetime; no direct ``-m gnn.importers`` path bypasses admission. validator = [ "uv", "run", "python", "scripts/validate_gnn_spec.py", "--verify-tag-remote", "--json", ] if gnn_runtime: validator[-2:-2] = ["--gnn-runtime", gnn_runtime] commands.append(validator) - if gnn_runtime: - commands.append( - [ - gnn_runtime, "-m", "gnn.importers", "check", "--repo", ".", - "--require-pointer", - "--workflow", ".github/workflows/ci.yml", - "--job", "gnn-conformance", - ] - ) return commands if arm == "smoke": output_root = workdir / "output" @@ -250,12 +228,16 @@ def _plan( def _package_smoke() -> list[list[str]]: """Build a wheel and import it from a clean temporary virtualenv.""" - commands: list[list[str]] = [["uv", "build"]] - _run(commands[-1]) - wheels = sorted((ROOT / "dist").glob("*.whl")) - if not wheels: - raise FileNotFoundError("uv build produced no wheel") + commands: list[list[str]] = [] with tempfile.TemporaryDirectory(prefix="activeblockference-package-") as directory: + wheel_dir = Path(directory) / "dist" + commands.append(["uv", "build", "--wheel", "--out-dir", str(wheel_dir)]) + _run(commands[-1]) + wheels = [ + path for path in wheel_dir.glob("*.whl") if path.is_file() and not path.is_symlink() + ] + if len(wheels) != 1: + raise ValueError(f"uv build must produce exactly one fresh wheel; found {len(wheels)}") constraints = Path(directory) / "constraints.txt" commands.append( [ @@ -271,7 +253,7 @@ def _package_smoke() -> list[list[str]]: commands.append( [ "uv", "pip", "install", "--python", str(python), - "--constraint", str(constraints), str(wheels[-1]), + "--constraint", str(constraints), str(wheels[0]), ] ) _run(commands[-1]) @@ -364,9 +346,11 @@ def main(argv: list[str] | None = None) -> int: args = parser.parse_args(argv) selected = _selected(args.arm or []) - gnn_runtime = ( - args.gnn_runtime or os.environ.get("GNN_RUNTIME_PYTHON") or _checkout_runtime() - ) + runtime_error = None + try: + gnn_runtime = resolve_gnn_runtime(args.gnn_runtime, required=False) + except (OSError, ValueError) as exc: + gnn_runtime, runtime_error = None, str(exc) if args.list: for arm in (*ALIASES, *ARM_ORDER): print(f"{arm:10s} {ARM_HELP[arm]}") @@ -397,6 +381,12 @@ def main(argv: list[str] | None = None) -> int: started = time.perf_counter() commands: list[list[str]] = [] try: + if arm in {"gnn", "manuscript"} and (runtime_error or gnn_runtime is None): + raise ValueError( + "gnn validation not run: " + ( + runtime_error or "select --gnn-runtime/GNN_RUNTIME_PYTHON or GNN_ROOT" + ) + ) if arm == "package": commands = _package_smoke() else: diff --git a/scripts/validate_gnn_spec.py b/scripts/validate_gnn_spec.py index 4afb61e..1088ecc 100644 --- a/scripts/validate_gnn_spec.py +++ b/scripts/validate_gnn_spec.py @@ -1,21 +1,17 @@ """Validate the committed GNN specification with the pinned upstream parser. -The canonical GNN pin is recorded in ``specs/gnn-pin.json`` (repository, tag, -commit, and SHA-256 digests of the parser files). The pin is read by the -upstream ``gnn.importers`` reader through ``scripts/gnn_importer_report.py``, so -this repository carries no copy of the pin shape. This script supports two -verified sources for that pin: - -* a GNN git checkout (``--gnn-root`` or ``GNN_ROOT``): the pinned commit is - materialized with ``git archive`` and every recorded digest is verified, so - the live working tree is never imported; -* an installed pinned runtime (``--gnn-runtime`` or ``GNN_RUNTIME_PYTHON``): - an interpreter whose ``gnn`` package is installed at the pinned revision; the - installed parser file digests are verified *before* the document is parsed - (the package is located with the interpreter's import machinery, never - imported to parse), the VCS commit the installer recorded - (``direct_url.json``) is compared with the pin, and the parser must be imported - from the verified package. +The canonical pin is read by the independently hash-checked producer bootstrap +in the selected external interpreter. No target ``gnn`` code runs to discover +its expected identity. ``GNN_BOOTSTRAP`` and ``GNN_SOURCE_MANIFEST`` select the +reviewed bootstrap and independently frozen complete v5.1.0 package manifest. + +A selected checkout is materialized with ``git archive`` at the exact pin, or +explicitly admitted as a source artifact when no Git metadata exists. Installed +mode requires the producer's actual matching distribution/PEP610 Git origin and +complete package content; an unavailable origin never falls back to source. +``blockference/gnn_source.py`` runs parser, semantic, orientation, consistency +and shared importer checks in fresh isolated external processes. Every GNN +import and verdict stays inside producer qualification through exit revalidation. The pin's ``tag`` and ``commit`` name one revision. A GNN checkout resolves ``refs/tags/^{commit}`` locally; ``--verify-tag-remote`` resolves it upstream @@ -27,8 +23,8 @@ as a pass, and no network is used. With the flag, a tag that cannot be resolved ends the run as *not run* (exit ``2``). -Either way the document is parsed by ``scripts/gnn_parser_probe.py`` in a -subprocess and checked for conformance: the declared fixture parameters, the +The qualified ``blockference/gnn_source.py`` worker parses the document in a +separate interpreter and checks conformance: the declared fixture parameters, the declared ``A``/``B``/``C``/``D``/``E`` matrices against the runtime model built by ``blockference.gnn``, the pinned semantic validator, the B-tensor orientation diagnostic, and the consistency checker. @@ -52,7 +48,6 @@ from __future__ import annotations import argparse -import hashlib import json import os import subprocess @@ -72,115 +67,40 @@ spec_arrays, spec_parameters, ) +from blockference.gnn_runtime import resolve_gnn_runtime +from blockference.gnn_source import worker_command ROOT = Path(__file__).resolve().parents[1] -PROBE = ROOT / "scripts" / "gnn_parser_probe.py" -REPORT = ROOT / "scripts" / "gnn_importer_report.py" DEFAULT_RECEIPT = ROOT / "docs" / "_build" / "gnn" / "validation-receipt.json" -PACKAGE_PREFIX = "src/gnn/" #: Named failure: the pin's tag and commit are two spellings of one revision. TAG_COMMIT_MISMATCH = "tag-commit-mismatch" -# Locating the installed package and reading its installer metadata never parses -# a document, so the digest and revision checks run before the probe. -LOCATE_EXPRESSION = ( - "import importlib.util, json; " - "spec = importlib.util.find_spec('gnn'); " - "print(json.dumps({'module': spec.origin if spec else None, " - "'locations': [str(path) for path in (spec.submodule_search_locations or [])] " - "if spec else []}))" -) -REVISION_PROGRAM = """ -import importlib.metadata as md -import json - -records = [] -for name in md.packages_distributions().get("gnn", []): - try: - distribution = md.distribution(name) - except md.PackageNotFoundError: - continue - record = {"name": name, "version": distribution.version, "commit": None} - raw = distribution.read_text("direct_url.json") - if raw: - try: - direct = json.loads(raw) - except ValueError: - direct = {} - record["commit"] = (direct.get("vcs_info") or {}).get("commit_id") - records.append(record) -print(json.dumps(records)) -""" - class Unavailable(RuntimeError): """Raised when the pinned parser runtime or checkout is not available.""" -def _sha256(path: Path) -> str: - digest = hashlib.sha256() - with path.open("rb") as handle: - for block in iter(lambda: handle.read(1 << 20), b""): - digest.update(block) - return digest.hexdigest() - - -def read_importer_report(python: str, *, source: Path | None = None) -> dict[str, Any]: - """Return the shared ``gnn.importers`` reading of this repository's pin. - - ``source`` puts a GNN source tree first on ``PYTHONPATH``, which is how a - checkout supplies the reader when no installed distribution is present. - """ - - environment = dict(os.environ) - if source is not None: - existing = environment.get("PYTHONPATH", "") - environment["PYTHONPATH"] = str(source) + ( - os.pathsep + existing if existing else "" - ) - completed = subprocess.run( - [python, str(REPORT), "--repo", str(ROOT)], - capture_output=True, - text=True, - check=False, - env=environment, +def read_pin_report(python: str) -> dict[str, Any]: + """Read metadata with checked producer bytes, without importing target GNN.""" + output = _run_text( + worker_command(python, "inspect", "--repo", str(ROOT)), + what=f"cannot run the reviewed GNN pin reader in {python}", ) - if completed.returncode != 0: - detail = (completed.stderr or completed.stdout).strip().splitlines() - tail = " | ".join(detail[-3:]) if detail else "no output" - raise Unavailable( - f"the shared gnn.importers reader could not be run with {python}: {tail}. " - "Supply --gnn-runtime/GNN_RUNTIME_PYTHON, or --python naming an interpreter " - "with the pinned GNN distribution, or a GNN checkout via GNN_ROOT." - ) - payload = json.loads(completed.stdout) + try: + payload = json.loads(output) + except ValueError as exc: + raise Unavailable(f"the reviewed GNN pin reader returned invalid JSON: {exc}") from exc if not isinstance(payload, dict) or not isinstance(payload.get("pin"), dict): - raise Unavailable(f"the shared gnn.importers reader returned no pin: {payload!r}") + raise Unavailable("the reviewed GNN pin reader returned no pin") return payload -def _verify_digests(package_dir: Path, digests: dict[str, str], *, origin: str) -> dict[str, str]: - """Verify every recorded parser digest under an installed ``gnn`` package.""" - - observed: dict[str, str] = {} - for relative, expected in sorted(digests.items()): - suffix = relative[len(PACKAGE_PREFIX) :] if relative.startswith(PACKAGE_PREFIX) else relative - path = package_dir / suffix - if not path.is_file(): - raise Unavailable(f"pinned parser file is missing from {origin}: {suffix}") - observed[relative] = _sha256(path) - if observed[relative] != expected: - raise Unavailable( - f"pinned parser file digest mismatch for {suffix} in {origin}: " - f"expected {expected}, observed {observed[relative]}" - ) - return observed - - def _run_text(command: list[str], *, what: str) -> str: try: - completed = subprocess.run(command, capture_output=True, text=True, check=False) + completed = subprocess.run( + command, capture_output=True, text=True, check=False, stdin=subprocess.DEVNULL, + ) except OSError as exc: raise Unavailable(f"{what}: {exc}") from exc if completed.returncode != 0: @@ -190,74 +110,6 @@ def _run_text(command: list[str], *, what: str) -> str: return completed.stdout -def locate_package(python: str) -> Path: - """Return the ``gnn`` package directory ``python`` would import, without importing it.""" - - output = _run_text( - [python, "-c", LOCATE_EXPRESSION], what=f"cannot locate the gnn package in {python}" - ) - try: - located = json.loads(output) - except json.JSONDecodeError as exc: - raise Unavailable(f"cannot locate the gnn package in {python}: {exc}") from exc - if not located.get("module"): - raise Unavailable( - f"the gnn package is not installed in {python}; provision the pinned revision " - "or pass --gnn-root" - ) - locations = located.get("locations") or [] - return ( - Path(locations[0]).resolve() if locations else Path(located["module"]).resolve().parent - ) - - -def installed_revision(python: str) -> dict[str, Any]: - """Return the VCS commit the installer recorded for the ``gnn`` distribution. - - ``direct_url.json`` carries ``vcs_info.commit_id`` only for an install from a - git URL; an editable or index install has no commit to compare and is - reported as ``unresolvable-offline`` rather than assumed to match. - """ - - output = _run_text( - [python, "-c", REVISION_PROGRAM], what=f"cannot read the installed gnn metadata in {python}" - ) - try: - records = json.loads(output) - except json.JSONDecodeError as exc: - raise Unavailable(f"cannot read the installed gnn metadata in {python}: {exc}") from exc - commits = sorted({record["commit"] for record in records if record.get("commit")}) - if not commits: - return { - "status": "unresolvable-offline", - "commit": None, - "detail": "the installer recorded no VCS commit (not installed from a git URL)", - } - if len(commits) > 1: - return { - "status": "conflicting", - "commit": None, - "detail": f"the installer recorded several commits {commits}", - } - return {"status": "verified", "commit": commits[0], "detail": "direct_url.json vcs_info.commit_id"} - - -def revision_failures(revision: dict[str, Any], pin: dict[str, Any]) -> list[str]: - """Return failures when the installed runtime's recorded commit is not the pin.""" - - if revision.get("status") == "verified" and revision.get("commit") != pin["commit"]: - return [ - f"{TAG_COMMIT_MISMATCH}: the installed runtime records commit " - f"{revision.get('commit')} but the pin records {pin['commit']}" - ] - if revision.get("status") == "conflicting": - return [ - f"{TAG_COMMIT_MISMATCH}: the installed runtime metadata is ambiguous: " - f"{revision.get('detail')}" - ] - return [] - - def remote_url(repository: str) -> str: """Return a git URL for the pin's repository. @@ -302,6 +154,7 @@ def tag_binding( capture_output=True, text=True, check=False, + stdin=subprocess.DEVNULL, ) except OSError as exc: record["detail"] = f"git could not run: {exc}" @@ -323,6 +176,7 @@ def tag_binding( capture_output=True, text=True, check=False, + stdin=subprocess.DEVNULL, ) except OSError as exc: record["detail"] = f"git ls-remote could not run: {exc}" @@ -362,8 +216,7 @@ def materialize_pin(gnn_root: Path, pin: dict[str, Any], target: Path) -> tuple[ if not gnn_root.is_dir(): raise Unavailable(f"GNN checkout is not a directory: {gnn_root}") if not (gnn_root / ".git").exists(): - _verify_digests(gnn_root / "src" / "gnn", pin["parser_files"], origin=str(gnn_root)) - return gnn_root, f"digest-verified source tree {gnn_root} (no git metadata)" + return gnn_root, f"explicit source tree {gnn_root} (no Git metadata)" commit = pin["commit"] resolved = subprocess.run( @@ -371,6 +224,7 @@ def materialize_pin(gnn_root: Path, pin: dict[str, Any], target: Path) -> tuple[ capture_output=True, text=True, check=False, + stdin=subprocess.DEVNULL, ) if resolved.returncode != 0: raise Unavailable(f"pinned commit {commit} is not present in {gnn_root}") @@ -386,6 +240,7 @@ def materialize_pin(gnn_root: Path, pin: dict[str, Any], target: Path) -> tuple[ capture_output=True, text=True, check=False, + stdin=subprocess.DEVNULL, ) if completed.returncode != 0: raise Unavailable(f"git archive failed for {commit}: {completed.stderr.strip()}") @@ -395,37 +250,50 @@ def materialize_pin(gnn_root: Path, pin: dict[str, Any], target: Path) -> tuple[ except TypeError: # pragma: no cover - Python < 3.12 fallback handle.extractall(target) archive.unlink() - _verify_digests(target / "src" / "gnn", pin["parser_files"], origin=f"archive of {commit}") return target, f"git archive of {commit}" -def run_probe( - python: str, spec: Path, output: Path, *, source: Path | None +def _run_worker( + python: str, action: str, output: Path, *, source: Path | None, spec: Path | None = None, ) -> dict[str, Any]: - """Run the pinned parser probe in a subprocess and return its payload.""" - - environment = dict(os.environ) + arguments = ["--repo", str(ROOT), "--output", str(output)] + if spec is not None: + arguments += ["--spec", str(spec)] if source is not None: - existing = environment.get("PYTHONPATH", "") - environment["PYTHONPATH"] = str(source / "src") + ( - os.pathsep + existing if existing else "" + arguments += ["--source-root", str(source)] + command = worker_command(python, action, *arguments) + try: + completed = subprocess.run( + command, capture_output=True, text=True, check=False, stdin=subprocess.DEVNULL, ) - completed = subprocess.run( - [python, str(PROBE), "--spec", str(spec), "--output", str(output)], - capture_output=True, - text=True, - check=False, - env=environment, - ) - if completed.returncode != 0: + except OSError as exc: + raise Unavailable(f"cannot run the qualified GNN {action} worker in {python}: {exc}") from exc + if completed.returncode not in ({0, 1} if action == "check" else {0}): detail = (completed.stderr or completed.stdout).strip().splitlines() tail = " | ".join(detail[-3:]) if detail else "no output" - raise Unavailable( - f"pinned parser probe failed with {python}: {tail}. Provide an interpreter that " - "has the GNN parser dependencies (the GNN checkout's own .venv, or a runtime " - "installed from the pinned revision) via --python/--gnn-runtime." - ) - return json.loads(output.read_text(encoding="utf-8")) + raise Unavailable(f"qualified GNN {action} worker failed in {python}: {tail}") + try: + payload = json.loads(output.read_text(encoding="utf-8")) + except (OSError, ValueError) as exc: + raise Unavailable(f"qualified GNN {action} worker returned no readable JSON: {exc}") from exc + qualification = payload.get("source_qualification", {}) + if not qualification.get("ok") or not qualification.get("imports_verified"): + raise Unavailable(f"GNN {action} worker did not complete source/origin revalidation") + return payload + + +def run_probe( + python: str, spec: Path, output: Path, *, source: Path | None, +) -> dict[str, Any]: + """Run the fully qualified parser/verdict worker and return only JSON data.""" + return _run_worker(python, "probe", output, source=source, spec=spec) + + +def run_importer_check( + python: str, output: Path, *, source: Path | None, +) -> dict[str, Any]: + """Run the producer's qualified syntax/pointer check in a separate lifetime.""" + return _run_worker(python, "check", output, source=source) def _variable_dimensions(parser: dict[str, Any]) -> dict[str, list[int]]: @@ -491,13 +359,25 @@ def conformance_failures( if spec_text != render_spec(parameters): failures.append("committed document differs from blockference.gnn.render_spec output") + dimensions = _variable_dimensions(parser) + for name in ("π", "G"): + if dimensions.get(name) != [parameters.n_policies]: + failures.append( + f"StateSpaceBlock {name} must have {parameters.n_policies} policy entries" + ) + declared_parameters = parser.get("parameters", {}) + for name, value in ( + ("n_actions", parameters.n_actions), ("n_policies", parameters.n_policies), + ): + observed = declared_parameters.get(name) if isinstance(declared_parameters, dict) else None + if isinstance(observed, bool) or not isinstance(observed, (int, float)) or observed != value: + failures.append(f"declared {name} {observed!r} differs from {value}") expected = spec_arrays(parameters) try: declared = declared_arrays(parser) except (KeyError, TypeError, ValueError) as exc: failures.append(f"cannot read declared matrices from the document: {exc}") else: - dimensions = _variable_dimensions(parser) for key, array in expected.items(): observed = declared[key] if observed.shape != array.shape: @@ -550,13 +430,11 @@ def main(argv: list[str] | None = None) -> int: ) parser.add_argument( "--gnn-runtime", - default=os.environ.get("GNN_RUNTIME_PYTHON"), help="interpreter with the pinned GNN distribution installed", ) parser.add_argument( "--python", - default=os.environ.get("GNN_PYTHON"), - help="parser interpreter used with --gnn-root (default: $GNN_PYTHON or this interpreter)", + help="legacy external interpreter selector after --gnn-runtime/$GNN_RUNTIME_PYTHON", ) parser.add_argument( "--verify-tag-remote", @@ -568,20 +446,15 @@ def main(argv: list[str] | None = None) -> int: parser.add_argument("--json", action="store_true", help="print the receipt to stdout") args = parser.parse_args(argv) - if args.gnn_root is None and not args.gnn_runtime: - print( - "gnn validation not run: supply --gnn-root/GNN_ROOT or --gnn-runtime/" - "GNN_RUNTIME_PYTHON", - file=sys.stderr, + try: + interpreter = resolve_gnn_runtime( + args.gnn_runtime, checkout=args.gnn_root, python=args.python, ) + except (OSError, ValueError) as exc: + print(f"gnn validation not run: {exc}", file=sys.stderr) return 2 - - reader_python = args.gnn_runtime or args.python or sys.executable try: - pin = read_importer_report( - reader_python, - source=args.gnn_root / "src" if args.gnn_root is not None else None, - )["pin"] + pin = read_pin_report(interpreter)["pin"] except Unavailable as exc: print(f"gnn validation not run: {exc}", file=sys.stderr) return 2 @@ -598,10 +471,12 @@ def main(argv: list[str] | None = None) -> int: try: if args.gnn_root is not None: source, origin = materialize_pin( + # Materialization selects bytes; only the external producer + # guard below can admit them for execution. args.gnn_root, pin, Path(directory) / "gnn-pin" ) - package_dir = None - if (args.gnn_root / ".git").exists(): + archived = (args.gnn_root / ".git").exists() + if archived: revision = { "status": "verified", "commit": pin["commit"], @@ -611,20 +486,24 @@ def main(argv: list[str] | None = None) -> int: revision = { "status": "unresolvable-offline", "commit": None, - "detail": "digest-verified source tree without git metadata", + "detail": "explicit complete-manifest source without Git metadata", } - payload = run_probe( - args.python or sys.executable, args.spec, output, source=source - ) + package_dir = None + payload = run_probe(interpreter, args.spec, output, source=source) else: source = None - # The digest and revision checks come before the parser runs, so a - # tampered parser is never reached by parsing first. - package_dir = locate_package(args.gnn_runtime) - _verify_digests(package_dir, pin["parser_files"], origin=args.gnn_runtime) - revision = installed_revision(args.gnn_runtime) - payload = run_probe(args.gnn_runtime, args.spec, output, source=None) - origin = f"installed runtime {args.gnn_runtime} ({package_dir})" + payload = run_probe(interpreter, args.spec, output, source=None) + package = payload["source_qualification"] + package_dir = Path(package["package_root"]) + revision = { + "status": "verified", + "commit": package["origin"]["commit"], + "detail": "producer-qualified installed distribution/PEP610 Git origin", + } + origin = f"installed runtime {interpreter} ({package_dir})" + importer = run_importer_check( + interpreter, Path(directory) / "importer.json", source=source, + ) except Unavailable as exc: print(f"gnn validation not run: {exc}", file=sys.stderr) return 2 @@ -637,10 +516,15 @@ def main(argv: list[str] | None = None) -> int: package_dir=package_dir, tag=tag, ) - failures.extend(revision_failures(revision, pin)) + if not importer["ok"]: + failures.extend( + f"shared importer {item['code']}: {item['message']}" + for item in importer["findings"] if item["level"] == "error" + ) receipt = { "ok": not failures, + "runtime_python": interpreter, "spec": str(args.spec), "pin": pin, "pin_source": origin, @@ -648,6 +532,8 @@ def main(argv: list[str] | None = None) -> int: "gnn_module": payload["gnn_module"], "tag_binding": tag, "revision": revision, + "source_qualification": payload["source_qualification"], + "importer_check": importer, "parser_success": payload["parser"]["success"], "semantic_valid": payload["semantic"].get("is_valid"), "orientation": [ diff --git a/scripts/validate_manuscript.py b/scripts/validate_manuscript.py index b4396b5..ae98808 100644 --- a/scripts/validate_manuscript.py +++ b/scripts/validate_manuscript.py @@ -10,7 +10,7 @@ import yaml -from blockference.config import load_experiment_config +from blockference.config import load_manuscript_experiment ROOT = Path(__file__).resolve().parents[1] MANUSCRIPT = ROOT / "docs" / "manuscript" @@ -140,37 +140,33 @@ def validate() -> list[str]: metadata_path = MANUSCRIPT / "config.yaml" try: metadata = yaml.safe_load(metadata_path.read_text(encoding="utf-8")) - experiment = metadata.get("experiment", {}) if isinstance(metadata, dict) else {} - relative_config = experiment.get("config_path") - if not isinstance(relative_config, str): - errors.append("manuscript metadata must name experiment.config_path") - else: - config = load_experiment_config(ROOT / relative_config) - expected = { - "engine": config.engine, - "dimension": config.grid.dimension, - "planning_length": config.grid.planning_length, - "max_policies": config.grid.max_policies, - "timesteps": config.simulation.timesteps, - "runs": config.simulation.runs, - "agents": config.simulation.n_agents, - "seed": config.seed, - "target": list(config.simulation.target) - if config.simulation.target != "random" - else "random", - "initial_states": [list(value) for value in config.simulation.resolved_initial_states], - "affordances": list(config.grid.affordances), - } - mismatches = [ - f"{key} metadata={experiment.get(key)!r} config={value!r}" - for key, value in expected.items() - if experiment.get(key) != value - ] - if mismatches: - errors.append( - "manuscript metadata disagrees with executable config: " - + "; ".join(mismatches) - ) + _selected, config = load_manuscript_experiment(ROOT, metadata) + experiment = metadata["experiment"] + expected = { + "engine": config.engine, + "dimension": config.grid.dimension, + "planning_length": config.grid.planning_length, + "max_policies": config.grid.max_policies, + "timesteps": config.simulation.timesteps, + "runs": config.simulation.runs, + "agents": config.simulation.n_agents, + "seed": config.seed, + "target": list(config.simulation.target) + if config.simulation.target != "random" + else "random", + "initial_states": [list(value) for value in config.simulation.resolved_initial_states], + "affordances": list(config.grid.affordances), + } + mismatches = [ + f"{key} metadata={experiment.get(key)!r} config={value!r}" + for key, value in expected.items() + if experiment.get(key) != value + ] + if mismatches: + errors.append( + "manuscript metadata disagrees with executable config: " + + "; ".join(mismatches) + ) except (OSError, TypeError, ValueError, yaml.YAMLError) as exc: errors.append(f"manuscript executable config invalid: {exc}") return errors diff --git a/scripts/validate_notebooks.py b/scripts/validate_notebooks.py index 263fb0f..c6678dd 100644 --- a/scripts/validate_notebooks.py +++ b/scripts/validate_notebooks.py @@ -2,62 +2,22 @@ from __future__ import annotations -import re from pathlib import Path -import nbformat - -ABSOLUTE_PATH_RE = re.compile(r"(?:/Users/|/home/|[A-Za-z]:[\\/])") - - -def validate_notebook(path: str | Path) -> list[str]: - """Return contract violations found in one notebook.""" - - notebook_path = Path(path) - errors: list[str] = [] - notebook = nbformat.read(notebook_path, as_version=4) - cells = notebook.cells - if not cells or cells[0].cell_type != "markdown": - errors.append("first cell must be a teaching-summary markdown cell") - elif len(cells[0].source.split()) < 12: - errors.append("teaching-summary markdown cell is too short") - for index, cell in enumerate(cells): - source = cell.source if isinstance(cell.source, str) else "".join(cell.source) - if ABSOLUTE_PATH_RE.search(source): - errors.append(f"cell {index} contains an absolute filesystem path") - if cell.cell_type == "code": - if "GRTs" not in notebook_path.parts and "blockference" not in source: - errors.append(f"code cell {index} does not import the current package API") - if cell.outputs or cell.execution_count is not None: - errors.append(f"code cell {index} contains committed execution output") - return errors - - -def validate_all(root: str | Path) -> dict[Path, list[str]]: - """Validate all tracked notebooks below ``root``.""" - - root_path = Path(root) - failures: dict[Path, list[str]] = {} - for path in sorted(root_path.rglob("*.ipynb")): - if ".ipynb_checkpoints" in path.parts or ".venv" in path.parts: - continue - errors = validate_notebook(path) - if errors: - failures[path.relative_to(root_path)] = errors - return failures +from blockference.notebook_inventory import validate_all def main() -> int: """Validate repository notebooks and print a concise report.""" root = Path(__file__).resolve().parents[1] - failures = validate_all(root) + notebooks, failures = validate_all(root) if failures: for path, errors in failures.items(): for error in errors: print(f"ERROR: {path}: {error}") return 1 - print("notebook hygiene validation passed") + print(f"notebook hygiene validation passed: {len(notebooks)} tracked notebooks") return 0 diff --git a/specs/README.md b/specs/README.md index d2fc8a0..027ba78 100644 --- a/specs/README.md +++ b/specs/README.md @@ -7,7 +7,10 @@ file, under schema `gnn-importer-pin/v1`. The pin is read by the upstream `gnn.importers` reader, not by a local copy. -Verify: `uv run python scripts/export_gnn_spec.py --check`, then -`python -m gnn.importers check --repo .` and -`uv run python scripts/validate_gnn_spec.py` in the pinned runtime. The spec -renderer is [`../blockference/gnn.py`](../blockference/gnn.py). +Verify exporter drift with `uv run python scripts/export_gnn_spec.py --check`, +then run `uv run python scripts/validate_gnn_spec.py` from the project runtime +with the separate GNN interpreter and independently reviewed bootstrap/full +manifest selected per [`../docs/gnn.md`](../docs/gnn.md). The validator owns +both admitted parser and shared importer verdicts; direct unchecked imports +are not an alternative. The renderer is +[`../blockference/gnn.py`](../blockference/gnn.py). diff --git a/specs/gridworld_3x3.gnn.md b/specs/gridworld_3x3.gnn.md index 6090799..0c7b84e 100644 --- a/specs/gridworld_3x3.gnn.md +++ b/specs/gridworld_3x3.gnn.md @@ -26,7 +26,7 @@ Discrete, deterministic, fully observed grid-world POMDP implemented by deterministic and column-stochastic: every column selects exactly one next cell, and moves outside the grid clamp to the border. - `C` is a one-hot preference over the preferred cell 2, 2; `D` is a one-hot prior over - the initial cell 0, 0; `E` is the uniform policy prior over the 5 affordances. + the initial cell 0, 0; `E` is the uniform prior over the 25 length-2 policies. - `G` is the expected free energy per policy and `pi` the policy posterior; the pipeline persists both components (`update_efe_epistemic`, `update_efe_pragmatic`) for every step. @@ -37,14 +37,14 @@ A[9,9,type=float] # Likelihood: identity, fully observed B[9,9,5,type=float] # Transition: B[next_state,previous_state,action] C[9,type=float] # Preference over observations D[9,type=float] # Prior over hidden states -E[5,type=float] # Policy prior over affordances +E[25,type=float] # Uniform prior over complete policies s[9,1,type=float] # Current hidden state distribution s_prime[9,1,type=float] # Next hidden state distribution o[9,1,type=int] # Current observation -pi[5,type=float] # Policy posterior over affordances +pi[25,type=float] # Posterior over complete policies u[1,type=int] # Sampled affordance index -G[5,type=float] # Expected free energy per affordance +G[25,type=float] # Expected free energy per policy t[1,type=int] # Discrete time step ## Connections @@ -182,7 +182,7 @@ C=(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0) D=(1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0) -E=(0.2, 0.2, 0.2, 0.2, 0.2) +E=(0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04) ## Equations diff --git a/tests/test_configuration_files.py b/tests/test_configuration_files.py new file mode 100644 index 0000000..c0778bf --- /dev/null +++ b/tests/test_configuration_files.py @@ -0,0 +1,88 @@ +"""Mapping-only file admission and one metadata-selected typed experiment.""" + +from __future__ import annotations + +import pytest +import yaml + +from blockference.config import ( + ExperimentConfig, + load_experiment_config, + load_manuscript_experiment, +) +from blockference.pipeline import run_pipeline + + +@pytest.mark.parametrize("extension", ["yml", "yaml"]) +@pytest.mark.parametrize("content", ["[]", "false", "0", "0.0", "''", "[1]", "plain text"]) +def test_nonmapping_yaml_roots_fail_before_any_output_tree(tmp_path, extension, content): + path = tmp_path / f"invalid.{extension}" + path.write_text(content, encoding="utf-8") + output = tmp_path / "uncreated-output" + with pytest.raises(TypeError, match="config root must be a mapping"): + run_pipeline(path, output_root=output) + assert not output.exists() + + +@pytest.mark.parametrize("content", ["", "# comment only\n", "null", "~", "{}"]) +def test_empty_and_null_yaml_keep_explicit_default_compatibility(tmp_path, content): + path = tmp_path / "empty.yml" + path.write_text(content, encoding="utf-8") + assert load_experiment_config(path).to_dict() == ExperimentConfig().to_dict() + + +def test_yaml_toml_and_metadata_selection_share_typed_defaults(tmp_path): + configs = tmp_path / "configs" + configs.mkdir() + toml = configs / "alternate.toml" + toml.write_text( + 'engine = "CaDcAd"\n[grid]\ndimension = 4\nplanning_length = 1\n' + 'affordances = ["RIGHT", "STAY"]\n[simulation]\ntarget = [3, 3]\n', + encoding="utf-8", + ) + selected, config = load_manuscript_experiment( + tmp_path, {"experiment": {"config_path": "configs/alternate.toml"}}, + ) + assert selected == toml + assert config.engine == "cadcad" + assert config.grid.dimension == 4 + assert config.grid.affordances == ("RIGHT", "STAY") + assert config.simulation.timesteps == ExperimentConfig().simulation.timesteps + equivalent = configs / "same.yaml" + equivalent.write_text(yaml.safe_dump(config.to_dict()), encoding="utf-8") + assert load_experiment_config(equivalent).to_dict() == config.to_dict() + + +@pytest.mark.parametrize("metadata", [ + None, [], {}, {"experiment": []}, {"experiment": {"config_path": ""}}, + {"experiment": {"config_path": "../outside.yml"}}, +]) +def test_missing_or_escaping_metadata_never_selects_a_default_config(tmp_path, metadata): + root = tmp_path / "repo" + root.mkdir() + (tmp_path / "outside.yml").write_text("{}", encoding="utf-8") + with pytest.raises((TypeError, ValueError)): + load_manuscript_experiment(root, metadata) + + +def test_absolute_missing_and_symlinked_outside_selections_refuse(tmp_path): + root = tmp_path / "repo" + root.mkdir() + outside = tmp_path / "outside.yml" + outside.write_text("{}", encoding="utf-8") + linked = root / "linked.yml" + linked.symlink_to(outside) + for selection in (str(outside), "linked.yml"): + with pytest.raises(ValueError): + load_manuscript_experiment(root, {"experiment": {"config_path": selection}}) + with pytest.raises(FileNotFoundError): + load_manuscript_experiment(root, {"experiment": {"config_path": "missing.yml"}}) + + +def test_nested_null_compatibility_does_not_weaken_unknown_key_rejection(tmp_path): + path = tmp_path / "nested.yml" + path.write_text("grid: null\nsimulation: null\noutput: null\n", encoding="utf-8") + assert load_experiment_config(path).to_dict() == ExperimentConfig().to_dict() + path.write_text("unexpected: true\n", encoding="utf-8") + with pytest.raises(ValueError, match="unknown configuration"): + load_experiment_config(path) diff --git a/tests/test_contracts_extended.py b/tests/test_contracts_extended.py index d1da0ad..2ece081 100644 --- a/tests/test_contracts_extended.py +++ b/tests/test_contracts_extended.py @@ -233,14 +233,14 @@ def test_persistence_manifest_and_summary_helpers(tmp_path): cfg = ExperimentConfig.from_dict({"output": {"path": None}}) frame = _frame() persist_config(cfg, paths) - persist_dataframe(frame, paths) + persist_dataframe(frame, paths, models={(1, "0"): frame.iloc[0]["agents"][0]}) persist_summary(summarise_trajectory(frame), paths) agent = ActiveGridference(make_grid(2), planning_length=1) agent.get_C((1, 1)) agent.get_D((0, 0)) - persist_generative_model({0: agent}, paths) - persist_generative_model_npz({0: agent}, paths) - persist_policies([np.array([[0]])], paths) + persist_generative_model({(1, "0"): agent}, paths) + persist_generative_model_npz({(1, "0"): agent}, paths) + persist_policies({(1, "0"): [np.array([[0]])]}, paths) persist_per_step_records(build_per_step_records(frame), paths) assert persist_manifest(paths).is_file() assert paths.manifest_json.read_text(encoding="utf-8").find("sha256") >= 0 @@ -297,10 +297,10 @@ def test_validation_rejects_bad_vectors_bounds_and_manifest_entries(tmp_path): def test_viz_common_and_renderers_reject_bad_inputs_and_write_outputs(tmp_path): frame = _frame() assert coerce_cell("[1, 2]") == [1, 2] - assert extract_agent_positions(frame)[0] == [(0, 0)] - assert extract_action_history(frame)[0] == [3] - assert extract_belief_history(frame)[0][0].shape == (4,) - assert extract_efe_history(frame)[0][0].shape == (2,) + assert extract_agent_positions(frame)[(1, 0)] == [(0, 0)] + assert extract_action_history(frame)[(1, 0)] == [3] + assert extract_belief_history(frame)[(1, 0)][0].shape == (4,) + assert extract_efe_history(frame)[(1, 0)][0].shape == (2,) assert infer_grid_dimension(frame) == 2 for renderer, name in ( (plot_trajectory, "trajectory.png"), @@ -363,10 +363,12 @@ def test_atomic_npz_round_trip_is_loadable(tmp_path): agent = ActiveGridference(make_grid(2), planning_length=1) agent.get_C((1, 1)) agent.get_D((0, 0)) - persist_generative_model_npz({0: agent}, paths) + persist_generative_model_npz({(1, "0"): agent}, paths) with np.load(paths.matrices_npz, allow_pickle=False) as archive: - assert set(archive.files) == {"agent_0/A", "agent_0/B", "agent_0/C", "agent_0/D", "agent_0/E"} - assert archive["agent_0/A"].shape == (4, 4) + assert set(archive.files) == { + f"run_1/agent_0/{name}" for name in ("A", "B", "C", "D", "E") + } + assert archive["run_1/agent_0/A"].shape == (4, 4) def test_trajectory_schema_typed_round_trip(tmp_path): @@ -382,7 +384,7 @@ def test_trajectory_schema_typed_round_trip(tmp_path): assert rec.prior == (1.0, 0.0, 0.0, 0.0) # The CSV round-trip preserves the same typed values. paths = build_run_paths(tmp_path, "schema").ensure() - persist_dataframe(frame, paths) + persist_dataframe(frame, paths, models={(1, "0"): frame.iloc[0]["agents"][0]}) reloaded = pd.read_csv(paths.trajectory_csv) assert parse_trajectory_records(reloaded) == records diff --git a/tests/test_core_hardening.py b/tests/test_core_hardening.py index 9366579..3e08825 100644 --- a/tests/test_core_hardening.py +++ b/tests/test_core_hardening.py @@ -218,10 +218,12 @@ def test_trajectory_validation_rejects_inconsistent_agent_registries(): def test_persisted_model_validation_fails_closed_on_malformed_payload(tmp_path): paths = build_run_paths(tmp_path, "malformed").ensure() - paths.matrices_json.write_text(json.dumps({"0": []}), encoding="utf-8") + paths.matrices_json.write_text( + json.dumps({"version": 2, "runs": {"1": {"0": []}}}), encoding="utf-8" + ) report = validate_run_outputs(paths) assert not report.ok - assert any("model.0.payload" in issue for issue in report.issues) + assert any("model.run_1.agent_0.payload" in issue for issue in report.issues) def test_run_name_stays_inside_output_root(tmp_path): @@ -269,10 +271,9 @@ def test_gridworld_conforms_to_discrete_environment_protocol_and_serialises(): assert world.stochastic is False payload = world.serialize() assert payload["dimension"] == 3 - restored = GridWorld.load(payload) + restored = GridWorld.load(json.loads(json.dumps(payload))) assert isinstance(restored, DiscreteEnvironment) - # Serialization stringifies agent keys for JSON; values round-trip losslessly. - assert set(restored.current_state.values()) == {(0, 0), (2, 2)} + assert list(restored.current_state.items()) == list(world.current_state.items()) assert restored.affordances == world.affordances assert restored.stochastic == world.stochastic diff --git a/tests/test_environment_identity.py b/tests/test_environment_identity.py new file mode 100644 index 0000000..f05d8ac --- /dev/null +++ b/tests/test_environment_identity.py @@ -0,0 +1,110 @@ +"""Lossless supported identities and deliberately distinct world occupancy rules.""" + +from __future__ import annotations + +import copy +import json + +import networkx as nx +import numpy as np +import pytest + +from blockference.envs import GridWorld, resolve_moves +from blockference.gridference import ActiveGridference, actinf_graph, make_grid +from blockference.utils.policy import p_actinf_dict + + +def test_json_round_trip_preserves_mixed_identity_types_registry_and_sequence_actions(): + positions = {2: (0, 0), 10: (2, 2), 1: (0, 2), "1": (2, 0)} + world = GridWorld(3, positions, stochastic=True) + restored = GridWorld.load(json.loads(json.dumps(world.serialize()))) + assert list(restored.current_state.items()) == list(positions.items()) + assert [type(key) for key in restored.current_state] == [int, int, int, str] + assert restored.affordances == world.affordances + assert restored.stochastic is True + expected = {2: (0, 1), 10: (2, 1), 1: (1, 2), "1": (1, 0)} + assert world.step([3, 2, 1, 0]) == expected + assert restored.step([3, 2, 1, 0]) == expected + + +@pytest.mark.parametrize(("left", "right", "winner"), [(1, "1", 1), (2, 10, 10)]) +@pytest.mark.parametrize("reverse", [False, True]) +def test_json_round_trip_retains_existing_type_repr_collision_priority(left, right, winner, reverse): + entries = [(left, (1, 0)), (right, (1, 2))] + positions = dict(reversed(entries) if reverse else entries) + world = GridWorld(3, positions) + restored = GridWorld.load(json.loads(json.dumps(world.serialize()))) + actions = {left: 3, right: 2} + expected = dict(positions) + expected[winner] = (1, 1) + assert world.step(actions) == expected + assert restored.step(actions) == expected + assert list(restored.current_state) == list(positions) + + +@pytest.mark.parametrize("identity", [True, 1.0, np.int64(1), b"1", (1,), frozenset({1}), object()]) +def test_unsupported_hashables_cannot_enter_construction_direct_moves_or_serialization(identity): + with pytest.raises(TypeError): + GridWorld(3, {identity: (0, 0)}) + with pytest.raises(TypeError): + resolve_moves({identity: (0, 0)}, {identity: 4}, 3) + with pytest.raises(TypeError): + resolve_moves({1: (0, 0)}, {identity: 4}, 3) + world = GridWorld(3) + world.positions[identity] = (0, 0) + with pytest.raises(TypeError): + world.serialize() + + +@pytest.mark.parametrize("identity", [ + {"type": "int", "value": True}, {"type": "int", "value": 1.0}, + {"type": "int", "value": "1"}, {"type": "str", "value": 1}, + {"type": "repr", "value": "1"}, {"value": 1}, None, +]) +def test_malformed_typed_identity_records_are_not_coerced(identity): + payload = GridWorld(3, {1: (0, 0)}).serialize() + payload["positions"][0]["agent_id"] = identity + with pytest.raises((TypeError, ValueError)): + GridWorld.load(payload) + + +def test_duplicate_records_and_lossy_legacy_payloads_are_rejected(): + payload = GridWorld(3, {1: (0, 0)}).serialize() + duplicate = copy.deepcopy(payload["positions"][0]) + duplicate["position"] = [1, 1] + payload["positions"].append(duplicate) + with pytest.raises(ValueError, match="duplicate"): + GridWorld.load(payload) + with pytest.raises(ValueError): + GridWorld.load({"dimension": 3, "positions": {"1": [0, 0]}}) + empty = GridWorld.load(json.loads(json.dumps(GridWorld(3).serialize()))) + assert empty.current_state == {} + assert empty.step([]) == {} + + +def test_graph_worlds_and_shared_occupancy_keep_distinct_realized_priors(monkeypatch): + grid = make_grid(3) + agents = {} + graph = nx.Graph() + for agent_id, position in ((0, (1, 0)), (1, (1, 2))): + agent = ActiveGridference(grid, planning_length=1) + agent.get_C((2, 2)) + agent.get_D(position) + agents[agent_id] = agent + graph.add_node( + agent_id, agent=agent, prior=agent.D, prior_A=agent.A, + prior_B=agent.B, prior_C=agent.C, env_state=position, + ) + actions = iter([3, 2, 3, 2]) + monkeypatch.setattr("blockference.gridference.bu.sample", lambda _p, rng=None: next(actions)) + independent = { + update["source"]: update for update in actinf_graph(graph)["agent_updates"] + } + shared = { + update["source"]: update + for update in p_actinf_dict({}, 0, [], {"agents": agents}, grid)["agent_updates"] + } + assert [independent[agent]["update_env"] for agent in (0, 1)] == [(1, 1), (1, 1)] + assert [shared[agent]["update_env"] for agent in (0, 1)] == [(1, 1), (1, 2)] + assert np.argmax(independent[1]["update_prior"]) == grid.index((1, 1)) + assert np.argmax(shared[1]["update_prior"]) == grid.index((1, 2)) diff --git a/tests/test_external_runtime_contracts.py b/tests/test_external_runtime_contracts.py new file mode 100644 index 0000000..98482c5 --- /dev/null +++ b/tests/test_external_runtime_contracts.py @@ -0,0 +1,204 @@ +"""Runtime-selection and invocation-output contracts, not GNN/package qualification.""" + +from __future__ import annotations + +import json +import os +import subprocess +from pathlib import Path +from types import SimpleNamespace + +import pytest +import yaml + +import scripts.manuscript_variables as variables +import scripts.release_check as gate +from blockference.gnn_runtime import resolve_gnn_runtime + + +@pytest.fixture +def runtimes(tmp_path, monkeypatch): + for name in ("GNN_ROOT", "GNN_RUNTIME_PYTHON", "GNN_PYTHON"): + monkeypatch.delenv(name, raising=False) + paths = {} + for name in ("cli", "environment", "legacy"): + path = tmp_path / f"{name}-python" + path.write_text("selection fixture, not an executable runtime\n", encoding="utf-8") + paths[name] = path + checkout = tmp_path / "checkout" + python = checkout / ".venv" / ("Scripts/python.exe" if os.name == "nt" else "bin/python") + python.parent.mkdir(parents=True) + python.write_text("checkout interpreter selection fixture\n", encoding="utf-8") + paths.update(checkout=checkout, checkout_python=python) + return paths + + +def test_shared_selector_has_one_precedence_without_project_python_fallback(runtimes, monkeypatch): + monkeypatch.setenv("GNN_ROOT", str(runtimes["checkout"])) + monkeypatch.setenv("GNN_PYTHON", str(runtimes["legacy"])) + monkeypatch.setenv("GNN_RUNTIME_PYTHON", str(runtimes["environment"])) + assert resolve_gnn_runtime(runtimes["cli"], python=runtimes["legacy"]) == str(runtimes["cli"]) + assert resolve_gnn_runtime(python=runtimes["legacy"]) == str(runtimes["environment"]) + monkeypatch.delenv("GNN_RUNTIME_PYTHON") + assert resolve_gnn_runtime(python=runtimes["cli"]) == str(runtimes["cli"]) + assert resolve_gnn_runtime() == str(runtimes["legacy"]) + monkeypatch.delenv("GNN_PYTHON") + assert resolve_gnn_runtime() == str(runtimes["checkout_python"]) + monkeypatch.delenv("GNN_ROOT") + assert resolve_gnn_runtime(required=False) is None + with pytest.raises(FileNotFoundError): + resolve_gnn_runtime() + + +@pytest.mark.parametrize("explicit", ["missing", "empty"]) +def test_invalid_explicit_runtime_never_falls_back_to_an_available_environment(runtimes, monkeypatch, explicit): + monkeypatch.setenv("GNN_RUNTIME_PYTHON", str(runtimes["environment"])) + selection = str(runtimes["cli"].parent / "missing") if explicit == "missing" else "" + with pytest.raises(FileNotFoundError): + resolve_gnn_runtime(selection) + + +def test_venv_launcher_symlink_is_not_replaced_by_its_base_interpreter(runtimes): + launcher = runtimes["cli"].parent / "venv-python" + launcher.symlink_to(runtimes["cli"]) + assert resolve_gnn_runtime(launcher) == str(launcher) + assert resolve_gnn_runtime(launcher) != str(launcher.resolve()) + + +def test_gate_records_missing_external_runtime_before_executing_any_arm(tmp_path, monkeypatch, capsys): + for name in ("GNN_ROOT", "GNN_RUNTIME_PYTHON", "GNN_PYTHON"): + monkeypatch.delenv(name, raising=False) + + def forbidden(*_args, **_kwargs): + raise AssertionError("a gate command executed before required runtime admission") + + monkeypatch.setattr(gate, "_run", forbidden) + monkeypatch.setattr(gate, "_changed_paths", forbidden) + receipt = tmp_path / "receipt.json" + assert gate.main(["--arm", "manuscript", "--timings", str(receipt), "--json"]) == 1 + payload = json.loads(receipt.read_text(encoding="utf-8")) + assert payload["arms"]["manuscript"]["status"] == "failed" + summary = next(line for line in capsys.readouterr().out.splitlines() if line.startswith('{"arms":')) + assert json.loads(summary)["ok"] is False + + +def _manuscript_sources(root): + (root / "pyproject.toml").write_text('[project]\nversion="1.0.0"\nrequires-python=">=3.11"\n', encoding="utf-8") + workflow = root / ".github" / "workflows" / "ci.yml" + workflow.parent.mkdir(parents=True) + workflow.write_text("jobs:\n gnn-conformance:\n name: GNN conformance\n", encoding="utf-8") + selected = root / "configs" / "alternate.toml" + selected.parent.mkdir() + selected.write_text('engine="CaDcAd"\n[grid]\ndimension=4\nplanning_length=1\n', encoding="utf-8") + metadata = root / "docs" / "manuscript" / "config.yaml" + metadata.parent.mkdir(parents=True) + metadata.write_text(yaml.safe_dump({"experiment": {"config_path": "configs/alternate.toml"}}), encoding="utf-8") + return metadata, workflow + + +@pytest.mark.parametrize("selection", ["cli", "checkout"]) +def test_manuscript_variables_consume_the_selected_runtime_and_typed_config( + tmp_path, runtimes, monkeypatch, selection, +): + root = tmp_path / "publication" + root.mkdir() + metadata, workflow = _manuscript_sources(root) + monkeypatch.setattr(variables, "ROOT", root) + monkeypatch.setattr(variables, "MANUSCRIPT_CONFIG_PATH", metadata) + monkeypatch.setattr(variables, "WORKFLOW_PATH", workflow) + if selection == "cli": + monkeypatch.setenv("GNN_RUNTIME_PYTHON", str(runtimes["environment"])) + expected = str(runtimes["cli"]) + argument = expected + else: + monkeypatch.setenv("GNN_ROOT", str(runtimes["checkout"])) + expected = str(runtimes["checkout_python"]) + argument = None + + def report(command, **_kwargs): + # Only the bridge protocol is simulated. No GNN origin/content is qualified. + payload = {"variables": {"schema": "fixture", "gnn_commit": f"report-from:{command[0]}"}} + return subprocess.CompletedProcess(command, 0, stdout=json.dumps(payload), stderr="") + + monkeypatch.setattr(variables, "subprocess", SimpleNamespace(run=report, DEVNULL=subprocess.DEVNULL)) + payload = variables.build(gnn_runtime=argument) + assert payload["gnn_commit"] == f"report-from:{expected}" + assert payload["experiment_engine"] == "cadcad" + assert payload["experiment_dimension"] == 4 + assert payload["experiment_config_path"] == "configs/alternate.toml" + + +@pytest.mark.parametrize("outputs", [[], ["one.whl", "two.whl"]]) +def test_package_smoke_refuses_missing_or_ambiguous_fresh_output(tmp_path, monkeypatch, outputs): + stale = tmp_path / "dist" / "zzzz-9999.whl" + stale.parent.mkdir() + stale.write_bytes(b"historical stale wheel") + monkeypatch.setattr(gate, "ROOT", tmp_path) + installed = [] + + def run(command, **_kwargs): + if command[:2] == ["uv", "build"]: + output = Path(command[command.index("--out-dir") + 1]) + output.mkdir() + for name in outputs: + (output / name).write_bytes(b"fresh") + elif command[:3] == ["uv", "pip", "install"]: + installed.append(Path(command[-1]).read_bytes()) + return subprocess.CompletedProcess(command, 0, stdout="", stderr="") + + monkeypatch.setattr(gate, "_run", run) + with pytest.raises(ValueError, match="exactly one fresh wheel"): + gate._package_smoke() + assert installed == [] + assert stale.read_bytes() == b"historical stale wheel" + assert list(stale.parent.iterdir()) == [stale] + + +def test_package_smoke_installs_only_its_own_fresh_bytes_across_invocations(tmp_path, monkeypatch): + stale = tmp_path / "dist" / "zzzz-9999.whl" + stale.parent.mkdir() + stale.write_bytes(b"do not install or delete") + monkeypatch.setattr(gate, "ROOT", tmp_path) + directories, installed = [], [] + + def run(command, **_kwargs): + if command[:2] == ["uv", "build"]: + output = Path(command[command.index("--out-dir") + 1]) + output.mkdir() + directories.append(output) + (output / "active_blockference-1.0.0-py3-none-any.whl").write_bytes(b"fresh wheel bytes") + (output / "unrelated.txt").write_text("not a wheel", encoding="utf-8") + elif command[:2] == ["uv", "export"]: + Path(command[-1]).write_text("locked constraints fixture\n", encoding="utf-8") + elif command[:3] == ["uv", "pip", "install"]: + wheel = Path(command[-1]) + assert wheel.parent == directories[-1] + installed.append(wheel.read_bytes()) + return subprocess.CompletedProcess(command, 0, stdout="", stderr="") + + monkeypatch.setattr(gate, "_run", run) + gate._package_smoke() + gate._package_smoke() + assert installed == [b"fresh wheel bytes", b"fresh wheel bytes"] + assert directories[0] != directories[1] + assert all(not path.exists() for path in directories) + assert stale.read_bytes() == b"do not install or delete" + assert list(stale.parent.iterdir()) == [stale] + + +def test_failed_build_never_installs_a_stale_wheel(tmp_path, monkeypatch): + stale = tmp_path / "dist" / "zzzz-9999.whl" + stale.parent.mkdir() + stale.write_bytes(b"retain") + monkeypatch.setattr(gate, "ROOT", tmp_path) + + def fail_build(command, **_kwargs): + if command[:2] != ["uv", "build"]: + raise AssertionError("package processing continued after failed build") + raise subprocess.CalledProcessError(7, command) + + monkeypatch.setattr(gate, "_run", fail_build) + with pytest.raises(subprocess.CalledProcessError) as error: + gate._package_smoke() + assert error.value.returncode == 7 + assert stale.read_bytes() == b"retain" diff --git a/tests/test_gnn_pin_binding.py b/tests/test_gnn_pin_binding.py index 3437d30..f3e1ce7 100644 --- a/tests/test_gnn_pin_binding.py +++ b/tests/test_gnn_pin_binding.py @@ -1,14 +1,12 @@ -"""Offline tests for the pin-binding checks in ``scripts/validate_gnn_spec.py``. +"""Offline tag-binding and pure document-conformance checks. -No test here uses the network or an installed GNN runtime: remote tag resolution -is exercised against a stubbed ``git ls-remote``, the checkout path uses a -throwaway local git repository, and the runtime is a stub. +Git tag resolution uses throwaway local repositories or explicit failed-reader +fixtures. Real producer/bootstrap/runtime controls live in test_gnn_source_admission. """ from __future__ import annotations import subprocess -import sys from pathlib import Path import pytest @@ -216,75 +214,6 @@ def test_failed_remote_is_unresolved_never_a_pass(monkeypatch: pytest.MonkeyPatc assert "ls-remote failed" in binding["detail"] -def test_installed_commit_must_match_the_pin() -> None: - pin = _pin() - - assert vgs.revision_failures({"status": "verified", "commit": COMMIT}, pin) == [] - assert vgs.revision_failures({"status": "unresolvable-offline", "commit": None}, pin) == [] - assert vgs.revision_failures({"status": "verified", "commit": OTHER}, pin)[0].startswith( - vgs.TAG_COMMIT_MISMATCH - ) - assert vgs.revision_failures({"status": "conflicting", "detail": "two"}, pin)[0].startswith( - vgs.TAG_COMMIT_MISMATCH - ) - - -def _run_main(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, *extra: str): - probed: list[str] = [] - - def fake_probe(*_args, **_kwargs): - probed.append("probe") - raise AssertionError("the parser must not run before the digests verify") - - monkeypatch.setattr(vgs, "run_probe", fake_probe) - monkeypatch.setattr( - vgs, "read_importer_report", lambda *_a, **_k: {"pin": _pin(), "variables": {}} - ) - code = vgs.main( - ["--gnn-runtime", sys.executable, "--receipt", str(tmp_path / "r.json"), *extra] - ) - return code, probed - - -def test_digests_are_verified_before_the_document_is_parsed( - monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str] -) -> None: - package = tmp_path / "gnn" - package.mkdir() - (package / "__init__.py").write_text("tampered", encoding="utf-8") - monkeypatch.setattr(vgs, "locate_package", lambda *_a, **_k: package) - - code, probed = _run_main(monkeypatch, tmp_path) - - assert code == 2 - assert probed == [] - assert "digest mismatch" in capsys.readouterr().err - - -def test_a_missing_pinned_package_is_not_run_before_parsing( - monkeypatch: pytest.MonkeyPatch, tmp_path: Path -) -> None: - def absent(*_args, **_kwargs): - raise vgs.Unavailable("the gnn package is not installed") - - monkeypatch.setattr(vgs, "locate_package", absent) - code, probed = _run_main(monkeypatch, tmp_path) - - assert code == 2 - assert probed == [] - - -def test_verify_tag_remote_that_cannot_answer_is_not_run_not_a_pass( - monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str] -) -> None: - _stub_ls_remote(monkeypatch, "", returncode=128) - code, probed = _run_main(monkeypatch, tmp_path, "--verify-tag-remote") - - assert code == 2 - assert probed == [] - assert "--verify-tag-remote" in capsys.readouterr().err - - def test_a_remote_tag_moved_off_the_pinned_commit_reaches_the_conformance_failures() -> None: binding = {"status": "verified", "tag": "v9.9.9", "commit": COMMIT, "resolved": OTHER} payload = { diff --git a/tests/test_gnn_source_admission.py b/tests/test_gnn_source_admission.py new file mode 100644 index 0000000..836c18c --- /dev/null +++ b/tests/test_gnn_source_admission.py @@ -0,0 +1,564 @@ +"""Real-file/process controls for exact-pin GNN source admission. + +The source cohort requires an explicitly supplied reviewed artifact in +GNN_TEST_SOURCE_ROOT, the reviewed GNN_BOOTSTRAP/GNN_SOURCE_MANIFEST resources, +and the existing selected external interpreter. It never installs a parser or +invents a source manifest/distribution. Installed success is a separate opt-in +cohort with GNN_TEST_INSTALLED_PYTHON and actual PEP610 Git provenance. +""" + +from __future__ import annotations + +import hashlib +import json +import os +import shutil +import subprocess +import sys +import venv +from pathlib import Path +from types import SimpleNamespace + +import pytest + +import scripts.manuscript_variables as variables +import scripts.validate_gnn_spec as validator +from blockference.gnn import render_spec +from blockference.gnn_runtime import resolve_gnn_runtime +from blockference.gnn_source import ( + BOOTSTRAP_SHA256, + PINNED_COMMIT, + SOURCE_MANIFEST_SHA256, + worker_command, +) + +ROOT = Path(__file__).resolve().parents[1] +WORKER = ROOT / "blockference" / "gnn_source.py" + + +def _process(command, *, cwd, environment=None): + return subprocess.run( + command, cwd=cwd, env=environment, stdin=subprocess.DEVNULL, + capture_output=True, text=True, check=False, timeout=120, + ) + + +def _worker(runtime, action, repo, *, cwd, source=None, spec=None, output=None): + arguments = ["--repo", str(repo)] + if source is not None: + arguments += ["--source-root", str(source)] + if spec is not None: + arguments += ["--spec", str(spec)] + if output is not None: + arguments += ["--output", str(output)] + return _process(worker_command(runtime, action, *arguments), cwd=cwd) + + +@pytest.mark.parametrize("selection", ["missing", "corrupt"]) +@pytest.mark.parametrize("action", ["inspect", "probe", "check"]) +def test_unchecked_bootstrap_cannot_execute_or_publish(tmp_path, monkeypatch, selection, action): + marker = tmp_path / "unchecked-bootstrap-executed" + if selection == "missing": + monkeypatch.delenv("GNN_BOOTSTRAP", raising=False) + else: + bootstrap = tmp_path / "unchecked.py" + bootstrap.write_text( + f"from pathlib import Path\nPath({str(marker)!r}).write_text('executed')\n", + encoding="utf-8", + ) + monkeypatch.setenv("GNN_BOOTSTRAP", str(bootstrap)) + output = tmp_path / "previous-output.json" + output.write_bytes(b"retain previous output") + result = _worker( + sys.executable, action, ROOT, cwd=tmp_path, + spec=tmp_path / "unread-spec.gnn.md", output=output, + ) + assert result.returncode == 2, result.stdout + result.stderr + assert "GNN_BOOTSTRAP" in result.stderr + assert not marker.exists() + assert output.read_bytes() == b"retain previous output" + + +def _consumer(root): + specs = root / "specs" + specs.mkdir(parents=True) + (specs / "gnn-pin.json").write_bytes((ROOT / "specs" / "gnn-pin.json").read_bytes()) + spec = specs / "gridworld_3x3.gnn.md" + spec.write_text(render_spec(), encoding="utf-8") + pointer = root / ".github" / "GNN.md" + pointer.parent.mkdir() + pointer.write_text( + f"specs/gnn-pin.json v5.1.0 {PINNED_COMMIT} ci.yml gnn-conformance\n", + encoding="utf-8", + ) + return spec + + +@pytest.fixture +def reviewed_resources(tmp_path, monkeypatch): + names = ("GNN_BOOTSTRAP", "GNN_SOURCE_MANIFEST") + if not all(os.environ.get(name) for name in names): + if os.environ.get("GNN_TEST_SOURCE_ROOT") or os.environ.get("GNN_TEST_INSTALLED_PYTHON"): + pytest.fail("the explicitly selected external cohort needs both reviewed resources") + pytest.skip("reviewed producer resources were not selected; no admission proof") + bootstrap_bytes = Path(os.environ["GNN_BOOTSTRAP"]).read_bytes() + manifest_bytes = Path(os.environ["GNN_SOURCE_MANIFEST"]).read_bytes() + assert hashlib.sha256(bootstrap_bytes).hexdigest() == BOOTSTRAP_SHA256 + assert hashlib.sha256(manifest_bytes).hexdigest() == SOURCE_MANIFEST_SHA256 + bootstrap = tmp_path / "reviewed-bootstrap.py" + manifest = tmp_path / "reviewed-manifest.json" + bootstrap.write_bytes(bootstrap_bytes) + manifest.write_bytes(manifest_bytes) + monkeypatch.setenv("GNN_BOOTSTRAP", str(bootstrap)) + monkeypatch.setenv("GNN_SOURCE_MANIFEST", str(manifest)) + repo = tmp_path / "consumer" + spec = _consumer(repo) + return SimpleNamespace(bootstrap=bootstrap, manifest=manifest, repo=repo, spec=spec) + + +@pytest.fixture +def source_inputs(reviewed_resources, tmp_path): + selected = os.environ.get("GNN_TEST_SOURCE_ROOT") + if not selected: + pytest.skip("explicit reviewed source artifact not selected; corruption cohort not qualified") + runtime = resolve_gnn_runtime() + package = Path(selected) / "src" / "gnn" + assert package.is_dir(), f"GNN_TEST_SOURCE_ROOT has no src/gnn: {selected}" + source = tmp_path / "artifact" + shutil.copytree( + package, source / "src" / "gnn", + ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"), + ) + return SimpleNamespace(**vars(reviewed_resources), source=source, runtime=runtime) + + +@pytest.mark.gnn +@pytest.mark.parametrize("action", ["probe", "check"]) +def test_real_source_verdict_finishes_guarded_imports_and_revalidation(source_inputs, tmp_path, action): + inputs = source_inputs + output = tmp_path / "verdict.json" + result = _worker( + inputs.runtime, action, inputs.repo, cwd=tmp_path, + source=inputs.source, spec=inputs.spec, output=output, + ) + assert result.returncode == 0, result.stdout + result.stderr + payload = json.loads(output.read_text(encoding="utf-8")) + qualification = payload["source_qualification"] + assert qualification["ok"] and qualification["imports_verified"] + assert qualification["commit"] == PINNED_COMMIT + assert qualification["manifest_sha256"] == SOURCE_MANIFEST_SHA256 + assert qualification["package_root"] == str((inputs.source / "src" / "gnn").resolve()) + assert qualification["origin"]["kind"] == "explicit-source" + assert qualification["origin"]["vcs_verified"] is False + assert qualification["execution_verified"] is False + modules = qualification["loaded_modules"] + if action == "probe": + assert payload["parser"]["success"], payload["parser"] + assert { + "gnn.validation.semantic_validator", + "gnn.validation.orientation", + "gnn.validation.consistency_checker", + } <= modules.keys() + else: + assert payload["qualified"] and payload["specs"]["validated"] == 1 + assert "gnn.parsers.basic" in modules + + +@pytest.mark.gnn +@pytest.mark.parametrize("member", [ + "importers.py", "validation/semantic_validator.py", "validation/orientation.py", + "validation/consistency_checker.py", "parsers/basic.py", +]) +@pytest.mark.parametrize("action", ["probe", "check", "validator"]) +def test_changed_verdict_members_refuse_before_execution(source_inputs, tmp_path, member, action): + inputs = source_inputs + marker = tmp_path / "unauthorized-module-executed" + target = inputs.source / "src" / "gnn" / member + target.write_bytes( + target.read_bytes() + + f"\nfrom pathlib import Path as _P\n_P({str(marker)!r}).write_text('executed')\n".encode() + ) + # These verdict modules are outside the historical five-file parser pin. + pin = json.loads((inputs.repo / "specs" / "gnn-pin.json").read_text(encoding="utf-8")) + for relative, expected in pin["parser_files"].items(): + assert hashlib.sha256((inputs.source / relative).read_bytes()).hexdigest() == expected + output = tmp_path / "verdict.json" + if action == "validator": + result = _process( + [sys.executable, "-B", str(ROOT / "scripts" / "validate_gnn_spec.py"), + "--gnn-runtime", inputs.runtime, "--gnn-root", str(inputs.source), + "--spec", str(inputs.spec), "--receipt", str(output), "--json"], + cwd=ROOT, + ) + else: + result = _worker( + inputs.runtime, action, inputs.repo, cwd=tmp_path, + source=inputs.source, spec=inputs.spec, output=output, + ) + assert result.returncode == 2, result.stdout + result.stderr + assert "source-content-mismatch" in result.stdout + result.stderr + assert not marker.exists() + if output.exists(): + failed = json.loads(output.read_text(encoding="utf-8")) + assert failed["ok"] is False and failed["qualified"] is False + + +@pytest.mark.gnn +@pytest.mark.parametrize("action", ["probe", "check"]) +def test_changed_manifest_is_not_replaced_by_a_target_inventory(source_inputs, tmp_path, action): + inputs = source_inputs + inputs.manifest.write_bytes(inputs.manifest.read_bytes() + b" ") + result = _worker( + inputs.runtime, action, inputs.repo, cwd=tmp_path, + source=inputs.source, spec=inputs.spec, + ) + assert result.returncode == 2, result.stdout + result.stderr + assert "source-manifest-hash-mismatch" in result.stdout + result.stderr + + +@pytest.mark.gnn +@pytest.mark.parametrize("mutation", ["missing", "extra"]) +def test_complete_manifest_rejects_package_membership_changes(source_inputs, tmp_path, mutation): + inputs = source_inputs + package = inputs.source / "src" / "gnn" + if mutation == "missing": + (package / "validation" / "orientation.py").unlink() + else: + (package / "unreviewed-resource.txt").write_text("not reviewed\n", encoding="utf-8") + result = _worker( + inputs.runtime, "probe", inputs.repo, cwd=tmp_path, + source=inputs.source, spec=inputs.spec, + ) + assert result.returncode == 2, result.stdout + result.stderr + assert "source-content-mismatch" in result.stdout + result.stderr + + +@pytest.mark.gnn +def test_bootstrap_execution_uses_the_checked_buffer_not_a_file_reread(reviewed_resources, tmp_path): + inputs = reviewed_resources + marker = tmp_path / "unchecked-reread-executed" + program = f''' +import runpy +import sys +from pathlib import Path +bootstrap = Path({str(inputs.bootstrap)!r}) +original = Path.read_bytes +changed = False +def read_bytes(path): + global changed + data = original(path) + if path == bootstrap and not changed: + changed = True + path.write_text("from pathlib import Path\\nPath({str(marker)!r}).write_text('executed')\\n") + return data +Path.read_bytes = read_bytes +sys.argv = [{str(WORKER)!r}, "inspect", "--repo", {str(inputs.repo)!r}] +runpy.run_path({str(WORKER)!r}, run_name="__main__") +''' + result = _process([sys.executable, "-I", "-B", "-c", program], cwd=tmp_path) + assert result.returncode == 2, result.stdout + result.stderr + assert "bootstrap-changed" in result.stderr + assert not marker.exists() + + +@pytest.mark.gnn +def test_probe_revalidates_after_the_actual_parser_and_verdict_calls(source_inputs, tmp_path): + inputs = source_inputs + published = tmp_path / "incorrect-success.json" + member = inputs.source / "src" / "gnn" / "validation" / "semantic_validator.py" + program = f''' +import runpy +from pathlib import Path +worker = runpy.run_path({str(WORKER)!r}) +class ChangingSpec(type(Path())): + def read_text(self, *args, **kwargs): + text = super().read_text(*args, **kwargs) + member = Path({str(member)!r}) + member.write_bytes(member.read_bytes() + b"\\n# changed during actual verdict\\n") + return text +try: + worker["probe"]( + Path({str(inputs.repo)!r}), ChangingSpec({str(inputs.spec)!r}), + source_root=Path({str(inputs.source)!r}), + ) +except ValueError as exc: + raise RuntimeError(getattr(exc, "code", "unexpected-admission-failure")) from exc +Path({str(published)!r}).write_text("should never publish") +''' + result = _process([inputs.runtime, "-I", "-B", "-c", program], cwd=tmp_path) + assert result.returncode != 0, result.stdout + result.stderr + assert "source-content-mismatch" in result.stderr + assert not published.exists() + assert member.read_bytes().endswith(b"# changed during actual verdict\n") + + +@pytest.mark.gnn +def test_already_imported_real_gnn_cannot_start_a_new_verdict(source_inputs, tmp_path): + inputs = source_inputs + program = f''' +import runpy +import sys +sys.path.insert(0, {str(inputs.source / "src")!r}) +import gnn +sys.argv = [{str(WORKER)!r}, "probe", "--repo", {str(inputs.repo)!r}, + "--source-root", {str(inputs.source)!r}, "--spec", {str(inputs.spec)!r}] +runpy.run_path({str(WORKER)!r}, run_name="__main__") +''' + result = _process([inputs.runtime, "-I", "-B", "-c", program], cwd=tmp_path) + assert result.returncode == 2, result.stdout + result.stderr + assert "source-already-imported" in result.stderr + + +@pytest.mark.gnn +def test_parent_helpers_use_the_selected_external_runtime_for_real_verdicts( + source_inputs, tmp_path, monkeypatch, +): + inputs = source_inputs + monkeypatch.setattr(validator, "ROOT", inputs.repo) + monkeypatch.setenv("GNN_RUNTIME_PYTHON", sys.executable) + selected = resolve_gnn_runtime(inputs.runtime) + report = validator.read_pin_report(selected) + probe = validator.run_probe( + selected, inputs.spec, tmp_path / "probe.json", source=inputs.source, + ) + importer = validator.run_importer_check( + selected, tmp_path / "importer.json", source=inputs.source, + ) + assert report["mode"] == "inspection" and report["qualified"] is False + for payload in (report, probe, importer): + assert Path(payload["runtime_python"]).absolute() == Path(selected).absolute() + assert probe["parser"]["success"] + assert importer["qualified"] + + +@pytest.mark.gnn +def test_manuscript_metadata_uses_checked_reader_without_executing_target_gnn( + source_inputs, tmp_path, monkeypatch, +): + inputs = source_inputs + marker = tmp_path / "target-importer-executed" + target = inputs.source / "src" / "gnn" / "importers.py" + target.write_bytes( + target.read_bytes() + + f"\nfrom pathlib import Path as _P\n_P({str(marker)!r}).write_text('executed')\n".encode() + ) + monkeypatch.setattr(variables, "ROOT", inputs.repo) + monkeypatch.setenv("PYTHONPATH", str(inputs.source / "src")) + payload = variables._gnn_variables( + "gnn-conformance", "Pinned conformance", gnn_runtime=inputs.runtime, + ) + assert payload["gnn_commit"] == PINNED_COMMIT + assert payload["gnn_job_key"] == "gnn-conformance" + assert not marker.exists() + + +@pytest.mark.gnn +def test_installed_mode_does_not_fall_back_to_environment_source(source_inputs, tmp_path, monkeypatch): + inputs = source_inputs + empty = tmp_path / "unprovisioned-runtime" + venv.EnvBuilder(with_pip=False).create(empty) + python = empty / ("Scripts/python.exe" if os.name == "nt" else "bin/python") + monkeypatch.setenv("GNN_ROOT", str(inputs.source)) + monkeypatch.setenv("PYTHONPATH", str(inputs.source / "src")) + result = _worker(str(python), "probe", inputs.repo, cwd=tmp_path, spec=inputs.spec) + assert result.returncode == 2, result.stdout + result.stderr + assert "source-origin-unavailable" in result.stderr + + +@pytest.mark.gnn +def test_wrong_explicit_runtime_is_not_substituted_after_source_admission( + source_inputs, tmp_path, monkeypatch, +): + inputs = source_inputs + empty = tmp_path / "unprovisioned-runtime" + venv.EnvBuilder(with_pip=False).create(empty) + python = empty / ("Scripts/python.exe" if os.name == "nt" else "bin/python") + monkeypatch.setenv("GNN_RUNTIME_PYTHON", inputs.runtime) + selected = resolve_gnn_runtime(str(python)) + monkeypatch.setattr(validator, "ROOT", inputs.repo) + output = tmp_path / "never-published.json" + with pytest.raises(validator.Unavailable, match="worker failed"): + validator.run_probe(selected, inputs.spec, output, source=inputs.source) + assert not output.exists() + + +@pytest.mark.gnn +def test_prepared_installed_runtime_qualifies_actual_distribution_origin(reviewed_resources, tmp_path): + runtime = os.environ.get("GNN_TEST_INSTALLED_PYTHON") + if not runtime: + pytest.skip("actual installed-origin cohort not selected; source proof is not installed proof") + inputs = reviewed_resources + output = tmp_path / "installed.json" + result = _worker( + resolve_gnn_runtime(runtime), "probe", inputs.repo, + cwd=tmp_path, spec=inputs.spec, output=output, + ) + assert result.returncode == 0, result.stdout + result.stderr + payload = json.loads(output.read_text(encoding="utf-8")) + qualification = payload["source_qualification"] + assert qualification["ok"] and qualification["imports_verified"] + origin = qualification["origin"] + assert origin["kind"] == "installed-vcs" and origin["vcs_verified"] + assert origin["distribution"] == "generalized-notation-notation" + assert origin["commit"] == PINNED_COMMIT + assert origin["repository"] == "ActiveInferenceInstitute/Generalized_Notation_Notation" + assert payload["parser"]["success"] + + +def _installed_command(inputs, action, *, output=None): + arguments = [ + str(WORKER), action, "--repo", str(inputs.repo), "--spec", str(inputs.spec), + ] + if output is not None: + arguments += ["--output", str(output)] + program = ( + "import runpy, sys; " + f"sys.path.insert(0, {str(inputs.site)!r}); " + f"sys.argv = {arguments!r}; " + f"runpy.run_path({str(WORKER)!r}, run_name='__main__')" + ) + return [inputs.runtime, "-I", "-B", "-c", program] + + +@pytest.fixture +def installed_inputs(reviewed_resources, tmp_path): + selected = os.environ.get("GNN_TEST_INSTALLED_PYTHON") + if not selected: + pytest.skip("real installed-origin corruption cohort not selected; no installed proof") + runtime = resolve_gnn_runtime(selected) + # Read only actual distribution metadata in the prepared interpreter. Never + # create a pretend direct_url, version, RECORD or successful parser module. + locate = """ +import importlib.metadata as md +import json +from pathlib import Path +distribution = md.distribution("generalized-notation-notation") +metadata = [ + Path(distribution.locate_file(item)).parent + for item in distribution.files or () + if item.name == "METADATA" and item.parent.name.endswith(".dist-info") +] +if len(metadata) != 1: + raise ValueError("installed distribution has no unique real metadata directory") +print(json.dumps({ + "package": str(Path(distribution.locate_file("gnn/__init__.py")).parent), + "metadata": str(metadata[0]), +})) +""" + located = _process([runtime, "-I", "-B", "-c", locate], cwd=tmp_path) + assert located.returncode == 0, located.stdout + located.stderr + paths = json.loads(located.stdout) + site = tmp_path / "private-installed-copy" + shutil.copytree( + paths["package"], site / "gnn", + ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"), + ) + metadata = Path(paths["metadata"]) + shutil.copytree(metadata, site / metadata.name) + inputs = SimpleNamespace( + **vars(reviewed_resources), runtime=runtime, site=site, + metadata=site / metadata.name, + ) + # The unchanged genuine distribution copy must run a real admitted verdict + # before its negative control can claim an origin/content refusal. + baseline = tmp_path / "installed-baseline.json" + result = _process(_installed_command(inputs, "probe", output=baseline), cwd=tmp_path) + assert result.returncode == 0, result.stdout + result.stderr + payload = json.loads(baseline.read_text(encoding="utf-8")) + proof = payload["source_qualification"] + assert proof["ok"] and proof["imports_verified"] + assert proof["origin"]["kind"] == "installed-vcs" + assert proof["origin"]["commit"] == PINNED_COMMIT + assert payload["parser"]["success"] + return inputs + + +@pytest.mark.gnn +@pytest.mark.parametrize("member", [ + "importers.py", "validation/semantic_validator.py", "validation/orientation.py", + "validation/consistency_checker.py", +]) +@pytest.mark.parametrize("action", ["probe", "check"]) +def test_installed_verdict_member_corruption_refuses_before_execution( + installed_inputs, tmp_path, member, action, +): + inputs = installed_inputs + marker = tmp_path / "unreviewed-installed-code-executed" + target = inputs.site / "gnn" / member + target.write_bytes( + target.read_bytes() + + f"\nfrom pathlib import Path as _P\n_P({str(marker)!r}).write_text('executed')\n".encode() + ) + result = _process(_installed_command(inputs, action), cwd=tmp_path) + assert result.returncode == 2, result.stdout + result.stderr + assert "source-content-mismatch" in result.stdout + result.stderr + assert not marker.exists() + + +@pytest.mark.gnn +@pytest.mark.parametrize("change", ["missing", "wrong-revision", "wrong-repository", "unowned"]) +@pytest.mark.parametrize("action", ["probe", "check"]) +def test_actual_installed_origin_and_module_ownership_are_required( + installed_inputs, tmp_path, monkeypatch, change, action, +): + inputs = installed_inputs + direct_url = inputs.metadata / "direct_url.json" + if change == "missing": + direct_url.unlink() + elif change == "unowned": + # Keep genuine metadata, but relocate only the package away from its + # owner's locate_file root. A shadow package is never distribution-owned. + shadow = tmp_path / "shadow" + shutil.copytree(inputs.site / "gnn", shadow / "gnn") + inputs.site = shadow + else: + origin = json.loads(direct_url.read_text(encoding="utf-8")) + if change == "wrong-revision": + origin["vcs_info"]["commit_id"] = "0" * 40 + else: + origin["url"] = "https://github.com/not-the-producer/Generalized_Notation_Notation" + direct_url.write_text(json.dumps(origin), encoding="utf-8") + # Environment source inputs cannot rescue an installed-origin failure. + monkeypatch.setenv("GNN_ROOT", str(tmp_path / "unselected-source")) + result = _process(_installed_command(inputs, action), cwd=tmp_path) + assert result.returncode == 2, result.stdout + result.stderr + expected = "source-origin-unavailable" if change == "missing" else "source-origin-mismatch" + assert expected in result.stdout + result.stderr + + +@pytest.mark.gnn +def test_source_changed_after_admission_is_checked_again_before_import(source_inputs, tmp_path): + inputs = source_inputs + target = inputs.source / "src" / "gnn" / "__init__.py" + marker = tmp_path / "late-unchecked-import-executed" + replacement = ( + target.read_bytes() + + f"\nfrom pathlib import Path as _P\n_P({str(marker)!r}).write_text('executed')\n".encode() + ) + program = f''' +import builtins +import runpy +from pathlib import Path +worker = runpy.run_path({str(WORKER)!r}) +original_import = builtins.__import__ +changed = False +def importing(name, *args, **kwargs): + global changed + if name == "gnn" and not changed: + changed = True + Path({str(target)!r}).write_bytes({replacement!r}) + return original_import(name, *args, **kwargs) +builtins.__import__ = importing +try: + worker["probe"]( + Path({str(inputs.repo)!r}), Path({str(inputs.spec)!r}), + source_root=Path({str(inputs.source)!r}), + ) +except ValueError as exc: + raise RuntimeError(getattr(exc, "code", "unexpected-admission-failure")) from exc +''' + result = _process([inputs.runtime, "-I", "-B", "-c", program], cwd=tmp_path) + assert result.returncode != 0, result.stdout + result.stderr + assert "source-content-mismatch" in result.stderr + assert target.read_bytes() == replacement + assert not marker.exists() diff --git a/tests/test_gnn_spec.py b/tests/test_gnn_spec.py index 89cf4cc..8a6a8a7 100644 --- a/tests/test_gnn_spec.py +++ b/tests/test_gnn_spec.py @@ -21,6 +21,7 @@ spec_arrays, spec_parameters, ) +from blockference.gnn_runtime import resolve_gnn_runtime from blockference.gridference import _move ROOT = Path(__file__).resolve().parents[1] @@ -43,7 +44,7 @@ def _parsed_payload() -> dict: - """Return a payload shaped like ``scripts/gnn_parser_probe.py`` output.""" + """Return the JSON data contract emitted by ``blockference/gnn_source.py``.""" parameters = spec_parameters() arrays = spec_arrays(parameters) @@ -101,7 +102,7 @@ def test_declared_arrays_match_the_runtime_model(): assert arrays["B"].shape == (9, 9, 5) assert arrays["C"].shape == (9,) assert arrays["D"].shape == (9,) - assert arrays["E"].shape == (5,) + assert arrays["E"].shape == (25,) assert np.array_equal(arrays["A"], model.A) assert np.array_equal(arrays["B"], model.B) assert np.array_equal(arrays["C"], model.C) @@ -119,7 +120,7 @@ def test_declared_matrices_are_valid_probability_arrays(): for name in ("C", "D", "E"): assert np.isclose(arrays[name].sum(), 1.0) assert (arrays[name] >= 0).all() - assert np.array_equal(arrays["E"], np.full(5, 0.2)) + assert np.array_equal(arrays["E"], np.full(25, 0.04)) def test_transition_tensor_matches_the_declared_movement_rules(): @@ -160,15 +161,7 @@ def test_parameter_reconstruction_rejects_malformed_documents(): def _pinned_runtime_python() -> str | None: - runtime = os.environ.get("GNN_RUNTIME_PYTHON") - if runtime and Path(runtime).is_file(): - return runtime - root = os.environ.get("GNN_ROOT") - if root: - candidate = Path(root) / ".venv" / "bin" / "python" - if candidate.is_file(): - return str(candidate) - return None + return resolve_gnn_runtime(required=False) @pytest.mark.gnn @@ -186,15 +179,139 @@ def test_pinned_parser_validates_the_committed_spec(tmp_path): "--receipt", str(receipt), ] + command += ["--gnn-runtime", runtime] if os.environ.get("GNN_ROOT"): - command += ["--gnn-root", os.environ["GNN_ROOT"], "--python", runtime] - else: - command += ["--gnn-runtime", runtime] + command += ["--gnn-root", os.environ["GNN_ROOT"]] completed = subprocess.run(command, cwd=ROOT, capture_output=True, text=True, check=False) assert completed.returncode == 0, completed.stdout + completed.stderr payload = json.loads(receipt.read_text(encoding="utf-8")) assert payload["ok"] is True + assert payload["source_qualification"]["ok"] is True + assert payload["source_qualification"]["imports_verified"] is True + assert payload["importer_check"]["qualified"] is True + assert payload["importer_check"]["source_qualification"]["imports_verified"] is True assert payload["failures"] == [] assert payload["gnn_version"] == "5.1.0" assert payload["orientation"] == ["canonical"] assert payload["consistency_score"] == 1.0 + + +@pytest.mark.parametrize(("affordances", "horizon", "count"), [ + (("UP", "DOWN", "LEFT", "RIGHT", "STAY"), 2, 25), + (("RIGHT", "DOWN", "STAY"), 2, 9), + (("STAY",), 3, 1), +]) +def test_exported_policy_prior_round_trips_without_changing_action_vocabulary(affordances, horizon, count): + import ast + import re + + from blockference.gnn import GridWorldSpecParameters + + parameters = GridWorldSpecParameters(affordances=affordances, planning_length=horizon) + model = build_spec_model(parameters) + rendered = render_spec(parameters) + declared = ast.literal_eval(re.search(r"^E=(\([^\n]+\))$", rendered, re.MULTILINE).group(1)) + assert np.array_equal(np.asarray(declared), np.full(count, 1.0 / count)) + for name in ("E", "pi", "G"): + shape = re.search(rf"^{name}\[(\d+),type=float\]", rendered, re.MULTILINE) + assert int(shape.group(1)) == count + assert spec_arrays(parameters)["B"].shape == (9, 9, len(affordances)) + assert model.E == list(affordances) + + +@pytest.mark.parametrize("value", [1 / 3, 1 / 25, np.nextafter(0.0, 1.0), 1 - np.finfo(float).eps]) +def test_probability_text_is_float_round_trip_exact(value): + from blockference.gnn import _format_value + + assert float(_format_value(value)) == value + + +def _conformance_fixture(): + parameters = spec_parameters() + arrays = spec_arrays() + parser = _parsed_payload()["parser"] + parser.update( + success=True, errors=[], warnings=[], model_name=parameters.model_name, + variables=[ + {"name": name, "dimensions": list(array.shape)} for name, array in arrays.items() + ] + [ + {"name": "π", "dimensions": [parameters.n_policies]}, + {"name": "G", "dimensions": [parameters.n_policies]}, + ], + ) + return { + "gnn_version": "5.1.0", "gnn_module": "/fixture/gnn/__init__.py", "parser": parser, + "semantic": {"is_valid": True, "warnings": []}, + "orientation": {"warnings": [], "tensors": []}, + "consistency": {"consistent": True}, + } + + +@pytest.mark.parametrize("name", ["π", "G"]) +@pytest.mark.parametrize("dimensions", [[5], [25, 1], []]) +def test_conformance_rejects_action_sized_or_missing_policy_vector_dimensions(name, dimensions): + from scripts.validate_gnn_spec import conformance_failures + + pin = {"tag": "v5.1.0", "commit": "a" * 40} + payload = _conformance_fixture() + assert conformance_failures(payload, pin=pin, source=None, spec_text=render_spec()) == [] + variable = next(value for value in payload["parser"]["variables"] if value["name"] == name) + variable["dimensions"] = dimensions + assert conformance_failures(payload, pin=pin, source=None, spec_text=render_spec()) + + +@pytest.mark.parametrize(("name", "value"), [("n_actions", 25), ("n_policies", 5), ("n_policies", None)]) +def test_conformance_rejects_inconsistent_redundant_control_policy_counts(name, value): + from scripts.validate_gnn_spec import conformance_failures + + pin = {"tag": "v5.1.0", "commit": "a" * 40} + payload = _conformance_fixture() + assert conformance_failures(payload, pin=pin, source=None, spec_text=render_spec()) == [] + payload["parser"]["parameters"][name] = value + assert conformance_failures(payload, pin=pin, source=None, spec_text=render_spec()) + + +@pytest.mark.gnn +@pytest.mark.parametrize(("affordances", "policy_count"), [ + (("RIGHT", "DOWN", "STAY"), 9), + (("STAY",), 1), +]) +def test_pinned_parser_round_trips_policy_cardinality_and_precision(tmp_path, affordances, policy_count): + # Real parsing stays inside producer admission; only primitive data returns + # to the project interpreter. + from blockference.gnn import GridWorldSpecParameters + from scripts.validate_gnn_spec import ( + materialize_pin, + read_pin_report, + run_probe, + ) + + runtime = _pinned_runtime_python() + if runtime is None: + pytest.skip("pinned GNN runtime unavailable; external parsing is not qualified") + checkout = Path(os.environ["GNN_ROOT"]) if os.environ.get("GNN_ROOT") else None + pin = read_pin_report(runtime)["pin"] + if checkout is not None: + source, _origin = materialize_pin(checkout, pin, tmp_path / "pinned-source") + else: + source = None + parameters = GridWorldSpecParameters(affordances=affordances, planning_length=2) + spec = tmp_path / "policy-case.gnn.md" + spec.write_text(render_spec(parameters), encoding="utf-8") + payload = run_probe(runtime, spec, tmp_path / "policy-case-probe.json", source=source) + qualification = payload["source_qualification"] + assert qualification["ok"] and qualification["imports_verified"] + assert qualification["commit"] == pin["commit"] + package = Path(qualification["package_root"]) + assert payload["gnn_version"] == pin["tag"].lstrip("v") + assert Path(payload["gnn_module"]).resolve().is_relative_to(package.resolve()) + parser = payload["parser"] + assert parser["success"] and parser["errors"] == [] + assert parameters_from_parsed(parser) == parameters + arrays = declared_arrays(parser) + assert arrays["B"].shape == (9, 9, len(affordances)) + assert np.array_equal(arrays["E"], np.full(policy_count, 1 / policy_count)) + dimensions = {variable["name"]: variable["dimensions"] for variable in parser["variables"]} + assert {name: dimensions[name] for name in ("E", "π", "G")} == { + "E": [policy_count], "π": [policy_count], "G": [policy_count], + } diff --git a/tests/test_grts.py b/tests/test_grts.py index 150696b..3983b04 100644 --- a/tests/test_grts.py +++ b/tests/test_grts.py @@ -1,6 +1,7 @@ """Credential-free tests for the optional research workflow.""" import json +from pathlib import Path import pytest @@ -11,6 +12,7 @@ build_provider, process_csv, ) +from GRTs.cli import main def test_offline_orchestrator_writes_report(tmp_path): @@ -35,3 +37,88 @@ def test_openai_provider_fails_clearly_without_key(monkeypatch): monkeypatch.delenv("OPENAI_API_KEY", raising=False) with pytest.raises(RuntimeError, match="OPENAI_API_KEY"): build_provider("openai") + + +@pytest.mark.parametrize("fault", ["missing", "directory", "broken-link", "unreadable", "utf8"]) +@pytest.mark.parametrize("existing_workspace", [False, True]) +def test_explicit_corpus_path_failure_precedes_all_workspace_mutation( + tmp_path, monkeypatch, fault, existing_workspace, +): + corpus = tmp_path / "corpus.txt" + if fault == "directory": + corpus.mkdir() + elif fault == "broken-link": + corpus.symlink_to(tmp_path / "absent.txt") + elif fault == "utf8": + corpus.write_bytes(b"\xff") + elif fault == "unreadable": + corpus.write_text("private corpus", encoding="utf-8") + read_text = Path.read_text + + def denied(path, *args, **kwargs): + if path == corpus: + raise PermissionError("controlled corpus admission failure") + return read_text(path, *args, **kwargs) + + monkeypatch.setattr(Path, "read_text", denied) + workspace = tmp_path / "workspace" + sentinels = {} + if existing_workspace: + workspace.mkdir() + for name in ("requests.txt", "research_data.txt", "report.txt"): + path = workspace / name + sentinels[path] = f"preserve {name}\n".encode() + path.write_bytes(sentinels[path]) + with pytest.raises((OSError, UnicodeError)): + provider = OfflineCorpusProvider(corpus) + ResearchOrchestrator(provider, ResearchWorkspace(workspace)).run() + with pytest.raises((OSError, UnicodeError)): + main(["run", "--workspace", str(workspace), "--corpus", str(corpus)]) + if existing_workspace: + assert {path: path.read_bytes() for path in sentinels} == sentinels + assert {path.name for path in workspace.iterdir()} == {path.name for path in sentinels} + else: + assert not workspace.exists() + + +def test_missing_corpus_refuses_before_optional_provider_construction(tmp_path, monkeypatch): + def forbidden(*_args, **_kwargs): + raise AssertionError("optional provider constructed before explicit Path admission") + + monkeypatch.setattr("GRTs.agents.OpenAIProvider", forbidden) + with pytest.raises(FileNotFoundError): + main([ + "run", "--workspace", str(tmp_path / "workspace"), + "--provider", "openai", "--corpus", str(tmp_path / "missing.txt"), + ]) + assert not (tmp_path / "workspace").exists() + + +def test_readable_corpus_is_admitted_before_workspace_and_keeps_its_snapshot(tmp_path): + corpus = tmp_path / "corpus.txt" + corpus.write_text("Beliefs guide actions.", encoding="utf-8") + provider = OfflineCorpusProvider(corpus) + corpus.write_text("Unrelated later replacement.", encoding="utf-8") + workspace = ResearchWorkspace(tmp_path / "new-workspace") + assert not workspace.root.exists() + report = ResearchOrchestrator(provider, workspace).run() + text = report.read_text(encoding="utf-8") + assert "Beliefs guide actions." in text + assert "Unrelated later replacement." not in text + assert main([ + "run", "--workspace", str(tmp_path / "cli-workspace"), "--corpus", str(corpus), + ]) == 0 + assert "Unrelated later replacement." in ( + tmp_path / "cli-workspace" / "report.txt" + ).read_text(encoding="utf-8") + + +def test_literal_default_and_existing_filename_string_modes_remain_distinct(tmp_path): + corpus = tmp_path / "source.txt" + corpus.write_text("A literal result from an existing file.", encoding="utf-8") + assert "existing file" in OfflineCorpusProvider(str(corpus)).complete("result") + assert "Absent filename text" in OfflineCorpusProvider("Absent filename text").complete("text") + long_text = "Belief " * 1000 + assert "Belief Belief" in OfflineCorpusProvider(long_text).complete("belief") + assert "Active inference" in OfflineCorpusProvider().complete("active") + assert "Active inference" not in OfflineCorpusProvider("").complete("active") diff --git a/tests/test_manuscript_resources.py b/tests/test_manuscript_resources.py new file mode 100644 index 0000000..1ae2b5e --- /dev/null +++ b/tests/test_manuscript_resources.py @@ -0,0 +1,196 @@ +"""Source-relative resource relocation and metadata-selected publication figures.""" + +from __future__ import annotations + +import json +import re +import shutil +from urllib.parse import unquote, urlsplit + +import numpy as np +import pandas as pd +import pytest +import yaml + +import scripts.build_manuscript as builder +import scripts.validate_manuscript as validator +from blockference.config import ExperimentConfig +from blockference.manuscript_links import rebase_local_links + + +def _publication(tmp_path, monkeypatch): + original_root = builder.REPO_ROOT + original_manuscript = builder.MANUSCRIPT_DIR + root = tmp_path / "publication" + manuscript = root / "docs" / "manuscript" + manuscript.mkdir(parents=True) + for source in [ + *original_manuscript.glob("[0-9][0-9]_*.md"), + original_manuscript / "references.bib", original_manuscript / "config.yaml", + original_manuscript / "figure-registry.json", + ]: + shutil.copy2(source, manuscript / source.name) + figures = manuscript / "figures" + figures.mkdir() + for source in builder.FIGURE_DIR.iterdir(): + if source.suffix in {".svg", ".png"}: + shutil.copy2(source, figures / source.name) + shutil.copy2(original_root / "docs" / "gnn.md", root / "docs" / "gnn.md") + (root / ".github").mkdir() + shutil.copy2(original_root / ".github" / "GNN.md", root / ".github" / "GNN.md") + (root / "configs").mkdir() + shutil.copy2(original_root / "configs" / "manuscript.yml", root / "configs" / "manuscript.yml") + output = root / "relocated" / "deep" / "output" + monkeypatch.setattr(builder, "REPO_ROOT", root) + monkeypatch.setattr(builder, "MANUSCRIPT_DIR", manuscript) + monkeypatch.setattr(builder, "FIGURE_DIR", figures) + monkeypatch.setattr(builder, "BUILD_DIR", output) + monkeypatch.setattr(validator, "ROOT", root) + monkeypatch.setattr(validator, "MANUSCRIPT", manuscript) + return root, manuscript, output + + +def test_relocated_real_composition_resolves_gnn_bibliography_and_copied_figures(tmp_path, monkeypatch): + root, manuscript, output = _publication(tmp_path, monkeypatch) + compiled, _labels = builder.compose_manuscript() + path = builder._write_outputs(compiled) + targets = set() + for destination in re.findall(r"!?\[[^\]]*\]\(([^\s)]+)", compiled): + parsed = urlsplit(destination) + if parsed.scheme or parsed.netloc or not parsed.path: + continue + target = (path.parent / unquote(parsed.path)).resolve() + assert target.is_file(), destination + targets.add(target) + assert root / "docs" / "gnn.md" in targets + assert root / ".github" / "GNN.md" in targets + assert output / "references.bib" in targets + assert (output / "references.bib").read_bytes() == (manuscript / "references.bib").read_bytes() + assert (output / "config.yaml").read_bytes() == (manuscript / "config.yaml").read_bytes() + registry = json.loads((manuscript / "figure-registry.json").read_text(encoding="utf-8")) + for entry in registry["figures"]: + assert output / "figures" / entry["png"] in targets + + +def test_inline_reference_and_escaped_parenthesis_destinations_keep_suffixes_and_titles(tmp_path): + source = tmp_path / "sources" / "manuscript" / "section.md" + source.parent.mkdir(parents=True) + spaced = source.parent.parent / "a file(v1).md" + spaced.write_text("# Target\n", encoding="utf-8") + parenthesized = source.parent / "manual(v2).md" + parenthesized.write_text("# Part\n", encoding="utf-8") + figure = source.parent / "figures" / "chart.png" + figure.parent.mkdir() + figure.write_bytes(b"resource fixture") + output = tmp_path / "compiled" / "nested" + output.mkdir(parents=True) + text = ( + '[inline](<../a%20file(v1).md?version=1#target> "A title")\n' + '[manual]: <../a%20file(v1).md?version=2#target> "Reference title"\n' + '[plain](manual(v2).md#part)\n' + '[escaped](manual\\(v2\\).md#part)\n' + '![chart](figures/chart.png)\n' + ) + rendered = rebase_local_links(text, source=source, output_dir=output, copied={figure: output / "figures" / "chart.png"}) + assert '?version=1#target> "A title"' in rendered + assert '?version=2#target> "Reference title"' in rendered + destinations = re.findall(r"<([^>]+)>|\]\(([^<\s)]+)", rendered) + resolved = [ + (output / unquote(urlsplit(first or second).path)).resolve() + for first, second in destinations + ] + assert resolved == [spaced, spaced, parenthesized, parenthesized, output / "figures" / "chart.png"] + assert "#part" in rendered + assert "# Target" in spaced.read_text(encoding="utf-8") + assert "# Part" in parenthesized.read_text(encoding="utf-8") + + +def test_external_links_fragments_citations_and_code_are_not_rewritten(tmp_path): + original = ( + '[web](https://example.invalid/a(b)?v=1#part)\n' + '[mail](mailto:someone@example.invalid) [doi](doi:10.1000/example)\n' + '[cdn](//example.invalid/a) [local](#sec:overview) [@Scholar2020] [@eq:belief]\n' + '`[inline code](missing.md)`\n' + '````markdown\n[fenced](also-missing.md)\n````\n' + ) + assert rebase_local_links( + original, source=tmp_path / "section.md", output_dir=tmp_path / "elsewhere", + ) == original + + +def test_missing_local_resource_refuses_composition_without_a_fake_target(tmp_path): + with pytest.raises(FileNotFoundError): + rebase_local_links( + "[missing](no-such-file.md#anchor)", + source=tmp_path / "section.md", output_dir=tmp_path / "compiled", + ) + + +@pytest.mark.slow +def test_alternate_metadata_config_reaches_experiment_and_dimension_four_run_plots(tmp_path, monkeypatch): + root, manuscript, _output = _publication(tmp_path, monkeypatch) + config = ExperimentConfig.from_dict({ + "name": "selected", "engine": "cadcad", "seed": 19, + "grid": {"dimension": 4, "planning_length": 1, "max_policies": 20, + "affordances": ["RIGHT", "STAY"]}, + "simulation": {"timesteps": 2, "runs": 2, "n_agents": 1, "target": [3, 3]}, + "output": {"path": None}, + }) + selected = root / "configs" / "selected.yml" + selected.write_text(yaml.safe_dump(config.to_dict()), encoding="utf-8") + metadata_path = manuscript / "config.yaml" + metadata = yaml.safe_load(metadata_path.read_text(encoding="utf-8")) + metadata["experiment"].update( + config_path="configs/selected.yml", engine="cadcad", dimension=4, + planning_length=1, max_policies=20, timesteps=2, runs=2, agents=1, + seed=19, target=[3, 3], initial_states=[[0, 0]], affordances=["RIGHT", "STAY"], + ) + metadata_path.write_text(yaml.safe_dump(metadata), encoding="utf-8") + admitted = [] + + def synthetic(selected_config): + admitted.append(selected_config) + return pd.DataFrame([ + { + "run": run, "timestep": time, "substep": int(time > 0), + "env_states": {0: (0, time) if run == 1 else (time, 0)}, + "inferences": {0: np.eye(16)[0].tolist() if time else None}, + "efe": {0: [float(run + time)] * 2 if time else None}, + } + for run in (1, 2) for time in range(3) + ]) + + monkeypatch.setattr("blockference.simulations.grid_sim.run_experiment", synthetic) + observations = {} + save = builder._save_figure + + def observe(fig, path): + if path.name == "fig3_seeded_run.svg": + axis = fig.axes[0] + observations.update( + xlim=axis.get_xlim(), ylim=axis.get_ylim(), ticks=axis.get_xticks().tolist(), + lines={line.get_label(): line.get_xydata().tolist() for line in axis.lines}, + ) + return save(fig, path) + + monkeypatch.setattr(builder, "_save_figure", observe) + paths = builder.build_figures(tmp_path / "fresh-figures") + assert admitted[0].to_dict() == config.to_dict() + assert observations["xlim"] == (-0.25, 3.25) + assert observations["ylim"] == (3.25, -0.25) + assert observations["ticks"] == [0, 1, 2, 3] + assert observations["lines"] == { + "run 1 / agent 0": [[0.0, 0.0], [1.0, 0.0], [2.0, 0.0]], + "run 2 / agent 0": [[0.0, 0.0], [0.0, 1.0], [0.0, 2.0]], + } + assert all(path.with_suffix(".png").is_file() for path in paths) + + +def test_metadata_mirror_disagreement_remains_an_explicit_failure(tmp_path, monkeypatch): + _root, manuscript, _output = _publication(tmp_path, monkeypatch) + metadata_path = manuscript / "config.yaml" + metadata = yaml.safe_load(metadata_path.read_text(encoding="utf-8")) + metadata["experiment"]["dimension"] = 999 + metadata_path.write_text(yaml.safe_dump(metadata), encoding="utf-8") + errors = validator.validate() + assert any("metadata disagrees" in error and "dimension" in error for error in errors) diff --git a/tests/test_notebook_contracts.py b/tests/test_notebook_contracts.py new file mode 100644 index 0000000..e2cbcd6 --- /dev/null +++ b/tests/test_notebook_contracts.py @@ -0,0 +1,193 @@ +"""Tracked-only notebook admission and notebook-owned RNG behavior.""" + +from __future__ import annotations + +import os +import subprocess +import sys +from pathlib import Path + +import nbformat +import numpy as np +import pytest + +from blockference.notebook_inventory import ( + execute_notebooks, + tracked_notebooks, + validate_all, + validate_notebook, +) + + +def _git(root, *arguments): + environment = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")} + environment.update({ + "GIT_CONFIG_NOSYSTEM": "1", "GIT_CONFIG_GLOBAL": os.devnull, + "GIT_OPTIONAL_LOCKS": "0", "GIT_TERMINAL_PROMPT": "0", + }) + return subprocess.run( + ["git", "--no-optional-locks", "-c", "core.fsmonitor=false", "-c", "commit.gpgsign=false", + "-c", "user.name=Notebook Test", "-c", "user.email=notebook@example.invalid", + "-C", str(root), *arguments], + check=True, capture_output=True, text=True, env=environment, stdin=subprocess.DEVNULL, + ) + + +@pytest.fixture +def repository(tmp_path): + root = tmp_path / "repo" + root.mkdir() + _git(root, "init", "-q") + _git(root, "config", "core.fsmonitor", "false") + hooks = root / ".git" / "empty-hooks" + hooks.mkdir() + _git(root, "config", "core.hooksPath", str(hooks)) + return root + + +def _notebook(path, label): + path.parent.mkdir(parents=True, exist_ok=True) + notebook = nbformat.v4.new_notebook(cells=[ + nbformat.v4.new_markdown_cell( + "This local teaching example introduces the supported package API with a controlled " + "environment. It uses deterministic local state without external services." + ), + nbformat.v4.new_code_cell( + "from blockference import GridWorld\n" + "assert GridWorld(2, {0: (0, 0)}).current_state == {0: (0, 0)}\n" + ), + ]) + notebook.metadata["selection_label"] = label + nbformat.write(notebook, path) + + +def test_only_tracked_nonignored_source_can_validate_and_reach_execution(repository, monkeypatch, tmp_path): + first = repository / "course.ipynb" + unusual = repository / "nb α\ncopy.ipynb" + _notebook(first, "course") + _notebook(unusual, "unicode-newline") + _git(repository, "add", first.name, unusual.name) + (repository / ".gitignore").write_text("ignored.ipynb\n", encoding="utf-8") + ignored = repository / "ignored.ipynb" + ignored.write_bytes(b"invalid notebook must not be parsed") + _git(repository, "add", "-f", ignored.name) + for directory in (".venv", "venv", "env", "cad", ".ipynb_checkpoints", "build", "dist", "output", "results"): + path = repository / directory / "decoy.ipynb" + path.parent.mkdir() + path.write_bytes(b"tracked non-source decoy must not be parsed") + _git(repository, "add", "-f", str(path.relative_to(repository))) + (repository / "untracked.ipynb").write_bytes(b"untracked invalid notebook") + (repository / ".git" / "decoy.ipynb").write_bytes(b"git administrative decoy") + selected, failures = validate_all(repository) + assert selected == (first, unusual) + assert failures == {} + executed = [] + + class Client: + def __init__(self, notebook, **_kwargs): + self.notebook = notebook + + def execute(self): + executed.append(self.notebook.metadata["selection_label"]) + return self.notebook + + monkeypatch.setattr("nbclient.NotebookClient", Client) + assert execute_notebooks(repository, workspace=tmp_path) == (first, unusual) + assert executed == ["course", "unicode-newline"] + + +def test_empty_tracked_inventory_stays_empty_even_with_invalid_disk_decoys(repository, tmp_path, monkeypatch): + (repository / "untracked.ipynb").write_bytes(b"must not be parsed") + assert tracked_notebooks(repository) == () + assert validate_all(repository) == ((), {}) + monkeypatch.setitem(sys.modules, "nbclient", None) + assert execute_notebooks(repository, workspace=tmp_path) == () + + +def test_worktree_git_file_is_a_valid_inventory_root(repository, tmp_path): + source = repository / "tracked.ipynb" + _notebook(source, "worktree") + _git(repository, "add", source.name) + _git(repository, "commit", "-qm", "fixture") + worktree = tmp_path / "linked-worktree" + _git(repository, "worktree", "add", "--detach", str(worktree), "HEAD") + assert (worktree / ".git").is_file() + assert tracked_notebooks(worktree) == (worktree / source.name,) + + +def test_nested_directory_cannot_inherit_an_unrelated_repository_inventory(repository): + nested = repository / "nested" + nested.mkdir() + _notebook(nested / "untracked.ipynb", "not-a-root") + with pytest.raises(ValueError, match="exact Git repository root"): + tracked_notebooks(nested) + + +def test_missing_tracked_notebook_and_symlink_escape_are_explicit_errors(repository, tmp_path): + source = repository / "tracked.ipynb" + _notebook(source, "tracked") + _git(repository, "add", source.name) + source.unlink() + with pytest.raises(FileNotFoundError): + tracked_notebooks(repository) + outside = tmp_path / "outside.ipynb" + _notebook(outside, "outside") + source.symlink_to(outside) + _git(repository, "add", source.name) + with pytest.raises(ValueError, match="symlink|escapes"): + tracked_notebooks(repository) + + +def test_git_unavailable_or_failed_inventory_never_falls_back_to_recursive_scan(repository, monkeypatch): + (repository / "untracked.ipynb").write_bytes(b"not source") + with monkeypatch.context() as context: + context.setenv("PATH", "") + with pytest.raises(FileNotFoundError): + tracked_notebooks(repository) + (repository / ".git" / "index").write_bytes(b"broken owned fixture index") + with pytest.raises(RuntimeError, match="cannot read tracked notebooks"): + tracked_notebooks(repository) + + +def test_selected_hygiene_failure_prevents_any_notebook_execution(repository, tmp_path, monkeypatch): + source = repository / "tracked.ipynb" + _notebook(source, "invalid-summary") + notebook = nbformat.read(source, as_version=4) + notebook.cells[0].source = "Too short." + nbformat.write(notebook, source) + _git(repository, "add", source.name) + assert validate_notebook(source) + + def forbidden(*_args, **_kwargs): + raise AssertionError("execution began despite selected-source hygiene failure") + + monkeypatch.setattr("nbclient.NotebookClient", forbidden) + with pytest.raises(ValueError, match="hygiene violations"): + execute_notebooks(repository, workspace=tmp_path) + + +@pytest.mark.slow +def test_single_agent_notebook_source_owns_a_seeded_stream_independent_of_global_rng(): + path = Path(__file__).resolve().parents[1] / "notebooks" / "simple_gridworld" / "gridference_single.ipynb" + notebook = nbformat.read(path, as_version=4) + source = next(cell.source for cell in notebook.cells if cell.cell_type == "code") + original = np.random.get_state() + updates = [] + try: + for seed in (13, 971): + np.random.seed(seed) + np.random.random(37) + before = np.random.get_state() + namespace = {} + exec(compile(source, str(path), "exec"), namespace) + updates.append(namespace["update"]) + after = np.random.get_state() + assert before[0] == after[0] + assert np.array_equal(before[1], after[1]) + assert before[2:] == after[2:] + assert updates[0]["update_action"] == updates[1]["update_action"] + assert updates[0]["update_env"] == updates[1]["update_env"] + for name in ("update_prior", "update_inference", "update_efe", "update_q_pi", "update_p_u"): + assert np.array_equal(updates[0][name], updates[1][name]) + finally: + np.random.set_state(original) diff --git a/tests/test_notebooks.py b/tests/test_notebooks.py index 69ab181..ffef834 100644 --- a/tests/test_notebooks.py +++ b/tests/test_notebooks.py @@ -2,25 +2,13 @@ from pathlib import Path -import nbformat import pytest -from nbclient import NotebookClient -from scripts.validate_notebooks import validate_all +from blockference.notebook_inventory import execute_notebooks pytestmark = pytest.mark.slow def test_notebooks_parse_and_execute(tmp_path): root = Path(__file__).parents[1] - assert validate_all(root) == {} - for path in sorted(root.rglob("*.ipynb")): - if ".venv" in path.parts: - continue - notebook = nbformat.read(path, as_version=4) - NotebookClient( - notebook, - timeout=120, - kernel_name="python3", - resources={"metadata": {"path": str(tmp_path)}}, - ).execute() + execute_notebooks(root, workspace=tmp_path) diff --git a/tests/test_pipeline_real.py b/tests/test_pipeline_real.py index fffa7f7..980878c 100644 --- a/tests/test_pipeline_real.py +++ b/tests/test_pipeline_real.py @@ -168,8 +168,33 @@ def test_validate_stages_are_focused_and_aggregate(tmp_path): model_report, model_payload = validate_model_boundary(paths, cfg) assert model_report.ok and model_payload is not None assert validate_manifest_boundary(paths).ok - assert validate_policies_boundary(paths).ok - assert validate_per_step_boundary(paths, cfg, trajectory).ok + assert validate_policies_boundary(paths, cfg, model_payload).ok + assert validate_per_step_boundary(paths, cfg, trajectory, model_payload).ok assert validate_config_trajectory_agreement(cfg, trajectory, summary).ok - assert validate_config_model_agreement(cfg, model_payload).ok + assert validate_config_model_agreement(cfg, model_payload, trajectory).ok assert validate_run_outputs(paths).ok + + +@pytest.mark.parametrize("engine", ["radcad", "cadcad"]) +def test_real_two_run_pipeline_retains_each_model_and_keyed_diagnostics(tmp_path, engine): + import numpy as np + + values = config(engine).to_dict() + values["simulation"].update(runs=2, timesteps=1, target="random") + selected = ExperimentConfig.from_dict(values) + result = run_pipeline(selected, output_root=tmp_path, run_name=f"two_runs_{engine}") + assert result.ok + models = json.loads(result.paths.matrices_json.read_text(encoding="utf-8"))["runs"] + assert set(models) == {"1", "2"} + with np.load(result.paths.matrices_npz, allow_pickle=False) as archive: + for run in (1, 2): + agent = result.trajectory.loc[result.trajectory["run"] == run].iloc[-1]["agents"][0] + assert np.array_equal(models[str(run)]["0"]["C"], agent.C) + assert np.array_equal(archive[f"run_{run}/agent_0/C"], agent.C) + records = pd.read_csv(result.paths.per_step_csv) + assert set(records[["run", "timestep", "substep", "agent_id"]].itertuples(index=False, name=None)) == { + (1, 1, 1, 0), (2, 1, 1, 0), + } + summary = json.loads(result.paths.summary_json.read_text(encoding="utf-8")) + assert summary["runs"]["1"]["trajectory_lengths"] == {"0": 2} + assert summary["runs"]["2"]["trajectory_lengths"] == {"0": 2} diff --git a/tests/test_publication.py b/tests/test_publication.py index 6cd0c26..a8a9de1 100644 --- a/tests/test_publication.py +++ b/tests/test_publication.py @@ -68,14 +68,20 @@ def test_figure_registry_mismatches_fail_validation_and_build( monkeypatch, tmp_path, capsys, mode, fault, message ): manuscript = builder.MANUSCRIPT_DIR + copied = tmp_path / "docs" / "manuscript" + copied.mkdir(parents=True) + (copied.parent / "gnn.md").write_text("# GNN\n", encoding="utf-8") + pointer = tmp_path / ".github" / "GNN.md" + pointer.parent.mkdir() + pointer.write_text("# GNN\n", encoding="utf-8") for source in [ *manuscript.glob("[0-9][0-9]_*.md"), manuscript / "references.bib", manuscript / "config.yaml", ]: - (tmp_path / source.name).write_text(source.read_text(encoding="utf-8"), encoding="utf-8") + (copied / source.name).write_text(source.read_text(encoding="utf-8"), encoding="utf-8") registry = json.loads((manuscript / "figure-registry.json").read_text(encoding="utf-8")) - figures = tmp_path / "figures" + figures = copied / "figures" figures.mkdir() for entry in registry["figures"]: for suffix in ("svg", "png"): @@ -86,9 +92,9 @@ def test_figure_registry_mismatches_fail_validation_and_build( (figures / registry["figures"][0]["png"]).unlink() else: (figures / "orphan.svg").write_bytes(b"") - (tmp_path / "figure-registry.json").write_text(json.dumps(registry), encoding="utf-8") - monkeypatch.setattr(validator, "MANUSCRIPT", tmp_path) - monkeypatch.setattr(builder, "MANUSCRIPT_DIR", tmp_path) + (copied / "figure-registry.json").write_text(json.dumps(registry), encoding="utf-8") + monkeypatch.setattr(validator, "MANUSCRIPT", copied) + monkeypatch.setattr(builder, "MANUSCRIPT_DIR", copied) monkeypatch.setattr(builder, "FIGURE_DIR", figures) assert any(message in error for error in validator.validate()) diff --git a/tests/test_release_gate.py b/tests/test_release_gate.py index add521e..5f1fb49 100644 --- a/tests/test_release_gate.py +++ b/tests/test_release_gate.py @@ -16,67 +16,6 @@ ROOT = Path(__file__).resolve().parents[1] -def test_gnn_arm_runs_the_shared_pin_reader_after_digest_verification(): - runtime = "/opt/gnn-runtime/bin/python" - plan = gate._plan("gnn", workdir=Path(""), gnn_runtime=runtime) - - assert plan is not None - assert plan[0] == ["uv", "run", "python", "scripts/export_gnn_spec.py", "--check"] - assert plan[1] == [ - "uv", - "run", - "python", - "scripts/validate_gnn_spec.py", - "--gnn-runtime", - runtime, - "--verify-tag-remote", - "--json", - ] - assert plan[2] == [ - runtime, - "-m", - "gnn.importers", - "check", - "--repo", - ".", - "--require-pointer", - "--workflow", - ".github/workflows/ci.yml", - "--job", - "gnn-conformance", - ] - - -def test_gnn_arm_verifies_the_pinned_parser_digests_before_it_parses(): - """``gnn.importers check`` parses the document; the digests must be verified first. - - ``check`` calls ``gnn.importers._validate_spec``, which imports the installed - parser and parses every ``*.gnn.md``. The validator is the command that - verifies the pin's parser digests before it parses anything, so it has to - come first or a tampered parser is executed before its digests are checked. - """ - - plan = gate._plan("gnn", workdir=Path(""), gnn_runtime="/opt/gnn/bin/python") - - assert plan is not None - verify = next( - index - for index, command in enumerate(plan) - if any("validate_gnn_spec.py" in part for part in command) - ) - parses = next( - index for index, command in enumerate(plan) if "gnn.importers" in command - ) - assert verify < parses - - -def test_gnn_arm_omits_the_reader_without_a_runtime(): - plan = gate._plan("gnn", workdir=Path(""), gnn_runtime=None) - - assert plan is not None - assert not any("gnn.importers" in " ".join(command) for command in plan) - - def test_checkout_runtime_comes_from_the_gnn_checkout(tmp_path, monkeypatch): relative = Path("Scripts" if os.name == "nt" else "bin") / ( "python.exe" if os.name == "nt" else "python" @@ -86,10 +25,12 @@ def test_checkout_runtime_comes_from_the_gnn_checkout(tmp_path, monkeypatch): python.write_text("", encoding="utf-8") monkeypatch.setenv("GNN_ROOT", str(tmp_path)) - assert gate._checkout_runtime() == str(python) + monkeypatch.delenv("GNN_RUNTIME_PYTHON", raising=False) + monkeypatch.delenv("GNN_PYTHON", raising=False) + assert gate.resolve_gnn_runtime() == str(python) monkeypatch.delenv("GNN_ROOT") - assert gate._checkout_runtime() is None + assert gate.resolve_gnn_runtime(required=False) is None def test_gnn_arm_without_runtime_cannot_write_a_passing_receipt(tmp_path): @@ -155,13 +96,3 @@ def test_render_provenance_requires_the_pdf(tmp_path, monkeypatch): gate._render_artifact() -def test_gnn_arm_always_asks_the_validator_to_resolve_the_tag_upstream(): - for runtime in (None, "/opt/gnn-runtime/bin/python"): - plan = gate._plan("gnn", workdir=Path(""), gnn_runtime=runtime) - - assert plan is not None - validator = next( - command for command in plan if any("validate_gnn_spec.py" in part for part in command) - ) - assert "--verify-tag-remote" in validator - assert validator[-1] == "--json" diff --git a/tests/test_run_artifact_boundaries.py b/tests/test_run_artifact_boundaries.py new file mode 100644 index 0000000..bf32c6d --- /dev/null +++ b/tests/test_run_artifact_boundaries.py @@ -0,0 +1,380 @@ +"""Synthetic multi-run producer/consumer round trips and refreshed-manifest attacks.""" + +from __future__ import annotations + +import itertools +import json +from pathlib import Path + +import numpy as np +import pandas as pd +import pytest +from PIL import Image + +from blockference.cli import main +from blockference.config import ExperimentConfig +from blockference.gridference import ActiveGridference, make_grid +from blockference.io import build_run_paths, persist_manifest, validate_run_outputs +from blockference.io.validate import validate_manifest_boundary +from blockference.pipeline import _extract_policies, persist, summarise_trajectory +from blockference.viz import ( + animate_trajectory, + plot_action_distribution, + plot_belief_heatmap, + plot_efe, + plot_trajectory, +) +from blockference.viz._common import extract_agent_positions, extract_belief_history + + +def _fixture_frame(): + config = ExperimentConfig.from_dict({ + "name": "synthetic", "seed": None, + "grid": {"dimension": 2, "planning_length": 2, "max_policies": 16, + "affordances": ["DOWN", "RIGHT", "STAY"]}, + "simulation": {"timesteps": 2, "runs": 2, "n_agents": 1, "target": "random"}, + "output": {"path": None}, + }) + rows = [] + for run, destination in ((1, (0, 1)), (2, (1, 0))): + agent = ActiveGridference( + make_grid(2), planning_length=2, affordances=config.grid.affordances, max_policies=16, + ) + agent.get_D((0, 0)) + agent.get_C((0, 1) if run == 1 else (1, 1)) + previous = (0, 0) + for time in range(3): + position = (0, 0) if time == 0 else destination + posterior = np.eye(4)[previous[0] * 2 + previous[1]].tolist() + prior = np.eye(4)[position[0] * 2 + position[1]].tolist() + energy = [run + time / 10] * 9 + action = (1 if time == 1 else 2) if run == 1 else 0 + diagnostics = { + "actions": action, "inferences": posterior, "efe": energy, + "efe_epistemic": [0.0] * 9, "efe_pragmatic": energy, + "q_pi": [1 / 9] * 9, "p_u": [1 / 3] * 3, + "obs_idx": previous[0] * 2 + previous[1], + } + rows.append({ + "agents": {0: agent}, "priors": {0: prior}, "env_states": {0: position}, + **{key: {0: value if time else None} for key, value in diagnostics.items()}, + "run": run, "timestep": time, "substep": int(time > 0), + }) + previous = position + return config, pd.DataFrame(rows) + + +def _fresh(paths): + persist_manifest(paths) + assert validate_manifest_boundary(paths).ok + + +@pytest.fixture +def run_tree(tmp_path): + config, frame = _fixture_frame() + paths = build_run_paths(tmp_path, "synthetic").ensure() + persist(config, frame, paths) + image = Image.new("RGB", (8, 8), "white") + for name in ("trajectory.png", "action_distribution.png", "efe.png"): + image.save(paths.viz_dir / name) + for run in (1, 2): + for label in ("first", "last"): + image.save(paths.viz_dir / f"belief_heatmap_run_{run}_agent_0_{label}.png") + image.save(paths.animations_dir / "trajectory.gif") + paths.run_log.write_text("synthetic artifact fixture\n", encoding="utf-8") + _fresh(paths) + assert validate_run_outputs(paths).ok + return config, frame, paths + + +def _model_json(paths): + return json.loads(paths.matrices_json.read_text(encoding="utf-8")) + + +def _write_models(paths, payload): + paths.matrices_json.write_text(json.dumps(payload), encoding="utf-8") + arrays = { + f"run_{run}/agent_{agent}/{name}": np.asarray(value[name]) + for run, agents in payload["runs"].items() for agent, value in agents.items() + for name in ("A", "B", "C", "D", "E") + } + np.savez_compressed(paths.matrices_npz, **arrays) + + +def test_distinct_run_models_policies_and_summaries_round_trip(run_tree): + _config, frame, paths = run_tree + models = _model_json(paths)["runs"] + assert set(models) == {"1", "2"} + assert models["1"]["0"]["C"] != models["2"]["0"]["C"] + with np.load(paths.matrices_npz, allow_pickle=False) as archive: + assert np.array_equal(archive["run_1/agent_0/C"], models["1"]["0"]["C"]) + assert np.array_equal(archive["run_2/agent_0/C"], models["2"]["0"]["C"]) + policies = json.loads(paths.policies_json.read_text(encoding="utf-8")) + for run in ("1", "2"): + assert policies["runs"][run]["0"]["n_policies"] == 9 + summary = json.loads(paths.summary_json.read_text(encoding="utf-8")) + assert summary["n_agents"] == 1 and summary["n_runs"] == 2 + assert summary["runs"]["1"]["final_positions"] == {"0": [0, 1]} + assert summary["runs"]["2"]["final_positions"] == {"0": [1, 0]} + assert summary["runs"]["1"]["trajectory_lengths"] == {"0": 3} + assert summary["runs"]["2"]["belief_history_lengths"] == {"0": 2} + shuffled = frame.sample(frac=1, random_state=7) + assert extract_agent_positions(shuffled) == extract_agent_positions(frame) + assert len(extract_belief_history(shuffled)[(1, 0)]) == 2 + + +def test_swapped_json_and_npz_models_fail_even_after_manifest_refresh(run_tree): + _config, _frame, paths = run_tree + payload = _model_json(paths) + payload["runs"]["1"], payload["runs"]["2"] = payload["runs"]["2"], payload["runs"]["1"] + _write_models(paths, payload) + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert report.checks["artefacts.generative_model_npz_values"] + assert not report.checks["artefacts.model_run_association"] + + +@pytest.mark.parametrize("change", ["truncate-step", "truncate-run", "relabel-run"]) +def test_configured_schedule_rejects_coherent_history_rewrites(run_tree, change): + config, frame, paths = run_tree + if change == "truncate-step": + changed = frame.loc[frame["timestep"] < 2].copy() + elif change == "truncate-run": + changed = frame.loc[frame["run"] == 1].copy() + else: + changed = frame.copy() + changed.loc[changed["run"] == 2, "run"] = 3 + persist(config, changed, paths) + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert not report.checks["artefacts.configured_schedule"] + + +def test_duplicate_trajectory_identity_is_not_hidden_by_row_count(run_tree): + _config, _frame, paths = run_tree + frame = pd.read_csv(paths.trajectory_csv) + frame.loc[2] = frame.loc[1] + frame.to_csv(paths.trajectory_csv, index=False) + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert not report.checks["artefacts.trajectory.unique_row_identities"] + + +def test_every_run_initial_position_and_prior_are_checked(run_tree): + _config, _frame, paths = run_tree + frame = pd.read_csv(paths.trajectory_csv) + index = frame.index[(frame["run"] == 2) & (frame["timestep"] == 0)][0] + frame.at[index, "env_states"] = repr({"0": [1, 1]}) + frame.at[index, "priors"] = repr({"0": [0.5, 0.5]}) + frame.to_csv(paths.trajectory_csv, index=False) + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert not report.checks["artefacts.configured_initial_states"] + assert not report.checks["artefacts.model_initial_priors"] + + +@pytest.mark.parametrize("change", ["duplicate", "missing", "wrong-agent"]) +def test_diagnostics_are_one_to_one_by_configured_identity(run_tree, change): + _config, _frame, paths = run_tree + records = pd.read_csv(paths.per_step_csv) + if change == "duplicate": + records.loc[1] = records.loc[0] + elif change == "missing": + records = records.iloc[:-1] + else: + records.at[0, "agent_id"] = 1 + records.to_csv(paths.per_step_csv, index=False) + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert not report.checks["artefacts.per_step_coverage"] + + +def test_same_shape_cross_run_diagnostic_swap_cannot_qualify(run_tree): + _config, _frame, paths = run_tree + records = pd.read_csv(paths.per_step_csv) + columns = ["efe", "efe_epistemic", "efe_pragmatic"] + first = records.loc[0, columns].copy() + records.loc[0, columns] = records.loc[2, columns].to_numpy() + records.loc[2, columns] = first.to_numpy() + records.to_csv(paths.per_step_csv, index=False) + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert report.checks["artefacts.per_step_coverage"] + assert not report.checks["artefacts.per_step_trajectory_values"] + + +@pytest.mark.parametrize("column", ["actions", "obs_idx"]) +@pytest.mark.parametrize("convert", [str, float, bool], ids=["string", "float", "boolean"]) +def test_categorical_trajectory_types_cannot_be_hidden_by_numeric_agreement( + run_tree, column, convert, +): + _config, original, paths = run_tree + frame = pd.read_csv(paths.trajectory_csv) + index = frame.index[(frame["run"] == 1) & (frame["timestep"] == 1)][0] + frame.at[index, column] = repr({"0": convert(original.at[index, column][0])}) + frame.to_csv(paths.trajectory_csv, index=False) + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert not report.checks["artefacts.per_step_trajectory_values"] + + +def test_policy_vectors_are_policy_sized_not_merely_action_sized(run_tree): + _config, _frame, paths = run_tree + records = pd.read_csv(paths.per_step_csv) + trajectory = pd.read_csv(paths.trajectory_csv) + for field in ("efe", "efe_epistemic", "efe_pragmatic", "q_pi"): + value = [1 / 3] * 3 if field == "q_pi" else [0.0] * 3 + records.at[0, field] = repr(value) + trajectory.at[1, field] = repr({"0": value}) + records.to_csv(paths.per_step_csv, index=False) + trajectory.to_csv(paths.trajectory_csv, index=False) + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert not report.checks["artefacts.per_step.0.model_dimensions"] + + +@pytest.mark.parametrize("field", ["E", "policy_len", "max_policies"]) +def test_model_affordance_order_and_planning_metadata_match_configuration(run_tree, field): + _config, _frame, paths = run_tree + payload = _model_json(paths) + model = payload["runs"]["1"]["0"] + model[field] = list(reversed(model[field])) if field == "E" else model[field] + 1 + _write_models(paths, payload) + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert not report.checks["artefacts.configured_model_dimensions"] + + +def test_missing_run_model_and_policy_reordering_fail_with_fresh_digests(run_tree): + _config, _frame, paths = run_tree + payload = _model_json(paths) + del payload["runs"]["2"] + _write_models(paths, payload) + policies = json.loads(paths.policies_json.read_text(encoding="utf-8")) + policies["runs"]["1"]["0"]["policies"].reverse() + paths.policies_json.write_text(json.dumps(policies), encoding="utf-8") + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert not report.checks["artefacts.configured_model_agents"] + assert not report.checks["artefacts.policies_complete_ordered"] + + +@pytest.mark.parametrize("fault", ["scalar-policies", "missing-timestep", "nonmapping-state", "scalar-matrix", "invalid-utf8"]) +def test_malformed_artifacts_return_failed_cli_json_not_tracebacks(run_tree, capsys, fault): + _config, _frame, paths = run_tree + if fault == "scalar-policies": + payload = json.loads(paths.policies_json.read_text(encoding="utf-8")) + payload["runs"]["1"]["0"]["policies"] = 9 + paths.policies_json.write_text(json.dumps(payload), encoding="utf-8") + elif fault in {"missing-timestep", "nonmapping-state"}: + frame = pd.read_csv(paths.trajectory_csv) + if fault == "missing-timestep": + frame = frame.drop(columns="timestep") + else: + frame.at[0, "env_states"] = "[]" + frame.to_csv(paths.trajectory_csv, index=False) + elif fault == "scalar-matrix": + payload = _model_json(paths) + payload["runs"]["1"]["0"]["A"] = 0.5 + _write_models(paths, payload) + else: + paths.summary_json.write_bytes(b"\xff") + _fresh(paths) + assert main(["validation", "--run-dir", str(paths.run_dir)]) == 1 + lines = [line for line in capsys.readouterr().out.splitlines() if line.strip()] + assert len(lines) == 1 + report = json.loads(lines[0]) + assert report["ok"] is False and report["issues"] + assert report["checks"]["artefacts.manifest.digests"] + + +def test_required_heatmap_coverage_is_run_scoped(run_tree): + _config, _frame, paths = run_tree + (paths.viz_dir / "belief_heatmap_run_2_agent_0_last.png").unlink() + _fresh(paths) + report = validate_run_outputs(paths) + assert not report.ok + assert not report.checks["artefacts.render.belief_heatmap_run_2_agent_0_last.png"] + + +def test_policy_extraction_enforces_actual_cap_and_preserves_allowed_order(): + agent = ActiveGridference(make_grid(2), affordances=["RIGHT", "STAY"], planning_length=3, max_policies=8) + extracted = _extract_policies({(2, "0"): agent})[(2, "0")] + assert [tuple(policy[:, 0]) for policy in extracted] == list(itertools.product(range(2), repeat=3)) + agent.max_policies = 4 + with pytest.raises(ValueError, match="max_policies=4"): + _extract_policies({(2, "0"): agent}) + + +def test_run_scoped_plots_use_actual_times_and_never_connect_runs(tmp_path, monkeypatch): + import blockference.viz.plots as plots + + _config, frame = _fixture_frame() + captures = {} + save = plots.atomic_savefig + + def capture(fig, path, **kwargs): + axis = fig.axes[0] + captures[Path(path).name] = { + "lines": {line.get_label(): line.get_xydata().tolist() for line in axis.lines}, + "bars": {container.get_label(): [bar.get_height() for bar in container] for container in axis.containers}, + "images": [np.asarray(image.get_array()).tolist() for image in axis.images], + "title": axis.get_title(), + } + return save(fig, path, **kwargs) + + monkeypatch.setattr(plots, "atomic_savefig", capture) + shuffled = frame.sample(frac=1, random_state=5) + plot_trajectory(shuffled, tmp_path / "paths.png") + plot_efe(shuffled, tmp_path / "energy.png") + plot_action_distribution(shuffled, tmp_path / "actions.png", affordances=["DOWN", "RIGHT", "STAY"]) + plot_belief_heatmap(shuffled, tmp_path / "posterior.png", run=2, agent_id=0) + assert captures["paths.png"]["lines"] == { + "run 1 / agent 0": [[0.0, 0.0], [1.0, 0.0], [1.0, 0.0]], + "run 2 / agent 0": [[0.0, 0.0], [0.0, 1.0], [0.0, 1.0]], + } + assert [point[0] for point in captures["energy.png"]["lines"]["run 2 / agent 0"]] == [1.0, 2.0] + assert captures["actions.png"]["bars"] == {"run 1 / agent 0": [0, 1, 1], "run 2 / agent 0": [2, 0, 0]} + assert captures["posterior.png"]["images"] == [[[0.0, 0.0], [1.0, 0.0]]] + assert "run 2 / agent 0 @ t=2, substep=1" in captures["posterior.png"]["title"] + summary = summarise_trajectory(shuffled) + assert summary["runs"]["1"]["trajectory_lengths"] == {"0": 3} + with pytest.raises(ValueError, match="ambiguous"): + plot_belief_heatmap(shuffled, tmp_path / "ambiguous.png", agent_id=0) + + +def test_animation_keeps_separate_paths_and_actual_run_time_labels(tmp_path, monkeypatch): + import blockference.viz.animation as animation + + _config, frame = _fixture_frame() + snapshots = {} + implementation = animation.FuncAnimation + + def observe(fig, update, **kwargs): + def wrapped(index): + artists = update(index) + axis = fig.axes[0] + snapshots[index] = { + "lines": {line.get_label(): line.get_xydata().tolist() for line in axis.lines if line.get_label().startswith("run ")}, + "labels": [text.get_text() for text in axis.texts], + } + return artists + return implementation(fig, wrapped, **kwargs) + + monkeypatch.setattr(animation, "FuncAnimation", observe) + output = animate_trajectory(frame.sample(frac=1, random_state=3), tmp_path / "runs.gif") + assert len(snapshots[2]["lines"]["run 1 / agent 0"]) == 3 + assert len(snapshots[2]["lines"]["run 2 / agent 0"]) == 3 + assert any("run 1: t=2, substep=1" in text and "run 2: t=2, substep=1" in text for text in snapshots[2]["labels"]) + with Image.open(output) as image: + assert image.format == "GIF" and image.n_frames > 1 diff --git a/tests/utils/test_utils_math.py b/tests/utils/test_utils_math.py index 5f4488d..466a3cc 100644 --- a/tests/utils/test_utils_math.py +++ b/tests/utils/test_utils_math.py @@ -85,3 +85,88 @@ def test_sample_without_rng_uses_global_stream(): np.random.seed(7) second = u.sample(np.array([0.5, 0.5])) assert first == second + + +@pytest.fixture +def preserved_global_rng(): + state = np.random.get_state() + try: + yield + finally: + np.random.set_state(state) + + +def _assert_global_state_equal(expected): + actual = np.random.get_state() + assert actual[0] == expected[0] + assert np.array_equal(actual[1], expected[1]) + assert actual[2:] == expected[2:] + + +def test_extreme_finite_weights_normalize_per_slice_without_overflow(): + largest = np.finfo(float).max + smallest = np.nextafter(0.0, 1.0) + weights = np.array([[largest, largest / 2], [0.0, 0.0], [smallest, 2 * smallest]]) + expected = np.array([[2 / 3, 1 / 3], [0.5, 0.5], [1 / 3, 2 / 3]]) + original = weights.copy() + with np.errstate(over="raise", invalid="raise", divide="raise"): + rows = u.norm_dist(weights, axis=1) + columns = u.norm_dist(weights.T, axis=0) + tensor = u.norm_dist(np.stack([weights, weights]), axis=-1) + assert np.isfinite(rows).all() + assert np.allclose(rows, expected) + assert np.allclose(rows.sum(axis=1), 1.0) + assert np.allclose(columns, expected.T) + assert np.allclose(tensor, np.stack([expected, expected])) + assert np.array_equal(weights, original) + + +def test_extreme_sampling_matches_owned_generator_without_touching_global(preserved_global_rng): + largest = np.finfo(float).max + rng = np.random.default_rng(31) + expected_rng = np.random.default_rng(31) + global_state = np.random.get_state() + actual = [u.sample(np.array([largest, largest / 2]), rng=rng) for _ in range(64)] + expected = expected_rng.choice(2, size=64, p=[2 / 3, 1 / 3]) + assert np.array_equal(actual, expected) + assert rng.bit_generator.state == expected_rng.bit_generator.state + _assert_global_state_equal(global_state) + + +def test_extreme_sampling_preserves_legacy_global_stream(preserved_global_rng): + np.random.seed(23) + expected = np.random.choice(2, size=64, p=[2 / 3, 1 / 3]) + expected_state = np.random.get_state() + np.random.seed(23) + largest = np.finfo(float).max + actual = [u.sample(np.array([largest, largest / 2])) for _ in range(64)] + assert np.array_equal(actual, expected) + _assert_global_state_equal(expected_state) + + +@pytest.mark.parametrize("weights", [[], [0, 0], [-1, 2], [np.nan, 1], [np.inf, 1], [[1, 2]]]) +def test_sampling_refuses_invalid_mass_before_consuming_any_rng(weights, preserved_global_rng): + rng = np.random.default_rng(41) + owned_state = rng.bit_generator.state + global_state = np.random.get_state() + with pytest.raises(ValueError): + u.sample(weights, rng=rng) + with pytest.raises(ValueError): + u.sample(weights) + assert rng.bit_generator.state == owned_state + _assert_global_state_equal(global_state) + + +def test_retained_conditional_ambiguity_is_not_predictive_entropy(): + likelihood = np.eye(2) + belief = np.array([0.5, 0.5]) + transitions = np.eye(2)[:, :, None] + total, parts = u.calculate_G_policies_traced( + likelihood, transitions, belief, belief, [np.array([[0]])], + ) + predictive = likelihood @ belief + predictive_entropy = -float(np.sum(predictive * np.log(predictive))) + assert np.allclose(parts["epistemic"], [0.0]) + assert np.allclose(parts["pragmatic"], [0.0]) + assert np.allclose(total, [0.0]) + assert predictive_entropy == pytest.approx(np.log(2)) From aa70c31ddb0dfeacf7f75ebe07ead9b3a95cac07 Mon Sep 17 00:00:00 2001 From: Daniel Ari Friedman Date: Mon, 16 Nov 2026 18:08:35 -0800 Subject: [PATCH 2/4] Complete immutable GNN resource delivery and preserve gate diagnostics - Provision and verify authentic immutable bootstrap and version-correct full manifest before the original hosted all gate. - Preserve original captured command failure output and exact external-document diagnostics controls. - Reconcile only the observed current-main locked dependency delta; retain producer, science and full-release boundaries. --- .github/AGENTS.md | 3 +- .github/workflows/ci.yml | 26 ++++++- TODO.md | 8 +- docs/gate.md | 18 +++-- docs/gnn.md | 22 ++++-- scripts/release_check.py | 26 ++++--- tests/test_publication.py | 9 ++- tests/test_release_gate.py | 32 ++++++++ uv.lock | 146 ++++++++++++++++++------------------- 9 files changed, 189 insertions(+), 101 deletions(-) diff --git a/.github/AGENTS.md b/.github/AGENTS.md index e804535..34d54ae 100644 --- a/.github/AGENTS.md +++ b/.github/AGENTS.md @@ -10,7 +10,8 @@ There is no separate `gate` job. The `gnn` arm checks exporter drift, then shared pin/pointer/workflow/job check through qualified external workers. Require independently reviewed `GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` job inputs and complete content/module/installed-origin admission through exit. -Their hosted delivery remains a release prerequisite; never invent download +The workflow downloads both from the immutable producer resource revision and +verifies their source-owned SHA-256 digests before use; never invent download URLs or weaken admission. Missing prerequisites 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 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 72e316d..38f4335 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -58,8 +58,8 @@ jobs: # 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 project validator owns both guarded conformance - # and shared importer checks. Hosted acceptance also requires independently - # reviewed GNN_BOOTSTRAP/GNN_SOURCE_MANIFEST resource delivery; parser-file + # and shared importer checks. Independently reviewed immutable resources are + # downloaded and SHA-256 checked before release execution; parser-file # digests alone are not complete source or installed-origin admission. name: gnn conformance (pinned) runs-on: ubuntu-latest @@ -81,6 +81,26 @@ jobs: - name: Install locked package and development dependencies run: uv sync --locked --extra dev --python 3.12 + - name: Prepare reviewed GNN admission resources + id: resources + run: | + set -euo pipefail + # Resource delivery revision, not the parser revision in specs/gnn-pin.json. + BASE="https://raw.githubusercontent.com/ActiveInferenceInstitute/Generalized_Notation_Notation/66d491f86895443cf588011cc6f40c37b8bae8fd/interop" + RESOURCES="$RUNNER_TEMP/gnn-resources" + mkdir -p "$RESOURCES" + curl --fail --silent --show-error --location --proto '=https' --tlsv1.2 \ + "$BASE/gnn_bootstrap.py" --output "$RESOURCES/gnn_bootstrap.py" + curl --fail --silent --show-error --location --proto '=https' --tlsv1.2 \ + "$BASE/v5.1.0-source-manifest.json" --output "$RESOURCES/v5.1.0-source-manifest.json" + ( + cd "$RESOURCES" + echo "f638d4c01fe7de31e43d793e59bf382d0c3d1a82f365c59238334a2b40adfb37 gnn_bootstrap.py" | sha256sum --check --strict + echo "43b33c0b2b40386afa3f306fec4cc13bc1fd7c3b570fbf11d5008bad5c8e6b51 v5.1.0-source-manifest.json" | sha256sum --check --strict + ) + echo "bootstrap=$RESOURCES/gnn_bootstrap.py" >> "$GITHUB_OUTPUT" + echo "manifest=$RESOURCES/v5.1.0-source-manifest.json" >> "$GITHUB_OUTPUT" + - name: Provision the pinned GNN parser runtime id: runtime run: | @@ -99,4 +119,6 @@ jobs: - name: Release arms (including Python 3.12 full tests and GNN conformance) env: GNN_RUNTIME_PYTHON: ${{ steps.runtime.outputs.python }} + GNN_BOOTSTRAP: ${{ steps.resources.outputs.bootstrap }} + GNN_SOURCE_MANIFEST: ${{ steps.resources.outputs.manifest }} run: uv run python scripts/release_check.py --arm all diff --git a/TODO.md b/TODO.md index 9665c42..278efc8 100644 --- a/TODO.md +++ b/TODO.md @@ -103,8 +103,12 @@ source. Current scope: - [x] **B07:** one external interpreter-selection contract preserves venv launchers and separate NumPy environments without project-Python fallback. - [ ] **B08:** source and installed-origin/content admission controls plus - actual pinned parser/importer validation passed. Hosted reviewed-resource - delivery remains required; full native-ecosystem qualification is not claimed. + actual pinned parser/importer validation passed in their recorded scopes. + The workflow now prepares and forwards checksum-verified immutable producer + resources (`66d491f`, bootstrap `f638d4c`, v5.1.0 manifest `43b33c0`). Fresh + hosted/full-release acceptance remains required. A strict-origin replacement + needs producer qualification and a new public immutable identity; the private + candidate is not adopted and full native-ecosystem qualification is not claimed. - [x] **B09:** retain actual policy caps and ordered allowed policies. - [x] **B10:** preserve built-in integer/string identities, registry order, and established conflict priority through typed serialization. diff --git a/docs/gate.md b/docs/gate.md index 3b18055..5f5dd7c 100644 --- a/docs/gate.md +++ b/docs/gate.md @@ -17,6 +17,10 @@ dependency synchronization. Release selections also require the independently reviewed `GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` inputs described in [`gnn.md`](gnn.md). +Captured command failures retain their original stdout and stderr before the +nonzero exit is recorded. A failed pytest/coverage arm cannot hide its +diagnostics or become a passing receipt. + Measured wall times and test counts live in the generated [`_generated/gate-metrics.md`](_generated/gate-metrics.md), which shows the recorded before/after arm times and labels baseline workloads that are not @@ -85,7 +89,7 @@ contents. Protocol unit controls are not an actual build/install smoke. | Job | Arms | | --- | --- | | `test` (matrix: Python 3.11 only) | `--arm test-full` | -| `gnn-conformance` (Python 3.12; display name `gnn conformance (pinned)`) | `--arm all`, with `GNN_RUNTIME_PYTHON` set to the provisioned runtime | +| `gnn-conformance` (Python 3.12; display name `gnn conformance (pinned)`) | `--arm all`, with the provisioned `GNN_RUNTIME_PYTHON` and checksum-verified `GNN_BOOTSTRAP` / `GNN_SOURCE_MANIFEST` | The full suite therefore runs on both supported CI Python versions. The remaining release arms run in `gnn-conformance` on Python 3.12, alongside the @@ -94,11 +98,13 @@ runtime remains separate from the locked library environment because their NumPy requirements differ. PDF rendering is an explicit local `--arm render` selection, not part of `all` or CI. -Hosted resource delivery is still a release prerequisite: the workflow must -receive the reviewed bootstrap and exact full manifest as explicit -`GNN_BOOTSTRAP`/`GNN_SOURCE_MANIFEST` inputs. Do not insert machine-local -campaign paths, invent a published artifact URL, or waive admission when -these inputs are unavailable. +Before provisioning the parser runtime, the workflow downloads the reviewed +bootstrap and full v5.1.0 manifest from immutable producer resource commit +`66d491f86895443cf588011cc6f40c37b8bae8fd`, verifies both source-owned SHA-256 +digests, and forwards their paths to `all`. That delivery revision is not a +parser repin. Acquisition or digest failure stops the job before execution. +The bootstrap's known strict-origin limitation and the separate producer +qualification prerequisite are retained in [`gnn.md`](gnn.md). The workflow installs uv directly with `astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2` (`v10.3.3`, diff --git a/docs/gnn.md b/docs/gnn.md index df17f5b..8826d72 100644 --- a/docs/gnn.md +++ b/docs/gnn.md @@ -51,8 +51,20 @@ producer artifacts. The source-owned expected SHA-256 values are: Do not derive expected identity from the target package or replace complete content/module ownership with a version string or the five parser digests. -Artifact publication/acquisition is release-owner work; no public download -location is assumed here. +The hosted workflow acquires these two files from the published immutable +[producer resource revision `66d491f`](https://github.com/ActiveInferenceInstitute/Generalized_Notation_Notation/tree/66d491f86895443cf588011cc6f40c37b8bae8fd/interop), +checks both digests before use, and forwards their paths to the release gate. +The full manifest is for v5.1.0, not the separately published v5.0.3 manifest; +the resource revision does not change `specs/gnn-pin.json`. + +The frozen bootstrap has a known contextual origin-normalization defect: a +non-GitHub URL can be misclassified as the canonical repository identity. +Existing installed proof with the actual canonical HTTPS GitHub origin remains +valid only in its recorded scope; source-artifact proof remains +`vcs_verified=false`. Resource delivery does not repair or waive this defect. +Adopting a strict-origin replacement requires the producer's completed native +qualification and a newly published immutable resource identity. Do not adopt +an unpublished private candidate or modify the historical artifact. The cutover replaced the interim local reader. Until this change `specs/gnn-pin.json` pinned `v5.0.3` at `8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1`, a revision that @@ -102,9 +114,9 @@ to source. Exit codes are `0` pass, `1` conformance failure, and `2` unavailable required runtime/resources/origin or requested tag resolution. Missing prerequisites -are not passes. CI must separately provision the reviewed bootstrap and full -manifest alongside its pinned runtime before hosted acceptance; local source -proof does not supply those hosted inputs. See [`gate.md`](gate.md). +are not passes. CI provisions the checksum-verified reviewed bootstrap and full +manifest alongside its pinned runtime; this wiring is not itself hosted, +installed, or full-release acceptance. See [`gate.md`](gate.md). ## What the validation checks diff --git a/scripts/release_check.py b/scripts/release_check.py index edb3bc0..202f0d5 100644 --- a/scripts/release_check.py +++ b/scripts/release_check.py @@ -88,15 +88,23 @@ def _run( """Run one gate command without re-synchronizing the prepared locked environment.""" print("$", " ".join(command), flush=True) - return subprocess.run( - command, - cwd=cwd, - check=True, - text=True, - capture_output=capture, - env={**os.environ, "PYTHONUNBUFFERED": "1", "UV_NO_SYNC": "1"}, - stdin=subprocess.DEVNULL, - ) + try: + return subprocess.run( + command, + cwd=cwd, + check=True, + text=True, + capture_output=capture, + env={**os.environ, "PYTHONUNBUFFERED": "1", "UV_NO_SYNC": "1"}, + stdin=subprocess.DEVNULL, + ) + except subprocess.CalledProcessError as exc: + if capture: + if exc.stdout: + print(exc.stdout, end="", flush=True) + if exc.stderr: + print(exc.stderr, end="", file=sys.stderr, flush=True) + raise def _changed_paths() -> set[str]: diff --git a/tests/test_publication.py b/tests/test_publication.py index a8a9de1..ec124eb 100644 --- a/tests/test_publication.py +++ b/tests/test_publication.py @@ -109,18 +109,21 @@ def test_docs_link_checker_reports_broken_links_and_anchors(tmp_path): "[missing](nope.md)\n" "[anchor](b.md#nope)\n" "[escape](../../outside.md)\n" - "```\nfenced [fake](fake.md)\n```\n" - "[external](https://example.com/page)\n", + "```\nfenced [fake](fake.md)\n```\n", encoding="utf-8", ) (tmp_path / "b.md").write_text("# Title\n", encoding="utf-8") + external = Path("external.md") + (tmp_path / external).write_text( + "[external](https://example.com/page)\n", encoding="utf-8", + ) failures = docs_links.validate(tmp_path) messages = [message for issues in failures.values() for message in issues] assert any("nope.md" in message for message in messages) assert any("#nope" in message and "b.md" in message for message in messages) assert any("outside" in message for message in messages) assert not any("fake.md" in message for message in messages) - assert not any("example.com" in message for message in messages) + assert external not in failures assert not any("same-file anchor" in message for message in messages) diff --git a/tests/test_release_gate.py b/tests/test_release_gate.py index 5f1fb49..a57cdc9 100644 --- a/tests/test_release_gate.py +++ b/tests/test_release_gate.py @@ -10,8 +10,10 @@ from pathlib import Path import pytest +import yaml import scripts.release_check as gate +from blockference.gnn_source import BOOTSTRAP_SHA256, SOURCE_MANIFEST_SHA256 ROOT = Path(__file__).resolve().parents[1] @@ -96,3 +98,33 @@ def test_render_provenance_requires_the_pdf(tmp_path, monkeypatch): gate._render_artifact() +def test_workflow_delivers_reviewed_resources_before_release(): + """Keep immutable resource delivery and release-environment forwarding together.""" + workflow = yaml.safe_load((ROOT / ".github/workflows/ci.yml").read_text(encoding="utf-8")) + steps = workflow["jobs"]["gnn-conformance"]["steps"] + resources = next(step for step in steps if step.get("id") == "resources") + release = next(step for step in steps if "--arm all" in step.get("run", "")) + assert steps.index(resources) < steps.index(release) + script = resources["run"] + assert "66d491f86895443cf588011cc6f40c37b8bae8fd/interop" in script + assert f"{BOOTSTRAP_SHA256} gnn_bootstrap.py" in script + assert f"{SOURCE_MANIFEST_SHA256} v5.1.0-source-manifest.json" in script + assert script.count("sha256sum --check --strict") == 2 + assert script.index("sha256sum --check --strict") < script.index('>> "$GITHUB_OUTPUT"') + assert release["env"]["GNN_BOOTSTRAP"] == "${{ steps.resources.outputs.bootstrap }}" + assert release["env"]["GNN_SOURCE_MANIFEST"] == "${{ steps.resources.outputs.manifest }}" + assert release["env"]["GNN_RUNTIME_PYTHON"] == "${{ steps.runtime.outputs.python }}" + + +def test_failed_captured_command_keeps_real_diagnostics_and_exit(tmp_path, capsys): + command = [ + sys.executable, "-c", + "import sys; print('real failure detail'); " + "print('real stderr detail', file=sys.stderr); sys.exit(7)", + ] + with pytest.raises(subprocess.CalledProcessError) as caught: + gate._run(command, cwd=tmp_path, capture=True) + assert caught.value.returncode == 7 + captured = capsys.readouterr() + assert "real failure detail" in captured.out + assert "real stderr detail" in captured.err diff --git a/uv.lock b/uv.lock index a8a9563..8b7793a 100644 --- a/uv.lock +++ b/uv.lock @@ -1881,7 +1881,7 @@ wheels = [ [[package]] name = "mkdocs-material" -version = "9.8.0" +version = "9.8.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "babel" }, @@ -1896,9 +1896,9 @@ dependencies = [ { name = "pymdown-extensions" }, { name = "requests" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/b9/02/3c0df248819286810d8479b3a72d9531db0cc36c042fe1ab3985f137c664/mkdocs_material-9.8.0.tar.gz", hash = "sha256:1ed4c5edaf405a3fb62e55288b8fdff592971729361548b1ffa757bf9849fb81", size = 4094495, upload-time = "2026-10-24T09:50:16.181Z" } +sdist = { url = "https://files.pythonhosted.org/packages/e2/b2/dee93bf227b481e28ba4d800c322dffc41b16d524ae84ca8d85aa7ec3a81/mkdocs_material-9.8.1.tar.gz", hash = "sha256:cddae7d77bb98d1d347aa68ee252ab40926171a1b34ba8777c44e16de9629f00", size = 4160481, upload-time = "2026-11-07T13:05:04.482Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/c8/16/360f44c7702f27ff4670a647a16c72432291e311371d72b4c34a57e990e0/mkdocs_material-9.8.0-py3-none-any.whl", hash = "sha256:19304a7263c5700428227122b3b2699aa73f432c9de8816876adaec7d7293ce3", size = 9302245, upload-time = "2026-10-24T09:50:12.636Z" }, + { url = "https://files.pythonhosted.org/packages/70/05/a4011d6a6af86cd03059a5b165cd69a3695ef4bd7bd477c66befe399640a/mkdocs_material-9.8.1-py3-none-any.whl", hash = "sha256:2115af67ee680e1398bdd0ea02e517721e4bba88b342503a93f97ea8eb3de51c", size = 9302217, upload-time = "2026-11-07T13:05:00.747Z" }, ] [[package]] @@ -2133,7 +2133,7 @@ wheels = [ [[package]] name = "openai" -version = "3.45.0" +version = "3.46.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, @@ -2143,9 +2143,9 @@ dependencies = [ { name = "sniffio" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/de/ef/639821491538e8bb4c56f3367f00787e8aadc1665ce1598e7506bcb65663/openai-3.45.0.tar.gz", hash = "sha256:6cff2b5c7b463123fcb94d1bb7e4920e5fab9bb3ed4f837faa0d0bf1d6d6ea3b", size = 2386886, upload-time = "2026-11-04T02:24:10.931Z" } +sdist = { url = "https://files.pythonhosted.org/packages/34/b6/23cddcb571d6eafe7b4bb58c7e0a068076121b7b001b776179994cca6a03/openai-3.46.0.tar.gz", hash = "sha256:fb34cd8cab6809ad0aa8dc42493fa622aaa87c814fd8e67a6fb3fa1f1e5d952d", size = 2408622, upload-time = "2026-11-05T00:55:55.463Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/f5/ff/3ff596d5fc94d241a105777e3bf8c696ff949afa3eb04f1c09bd6d4c20b8/openai-3.45.0-py3-none-any.whl", hash = "sha256:b63aa90e3b7b57b501f2bba231a17976618aa133f457562ad84a5c6431fd0425", size = 2426748, upload-time = "2026-11-04T02:24:08.659Z" }, + { url = "https://files.pythonhosted.org/packages/f4/63/454e6faad68ac903e7669932db8d0a91c95dfca829ec9476e52045b17684/openai-3.46.0-py3-none-any.whl", hash = "sha256:7b650117e9bf539029bf880c2eff94a26f281394f6572284efa5d068d4b1c98e", size = 2438918, upload-time = "2026-11-05T00:55:53.301Z" }, ] [[package]] @@ -3036,27 +3036,27 @@ wheels = [ [[package]] name = "ruff" -version = "0.17.3" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/59/73/81f140c4edd9cc323de5478e6bbd3bbcfae9a82692df1a258de8cec6a6d2/ruff-0.17.3.tar.gz", hash = "sha256:a57049c8addb3662073859bb55a7ad35aa54f8a7c9ed268911d1333c5aadaaa9", size = 5339444, upload-time = "2026-10-27T00:34:05.914Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/9e/8c/083365310c4e79c842f25bf5a842facbd9b0c0ec336f96dffa5074fe723d/ruff-0.17.3-py3-none-linux_armv6l.whl", hash = "sha256:ab86b84cd9d05e56d329742c0cabdcbe2d1d56c98f4a04aab9b5b66196febfb4", size = 10216522, upload-time = "2026-10-27T00:33:29.822Z" }, - { url = "https://files.pythonhosted.org/packages/72/26/4b2edf31cfebe9605d8f6ed8f1d6f376d3a53d4c9a123e62661c64c440f0/ruff-0.17.3-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:e407b4a6852853a9a2cdce96963e94ad9775578bb44e7561a0f2829f3cc04b11", size = 10217786, upload-time = "2026-10-27T00:33:33.949Z" }, - { url = "https://files.pythonhosted.org/packages/a2/7e/537aba4b7f54397a374d2f6a6fc93e9c8015e18553f31a4a7b7dbced48b5/ruff-0.17.3-py3-none-macosx_11_0_arm64.whl", hash = "sha256:b75cc113b3aca388933d8296b667b1ac401a80317ea3074c9b0a66541199da29", size = 9440362, upload-time = "2026-10-27T00:33:35.784Z" }, - { url = "https://files.pythonhosted.org/packages/3d/66/283e39734f66c8a5ebaa93c22eb7b7515779a0b1d5a5c0ad20e05c0edb41/ruff-0.17.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ab5fa7ed5ce18554ea69d850ad162cbaa0c85fc47c08d83a569f806681c9a6ad", size = 10094281, upload-time = "2026-10-27T00:33:38.216Z" }, - { url = "https://files.pythonhosted.org/packages/21/4c/1ffc768497bd025a32c72152771e40c0b99bddc5cc6e4f50c7949a395346/ruff-0.17.3-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:c673c170e27834d1262e3a9c1e97bdc9b9c3b180c63d89173ce69747232474c1", size = 10022543, upload-time = "2026-10-27T00:33:40.181Z" }, - { url = "https://files.pythonhosted.org/packages/73/c3/f90db547301080fcb82c92abf914c8bd57b89911d9b65a6c4cc6b52d0635/ruff-0.17.3-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:6a754c0341bc9ca151b7b335988b3263921c08859f84ca219b70cee825571b6f", size = 10683921, upload-time = "2026-10-27T00:33:42.182Z" }, - { url = "https://files.pythonhosted.org/packages/e5/98/92d4a8a26c6c96cf1a5b34dd59036d8a71e52d650aab065c58867e964e63/ruff-0.17.3-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4590b9d86c0b1543ebb09094254e191cd43fe8edaf330baa035aab03da251532", size = 11373408, upload-time = "2026-10-27T00:33:44.19Z" }, - { url = "https://files.pythonhosted.org/packages/43/02/1f24d2e3064c9753926deeb901afa57777b37ee46799b09ddd7aee6e5145/ruff-0.17.3-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bbde18beccd98c29a227c63c99022e3443b99258e08326df6425dfe0443705ef", size = 10977469, upload-time = "2026-10-27T00:33:46.179Z" }, - { url = "https://files.pythonhosted.org/packages/f0/20/fecedea2209f574ab92033b344e01a7f0c2dc76c6d6d19a14c9f8141173f/ruff-0.17.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7fa4b0f931cdbcb8a52044f370a3eb429fb42eb88807b0e800fcaa98dd42b24e", size = 10577491, upload-time = "2026-10-27T00:33:48.233Z" }, - { url = "https://files.pythonhosted.org/packages/33/36/b93fdf0bc6f84f0cd487aadfb0354deb40013669ea35ac3d26855de1e959/ruff-0.17.3-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:39405f341deec934b4289634324ad695f72df2970f9121582872eaf5b722f0f5", size = 10608748, upload-time = "2026-10-27T00:33:50.284Z" }, - { url = "https://files.pythonhosted.org/packages/5d/b7/7d3f5f14145daead1efb0b9a8289ed1daa100f419d60774375951723ce00/ruff-0.17.3-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:68074094f55ca3d29ab19491f640282f7a84061c4c7977aa5094b968ca457e9a", size = 10075057, upload-time = "2026-10-27T00:33:52.074Z" }, - { url = "https://files.pythonhosted.org/packages/b0/ed/93ff7a5909ee56e2bd4b982deae9e0efb2724417874a90c9e41ad66c6dd7/ruff-0.17.3-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:27bb571ac78fef178fe5118d2827df95c2aae74a48fff2b15f6acd03af5ff5bb", size = 10022431, upload-time = "2026-10-27T00:33:54.061Z" }, - { url = "https://files.pythonhosted.org/packages/9b/07/a83b9eeec8c1c3c0e4eda15f06c3a91001bfd2687ea2f07b750719bf9712/ruff-0.17.3-py3-none-musllinux_1_2_i686.whl", hash = "sha256:029c37cbd3de48ca37aa12117bead2d065f15da17d66bf84e0d4274013705db2", size = 10394903, upload-time = "2026-10-27T00:33:56.158Z" }, - { url = "https://files.pythonhosted.org/packages/af/b2/05c39857c2526fcbebe46ad93a8dc97424656dfef14d3ef933abe1ffd331/ruff-0.17.3-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:692fdb46d0fd9c71e380947dc5fc72f2c3f881073bc1f739e4579376231affbe", size = 10799780, upload-time = "2026-10-27T00:33:58.204Z" }, - { url = "https://files.pythonhosted.org/packages/ec/d9/47171a16739eb7a353936b31c20cf54340531e68c9af7d72fd7a784e235d/ruff-0.17.3-py3-none-win32.whl", hash = "sha256:46539cb031b01fd29ae0a02142483c46640b233ee12bb1c1b690bffa1555d5ca", size = 9908481, upload-time = "2026-10-27T00:34:00.087Z" }, - { url = "https://files.pythonhosted.org/packages/d0/a0/f08c1631bfd81faa6a90eaf70c37c786c11bed2046302b56bb506c25e1a0/ruff-0.17.3-py3-none-win_amd64.whl", hash = "sha256:56b8ffb3f3b3cbccb8b76b71b38261b7ed982ef5d20f5b447b1b61a7f4949b24", size = 10341333, upload-time = "2026-10-27T00:34:02.099Z" }, - { url = "https://files.pythonhosted.org/packages/99/d5/4ad4ed31413c301430918e70d3d38ae6f097af0766cb9ab8c9d502b2a4d6/ruff-0.17.3-py3-none-win_arm64.whl", hash = "sha256:81fce74bcd6be0e9da7c67c7553fd0f1f12964a2052cd728ef917b937a5ca1d9", size = 9854332, upload-time = "2026-10-27T00:34:03.847Z" }, +version = "0.17.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/84/0e/3d154514b5bad104f7e1c13169c2d09aa9959fccdc06eb47610ccdfa83ed/ruff-0.17.4.tar.gz", hash = "sha256:f32d178b50e826e00f6c6c1be3f56333068acb9b67fe167143527fa9b81e890d", size = 5357750, upload-time = "2026-11-05T18:52:17.638Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e0/61/c83c78bbb6108f6c6270a106cf12b54175f4f42da088b9bb880f18e31289/ruff-0.17.4-py3-none-linux_armv6l.whl", hash = "sha256:2b08c4ff98dc234f4a3871a3105353b922fa875ea1073ca31001eb8c06bb4d89", size = 10252195, upload-time = "2026-11-05T18:51:36.594Z" }, + { url = "https://files.pythonhosted.org/packages/0a/12/dd158708378866e8b53e145a465dbc51a7cccb9fa197a74d67eaedde7234/ruff-0.17.4-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:13e781c3c5f663e7fba737eaaeb70dd943dd55171daf316afb25cd5268cfe0c7", size = 10266044, upload-time = "2026-11-05T18:51:39.502Z" }, + { url = "https://files.pythonhosted.org/packages/28/32/89a94a8eb11fd505a381ae6f04e190d038d9958695209dc1786ce5cfcda3/ruff-0.17.4-py3-none-macosx_11_0_arm64.whl", hash = "sha256:7ed2f416349944f908f9574215994602242b0836844eba48eec61473033afca0", size = 9432227, upload-time = "2026-11-05T18:51:41.968Z" }, + { url = "https://files.pythonhosted.org/packages/58/de/a392dc38b215798ae72e639d228b7f6c02d826a95d1c0ad7c4c0ee49ef5b/ruff-0.17.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8ea6e0017c785f7282092b11e46338e4ebed1b9e575ebf2e55a8a1eda968241a", size = 10136900, upload-time = "2026-11-05T18:51:44.562Z" }, + { url = "https://files.pythonhosted.org/packages/b7/8f/a880f60f42005f6ffdf58f77af34c7ee327000b5607f48a2f6a69d8b242c/ruff-0.17.4-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:7e061dcc0933c7031a616ac8d66ac540309b2aa21ab558101a8f53e9ac7a1185", size = 10051245, upload-time = "2026-11-05T18:51:46.7Z" }, + { url = "https://files.pythonhosted.org/packages/09/55/98844264108af7d5ec27ca3a9cd5a989094ca657a14599c4b69a537a0e9a/ruff-0.17.4-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f99e95a1515161138be3cbd1b06c06e739d8feb38ade35564556999fffc3686e", size = 10704341, upload-time = "2026-11-05T18:51:49.228Z" }, + { url = "https://files.pythonhosted.org/packages/28/a2/5edf97659c3ac7c73f978003bd314936f671037fdac6b978e9de3e4b2b65/ruff-0.17.4-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5f28cf0dd37cb172fa5a8d2e92e6ada3a9dbd0609f094ed24039929eef0b7524", size = 11394465, upload-time = "2026-11-05T18:51:51.534Z" }, + { url = "https://files.pythonhosted.org/packages/f2/8f/51371ae856b2bef4d15a044a574695fbc0f6ae63aafa42a2a22428070fb6/ruff-0.17.4-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6b21c771b296888e8a35c6f48555f4b44e4483f61675d6ed51810a5203469ce6", size = 10988262, upload-time = "2026-11-05T18:51:53.91Z" }, + { url = "https://files.pythonhosted.org/packages/af/1b/62874f14c7873f27c7887d2b1ea41de990e14ba9518801ffe8eacb5d51a6/ruff-0.17.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2cd025509b2e15721b426fc70fd946d71f43b3db3b08e946dfec2d696d911690", size = 10572829, upload-time = "2026-11-05T18:51:56.129Z" }, + { url = "https://files.pythonhosted.org/packages/98/30/860b9dae67432b16b88558a9cb2d3194825fa62838f8b9cc49f5d9022095/ruff-0.17.4-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:49b77f7b3921669466882a4881168801bdb06ec2cd83fb936049016cf5fdece1", size = 10617545, upload-time = "2026-11-05T18:51:58.172Z" }, + { url = "https://files.pythonhosted.org/packages/0f/08/781a4b41a1c83fd6e30fea610d6502a6f94e49cf94693fd37bdcbc6bfe11/ruff-0.17.4-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:e3b84eb74f260d1c2dbd236fd9d4c011d4fdd0a52bdf8aea57a10e3a1b71fca5", size = 10111955, upload-time = "2026-11-05T18:52:00.59Z" }, + { url = "https://files.pythonhosted.org/packages/3c/e9/94b1c7b677120f30839254518924f73a8157e9bcfa200edcd5796fecdb99/ruff-0.17.4-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:20e43d7a08e712e33067ba887e6574546c79bd4831596ce8f16803ac7ff9ad90", size = 10058355, upload-time = "2026-11-05T18:52:03.61Z" }, + { url = "https://files.pythonhosted.org/packages/27/5f/a825910b9f309336dc33cb8c0774126662c1d2f765699b3e0a1bd538d01f/ruff-0.17.4-py3-none-musllinux_1_2_i686.whl", hash = "sha256:0d1f4848fd2ec0499be4046db9b7dfcc952666885f00233cc7033515282556a8", size = 10415932, upload-time = "2026-11-05T18:52:06.264Z" }, + { url = "https://files.pythonhosted.org/packages/8b/b8/0796468423413ea4df1a6e2442ae26cf49b8f7dda0eecf246e0d5d0dde54/ruff-0.17.4-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:6007e7f3a0e55b0fbdb947af69cf24c21b4928df6be8ef3e767c69b5ccccf496", size = 10826033, upload-time = "2026-11-05T18:52:08.675Z" }, + { url = "https://files.pythonhosted.org/packages/b9/ab/d8e407669ffe5014429baf780c2df47e001968a6e4c17f615e2e7b13a9ba/ruff-0.17.4-py3-none-win32.whl", hash = "sha256:3971a78cba76298b284c8321e6d40d93045ed348bec5c369d85099efc97fb7cf", size = 9931993, upload-time = "2026-11-05T18:52:11.169Z" }, + { url = "https://files.pythonhosted.org/packages/bd/15/42af8a72d8946e3c9efd2bbf6641e462b6832783b0d043d63ef5b280ba7f/ruff-0.17.4-py3-none-win_amd64.whl", hash = "sha256:67c5a894fc054cf41f75f7afa24815de5a74329d97634126c2a1015740ff4e8c", size = 10292922, upload-time = "2026-11-05T18:52:13.436Z" }, + { url = "https://files.pythonhosted.org/packages/68/9e/f1dbffcfb8ff25dadbc21f87a8b73c3848abe4abada9d4b08ccef8bec40c/ruff-0.17.4-py3-none-win_arm64.whl", hash = "sha256:181ae38a9a8fb94925bf7d0794327b48d7fd7f4b50cfd84c0e999cc09ef8d131", size = 9889396, upload-time = "2026-11-05T18:52:15.549Z" }, ] [[package]] @@ -3262,52 +3262,52 @@ wheels = [ [[package]] name = "tornado" -version = "6.6" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/d0/02/5f549b1ad5da6267ed1e1fac2eef69257b1979cc812497002499b7895ff9/tornado-6.6.tar.gz", hash = "sha256:34c4aa916d7f2b2d5cadee2c6850f5a4a7f3d688cbf58399ea9bd3057af4abd5", size = 617998, upload-time = "2026-10-21T15:31:04.733Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/df/f5/d3e6f76b945f9812842db742d0708a3b6287e850e81be3ca10e290c103c6/tornado-6.6-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:01abf15429d64f04ccfafc238b191cc2c177108b7a331f4461707ad77198c8c2", size = 528326, upload-time = "2026-10-21T15:30:05.528Z" }, - { url = "https://files.pythonhosted.org/packages/30/69/b20cf3a8bf641ec792a5a6050aa153e8f120604f9c23471142de535113e5/tornado-6.6-cp311-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:11bb97c00981eb8254e55bd6a5ad960c983ae343fef8ae3ae5584cd1fb70236a", size = 529544, upload-time = "2026-10-21T15:30:07.126Z" }, - { url = "https://files.pythonhosted.org/packages/0f/f4/d9d8d3ac345aa9df3a132ad03bd443160c2ab24ad4003b4e8d6d5af06371/tornado-6.6-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4e152a3b2d3eae113b836d979823f7bb2320f7e334a84449729964921f374a4c", size = 530523, upload-time = "2026-10-21T15:30:08.478Z" }, - { url = "https://files.pythonhosted.org/packages/ad/82/1296ade1c14dee5a4906e5ca092997622ece7c4dc768c68ed9caaf895d1b/tornado-6.6-cp311-abi3-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e912d4c4babd04db6f34b25b748174a4a176debe86c8610beedf1815f9af7fdd", size = 530739, upload-time = "2026-10-21T15:30:09.98Z" }, - { url = "https://files.pythonhosted.org/packages/66/30/6ac1eab66c81af46dafd93c9b24bd311f82e199d9d7b8ce2a64a91b6a200/tornado-6.6-cp311-abi3-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:33aabe8a03d426cef4e0fe5669f0643cadd983b54957f1a7ac2789ec326e9644", size = 529738, upload-time = "2026-10-21T15:30:11.498Z" }, - { url = "https://files.pythonhosted.org/packages/24/b4/6c1f6aa1fd148e4d0f500a10cd0c9949e7bf385e161ff497c81de5b3ae4f/tornado-6.6-cp311-abi3-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:9aaf0e1c2fb9f046f30e2036b8d2060666399e8464d0a72769e43c754089567b", size = 527908, upload-time = "2026-10-21T15:30:13.298Z" }, - { url = "https://files.pythonhosted.org/packages/54/5b/67d3d452b1179bc9e265cebd381a56ab4cf2d7b2a54607aedd8d6e1ebc2e/tornado-6.6-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:61fc5513cea97720ab9bf54b04827ac0f4500c63f0b072b963d6145c798b4661", size = 530367, upload-time = "2026-10-21T15:30:15.183Z" }, - { url = "https://files.pythonhosted.org/packages/74/14/4e8e9a14f77bcafb2408634b2d4c8c676ad7a43bf8dac4ee2d48370698f9/tornado-6.6-cp311-abi3-musllinux_1_2_ppc64le.whl", hash = "sha256:31e1a0d5cd704d2fe8a008c1cc27a0e2b67269ca263630a27985dddc160b5537", size = 530456, upload-time = "2026-10-21T15:30:16.741Z" }, - { url = "https://files.pythonhosted.org/packages/56/12/e3ddef99a2089ccfc86f32bd3f39caaad87bee4868be1bacbf213a0b07a2/tornado-6.6-cp311-abi3-musllinux_1_2_riscv64.whl", hash = "sha256:74416e41e9bdf70fbc2fb242f6fbbc7a58ec11e59d39f15fc5a421ecb6845118", size = 529610, upload-time = "2026-10-21T15:30:18.031Z" }, - { url = "https://files.pythonhosted.org/packages/35/3d/62a692343d46b37e852e5078e0f6513534d925f70a04580072e3c127b129/tornado-6.6-cp311-abi3-musllinux_1_2_s390x.whl", hash = "sha256:8cdd69104ae9d705b3f04d2563aa96e357043e267a455802daae9a1e633a37c8", size = 529803, upload-time = "2026-10-21T15:30:19.326Z" }, - { url = "https://files.pythonhosted.org/packages/49/04/6c59a9413adfe4810f648a4dd9fdf476f13b0495f9cc25ef856b71f9ce1e/tornado-6.6-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:fc7c8a3263501fbe97518cd699101bc3c5f499a7dd4f75fc6cbb3bd9ee1db1f1", size = 529751, upload-time = "2026-10-21T15:30:20.826Z" }, - { url = "https://files.pythonhosted.org/packages/31/36/a1b3b84cd347ae43f982d3bf95628de6c6365668dba2543af47c6a1c888e/tornado-6.6-cp311-abi3-win32.whl", hash = "sha256:b54ca69ff93d0374efb083a12a1e9ec2dd2036e8496d197e0e8ef77b8d9135c3", size = 530643, upload-time = "2026-10-21T15:30:22.428Z" }, - { url = "https://files.pythonhosted.org/packages/b7/50/dc813fe35a672e14ee8bed8b5c634eeb343a05c98eb455318a169de24567/tornado-6.6-cp311-abi3-win_amd64.whl", hash = "sha256:48f26ed9d7beb64e5f06adc864524e581ab6d62ba8ff46eaaa1ac2d0e6d753fd", size = 530886, upload-time = "2026-10-21T15:30:23.975Z" }, - { url = "https://files.pythonhosted.org/packages/0d/71/62a9b9e980026d38874740d0a7c162f53eb0563f6a441e3aff84c48db7e8/tornado-6.6-cp311-abi3-win_arm64.whl", hash = "sha256:29114ffd4e4de869d390393df9e9a0f191065aae1a96f38a58d35e464c04a867", size = 530899, upload-time = "2026-10-21T15:30:25.264Z" }, - { url = "https://files.pythonhosted.org/packages/ac/4c/633e3568eb574df555d6ddd2dac44b7793a5c26cd63b444e653fcfb1d6ec/tornado-6.6-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:63fc8d243b52fd8dd9ed4ad02d0df08f2024f9aea632a433a8a6c91075076d44", size = 528432, upload-time = "2026-10-21T15:30:26.578Z" }, - { url = "https://files.pythonhosted.org/packages/37/eb/b525d1870ad28a56f47b664dd8fd3fab4f7ddd237c87c14e97248bf4762f/tornado-6.6-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8d4b85cac795bfc6a7f20ba81871abb8c2ae8fba019061b8a9ae1c2f97e29637", size = 532586, upload-time = "2026-10-21T15:30:28.027Z" }, - { url = "https://files.pythonhosted.org/packages/b7/35/909a33c253352346ca081a27ca66b45c1398468adf784b767597ca773c28/tornado-6.6-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e035c065edadfa696529d05eebcbeb25154c129b5aee6dbfb697a6abf5d4f697", size = 533641, upload-time = "2026-10-21T15:30:29.318Z" }, - { url = "https://files.pythonhosted.org/packages/6f/64/100202666d6e3d96288ab184827762415456c139798a15c962547f9fabf9/tornado-6.6-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:5b94e589ab855090c448b5c0937b3a75f1c1a604b7b36207e8236d209f720b9c", size = 533869, upload-time = "2026-10-21T15:30:30.882Z" }, - { url = "https://files.pythonhosted.org/packages/b1/e0/af3ed62bc15830d60328d5b4a1a9076b35ea0ba142cb17b1c1772cb15c59/tornado-6.6-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:1a394c8c9db9137f2a2b42869d9f7b91398fcf19da120d0dde4c4546172710f7", size = 532767, upload-time = "2026-10-21T15:30:32.273Z" }, - { url = "https://files.pythonhosted.org/packages/24/d7/1e2e1a6932eb62d63324b64dba2f62e6eaf79ad883dd209352c297b7848c/tornado-6.6-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0215d1df6e4b5e736ddad5adf0af4138cf7437fdd39c77c5e69768e37850a632", size = 530956, upload-time = "2026-10-21T15:30:33.746Z" }, - { url = "https://files.pythonhosted.org/packages/70/65/3b9a0e53d7a4c39f2ebe95486540fa8eeb67bfb6e8c437d603c00d35b128/tornado-6.6-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:4d711790e0a9576ad924d942c4607e4e401d697588ea6f30f6662824008a7add", size = 533372, upload-time = "2026-10-21T15:30:35.085Z" }, - { url = "https://files.pythonhosted.org/packages/44/48/90979cbfaa3ff941324a2605eb794af0f087c670cd99f18a69ab40498073/tornado-6.6-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:034a66bae0f55421d007803e2385d2a59707d8829b2f026373d42f08256e9922", size = 533425, upload-time = "2026-10-21T15:30:36.425Z" }, - { url = "https://files.pythonhosted.org/packages/bb/c4/ce743a86d91f85c255b77a4282eb5b2716b61e74430eb9d1df8578a539d2/tornado-6.6-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:5cb38483b077129056a94dd415a71d29ab4e42b46da894fee8b4657003f10b21", size = 532545, upload-time = "2026-10-21T15:30:37.789Z" }, - { url = "https://files.pythonhosted.org/packages/02/5e/a82131e35778540fc19139229d02aa8cf2453a8022e202be50c88f0f8ac3/tornado-6.6-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:46bbbd107efa37777ac4b83601866d19b4dbd5b770a7a9123582633d95959ad3", size = 532700, upload-time = "2026-10-21T15:30:39.336Z" }, - { url = "https://files.pythonhosted.org/packages/3a/09/6dac8c2c677c65d60b3d7dae94176dbfe392f314e7c8e2d709623edd6a26/tornado-6.6-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:b85e9d0263cdbc027b95947c8b873a7bc7fd6a08d16bfb4f5047350b0808e464", size = 532712, upload-time = "2026-10-21T15:30:40.698Z" }, - { url = "https://files.pythonhosted.org/packages/b2/ac/71e5776cbcdc3264e81aa6db28c69717ba50607a9eb8d5b766f11a4b020e/tornado-6.6-cp314-cp314t-win32.whl", hash = "sha256:4276eef0880e5fe4488e6799c2842f59af3b06637e9313ab4fb506f9c9c2d6cb", size = 530491, upload-time = "2026-10-21T15:30:42.115Z" }, - { url = "https://files.pythonhosted.org/packages/d8/0f/0b6a6908a5b5aa8320009dfdb84434b1cf160b577a00456e59ab9e6ea598/tornado-6.6-cp314-cp314t-win_amd64.whl", hash = "sha256:10d4af98c6df09f8429b1340ccaea3a72887b86f695dfb8056bda517c8115a00", size = 530780, upload-time = "2026-10-21T15:30:43.414Z" }, - { url = "https://files.pythonhosted.org/packages/3c/39/c152e1cc5371f75f5f9f0a4f44bf2dc9396be9407d384de7428446fb4651/tornado-6.6-cp314-cp314t-win_arm64.whl", hash = "sha256:b1f0ef20a5278854f5fdac31637bafadb055405df28b7fc945e54add12b172e3", size = 530781, upload-time = "2026-10-21T15:30:44.741Z" }, - { url = "https://files.pythonhosted.org/packages/0c/c5/f96c7d7a8895745bb37dfb6e6107e1ee40ad02a4b162d7d6c143644455ab/tornado-6.6-cp315-cp315t-macosx_10_15_universal2.whl", hash = "sha256:8f8e382da30fe042f27f27a871e21aefc2613870e5a41648de18446c72d6ea59", size = 528446, upload-time = "2026-10-21T15:30:46.112Z" }, - { url = "https://files.pythonhosted.org/packages/c0/dd/ab8f6500d274b9c55b025798eb54e92591bcff27515799bec443bd54e35a/tornado-6.6-cp315-cp315t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8c7a8a328396c2195454a2ecd9499512441bbce99505544a717e6a87d16ff6f9", size = 532774, upload-time = "2026-10-21T15:30:47.393Z" }, - { url = "https://files.pythonhosted.org/packages/87/23/b78e7d1bf329160b8157284005395421ea941864c16c7f04c3e48c98bcf9/tornado-6.6-cp315-cp315t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ca025bb0da81c294aef26f27427316df1525220820315f4bf32dc1e84a4d2232", size = 533872, upload-time = "2026-10-21T15:30:48.884Z" }, - { url = "https://files.pythonhosted.org/packages/e0/4f/ab66b614ad0bc9a219484be6bc2c002c8de9916a7b6c7b27fe6273838e5c/tornado-6.6-cp315-cp315t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:59c22ebc905ac2a267f8d9d8a878f86afbcbbde329d75c485f1422fc45a81b83", size = 534027, upload-time = "2026-10-21T15:30:50.157Z" }, - { url = "https://files.pythonhosted.org/packages/da/63/501fa15a36bace2f4b9158228cf922d606403261bf71c960c433ec3ca0a4/tornado-6.6-cp315-cp315t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f89802bc0bcd15f988d9325b4e6d2171bb04ea68d188732556335e10d3fd00bd", size = 532936, upload-time = "2026-10-21T15:30:51.45Z" }, - { url = "https://files.pythonhosted.org/packages/7f/b7/82d643f635f0300bda98613ca2660b4f3134b6fb594c6fddfa4de706806c/tornado-6.6-cp315-cp315t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:70043256d5958f9c655066153d23d60ea3e29bf9854f7fb75850e223c477758a", size = 531254, upload-time = "2026-10-21T15:30:52.865Z" }, - { url = "https://files.pythonhosted.org/packages/d4/53/92c40891a94750bc09257310af964bf25c59e3531d6199736c318baa864f/tornado-6.6-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:82b49495e3849d644b841ef33b35491160055997deaa93720ff647ef019421db", size = 533566, upload-time = "2026-10-21T15:30:54.15Z" }, - { url = "https://files.pythonhosted.org/packages/7e/88/b82f5c5efde731b88d839ad99cb6ace2a521f03bb6d7346d2de089c76da8/tornado-6.6-cp315-cp315t-musllinux_1_2_ppc64le.whl", hash = "sha256:07b2bcaa4bf447bdbfb664e4c28344226540db3f0ebccd74886528338a240765", size = 533567, upload-time = "2026-10-21T15:30:55.451Z" }, - { url = "https://files.pythonhosted.org/packages/02/2c/e9a7f5d0fca0bdbcd48b2d9c7884dd0b32669c9945d98bc6d303a80ecfea/tornado-6.6-cp315-cp315t-musllinux_1_2_riscv64.whl", hash = "sha256:c36b921374c302e54909bae17d9f354061d80e7ae7d8c94f73abbcc217866460", size = 532849, upload-time = "2026-10-21T15:30:56.729Z" }, - { url = "https://files.pythonhosted.org/packages/d0/f5/4ade737340ca6ce9c677ea0c2843591c8ad065d07f0913c28d922c7e078e/tornado-6.6-cp315-cp315t-musllinux_1_2_s390x.whl", hash = "sha256:7412d9e37aa9f7048e4b591f520a95f7a097278ffab15f1ddf3f5c2320cf6648", size = 532873, upload-time = "2026-10-21T15:30:58.067Z" }, - { url = "https://files.pythonhosted.org/packages/8e/04/6acdc937d0bb6189ddb34ceded517d7bd1c7b3bded5d4e1b3442160e6b6f/tornado-6.6-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:15bc95112b2d24b0bfaee9a004e3f974da929e33b4244a7f695a22f45b08a5e5", size = 532883, upload-time = "2026-10-21T15:30:59.395Z" }, - { url = "https://files.pythonhosted.org/packages/ab/27/0a766fac6b1cc629d96346329a0485287fd2857c51a887a3a154f2a69938/tornado-6.6-cp315-cp315t-win32.whl", hash = "sha256:f661c21117b875d612371f3eb243d0c69f56d9bdd6aee38b7c24453419dfe554", size = 530488, upload-time = "2026-10-21T15:31:00.77Z" }, - { url = "https://files.pythonhosted.org/packages/5c/80/3e4142570883da27b3f60ae82c638ac96e60997eac684740613557519c96/tornado-6.6-cp315-cp315t-win_amd64.whl", hash = "sha256:ee8853ab35da510dc952879ebd9995c82bc10ffb7925fd87930dc0d6916f4b39", size = 530777, upload-time = "2026-10-21T15:31:02.087Z" }, - { url = "https://files.pythonhosted.org/packages/17/57/4a85c617b6349962320b4afbe1386d5b05fd57218ee8ad6e82e0110ec9ee/tornado-6.6-cp315-cp315t-win_arm64.whl", hash = "sha256:7de62e2dfdf559fd7154d2b9aa58ff3d9cff8304ae0519341feb082618bc2a33", size = 530780, upload-time = "2026-10-21T15:31:03.425Z" }, +version = "6.6.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/64/2b/8ff2b41620cbba0eeb0862fed21dcaa5a2ad36c6dd9bb465f9ff7a147be2/tornado-6.6.1.tar.gz", hash = "sha256:28e6311402af59c8b02e3fa0f5e7d8eb465b25081381803b127d97e6a4395d5a", size = 623388, upload-time = "2026-11-09T21:09:22.71Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/77/d3/ef3a4d38d1a72c52ad07483ed760dbb93027d28f19c3a2d98148abdd63e1/tornado-6.6.1-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:a8d3e6acde5a80d13b13b5e4c7c226ca682f31d0a62b6c33cea038714bc2de1b", size = 533249, upload-time = "2026-11-09T21:08:22.475Z" }, + { url = "https://files.pythonhosted.org/packages/38/4d/c65ea949a3cdc185f1afac8c337074d4f2d029b48293d2db4d2c3dea4849/tornado-6.6.1-cp311-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:1b6ff57cc69b339f8feb9e7b567b0e0eacb16bfaf234159496623ef7a67ba640", size = 534470, upload-time = "2026-11-09T21:08:24.27Z" }, + { url = "https://files.pythonhosted.org/packages/03/ff/20911f85dd399b56761496e8138810e8608ea25f0912377f4205d52af853/tornado-6.6.1-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:da6ce2da215810d56539fa6cac77d9e27f4d8139c6868c53436b2fe933f43c79", size = 535446, upload-time = "2026-11-09T21:08:25.625Z" }, + { url = "https://files.pythonhosted.org/packages/be/70/a4a159dd4f1fef39ff8eadae655b133a85722b39087a89e21ce463af9832/tornado-6.6.1-cp311-abi3-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8cd28b2cacbe63d53e28a38546a3492b488417eeb3f7ecf10954476fc2508882", size = 535664, upload-time = "2026-11-09T21:08:27.191Z" }, + { url = "https://files.pythonhosted.org/packages/ed/d5/db70d5d23d3b4eaea0b26b710f28d2ca387bb44e68ccfede60ba3bbc2096/tornado-6.6.1-cp311-abi3-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:25b2619274bca77d0eb7b4d96dcf2d1142bb9bf172ad6a7491a1e1f82e6e48fa", size = 534660, upload-time = "2026-11-09T21:08:28.78Z" }, + { url = "https://files.pythonhosted.org/packages/f7/f6/0528ee039266902e707edd9996ee3ce7364dc1baf08bed585d8e6fb3ccd0/tornado-6.6.1-cp311-abi3-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:77dd6e0c659fdc45824e0746988ac5c060c2a9fee9b8cbbcdb999b3f29d3cd10", size = 532834, upload-time = "2026-11-09T21:08:30.432Z" }, + { url = "https://files.pythonhosted.org/packages/a6/bb/b733df2d487a78283080663bd6d96955121b58b6d445d9cb832607da9786/tornado-6.6.1-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:b62fded687e55acaf9e36c1230b006066a35b3f6df093ba1fd3b2ff592070e1d", size = 535289, upload-time = "2026-11-09T21:08:31.692Z" }, + { url = "https://files.pythonhosted.org/packages/a7/7c/c81cb83f2bbb5740fcba1eb83d794b6d6fab2063b16a475cc9039266091e/tornado-6.6.1-cp311-abi3-musllinux_1_2_ppc64le.whl", hash = "sha256:ecef88054d8a77878f61061ff67dfc5e1c17d1f7334890ab508b310e8e68ee46", size = 535382, upload-time = "2026-11-09T21:08:33.282Z" }, + { url = "https://files.pythonhosted.org/packages/8a/ae/c499da4cc8be1c1f31a5d8df2328f2aae091de2db13302ad5c20ed704ec4/tornado-6.6.1-cp311-abi3-musllinux_1_2_riscv64.whl", hash = "sha256:ca95e762df1ca761f330e3f2a034c15ac144569844b52527a5a9eca9f524c0f1", size = 534534, upload-time = "2026-11-09T21:08:34.57Z" }, + { url = "https://files.pythonhosted.org/packages/61/7c/6b163c9e58ca9df0c941bda9ba2dcabbd87ecb81c5fa546f54eeac689232/tornado-6.6.1-cp311-abi3-musllinux_1_2_s390x.whl", hash = "sha256:8cae3d8f2585be01670da9fd5010c61724c51b61ecd4c06820e95874739daf7c", size = 534728, upload-time = "2026-11-09T21:08:35.828Z" }, + { url = "https://files.pythonhosted.org/packages/18/11/b5107ac6a278387635d73d283e7ab5a5c76fb8ccf402efa57006ea25852f/tornado-6.6.1-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:6596f3e939962f13099ce8d1a96b83226e908ca369b193370a6efa84585a1601", size = 534676, upload-time = "2026-11-09T21:08:37.209Z" }, + { url = "https://files.pythonhosted.org/packages/65/df/0574c4479c565d9233def796afc9179fa840f41f8c240f740609f746da67/tornado-6.6.1-cp311-abi3-win32.whl", hash = "sha256:0f0f596a0dab6826aa21d103c7bc242e3fb7cfc99c5c3d44a35ba8c83abbdca4", size = 535565, upload-time = "2026-11-09T21:08:38.518Z" }, + { url = "https://files.pythonhosted.org/packages/36/57/35439a779582e3b19c98e799b6a41519fb3bdaa3a21b7a94ce4dd7b3b732/tornado-6.6.1-cp311-abi3-win_amd64.whl", hash = "sha256:5cb82ca38596e1350fceaf994f287847f82f7b8436380d36ba0937a03107d0ee", size = 535806, upload-time = "2026-11-09T21:08:39.892Z" }, + { url = "https://files.pythonhosted.org/packages/89/b8/2cb42845af01ea7e70ac23e6f6fe2f26b9b158bce186c6991c057c9abe1d/tornado-6.6.1-cp311-abi3-win_arm64.whl", hash = "sha256:58d2f47e7b54fded3407dbbbe4e59d29ca627f85bf6c0f21f0b151c6c7fc9c53", size = 535825, upload-time = "2026-11-09T21:08:41.339Z" }, + { url = "https://files.pythonhosted.org/packages/10/de/cfeae9e75c144ca22018ee3b858e343c1658d6edd2184f35d810ec1ef789/tornado-6.6.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:ed0bc5a1a9f6346e7bdadc106fa2d4c6e79d71d8b2df4366260ab3baf36a8399", size = 533356, upload-time = "2026-11-09T21:08:42.603Z" }, + { url = "https://files.pythonhosted.org/packages/3d/d8/7812a729c797fb8c15748c9a69faeaaa13630075cf9b76ba9f7fbcfb7f42/tornado-6.6.1-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:54c80f9bed0bf1533ecf5a90dc59651645622d62b0bcffa2692d108a1f794917", size = 537511, upload-time = "2026-11-09T21:08:43.84Z" }, + { url = "https://files.pythonhosted.org/packages/70/47/ebef304487feea6d8efb6a7d2642964ecb1f5cc785f687628e1d7cac4326/tornado-6.6.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:eb67ba2cbf598e842f14684eab029a5a4ba7ab587e8c4e40940a77ed0596b31e", size = 538566, upload-time = "2026-11-09T21:08:45.203Z" }, + { url = "https://files.pythonhosted.org/packages/a3/6a/87532e6745c415eb2daa9bc1c9c89c69ce9e8255b1c0bde9938f3299440b/tornado-6.6.1-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:d83bac141bd9360d8e995ec512097be19ead2e9213c3e7088510a036f3192b8d", size = 538793, upload-time = "2026-11-09T21:08:46.478Z" }, + { url = "https://files.pythonhosted.org/packages/e4/c7/26af60f71f7c32f19257bad58711500628f579edf1a2c3d8328ad15aae04/tornado-6.6.1-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:60aad449dbcebaa8d69bff50c6ba39858fab8d256e779a99bb30ebf6724b9b48", size = 537691, upload-time = "2026-11-09T21:08:47.975Z" }, + { url = "https://files.pythonhosted.org/packages/ba/9d/af233b8bf4311d3466099ab267eb595ec6f1655607d290dc7f706b6dbd6f/tornado-6.6.1-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b9ce0d6548bd73b1329075b247d3fdc61538922f558ee42059e08f5df53fc197", size = 535877, upload-time = "2026-11-09T21:08:49.76Z" }, + { url = "https://files.pythonhosted.org/packages/95/66/78e7583ce69f66e5177c65988a98373be2ab25c1d22405d274e037acbc58/tornado-6.6.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:ce5a18654f5d56d11400ab5d87103660e14deceab41818a06a42acc8dbbe427d", size = 538295, upload-time = "2026-11-09T21:08:51.221Z" }, + { url = "https://files.pythonhosted.org/packages/a3/3a/ad336d4994547cf268a3bd6d10f6ef691e1e888fc776940c0bfe02e8d85c/tornado-6.6.1-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:3298fce72c35f836eab4c4db8b960104ff1ea718033a6b5e236f04efe3a1b6e1", size = 538349, upload-time = "2026-11-09T21:08:52.761Z" }, + { url = "https://files.pythonhosted.org/packages/cf/cf/563d24516afd266f6b3c3f1c7ac15ad39b8668966d2bccce917c169ab0c0/tornado-6.6.1-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:0223e827cedf4e35ebb035e57a0d9974563cd043e3a53f8bb72a859b6f53777e", size = 537469, upload-time = "2026-11-09T21:08:54.279Z" }, + { url = "https://files.pythonhosted.org/packages/c8/ea/1705ff4014c8bad5d7045022647156cfebd6c7014886da47e13512d27c08/tornado-6.6.1-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:533185c89be3ffb01656c9425da4ff42587a3af784b37d39fe762e8fce3b2dbe", size = 537624, upload-time = "2026-11-09T21:08:55.648Z" }, + { url = "https://files.pythonhosted.org/packages/50/5d/421168e62c8b80e3ef88f80d642e9a7e5b1d0c6e8cd136d99064f663951c/tornado-6.6.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:fbaa022a49a27b65668592cf43b898ff3978cbe4e6926fdfe24dbef59053bd26", size = 537632, upload-time = "2026-11-09T21:08:57.797Z" }, + { url = "https://files.pythonhosted.org/packages/6a/b4/13b2f98a3141c152915fa3e69531a04bdc1cd7dd203f442136f3792a486f/tornado-6.6.1-cp314-cp314t-win32.whl", hash = "sha256:4bc6c60faf86162df25ba2ff5611d27b6ef8226de9d61c07a0fab53c169630a5", size = 535424, upload-time = "2026-11-09T21:08:59.145Z" }, + { url = "https://files.pythonhosted.org/packages/84/83/6d54c37b3e437ab0ff2bddd71249c6ea2a17051104dd2995cb4e181e95a7/tornado-6.6.1-cp314-cp314t-win_amd64.whl", hash = "sha256:71c16b382b22d3234913a3f74a1ea84bede197d11eb03871df17bb123088dfa5", size = 535715, upload-time = "2026-11-09T21:09:00.456Z" }, + { url = "https://files.pythonhosted.org/packages/d4/38/75419d8cd577b7c4f335f4c5e75f127af286545ad49047a73afffdf877fe/tornado-6.6.1-cp314-cp314t-win_arm64.whl", hash = "sha256:510c7261ed986ecd6f74edc1a13412759e7abc2e8be3a6c85e15f6c53e1f3c84", size = 535718, upload-time = "2026-11-09T21:09:01.783Z" }, + { url = "https://files.pythonhosted.org/packages/91/8b/96e460653f3e2ad83d70328414394132d73d5655047c692ce7b69ae2f6c0/tornado-6.6.1-cp315-cp315t-macosx_10_15_universal2.whl", hash = "sha256:01dc73e3697eb94d78c42e03931ab621da97d12fdfb6339e64ff5a934b220fcf", size = 533376, upload-time = "2026-11-09T21:09:03.097Z" }, + { url = "https://files.pythonhosted.org/packages/1a/1e/644bace0700e533235f01ffa68a7b5e3d6cc9eb7380e3929039d04b648b9/tornado-6.6.1-cp315-cp315t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:95bd4751357bef52aa655e236b9667ff054885de4b118e4ce9ba5c06e12ef5d0", size = 537696, upload-time = "2026-11-09T21:09:04.519Z" }, + { url = "https://files.pythonhosted.org/packages/e6/0a/afccc23d1ed71bcb1ce4a5b6e0f61f82c7a0b275f3b377ee7aee6680a565/tornado-6.6.1-cp315-cp315t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:29bce3190c2973fcd2171c95eeab8bf06d2f7a7eb107455ce3e4662c704aecdb", size = 538796, upload-time = "2026-11-09T21:09:05.956Z" }, + { url = "https://files.pythonhosted.org/packages/e5/24/69692f8ba851ed2738c2623eab592360d646f0a2e16b6deea16516aa8595/tornado-6.6.1-cp315-cp315t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:b777fbe0bdb2c4dc764aadf5f70e9b23b2e536c339d61c799d3ea1b575a7c285", size = 538951, upload-time = "2026-11-09T21:09:07.298Z" }, + { url = "https://files.pythonhosted.org/packages/00/82/234306b41b33600a470da7e595b8064b85e2f509f64f5c1d39387c0abbb8/tornado-6.6.1-cp315-cp315t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:15443805d6b7aa11610cc6c5be7e71b4a93369aeb2ca5a13c2def53a3af5ba45", size = 537861, upload-time = "2026-11-09T21:09:08.857Z" }, + { url = "https://files.pythonhosted.org/packages/5b/87/6d13a60c320c0379cbfa4c2520b4ba076780c33e6a01ba3073fff74b71db/tornado-6.6.1-cp315-cp315t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b77ab23d1520c807d11e703e79b020d3bc3676a0f5ebc8531f46d3fac8aecb2f", size = 536178, upload-time = "2026-11-09T21:09:10.424Z" }, + { url = "https://files.pythonhosted.org/packages/96/c7/e27f2a21e05d7c5aa9886db7368436e6436880b85349072988b4f62422e3/tornado-6.6.1-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:872249311539281c1e8a5d8d6f27f478bf705a9bd931bf374b6b31b05177dfda", size = 538491, upload-time = "2026-11-09T21:09:11.968Z" }, + { url = "https://files.pythonhosted.org/packages/f3/c7/1f981336039c51d81ee6f895e3412178edc409bd709e38767365c55c0daa/tornado-6.6.1-cp315-cp315t-musllinux_1_2_ppc64le.whl", hash = "sha256:08b808e8d3312c268f9fe1ffebfcfaaf342e7fe4ac40d219a7e1b58bac547d6f", size = 538491, upload-time = "2026-11-09T21:09:13.226Z" }, + { url = "https://files.pythonhosted.org/packages/5d/4f/7dafc65726778ac148b68c91920605892e84bf0ffcc02890aaf1a7d0ba8d/tornado-6.6.1-cp315-cp315t-musllinux_1_2_riscv64.whl", hash = "sha256:8d475f4053c693b5c1483eb4845824129b0b51c65712e736b3c2ea1c8f6080cd", size = 537775, upload-time = "2026-11-09T21:09:14.697Z" }, + { url = "https://files.pythonhosted.org/packages/a1/25/85c852307f9e49896b6dc5119f6a0131f5f6d97c478a687654c2c0c3f0f4/tornado-6.6.1-cp315-cp315t-musllinux_1_2_s390x.whl", hash = "sha256:e923e75c9d641cdb8bbac60070a2dccdb684fc555af2bff48b0eaded0f88c2dc", size = 537798, upload-time = "2026-11-09T21:09:15.946Z" }, + { url = "https://files.pythonhosted.org/packages/60/43/a37ec29b0f98c3c639da495e1d547d6c44c69a6727b9864cf149bf346433/tornado-6.6.1-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:a72f70b1aa630fa2106d39a025e2be75c272b7ec8233da94e2f407ea754cc32d", size = 537809, upload-time = "2026-11-09T21:09:17.265Z" }, + { url = "https://files.pythonhosted.org/packages/3b/d4/13973391071552e03acb308d93f6deb4fb535a769a6bbdafdb4cafcb2f91/tornado-6.6.1-cp315-cp315t-win32.whl", hash = "sha256:2fbfd2510b6163b189773155a8246c025cb260ccc7cd12ad18c36c54f5617bb9", size = 535422, upload-time = "2026-11-09T21:09:18.525Z" }, + { url = "https://files.pythonhosted.org/packages/19/94/c952b625904b63fdac5b747f2eeaca64ab5d36cdb8faff57effa57162d87/tornado-6.6.1-cp315-cp315t-win_amd64.whl", hash = "sha256:3c35091add5863feb9cf651851bb1b23592f1f9551b5dfed72837c83ea4e5b85", size = 535713, upload-time = "2026-11-09T21:09:20.061Z" }, + { url = "https://files.pythonhosted.org/packages/f8/62/8d0c0c42f3346f3f2455738d3bc689bbd8efba38abf7b90ab2b8294eae83/tornado-6.6.1-cp315-cp315t-win_arm64.whl", hash = "sha256:065bc741478b168df9baf754956a3010c04d1330bb45a84833d807c29e11b257", size = 535719, upload-time = "2026-11-09T21:09:21.317Z" }, ] [[package]] From 753684dccf0f600e0170fc56d11b7be8368343b0 Mon Sep 17 00:00:00 2001 From: Daniel Ari Friedman Date: Mon, 16 Nov 2026 18:26:24 -0800 Subject: [PATCH 3/4] Refresh generated software test collection inventory - Regenerate only the original full/fast/slow collection rows from the named producer. - Preserve all historical timings, coverage, baseline negatives and measured/scientific source identities; no measurement imports or rebaseline. --- docs/_generated/gate-metrics.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/_generated/gate-metrics.md b/docs/_generated/gate-metrics.md index e3a9d13..8fb1b0c 100644 --- a/docs/_generated/gate-metrics.md +++ b/docs/_generated/gate-metrics.md @@ -43,9 +43,9 @@ The baseline and current receipts are historical evidence. Timings include host | Selection | Collected tests | | --- | --- | -| full suite | 115 | -| fast (`-m "not slow"`) | 102 | -| slow (`-m slow`) | 13 | +| full suite | 309 | +| fast (`-m "not slow"`) | 292 | +| slow (`-m slow`) | 17 | Recorded run: 97 passed, 0 skipped. From 4b5e0f9c43f73b906590e4598a01840b0bf1d2d2 Mon Sep 17 00:00:00 2001 From: Daniel Ari Friedman Date: Tue, 17 Nov 2026 12:05:02 -0800 Subject: [PATCH 4/4] Cover the GNN source worker in process to restore the 90% floor Add 26 in-process tests for blockference.gnn_source: a hash-bound test-double bootstrap and a minimal double gnn package exercise the worker command, resource lookup, bootstrap hash/pin/session guards, source-path restoration, probe and importer checks, and the main exit codes (0/1/2) including refusal that keeps previous output. The module reaches 99% line coverage and the suite 91.97% on CPython 3.12 (92.01% on 3.11). Regenerate the gate-metrics collection counts. Co-Authored-By: Claude Opus 5.5 --- docs/_generated/gate-metrics.md | 4 +- tests/test_gnn_source_worker.py | 433 ++++++++++++++++++++++++++++++++ 2 files changed, 435 insertions(+), 2 deletions(-) create mode 100644 tests/test_gnn_source_worker.py diff --git a/docs/_generated/gate-metrics.md b/docs/_generated/gate-metrics.md index 8fb1b0c..18067d7 100644 --- a/docs/_generated/gate-metrics.md +++ b/docs/_generated/gate-metrics.md @@ -43,8 +43,8 @@ The baseline and current receipts are historical evidence. Timings include host | Selection | Collected tests | | --- | --- | -| full suite | 309 | -| fast (`-m "not slow"`) | 292 | +| full suite | 335 | +| fast (`-m "not slow"`) | 318 | | slow (`-m slow`) | 17 | Recorded run: 97 passed, 0 skipped. diff --git a/tests/test_gnn_source_worker.py b/tests/test_gnn_source_worker.py new file mode 100644 index 0000000..45419e0 --- /dev/null +++ b/tests/test_gnn_source_worker.py @@ -0,0 +1,433 @@ +"""In-process control-flow tests for ``blockference.gnn_source``. + +The admission cohort in ``test_gnn_source_admission.py`` drives the worker in +fresh external interpreters, which coverage cannot observe. These tests drive +the same functions in-process against a *test-double* bootstrap and a +test-double ``gnn`` package so the wrapper's own logic is exercised on every +run: hash binding, single-session guard, mid-operation bootstrap changes, pin +checks, sys.path restoration, JSON freezing, ok/qualified folding and the CLI +exit-code contract. + +Nothing here is an admission proof. The double is accepted only because each +test rebinds ``BOOTSTRAP_SHA256`` to the double's own digest; the reviewed +constant is never satisfied by these files, and real-producer verdicts remain +the job of the external cohort. +""" + +from __future__ import annotations + +import hashlib +import importlib.util +import json +import sys +from pathlib import Path +from types import SimpleNamespace + +import pytest + +import blockference.gnn_source as worker + +ROOT = Path(__file__).resolve().parents[1] + +_DOUBLE_BOOTSTRAP = """ +import json +from contextlib import contextmanager +from pathlib import Path +from types import SimpleNamespace + +UPSTREAM_REPOSITORY = "ActiveInferenceInstitute/Generalized_Notation_Notation" +CALLS = [] + + +def find_pin(repo_root): + path = Path(repo_root) / "specs" / "gnn-pin.json" + return path if path.is_file() else None + + +def read_pin(path): + raw = json.loads(Path(path).read_text(encoding="utf-8")) + repository = raw["repository"].removeprefix("https://github.com/") + return SimpleNamespace( + path=Path(path), schema=raw["schema"], repository=repository, tag=raw["tag"], + commit=raw["commit"], recorded=raw["recorded"], + spec_files=tuple(raw.get("spec_files", ())), raw=raw, + ) + + +def importer_variables(pin, *, repo_root, job, job_name): + return {"gnn_commit": pin.commit, "gnn_job_key": job, "gnn_job_name": job_name} + + +@contextmanager +def qualified_source(pin, *, manifest, manifest_sha256, package_root, origin_mode): + CALLS.append(("qualified_source", manifest, manifest_sha256, package_root, origin_mode)) + yield {"ok": True, "imports_verified": True, "origin_mode": origin_mode} + + +def check_importer(repo_root, **options): + CALLS.append(("check_importer", options)) + return dict(RESULT, source_qualification=dict(QUALIFICATION)) + + +RESULT = {"ok": True, "qualified": True} +QUALIFICATION = {"ok": True, "imports_verified": True} +""" + +_DOUBLE_GNN = { + "__init__.py": '__version__ = "double"\n', + "parsers/__init__.py": "", + "parsers/markdown_parser.py": """ +from types import SimpleNamespace + + +class MarkdownGNNParser: + def parse_file(self, path): + model = SimpleNamespace( + model_name="double", version="1", + variables=[SimpleNamespace(name="s", dimensions=(3, 1), data_type="categorical")], + connections=[SimpleNamespace( + source_variables=("s",), target_variables=("o",), connection_type="directed", + )], + ontology_mappings=[SimpleNamespace(variable_name="s", ontology_term="HiddenState")], + parameters=[SimpleNamespace(name="A", value=((1, 0), (0, 1)))], + raw_sections={"StateSpaceBlock": "", "Connections": ""}, + time_specification={1: object()}, + ) + return SimpleNamespace(success=True, errors=(), warnings=["w"], model=model) +""", + "validation/__init__.py": "", + "validation/semantic_validator.py": """ +class SemanticValidator: + def validate(self, text): + return {"valid": True, "length": len(text)} +""", + "validation/orientation.py": "def check_b_orientation(path):\n return ('ok', None)\n", + "validation/consistency_checker.py": "def check_consistency(path):\n return []\n", +} + + +def _drop_gnn_modules() -> None: + for name in [name for name in sys.modules if name == "gnn" or name.startswith("gnn.")]: + del sys.modules[name] + + +@pytest.fixture +def double(tmp_path, monkeypatch): + """Select a hash-bound test-double bootstrap and a consumer repository.""" + assert "gnn" not in sys.modules, "the project environment must not import GNN" + bootstrap = tmp_path / "double_bootstrap.py" + bootstrap.write_text(_DOUBLE_BOOTSTRAP, encoding="utf-8") + manifest = tmp_path / "manifest.json" + manifest.write_bytes(b'{"double": true}\n') + monkeypatch.setattr( + worker, + "BOOTSTRAP_SHA256", + hashlib.sha256(bootstrap.read_bytes()).hexdigest(), + ) + monkeypatch.setenv("GNN_BOOTSTRAP", str(bootstrap)) + monkeypatch.setenv("GNN_SOURCE_MANIFEST", str(manifest)) + repo = tmp_path / "consumer" + (repo / "specs").mkdir(parents=True) + (repo / "specs" / "gnn-pin.json").write_bytes((ROOT / "specs" / "gnn-pin.json").read_bytes()) + spec = repo / "specs" / "model.gnn.md" + spec.write_text("## ModelName\ndouble\n", encoding="utf-8") + source = tmp_path / "source" + for relative, text in _DOUBLE_GNN.items(): + path = source / "src" / "gnn" / relative + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding="utf-8") + yield SimpleNamespace( + bootstrap=bootstrap, manifest=manifest, repo=repo, spec=spec, source=source + ) + _drop_gnn_modules() + assert worker._BOOTSTRAP_NAME not in sys.modules + + +def test_worker_command_is_isolated_and_targets_this_file(): + command = worker.worker_command("/runtime/python", "probe", "--spec", "x.gnn.md") + assert command[:3] == ["/runtime/python", "-I", "-B"] + assert Path(command[3]) == Path(worker.__file__).resolve() + assert command[4:] == ["probe", "--spec", "x.gnn.md"] + + +def test_resource_must_be_selected(monkeypatch, tmp_path): + monkeypatch.delenv("GNN_SOURCE_MANIFEST", raising=False) + with pytest.raises(ValueError, match="GNN_SOURCE_MANIFEST must select"): + worker._resource("GNN_SOURCE_MANIFEST") + monkeypatch.setenv("GNN_SOURCE_MANIFEST", "relative/manifest.json") + monkeypatch.chdir(tmp_path) + assert worker._resource("GNN_SOURCE_MANIFEST") == tmp_path / "relative" / "manifest.json" + + +def test_unreviewed_bootstrap_bytes_are_never_executed(tmp_path, monkeypatch): + marker = tmp_path / "executed" + bootstrap = tmp_path / "unreviewed.py" + bootstrap.write_text(f"open({str(marker)!r}, 'w').write('x')\n", encoding="utf-8") + monkeypatch.setenv("GNN_BOOTSTRAP", str(bootstrap)) + with pytest.raises(ValueError, match="bootstrap-hash-mismatch"): + with worker._bootstrap(): + pass # pragma: no cover - the context must refuse before yielding + assert not marker.exists() + assert worker._BOOTSTRAP_NAME not in sys.modules + + +def test_one_bootstrap_session_at_a_time(double): + with worker._bootstrap() as module: + assert sys.modules[worker._BOOTSTRAP_NAME] is module + assert module.__file__ == str(double.bootstrap) + with pytest.raises(ValueError, match="already active"): + with worker._bootstrap(): + pass # pragma: no cover + # The refused nested entry must not tear down the active session. + assert sys.modules[worker._BOOTSTRAP_NAME] is module + assert worker._BOOTSTRAP_NAME not in sys.modules + + +def test_bootstrap_changed_during_operation_is_refused(double): + with pytest.raises(ValueError, match="bootstrap-changed"): + with worker._bootstrap(): + double.bootstrap.write_text(_DOUBLE_BOOTSTRAP + "\n# changed\n", encoding="utf-8") + assert worker._BOOTSTRAP_NAME not in sys.modules + + +def test_missing_pin_is_refused(double, tmp_path): + empty = tmp_path / "no-pin" + empty.mkdir() + with worker._bootstrap() as bootstrap: + with pytest.raises(ValueError, match="no GNN pin file"): + worker._read_pin(bootstrap, empty) + + +@pytest.mark.parametrize( + ("field", "value"), + [("commit", "0" * 40), ("tag", "v5.0.0"), ("repository", "https://github.com/other/gnn")], +) +def test_pin_must_match_the_reviewed_input(double, field, value): + pin_path = double.repo / "specs" / "gnn-pin.json" + pin = json.loads(pin_path.read_text(encoding="utf-8")) + pin[field] = value + pin_path.write_text(json.dumps(pin), encoding="utf-8") + with worker._bootstrap() as bootstrap: + with pytest.raises(ValueError, match="source-pin-mismatch"): + worker._read_pin(bootstrap, double.repo) + + +def test_pin_report_is_inspection_only(double): + payload = worker.pin_report(double.repo, job="gnn-conformance", job_name="Pinned") + assert payload["mode"] == "inspection" and payload["qualified"] is False + assert payload["runtime_python"] == sys.executable + assert payload["bootstrap_sha256"] == worker.BOOTSTRAP_SHA256 + assert payload["pin"]["path"] == "specs/gnn-pin.json" + assert payload["pin"]["commit"] == worker.PINNED_COMMIT + assert payload["pin"]["tag"] == "v5.1.0" + assert payload["pin"]["spec_files"] == [] + assert set(payload["pin"]["parser_files"]) >= {"src/gnn/__init__.py"} + assert payload["variables"] == { + "gnn_commit": worker.PINNED_COMMIT, + "gnn_job_key": "gnn-conformance", + "gnn_job_name": "Pinned", + } + assert "gnn" not in sys.modules + + +def test_jsonable_freezes_nested_values(): + marker = object() + value = {1: (1, 2.5, [True, None]), "nested": {"object": marker}} + assert worker._jsonable(value) == { + "1": [1, 2.5, [True, None]], + "nested": {"object": str(marker)}, + } + + +def test_source_path_is_explicit_and_restored(tmp_path): + before = sys.path[:] + with worker._source_path(None) as package_root: + assert package_root is None + assert sys.path == before + with worker._source_path(tmp_path / "source") as package_root: + assert package_root == tmp_path / "source" / "src" / "gnn" + assert sys.path[0] == str(tmp_path / "source" / "src") + assert sys.path == before + with pytest.raises(RuntimeError): + with worker._source_path(tmp_path / "source"): + raise RuntimeError("operation failed") + assert sys.path == before + + +def _record_qualified_source(monkeypatch, calls): + """Wrap the double's qualified_source as each session executes it.""" + original = worker._bootstrap + + def recording(): + context = original() + module = context.__enter__() + inner = module.qualified_source + + def wrapped(*args, **kwargs): + calls.append(kwargs) + return inner(*args, **kwargs) + + module.qualified_source = wrapped + return _Entered(context, module) + + monkeypatch.setattr(worker, "_bootstrap", recording) + + +class _Entered: + def __init__(self, context, module): + self._context, self._module = context, module + + def __enter__(self): + return self._module + + def __exit__(self, *exc): + return self._context.__exit__(*exc) + + +def test_probe_returns_frozen_json_from_one_qualified_lifetime(double, monkeypatch): + calls: list[dict] = [] + _record_qualified_source(monkeypatch, calls) + before = sys.path[:] + payload = worker.probe(double.repo, double.spec, source_root=double.source) + assert sys.path == before + assert calls == [ + { + "manifest": double.manifest.read_bytes(), + "manifest_sha256": worker.SOURCE_MANIFEST_SHA256, + "package_root": double.source.absolute() / "src" / "gnn", + "origin_mode": "source", + } + ] + assert payload["source_qualification"] == { + "ok": True, + "imports_verified": True, + "origin_mode": "source", + } + assert payload["gnn_version"] == "double" + parser = payload["parser"] + assert parser["success"] is True and parser["errors"] == [] and parser["warnings"] == ["w"] + assert parser["variables"] == [ + {"name": "s", "dimensions": [3, 1], "data_type": "categorical"}, + ] + assert parser["connections"] == [{"sources": ["s"], "targets": ["o"], "type": "directed"}] + assert parser["ontology_mappings"] == [{"variable": "s", "term": "HiddenState"}] + assert parser["parameters"] == {"A": [[1, 0], [0, 1]]} + assert parser["sections"] == ["Connections", "StateSpaceBlock"] + assert set(parser["time_specification"]) == {"1"} + assert payload["semantic"] == {"valid": True, "length": len(double.spec.read_text())} + assert payload["orientation"] == ["ok", None] + assert payload["consistency"] == [] + # Only primitive data escapes the admission boundary. + assert json.loads(json.dumps(payload)) == payload + + +def test_installed_probe_never_falls_back_to_source(double, monkeypatch): + if importlib.util.find_spec("gnn") is not None: + pytest.skip("this environment provides an importable gnn; installed-mode refusal is moot") + calls: list[dict] = [] + _record_qualified_source(monkeypatch, calls) + monkeypatch.setenv("GNN_ROOT", str(double.source)) + with pytest.raises(ImportError): + worker.probe(double.repo, double.spec) + assert calls[0]["origin_mode"] == "installed" and calls[0]["package_root"] is None + assert "gnn" not in sys.modules + + +def _set_check_result(monkeypatch, result, qualification): + original = worker._bootstrap + + def selecting(): + context = original() + module = context.__enter__() + module.RESULT = result + module.QUALIFICATION = qualification + return _Entered(context, module) + + monkeypatch.setattr(worker, "_bootstrap", selecting) + + +@pytest.mark.parametrize( + ("ok", "qualified", "expected"), + [(True, True, True), (True, False, False), (False, True, False)], +) +def test_check_importer_requires_ok_and_qualified(double, monkeypatch, ok, qualified, expected): + _set_check_result( + monkeypatch, + {"ok": ok, "qualified": qualified}, + {"ok": True, "imports_verified": True}, + ) + payload = worker.check_importer(double.repo, source_root=double.source) + assert payload["ok"] is expected + assert payload["runtime_python"] == sys.executable + + +def test_main_inspect_publishes_output(double, tmp_path, capsys): + output = tmp_path / "out" / "inspect.json" + code = worker.main(["inspect", "--repo", str(double.repo), "--output", str(output)]) + assert code == 0 + written = output.read_text(encoding="utf-8") + assert capsys.readouterr().out == written + assert json.loads(written)["mode"] == "inspection" + + +def test_main_probe_requires_a_spec(double): + with pytest.raises(SystemExit) as raised: + worker.main(["probe", "--repo", str(double.repo)]) + assert raised.value.code == 2 + + +def test_main_probe_success(double, capsys): + code = worker.main( + [ + "probe", + "--repo", + str(double.repo), + "--spec", + str(double.spec), + "--source-root", + str(double.source), + ] + ) + assert code == 0 + assert json.loads(capsys.readouterr().out)["parser"]["success"] is True + + +@pytest.mark.parametrize( + ("result", "qualification", "code"), + [ + ({"ok": True, "qualified": True}, {"ok": True, "imports_verified": True}, 0), + ({"ok": False, "qualified": True}, {"ok": True, "imports_verified": True}, 1), + ({"ok": False, "qualified": False}, {"ok": False, "imports_verified": False}, 2), + ({"ok": True, "qualified": False}, {"ok": True, "imports_verified": False}, 2), + ], +) +def test_main_check_exit_codes(double, monkeypatch, capsys, result, qualification, code): + _set_check_result(monkeypatch, result, qualification) + assert worker.main(["check", "--repo", str(double.repo), "--job", "gnn-conformance"]) == code + assert json.loads(capsys.readouterr().out)["ok"] is (code == 0) + + +def test_main_refusal_keeps_previous_output(tmp_path, monkeypatch, capsys): + monkeypatch.delenv("GNN_BOOTSTRAP", raising=False) + output = tmp_path / "previous.json" + output.write_bytes(b"retain") + assert worker.main(["inspect", "--repo", str(tmp_path), "--output", str(output)]) == 2 + captured = capsys.readouterr() + assert captured.out == "" + assert "gnn operation not run: source-unavailable" in captured.err + assert output.read_bytes() == b"retain" + + +def test_main_reports_a_coded_refusal(tmp_path, monkeypatch, capsys): + class Coded(ValueError): + code = "source-content-mismatch" + + def refuse(*args, **kwargs): + raise Coded("changed member") + + monkeypatch.setattr(worker, "probe", refuse) + spec = tmp_path / "x.gnn.md" + assert worker.main(["probe", "--repo", str(tmp_path), "--spec", str(spec)]) == 2 + assert "gnn operation not run: source-content-mismatch: changed member" in ( + capsys.readouterr().err + )