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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 34 additions & 8 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-11'
updated: '2026-11-12'
repo:
name: Knowledge-Engineering
slug: knowledge-engineering
Expand Down Expand Up @@ -88,16 +88,42 @@ capabilities:
- ci
- citation
tasks:
inventory:
cmd: git ls-files
description: List tracked files.
test:
links:
cmd: python .github/scripts/gate.py links
description: Check documentation links and Publishing digests; docs index is docs/documentation-index.md.
python:
cmd: python .github/scripts/gate.py python
description: Compile tracked Python sources.
notebooks:
cmd: python .github/scripts/gate.py notebooks
description: Check notebook JSON and absence of outputs.
checkpoints:
cmd: python .github/scripts/gate.py checkpoints
description: Reject tracked Jupyter checkpoints.
archive:
cmd: python .github/scripts/gate.py archive
description: Run the archive checks and Publishing digest checks.
tests:
cmd: python .github/scripts/gate.py tests
description: Run dependency-free gate tests.
gnn:
cmd: python .github/scripts/gate.py gnn
description: Check GNN conformance using .github/gnn-pin.json.
fast:
cmd: python .github/scripts/gate.py fast
description: Run the dependency-free gate arm (links, syntax, notebooks, tests).
description: Run archive checks and tests; no manuscript command exists.
full:
cmd: python .github/scripts/gate.py full
description: Run fast and GNN conformance.
timings:
cmd: python .github/scripts/gate.py timings
description: Measure offline arms and regenerate docs/gate-timings.md.
docs:
- README.md
- AGENTS.md
- docs/INTEGRATION.md
- .aii/docs/INTEGRATION.md
- docs/README.md
- docs/AGENTS.md
- .aii/docs/AGENTS.md
- docs/documentation-index.md
- docs/workflows/publishing.md
schema: aii-sidecar/v1
9 changes: 5 additions & 4 deletions .aii/docs/INTEGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,11 @@

## Portable tasks

| Task | Command | Working directory | Description |
| --- | --- | --- | --- |
| `inventory` | `git ls-files` | `.` | List tracked files. |
| `test` | `python .github/scripts/gate.py fast` | `.` | Run the default dependency-free gate arm (links, syntax, notebooks, gate tests). |
Portable tasks in [config.yaml](../config.yaml) map directly to the gate's arms.
The [run guide](../../docs/RUN_GUIDE.md) owns their commands and descriptions;
the [documentation index](../../docs/documentation-index.md) is the docs entry
point. There is no manuscript command. GNN conformance uses
[the pin](../../.github/gnn-pin.json).

## Validation

Expand Down
14 changes: 14 additions & 0 deletions .github/scripts/gate.py
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,20 @@ def _report(label: str, inspected: int, errors: list[str], note: str = "") -> in

