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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .aii/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# .aii — InstituteOS sidecar

This folder is the committed [InstituteOS](https://github.com/ActiveInferenceInstitute/InstituteOS)
sidecar for **`ActiveInferenceInstitute/Knowledge-Engineering`**. It records curated institutional metadata that the GitHub
This folder is the committed InstituteOS sidecar for **`ActiveInferenceInstitute/Knowledge-Engineering`**.
It records curated institutional metadata that the GitHub
API cannot provide — identity, category, maturity, ecosystem relations, key artifacts,
provenance, and portable tasks — so InstituteOS can federate a unified view across
Institute repositories without touching this project's own content. The schema is
Expand Down Expand Up @@ -45,10 +45,10 @@ Institute repositories without touching this project's own content. The schema i
| `notebooks` | `python .github/scripts/gate.py notebooks` | `.` | Check notebook JSON and absence of outputs. |
| `checkpoints` | `python .github/scripts/gate.py checkpoints` | `.` | Reject tracked Jupyter checkpoints. |
| `archive` | `python .github/scripts/gate.py archive` | `.` | Run the archive checks and Publishing digest checks. |
| `tests` | `python .github/scripts/gate.py tests` | `.` | Run dependency-free gate tests. |
| `gnn` | `python .github/scripts/gate.py gnn` | `.` | Check GNN conformance using .github/gnn-pin.json. |
| `tests` | `python .github/scripts/gate.py tests` | `.` | Run dependency-free gate contracts and controlled scraper regressions. |
| `gnn` | `python .github/scripts/gate.py gnn` | `.` | Verify the pinned parser's installed origin/content and sketch or exemplar conformance. |
| `fast` | `python .github/scripts/gate.py fast` | `.` | Run archive checks and tests; no manuscript command exists. |
| `full` | `python .github/scripts/gate.py full` | `.` | Run fast and GNN conformance. |
| `full` | `python .github/scripts/gate.py full` | `.` | Run fast checks, then the same qualified GNN conformance. |
| `timings` | `python .github/scripts/gate.py timings` | `.` | Measure offline arms and regenerate docs/gate-timings.md. |

## Links
Expand Down
10 changes: 4 additions & 6 deletions .aii/config.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# AII sidecar — InstituteOS metadata. Schema: aii_platform.aii_sidecar
meta:
sidecar_version: 1.2.1
updated: '2026-11-12'
updated: '2026-11-16'
repo:
name: Knowledge-Engineering
slug: knowledge-engineering
Expand Down Expand Up @@ -105,16 +105,16 @@ tasks:
description: Run the archive checks and Publishing digest checks.
tests:
cmd: python .github/scripts/gate.py tests
description: Run dependency-free gate tests.
description: Run dependency-free gate contracts and controlled scraper regressions.
gnn:
cmd: python .github/scripts/gate.py gnn
description: Check GNN conformance using .github/gnn-pin.json.
description: Verify the pinned parser's installed origin/content and sketch or exemplar conformance.
fast:
cmd: python .github/scripts/gate.py fast
description: Run archive checks and tests; no manuscript command exists.
full:
cmd: python .github/scripts/gate.py full
description: Run fast and GNN conformance.
description: Run fast checks, then the same qualified GNN conformance.
timings:
cmd: python .github/scripts/gate.py timings
description: Measure offline arms and regenerate docs/gate-timings.md.
Expand All @@ -124,6 +124,4 @@ docs:
- docs/INTEGRATION.md
- docs/README.md
- docs/AGENTS.md
- ../docs/documentation-index.md
- ../docs/workflows/publishing.md
schema: aii-sidecar/v1
6 changes: 3 additions & 3 deletions .aii/docs/INTEGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,10 +62,10 @@
| `notebooks` | `python .github/scripts/gate.py notebooks` | `.` | Check notebook JSON and absence of outputs. |
| `checkpoints` | `python .github/scripts/gate.py checkpoints` | `.` | Reject tracked Jupyter checkpoints. |
| `archive` | `python .github/scripts/gate.py archive` | `.` | Run the archive checks and Publishing digest checks. |
| `tests` | `python .github/scripts/gate.py tests` | `.` | Run dependency-free gate tests. |
| `gnn` | `python .github/scripts/gate.py gnn` | `.` | Check GNN conformance using .github/gnn-pin.json. |
| `tests` | `python .github/scripts/gate.py tests` | `.` | Run dependency-free gate contracts and controlled scraper regressions. |
| `gnn` | `python .github/scripts/gate.py gnn` | `.` | Verify the pinned parser's installed origin/content and sketch or exemplar conformance. |
| `fast` | `python .github/scripts/gate.py fast` | `.` | Run archive checks and tests; no manuscript command exists. |
| `full` | `python .github/scripts/gate.py full` | `.` | Run fast and GNN conformance. |
| `full` | `python .github/scripts/gate.py full` | `.` | Run fast checks, then the same qualified GNN conformance. |
| `timings` | `python .github/scripts/gate.py timings` | `.` | Measure offline arms and regenerate docs/gate-timings.md. |

## Validation
Expand Down
44 changes: 29 additions & 15 deletions .github/GNN.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,25 +13,39 @@ What it validates, in order:

1. The pin's schema, repository identity, tag shape, 40-hex revision, and
recorded date.
2. The installed `gnn.__version__` against the tag without its `v`.
3. Every `*.gnn.md` sketch in the repository: full parse, syntax validation, and
type checking of the collected models. When the repository has no sketch it
downloads the pinned upstream `input/gnn_files/basics/static_perception.md`
exemplar at the pin's revision and validates that instead, and the JSON
receipt says `"source": "pinned-exemplar"`.
2. Independently frozen reviewed bootstrap and complete v5.0.3 manifest bytes, checked before any `gnn` import. Default installed mode additionally requires matching PEP610 Git origin and full package content, not just a version string.
3. Version, parser, syntax, and type-check imports/calls run within the canonical source-qualification guard, including final origin/content rechecks. A verified receipt can escape only after that guard exits successfully.
4. Sorted tracked `*.gnn.md` paths from Git inventory. Untracked/ignored sketches are excluded; inventory errors refuse. Only an empty tracked selection downloads the pinned `input/gnn_files/basics/static_perception.md` exemplar and reports `"source": "pinned-exemplar"`.

`--gnn-source-root /exact/checkout/src/gnn` explicitly selects the narrower independently manifested source mode (`vcs_verified=false`). It is incompatible with `--install`; installed refusal never falls back to source. Each verdict requires a fresh process. `source` describes model provenance; `source-qualification` describes parser provenance, not scientific validity.

The type checker's verdict is tri-state, not boolean: `validate_gnn_files`
returns `True` when every file validated, `2` when one or more files had
type/consistency problems **or when no GNN file was found**, and `False` on a
hard failure. Only the literal `True` passes the arm. `2` is truthy, so a
truthiness test would report an invalid model set as `"result": "verified"`;
instead any other value exits non-zero and the refusal names the value the
checker returned. `.github/scripts/tests/test_gnn_conformance.py` pins all four
outcomes (`True`, `2`, `False`, `None`/`0`) without needing the parser
installed.

The arm needs network access and a Python version the pinned release supports
(`>=3.11,<3.15`); CI uses 3.12. The local recipe, including a throwaway virtual
environment, is in [`RUN_GUIDE.md`](../docs/RUN_GUIDE.md#running-the-gnn-arm-locally).
A green result is a pipeline and pin conformance baseline, not a claim that this
repository contains a model.
checker returned. Controlled fixtures also reject integer `1`, corrupted authority/content, cached or foreign modules, missing installed origin, and source drift across verdict execution. They do not establish installed-runtime provenance.

The pinned release supports Python `>=3.11,<3.15`; CI uses 3.12. Explicit installation and exemplar acquisition need separate authority. Source mode alone does not prepare the exemplar; without the explicit prepared selector below, an empty tracked set still needs the pinned HTTPS download. See the [run guide](../docs/RUN_GUIDE.md#running-the-gnn-arm-locally).

For separately authorized offline qualification, prepare the authentic complete
pinned Git project, its locked declared dependencies, and an installer-generated
immutable VCS wheel cache in task-owned storage. Preserve the installer's real
origin metadata; a source-only export, copied installed package, or rewritten
`direct_url.json` is not a fresh installation. Bind the prepared artifacts in the
native execution inputs, use a fresh supported target environment, and keep
`gnn --install` as the actual gate command. Pip's ordinary offline/cache settings
may consume those exact resources; setup itself is not a conformance verdict.

`GNN_PREPARED_EXEMPLAR=/prepared/static_perception.md` explicitly separates
acquisition of the unchanged upstream exemplar from the offline verdict. Its
bytes must match SHA-256
`1ddd0fbde8155e2083d586a368503278373f26f6aae11dd4a2b4adfdf5ea7b8c`
at the pinned revision. Missing, empty, symlinked, or changed prepared inputs
refuse without a network fallback. With no selector, the same pinned HTTPS
download remains available and must match that digest. Tracked-model selection,
fresh installed-origin/full-content admission, parse/syntax/literal-`True` type
checks, and the `pinned-exemplar` receipt semantics are unchanged.

A green parser result is not a model of this archive, dependency-lock qualification, or scientific evidence.
8 changes: 4 additions & 4 deletions .github/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@
- [`scripts/archive_checks.py`](scripts/archive_checks.py) — the dependency-free
archive checks (relative Markdown links, tracked-Python compilation, notebook
JSON and committed outputs, tracked Jupyter checkpoints).
- [`scripts/gnn_conformance.py`](scripts/gnn_conformance.py) — pin validation,
pinned-parser install, and sketch/exemplar conformance.
- [`scripts/tests/test_gate.py`](scripts/tests/test_gate.py) — the gate's own
tests, run by the `tests` arm.
- [`scripts/gnn_conformance.py`](scripts/gnn_conformance.py) — pin validation, guarded parser execution, and tracked-sketch/exemplar conformance.
- [`scripts/gnn_runtime.py`](scripts/gnn_runtime.py) — pre-import reviewed-bootstrap/full-manifest admission and explicit installed/source lifetime.
- [`gnn/gnn_bootstrap.py`](gnn/gnn_bootstrap.py), [`gnn/v5.0.3-source-manifest.json`](gnn/v5.0.3-source-manifest.json) — exact independently approved producer artifacts, not a local validator fork.
- [`scripts/tests/`](scripts/tests/) — dependency-free gate contracts and controlled CSV/text scraper regressions. PDF fixtures replace extraction; controlled parser fixtures do not qualify installed provenance.
- [`dependabot.yml`](dependabot.yml) — dependency update configuration.
- [`gnn-pin.json`](gnn-pin.json) — the `gnn-importer-pin/v1` pin used by the
conformance arm: repository, tag `v5.0.3`, revision
Expand Down
Loading
Loading