Skip to content

Commit d6599fa

Browse files
authored
Merge pull request #33 from ActiveInferenceInstitute/work/aii-blockference-integration-20261115
Harden GNN admission, package boundaries and artifact validation
2 parents 869d84a + 4b5e0f9 commit d6599fa

73 files changed

Lines changed: 4780 additions & 1440 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/AGENTS.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,14 @@ The workflow installs `uv.lock`, then calls the arms of
55
contains only Python 3.11 and runs `--arm test-full`. The `gnn-conformance` job
66
(display name `gnn conformance (pinned)`) runs `--arm all`
77
on Python 3.12 with `GNN_RUNTIME_PYTHON` set to the separate runtime provisioned from `specs/gnn-pin.json`.
8-
There is no separate `gate` job. Pinned conformance always runs in the `gnn`
9-
arm, where the shared `python -m gnn.importers check --repo .` reads the pin and
10-
the pointer, and `scripts/validate_gnn_spec.py --verify-tag-remote` checks the
11-
pinned v5.1.0 tag resolves to commit `75c834bd` and verifies the parser digests
12-
before parsing; missing runtime dependencies must fail, never skip. PDF rendering remains
8+
There is no separate `gate` job. The `gnn` arm checks exporter drift, then
9+
`scripts/validate_gnn_spec.py --verify-tag-remote` owns deep conformance and the
10+
shared pin/pointer/workflow/job check through qualified external workers.
11+
Require independently reviewed `GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` job
12+
inputs and complete content/module/installed-origin admission through exit.
13+
The workflow downloads both from the immutable producer resource revision and
14+
verifies their source-owned SHA-256 digests before use; never invent download
15+
URLs or weaken admission. Missing prerequisites fail, never skip. PDF rendering remains
1316
an explicit local `--arm render` selection. The workflow uses pinned
1417
`astral-sh/setup-uv` directly, not the Institute composite; see
1518
[`../docs/gate.md`](../docs/gate.md) for the exact action and command map.

‎.github/GNN.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,21 @@
77
(`75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf`) and records SHA-256 digests for
88
the five parser files under `src/gnn/`.
99

10-
The job installs that commit into a separate Python 3.12 runtime, then invokes
11-
the canonical release gate with `--arm all` and `GNN_RUNTIME_PYTHON` set to that runtime. Its `gnn`
12-
arm runs the estate's shared reader,
13-
`python -m gnn.importers check --repo . --require-pointer --workflow
14-
.github/workflows/ci.yml --job gnn-conformance`, from that runtime, then the
15-
offline drift check and the deep pinned-parser conformance check. The reader
16-
owns pin discovery and validation, and reports a pointer that fails to name the
17-
pin file, the pinned revision, the workflow or the job. A missing runtime
18-
fails instead of skipping conformance. See
10+
The job selects the canonical release gate with `--arm all` and a separate
11+
`GNN_RUNTIME_PYTHON`. It must also receive independently reviewed
12+
`GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` resources before hosted acceptance.
13+
Within the `gnn` arm, exporter drift is checked first; the project validator
14+
then owns deep conformance and the producer's syntax/pointer/workflow/job
15+
check in separate isolated qualified lifetimes. The shared producer remains
16+
authoritative for pin discovery and validation. Missing resources, runtime,
17+
installed provenance, or exit revalidation fail rather than skip. See
1918
[`docs/gate.md`](../docs/gate.md) for the complete job and arm map, and
2019
[`docs/gnn.md`](../docs/gnn.md) for standalone validation commands.
2120

22-
The validator checks that the resolved `gnn.__version__` matches the pin tag,
23-
verifies the installed parser file digests, parses `specs/gridworld_3x3.gnn.md`
24-
with the pinned `MarkdownGNNParser`, and compares the declared parameters and the `A`,
21+
Independent full-package content and actual module ownership are admitted
22+
before target GNN execution and revalidated at verdict exit. The validator
23+
also checks version and recorded parser hashes, parses the committed document
24+
with the pinned `MarkdownGNNParser`, and compares declared parameters and `A`,
2525
`B`, `C`, `D`, and `E` matrices against the runtime model built by
2626
`blockference.gnn`; it also requires the pinned semantic validator, the
2727
B-orientation check, and the consistency checker to report no errors or