def arm_archive(names: tuple[str, ...], label: str) -> int:
inspected, errors = archive_checks.run(names, ROOT)
if "links" in names:
for artifact in (
"docs/workflows/record-identity.schema.json",
"scripts/gate/identity.py",
".github/gnn-pin.json",
):
result = subprocess.run(
[sys.executable, "-B", "scripts/gate/identity.py", "--verify-copy", artifact],
cwd=ROOT,
stdin=subprocess.DEVNULL,
check=False,
)
if result.returncode:
errors.append(f"{artifact}: Publishing digest verification failed")
notes = {
"links": "links resolve",
"python": "Python compiles",
Expand Down
49 changes: 49 additions & 0 deletions .github/scripts/tests/test_publishing.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
"""Publishing drift must fail the member's existing documentation gate."""

from pathlib import Path
import shutil
import tempfile
import unittest
from unittest.mock import patch

import gate


class PublishingDriftTests(unittest.TestCase):
def setUp(self) -> None:
self.directory = tempfile.TemporaryDirectory()
self.addCleanup(self.directory.cleanup)
self.root = Path(self.directory.name)
for name in (
"scripts/gate/identity.py",
"docs/workflows/record-identity.schema.json",
"docs/workflows/publishing.md",
".github/gnn-pin.json",
):
destination = self.root / name
destination.parent.mkdir(parents=True, exist_ok=True)
shutil.copyfile(gate.ROOT / name, destination)

def check_links(self) -> int:
with patch.object(gate, "ROOT", self.root), patch.object(
gate.archive_checks, "run", return_value=(0, [])
):
return gate.arm_archive(("links",), "links")

def test_matching_artifacts_pass(self) -> None:
self.assertEqual(self.check_links(), 0)

def test_changed_artifact_fails_docs_gate(self) -> None:
for name in (
"scripts/gate/identity.py",
"docs/workflows/record-identity.schema.json",
".github/gnn-pin.json",
):
with self.subTest(artifact=name):
path = self.root / name
original = path.read_bytes()
try:
path.write_bytes(original + b"\n")
self.assertEqual(self.check_links(), 1)
finally:
path.write_bytes(original)
7 changes: 6 additions & 1 deletion docs/RUN_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ $ python .github/scripts/gate.py --list

| Arm | Command | What it checks |
| --- | --- | --- |
| `links` | `python .github/scripts/gate.py links` | Relative Markdown link and image targets resolve inside the repository. |
| `links` | `python .github/scripts/gate.py links` | Relative Markdown link and image targets resolve inside the repository; Publishing artifact digests match. |
| `python` | `python .github/scripts/gate.py python` | Tracked Python files compile under the running interpreter. |
| `notebooks` | `python .github/scripts/gate.py notebooks` | Tracked notebooks are valid JSON with no committed cell outputs. |
| `checkpoints` | `python .github/scripts/gate.py checkpoints` | No Jupyter checkpoint file is tracked. |
Expand All @@ -30,6 +30,11 @@ implementation in `.github/scripts/archive_checks.py`; running `archive` reads
`git ls-files` once instead of four times. `gnn` lives in
`.github/scripts/gnn_conformance.py` and is the only arm that needs the network.

The `links` check also invokes the byte-identical Publishing checker with
`--verify-copy` for the schema, checker module, and GNN pin recorded in the
[member contract](workflows/publishing.md). This runs through `archive`, `fast`,
and `full` too; no additional gate arm or corpus is introduced.

## Where the arms are measured

[`gate-timings.md`](gate-timings.md) is generated; never edit it by hand. It
Expand Down
2 changes: 2 additions & 0 deletions docs/documentation-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ place. Generated pages are marked as such and are refreshed by a script.
- [docs/index.md](index.md) — the same map rendered as guide and reference tables.
- [docs/RUN_GUIDE.md](RUN_GUIDE.md) — gate entry point, arms, CI jobs, GNN pin.
- [docs/gate-timings.md](gate-timings.md) — **generated** per-arm wall times.
- [docs/workflows/publishing.md](workflows/publishing.md) — member migration, canonical contract pointer, and artifact digests.
- [docs/workflows/record-identity.schema.json](workflows/record-identity.schema.json) — digest-pinned canonical Publishing identity schema.

## Guides

Expand Down
39 changes: 39 additions & 0 deletions docs/workflows/publishing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Publishing — Knowledge-Engineering member

The [Publishing contract](https://github.com/ActiveInferenceInstitute/ActiveInferenceJournal/blob/d8ec888a8f3051a66bed9af047ee4b206050bdce/docs/workflows/publishing.md)
in ActiveInferenceJournal owns the workflow and identity grammar. This member
points there rather than restating the schema or creating identities for historical
research exports.

## Member mapping

- Gate: `python .github/scripts/gate.py <arm>`; commands and arm descriptions live
in the [run guide](../RUN_GUIDE.md) and [sidecar tasks](../../.aii/config.yaml).
- Docs index: [docs/documentation-index.md](../documentation-index.md).
- Manuscript command: none.
- GNN pin: [.github/gnn-pin.json](../../.github/gnn-pin.json).

The sidecar lists only documented gate-arm commands and uses existing sidecar
documentation paths. The archive's existing link, syntax, notebook, checkpoint,
test, timing and GNN checks remain authoritative for what they already prove,
as permitted by the contract; no parallel implementations are introduced.

## Canonical copies and drift checks

[identity.py](../../scripts/gate/identity.py) and
[record-identity.schema.json](record-identity.schema.json) are unchanged copies
from the lead revision linked above. The identity grammar is defined only in the
schema, not mirrored in prose here. The existing GNN pin is also digest-bound.

```text
record-identity.schema.json 84f6c4df6efc3f15f0d8a9a05c8aabd0cbdc08b0f4feac5fcc8ae860a81e306b
identity.py 847328ff163fa90c869495164869caf4e83313748e8a444dbab8d4e459b11074
gnn-pin.json eb83f7f1b73eb31e116bd05b1f457dd07e6874a2a4ba0e9e95e5bc91f094cd55
```

The `links` arm invokes the canonical module's `--verify-copy` command for every
artifact above. `archive`, `fast`, and `full` include that check. Gate tests prove
that matching copies pass and changed copies fail. Checks are offline and
stdlib-only; no JSON Schema package, journal corpus, or fabricated record data is
required. These checks prove artifact agreement, not identity coverage of the
historical research exports.
137 changes: 137 additions & 0 deletions docs/workflows/record-identity.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/ActiveInferenceInstitute/ActiveInferenceJournal/blob/main/docs/workflows/record-identity.schema.json",
"title": "Publishing record identity",
"schema_version": "record-identity/v1",
"description": "Canonical identity of one publishing record in the Active Inference Institute estate. The journal's metadata.json is the record; item, video_id and session ids are the join keys every other repository uses. Machine-readable rules are under x-identity, which scripts/gate/identity.py enforces, so this file is the only copy of the grammar.",
"type": "object",
"required": [
"series",
"item",
"source",
"channel",
"category",
"episode",
"parts"
],
"properties": {
"series": {
"type": "string",
"description": "Name of a directory above the item directory inside the corpus.",
"pattern": "^(?!\\.)[^/]{0,119}[^/\\s]$"
},
"item": {
"type": "string",
"description": "Item directory name; the record's item id.",
"pattern": "^(?!\\.)[^/]{0,119}[^/\\s]$"
},
"source": {
"type": "string",
"description": "Producer family of the content, e.g. youtube."
},
"channel": {
"type": "string",
"description": "Channel or collection the source belongs to."
},
"category": {
"type": "string",
"description": "Top-level category used by the human index."
},
"episode": {
"type": "string",
"description": "Episode ordinal within the series, as text."
},
"duplicate_of": {
"type": "string",
"description": "Record path of the canonical item this one duplicates, with the leading data/<type>/<source>/ removed.",
"pattern": "^[^/]+(/[^/]+)+$"
},
"doi": {
"type": "string",
"description": "Paper DOI when the record is tied to a publication."
},
"parts": {
"type": "array",
"description": "Video parts of the record; each part is one video id.",
"items": {
"type": "object",
"required": ["video_id", "url", "title"],
"properties": {
"video_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{11}$"
},
"url": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string"
}
}
}
}
},
"x-identity": {
"record_path": "data/<type>/<source>/<series>/<item>",
"derived_prefix_components": 3,
"leaf_key": "item",
"ancestor_key": "series",
"duplicate_key": "duplicate_of",
"index_file": "INDEX.json",
"index_record_keys": ["path", "series", "item", "parts", "has_transcript", "duplicate_of"],
"transcript_flag": {
"key": "has_transcript",
"artifact": "transcript.txt"
},
"patterns": {
"video_id": "^[A-Za-z0-9_-]{11}$",
"session_id": "^(?P<video_id>[A-Za-z0-9_-]{11})_sess[0-9]{2}$",
"paper_id": "^(?:doi|arxiv|s2|openalex|title):.+$"
},
"namespaces": {
"item": {
"owner": "ActiveInferenceInstitute/ActiveInferenceJournal",
"home": "docs/workflows/record-identity.schema.json#/x-identity/leaf_key",
"carried_by": "metadata.json item + INDEX.json path",
"pattern": "item"
},
"video": {
"owner": "ActiveInferenceInstitute/ActiveInferenceJournal",
"home": "docs/workflows/record-identity.schema.json#/properties/parts/items/properties/video_id",
"carried_by": "metadata.json parts[].video_id; INDEX.json parts[]",
"pattern": "video_id"
},
"session": {
"owner": "ActiveInferenceInstitute/ActiveInferenceJournal",
"home": "docs/workflows/record-identity.schema.json#/x-identity/patterns/session_id",
"carried_by": "metadata.json sessions[].session_name; transcript.json blocks",
"pattern": "session_id"
},
"paper": {
"owner": "ActiveInferenceInstitute/act_inf_metaanalysis",
"home": "src/literature/models.py Paper.canonical_id",
"carried_by": "corpus.jsonl paper_id; journal metadata.json doi",
"pattern": "paper_id"
},
"doc": {
"owner": "ActiveInferenceInstitute/ISSS",
"home": "metadata_archiver.py document_name",
"carried_by": "archived_documents/metadata.json document_name",
"pattern": null
},
"pub": {
"owner": "ActiveInferenceInstitute/act_inf_metaanalysis",
"home": "manuscript/config.yaml doi + version",
"carried_by": "manuscript/config.yaml; output/reports/zenodo_deposit_metadata.json",
"pattern": null
}
},
"identity_free_artifacts": {
"captions/": "Filenames are verbatim source names (measured 2026-11-12: 421 of 624 begin youtube_captions, the rest are human titles). Never derive a record id from them.",
"translations/": "Filenames carry an id prefix for most files but not all (measured: 249 distinct prefixes, several are titles). Resolve the record through metadata.json first.",
"assets/": "Curated content, organised by type. Carries no identity."
},
"join_rule": "Consumers join on video (video_id), documents on paper (doi), publications on pub (doi + version). An item id is only meaningful inside this corpus and must be paired with its path."
}
}
Loading
Loading