‎.github/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,9 @@ arms of the canonical gate in [`scripts/release_check.py`](../scripts/release_ch
8282
* the Python 3.12 `gnn-conformance` job (display name
8383
`gnn conformance (pinned)`) runs `--arm all` with `GNN_RUNTIME_PYTHON` set to a
8484
separate pinned runtime provisioned from `specs/gnn-pin.json`.
85+
Independently reviewed `GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` inputs must
86+
also be delivered before hosted acceptance; source-only local proof does
87+
not establish installed provenance or provide those hosted artifacts.
8588

8689
The arms cover Ruff linting, repository-wide Markdown link/anchor validation,
8790
mypy, the test suite, notebook hygiene and execution, real pipeline and CLI

‎.github/workflows/README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,13 @@ release gate in two jobs:
1010

1111
The second job retains the display name `gnn conformance (pinned)` and installs
1212
the revision in [`../../specs/gnn-pin.json`](../../specs/gnn-pin.json) into a
13-
separate runtime; its `gnn` arm then calls the shared
14-
`python -m gnn.importers check --repo .` from that runtime. The full suite runs on both Python versions; all other release
15-
arms run with conformance on Python 3.12. Missing pinned-runtime validation
16-
fails the gate. There is no separate `gate` job, and PDF rendering remains an
17-
explicit local arm.
13+
separate runtime. Its `gnn` arm invokes the project validator for guarded deep
14+
conformance and the shared importer check. Independently reviewed bootstrap
15+
and full-manifest job inputs must be delivered before hosted acceptance;
16+
no machine-local path or invented publication URL substitutes for them.
17+
The full suite is selected on both Python versions; other release arms run
18+
on Python 3.12. Missing prerequisites fail. There is no separate `gate` job;
19+
PDF rendering remains an explicit local arm.
1820

1921
The workflow uses pinned `astral-sh/setup-uv` directly, not the Institute
2022
composite. [`../../docs/gate.md`](../../docs/gate.md) is authoritative for the

‎.github/workflows/ci.yml‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,10 @@ jobs:
5757
# Validates the committed GNN specification with the parser pinned in
5858
# specs/gnn-pin.json. The pinned revision is installed into a separate runtime
5959
# because the GNN distribution requires numpy>=2 while this package
60-
# resolves numpy 1.x. The gnn arm runs the shared `python -m gnn.importers
61-
# check` from that runtime, and the validator verifies the installed parser
62-
# file digests against the pin record before parsing.
60+
# resolves numpy 1.x. The project validator owns both guarded conformance
61+
# and shared importer checks. Independently reviewed immutable resources are
62+
# downloaded and SHA-256 checked before release execution; parser-file
63+
# digests alone are not complete source or installed-origin admission.
6364
name: gnn conformance (pinned)
6465
runs-on: ubuntu-latest
6566

@@ -80,6 +81,26 @@ jobs:
8081
- name: Install locked package and development dependencies
8182
run: uv sync --locked --extra dev --python 3.12
8283

84+
- name: Prepare reviewed GNN admission resources
85+
id: resources
86+
run: |
87+
set -euo pipefail
88+
# Resource delivery revision, not the parser revision in specs/gnn-pin.json.
89+
BASE="https://raw.githubusercontent.com/ActiveInferenceInstitute/Generalized_Notation_Notation/66d491f86895443cf588011cc6f40c37b8bae8fd/interop"
90+
RESOURCES="$RUNNER_TEMP/gnn-resources"
91+
mkdir -p "$RESOURCES"
92+
curl --fail --silent --show-error --location --proto '=https' --tlsv1.2 \
93+
"$BASE/gnn_bootstrap.py" --output "$RESOURCES/gnn_bootstrap.py"
94+
curl --fail --silent --show-error --location --proto '=https' --tlsv1.2 \
95+
"$BASE/v5.1.0-source-manifest.json" --output "$RESOURCES/v5.1.0-source-manifest.json"
96+
(
97+
cd "$RESOURCES"
98+
echo "f638d4c01fe7de31e43d793e59bf382d0c3d1a82f365c59238334a2b40adfb37 gnn_bootstrap.py" | sha256sum --check --strict
99+
echo "43b33c0b2b40386afa3f306fec4cc13bc1fd7c3b570fbf11d5008bad5c8e6b51 v5.1.0-source-manifest.json" | sha256sum --check --strict
100+
)
101+
echo "bootstrap=$RESOURCES/gnn_bootstrap.py" >> "$GITHUB_OUTPUT"
102+
echo "manifest=$RESOURCES/v5.1.0-source-manifest.json" >> "$GITHUB_OUTPUT"
103+
83104
- name: Provision the pinned GNN parser runtime
84105
id: runtime
85106
run: |
@@ -98,4 +119,6 @@ jobs:
98119
- name: Release arms (including Python 3.12 full tests and GNN conformance)
99120
env:
100121
GNN_RUNTIME_PYTHON: ${{ steps.runtime.outputs.python }}
122+
GNN_BOOTSTRAP: ${{ steps.resources.outputs.bootstrap }}
123+
GNN_SOURCE_MANIFEST: ${{ steps.resources.outputs.manifest }}
101124
run: uv run python scripts/release_check.py --arm all

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ coverage.xml
4343

4444
# Generated artefacts (commit on demand)
4545
result.csv
46+
ignored.csv
4647
*.csv.bak
4748
results/
4849
output/

‎AGENTS.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,17 @@ The grid-world model is declared in `specs/gridworld_3x3.gnn.md` (Generalized
2424
Notation Notation) and generated from the implementation by
2525
`blockference.gnn.render_spec`; `uv run python scripts/export_gnn_spec.py
2626
--check` fails when the committed document drifts. The upstream parser is
27-
pinned in `specs/gnn-pin.json` (GNN v5.1.0, commit `75c834bd8`), and
28-
`python -m gnn.importers check --repo .` reads that pin and the `.github/GNN.md`
29-
pointer while `scripts/validate_gnn_spec.py` parses the document with that
30-
revision, builds the runtime model from the declared parameters, and requires the
31-
declared matrices to match. Do not add a second pin reader: the shared reader is
32-
upstream. Both checks need an external runtime (`GNN_ROOT` or
33-
`GNN_RUNTIME_PYTHON`); the required `gnn-conformance` CI job provisions one from
34-
the pin and runs `scripts/release_check.py --arm gnn`. Do not
35-
hand-edit `specs/gridworld_3x3.gnn.md`: change the model or fixture in
27+
pinned in `specs/gnn-pin.json` (GNN v5.1.0, commit `75c834bd8`).
28+
`scripts/validate_gnn_spec.py` owns both deep conformance and the shared
29+
pin/pointer/workflow/job check through `blockference/gnn_source.py`.
30+
Require the selected separate interpreter plus independently reviewed
31+
`GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` resources. Complete source/module
32+
admission must remain active through verdict exit; metadata inspection alone
33+
is not qualification. Never add a local pin reader or an unchecked direct
34+
`-m gnn.importers` path. Installed provenance and source-artifact proof remain
35+
distinct. Hosted resource delivery is a release prerequisite, not an assumed
36+
published artifact. The required `gnn-conformance` job runs the `gnn` arm.
37+
Do not hand-edit `specs/gridworld_3x3.gnn.md`: change the model or fixture in
3638
`blockference/` and regenerate with `scripts/export_gnn_spec.py`. See
3739
`docs/gnn.md`.
3840

‎GRTs/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,10 @@ The optional OpenAI provider is selected explicitly with `--provider openai` and
1515
configured by the caller; there are no implicit global paths or provider instances. Offline
1616
tests and release gates never make network requests. A provider response is research input,
1717
not a software-integrity or scientific-validity verdict; preserve its provenance separately.
18+
19+
An explicit `Path` corpus means a readable regular UTF-8 file. It is admitted
20+
before workspace preparation or optional provider construction; missing,
21+
directory, broken-link, unreadable, and invalid-UTF-8 inputs fail without
22+
changing request/data/report sentinels. `None` selects the built-in corpus.
23+
Existing readable filename strings retain file behavior; other strings remain
24+
literal text, including empty or long text. No provider fallback is inferred.

‎GRTs/agents.py‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,19 +52,31 @@ def prepare(self) -> None:
5252
self.research_data.write_text("", encoding="utf-8")
5353

5454

55+
def _read_corpus_file(path: Path) -> str:
56+
if path.is_dir():
57+
raise IsADirectoryError(f"corpus must be a readable UTF-8 file: {path}")
58+
if not path.is_file():
59+
raise FileNotFoundError(f"corpus file not found: {path}")
60+
return path.read_text(encoding="utf-8")
61+
62+
5563
class OfflineCorpusProvider:
56-
"""Deterministic provider that answers from a local text corpus."""
64+
"""Use readable explicit Paths, existing filename strings, or literal/default text."""
5765

5866
def __init__(self, corpus: str | Path | None = None) -> None:
5967
if corpus is None:
6068
self.corpus = (
6169
"Active inference links observations, beliefs, actions, and expected free energy."
6270
)
71+
elif isinstance(corpus, Path):
72+
self.corpus = _read_corpus_file(corpus)
6373
else:
6474
corpus_path = Path(corpus)
65-
self.corpus = (
66-
corpus_path.read_text(encoding="utf-8") if corpus_path.is_file() else str(corpus)
67-
)
75+
try:
76+
is_file = corpus_path.is_file()
77+
except (OSError, ValueError):
78+
is_file = False
79+
self.corpus = _read_corpus_file(corpus_path) if is_file else corpus
6880

6981
def complete(self, prompt: str) -> str:
7082
"""Return stable corpus sentences selected by prompt terms."""
@@ -182,6 +194,8 @@ def build_provider(
182194
if name == "offline":
183195
return OfflineCorpusProvider(corpus)
184196
if name == "openai":
197+
if isinstance(corpus, Path):
198+
_read_corpus_file(corpus)
185199
return OpenAIProvider(model=model, timeout=timeout)
186200
raise ValueError("provider must be 'offline' or 'openai'")
187201

‎GRTs/data3/README.md‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,18 @@
11
# `GRTs/data3/` — shared working corpus
22

3-
Files in this folder are **the agents' communication channel**. The
4-
LangChain agents in `GRTs/agents.py` read and write here.
3+
These checked-in files are retained historical corpus/workspace material, not
4+
a live LangChain persona protocol. Current runtime locations come from an
5+
explicit `ResearchWorkspace(root)`.
56

6-
| File | Read by | Written by | Purpose |
7-
|-------------------------------|-----------------|--------------------|--------------------------------------------|
8-
| `O_Project_description.txt` | both | human (seed) | The original task description. |
9-
| `requests.txt` | Research Joe | Professor Karl | Outstanding research questions. |
10-
| `research_data.txt` | Professor Karl | Research Joe | Gathered evidence / sources. |
11-
| `report.txt` | human | Professor Karl | The final write-up. |
7+
| File | Current role |
8+
| --- | --- |
9+
| `O_Project_description.txt` | Optional prompt context. |
10+
| `requests.txt` | Human input, seeded only when missing. |
11+
| `research_data.txt` | Research data written by `ResearchOrchestrator`. |
12+
| `report.txt` | Report written by `ResearchOrchestrator`. |
1213

13-
## Conventions
14-
15-
* Files are plain UTF-8 text.
16-
* The agents append/overwrite with `WriteFileTool`; treat any file as
17-
potentially mutated by the next run.
18-
* Keep the seed `O_Project_description.txt` checked in; treat the rest as
19-
ephemeral artefacts (do not rely on their git history).
14+
`OfflineCorpusProvider` is deterministic and network-free. OpenAI is an
15+
explicit optional provider requiring external credentials. The implementation
16+
has no Research Joe/Professor Karl agents or `WriteFileTool` calls.
17+
Preserve the corpus, reports, and historical communication files; updating
18+
this description does not authorize running a provider or rewriting them.

0 commit comments

Comments
 (0)