AHBG: consume native UCHC input across runtime, queries, replay, and full-corpus CI

.github/workflows/ahbg-runtime.yml

@@ -4,13 +4,15 @@ on:
   pull_request:
     paths:
       - "ahbg/runtime/**"
+      - "ahbg/integration/**"
       - "ahbg/grok/**"
       - "libs/ucns/**"
       - ".github/workflows/ahbg-runtime.yml"
   push:
     branches: [main]
     paths:
       - "ahbg/runtime/**"
+      - "ahbg/integration/**"
       - "ahbg/grok/**"
       - "libs/ucns/**"
       - ".github/workflows/ahbg-runtime.yml"

.github/workflows/ahbg-uchc-structural.yml

@@ -0,0 +1,117 @@
+# Read-only AHBG consumption of the exact extracted UCHC a2 structural field.
+# This job does not publish UCHC, graduate the English domain, or choose senses.
+name: AHBG UCHC structural corpus
+on:
+  pull_request:
+    paths:
+      - "ahbg/integration/uchc_structural.py"
+      - "ahbg/integration/UCHC_STRUCTURAL.json"
+      - "ahbg/integration/tests/test_uchc_structural_installed.py"
+      - "ahbg/runtime/runtime.py"
+      - "ahbg/runtime/protocol.py"
+      - "research/zfae/uchc_input.py"
+      - ".github/workflows/ahbg-uchc-structural.yml"
+  push:
+    branches: [main]
+    paths:
+      - "ahbg/integration/uchc_structural.py"
+      - "ahbg/integration/UCHC_STRUCTURAL.json"
+      - "ahbg/integration/tests/test_uchc_structural_installed.py"
+      - "ahbg/runtime/runtime.py"
+      - "ahbg/runtime/protocol.py"
+      - "research/zfae/uchc_input.py"
+      - ".github/workflows/ahbg-uchc-structural.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  ahbg-structural-consumer:
+    runs-on: ubuntu-24.04
+    env:
+      SOURCE_DATE_EPOCH: '1790308800'
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/checkout@v6
+        with:
+          repository: The-Interdependency/uchc
+          ref: c18d984438bc30764edb05fd5ccc05691958a24e
+          path: _deps/uchc
+          persist-credentials: false
+      - uses: actions/checkout@v6
+        with:
+          repository: globalwordnet/english-wordnet
+          ref: dc343f2683279ecbb13fab4e2fd778d7b162d287
+          path: _deps/oewn
+          persist-credentials: false
+      - uses: actions/checkout@v6
+        with:
+          repository: The-Interdependency/ucns
+          ref: 4f863ad37096b7baab8f62820ad5cb937b62a3a7
+          path: _deps/ucns
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12.14'
+      - name: Preflight and build pinned wheel
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import os, sqlite3, shutil
+          assert shutil.disk_usage('.').free > 8 * 1024**3, 'insufficient disk'
+          assert os.sysconf('SC_PHYS_PAGES') * os.sysconf('SC_PAGE_SIZE') >= 5 * 1024**3, 'insufficient memory'
+          assert sqlite3.sqlite_version == '3.45.1', 'SQLite writer differs from pinned byte evidence'
+          PY
+          python -m pip install setuptools==82.0.1 wheel==0.46.3 packaging==26.0 PyYAML==6.0.2
+          python -m pip wheel --no-deps --no-build-isolation ./_deps/uchc -w /tmp/ahbg-uchc-a2-dist
+          python - <<'PY'
+          import hashlib, json, pathlib
+          lock = json.loads(pathlib.Path('ahbg/integration/UCHC_STRUCTURAL.json').read_text())
+          artifact = pathlib.Path('/tmp/ahbg-uchc-a2-dist') / lock['wheel']
+          with artifact.open('rb') as f:
+              assert hashlib.file_digest(f, 'sha256').hexdigest() == lock['wheel_sha256']
+          PY
+          python -m venv .uchc-a2
+          .uchc-a2/bin/python -m pip install PyYAML==6.0.2
+          .uchc-a2/bin/python -m pip install --no-index --no-deps /tmp/ahbg-uchc-a2-dist/uchc-0.1.0a2-py3-none-any.whl
+      - name: Build and verify full structural corpus through installed UCHC
+        run: |
+          set -euo pipefail
+          .uchc-a2/bin/python -I -m english_gonol.structural_construct build \
+            --source-root "$PWD/_deps/oewn/src/yaml" \
+            --ucns-source-root "$PWD/_deps/ucns" \
+            --out-dir "$PWD/_state/structural"
+          .uchc-a2/bin/python -I -m english_gonol.structural_construct verify "$PWD/_state/structural"
+          python - <<'PY'
+          import hashlib, json, pathlib
+          lock = json.loads(pathlib.Path('ahbg/integration/UCHC_STRUCTURAL.json').read_text())
+          root = pathlib.Path('_state/structural')
+          manifest = json.loads((root/'manifest.json').read_text())
+          with (root/'construct.db').open('rb') as f:
+              observed = hashlib.file_digest(f, 'sha256').hexdigest()
+          assert observed == lock['database_sha256'], 'physical structural bytes mismatch'
+          assert manifest['receipt_sha256'] == lock['logical_receipt'], 'structural logical receipt mismatch'
+          assert manifest['metadata']['implementation_sha256'] == lock['implementation_sha256']
+          assert manifest['metadata']['complete_corpus'] is True
+          assert manifest['metadata']['profile']['profile'] == lock['profile']
+          PY
+      - name: Consume full native structural field inside AHBG
+        env:
+          UCHC_STRUCTURAL_FIELD: ${{ github.workspace }}/_state/structural
+          UCHC_CORPUS_REQUIRED: '1'
+        run: |
+          set -euo pipefail
+          .uchc-a2/bin/python -m unittest discover -s ahbg/integration/tests \
+            -p 'test_uchc_structural_installed.py' -v
+      - name: Retain identity and test evidence, never republish corpus bytes
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: ahbg-uchc-structural-evidence
+          path: |
+            _state/structural/manifest.json
+            ahbg/integration/UCHC_STRUCTURAL.json
+          retention-days: 14
+          if-no-files-found: warn

.github/workflows/uchc-input.yml

@@ -3,10 +3,10 @@
 name: UCHC input integration
 on:
   pull_request:
-    paths: ['.github/workflows/uchc-input.yml', 'research/zfae/**', 'integration/uchc/**', 'stack-manifest.json', 'STACK_MANIFEST.md']
+    paths: ['.github/workflows/uchc-input.yml', 'research/zfae/**', 'integration/uchc/**', 'ahbg/integration/**', 'ahbg/runtime/**', 'stack-manifest.json', 'STACK_MANIFEST.md']
   push:
     branches: [main]
-    paths: ['.github/workflows/uchc-input.yml', 'research/zfae/**', 'integration/uchc/**', 'stack-manifest.json', 'STACK_MANIFEST.md']
+    paths: ['.github/workflows/uchc-input.yml', 'research/zfae/**', 'integration/uchc/**', 'ahbg/integration/**', 'ahbg/runtime/**', 'stack-manifest.json', 'STACK_MANIFEST.md']
 permissions:
   contents: read
 jobs:
@@ -66,7 +66,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          UCHC_INPUT_DATABASE="$PWD/evidence/construct/construct.db" \
+          UCHC_CORPUS_REQUIRED=1 UCHC_INPUT_DATABASE="$PWD/evidence/construct/construct.db" \
             .clean/bin/python -I -m pytest -q stack/integration/uchc/tests/test_input.py --junitxml=evidence/integration.xml
           .clean/bin/python -I producer/tools/verify_inference_corpus.py \
             --database evidence/construct/construct.db \
@@ -76,6 +76,11 @@ jobs:
           .clean/bin/python -I stack/research/zfae/uchc_input.py \
             --database evidence/construct/construct.db --source-id ci:exact-input \
             --text 'alpha letter alpha' > evidence/consumer-frame.json
+          # AHBG consumes this same installed wheel and complete verified
+          # construct, not a mock or a second Stack language implementation.
+          UCHC_INPUT_DATABASE="$PWD/evidence/construct/construct.db" \
+            .clean/bin/python -m unittest discover \
+              -s stack/ahbg/integration/tests -p 'test_uchc_installed.py' -v
           cp stack/research/zfae/UCHC_INPUT.json evidence/
           git -C stack rev-parse HEAD > evidence/STACK_COMMIT
           git -C producer rev-parse HEAD > evidence/UCHC_COMMIT

ahbg/README.md

@@ -20,6 +20,17 @@ The AHBG board is a **game projection of UCNS geometry**, not an independently i
 
 For implementation, depend on the canonical `ucns` package/source. In stack, `libs/ucns/` is the pinned canonical repository view and `research/ucns/` is noncanonical stack-local research; neither permits silently forking the geometry.
 
+## Native UCHC language construction
+
+AHBG now has an **optional native UCHC consumer**. Separately pinned clean-installed
+UCHC candidate wheels supply exact English input and structural constructions,
+source-bound word and definition records, full recovery, replay, local closure,
+and admission receipts. AHBG can inspect these results
+and pass read-only evidence to agents without defining new geometry, meanings,
+game actions, or consciousness criteria. Invalid wheel/database/receipt identity
+fails closed. See [the executable UCHC integration contract](integration/UCHC.md)
+and its full-corpus acceptance gate.
+
 ## Two coordination modes — do not mix them
 
 AHBG now has two different work modes.

ahbg/integration/UCHC.md

@@ -0,0 +1,209 @@
+# AHBG ↔ UCHC: native consumer contract
+
+## Done when
+
+AHBG installs the source- and wheel-locked UCHC candidate; independently verifies
+its package files and complete-corpus identity; constructs, queries and replays
+native English input; preserves unknowns; exposes the exact evidence to the
+agent observation and persisted turn record; and refuses changed artifacts or
+unlicensed operations. The AHBG engine and UCNS movement remain unchanged.
+
+**Authority:** UCHC constructs. UCNS owns geometry. Stack remains the English
+forge pending graduation. AHBG observes those native objects, never reimplements
+them or treats structural similarity as a game rule or consciousness proof.
+
+## Source and installation
+
+The canonical immutable candidate selection already exists at
+`research/zfae/UCHC_INPUT.json`. AHBG intentionally reuses the existing
+`research/zfae/uchc_input.py` verifier. The candidate is UCHC `0.1.0a1`,
+source `3d82007b88f74ded88ca913d6e85bcd6f6ff024d`.
+Wheel SHA-256, logical receipt, and database byte SHA-256 are **read from the
+trusted lock**, never discovered from the supplied database or guessed at run time.
+
+Use `.github/workflows/uchc-input.yml` as the full-corpus reproducibility and
+installed-artifact acceptance path. It fetches exactly pinned sources, builds
+and verifies wheel bytes, constructs the full OEWN corpus, and runs both the
+existing ZFAE consumer and AHBG's real native-language integration tests.
+
+For a local install, first verify the wheel SHA-256 against the lock and
+install the exact wheel from a local archive into a separate environment.
+Use the corresponding verified complete `construct.db`:
+
+```bash
+python -m ahbg.integration.uchc \
+  --database /artifacts/construct.db \
+  text 'alpha letter alpha' --source-id 'ahbg:query:1'
+
+python -m ahbg.integration.uchc \
+  --database /artifacts/construct.db word alpha
+
+python -m ahbg.integration.uchc \
+  --database /artifacts/construct.db definition 1
+
+python -m ahbg.integration.uchc \
+  --database /artifacts/construct.db replay /artifacts/saved-frame.json
+
+PYTHONPATH=.:libs/ucns/src python -m ahbg.runtime play \
+  --agent a0 --turns 3 --out /tmp/ahbg-native \
+  --uchc-database /artifacts/construct.db
+```
+
+The query CLI returns a source-bound frame, UCHC-native word object, complete
+native definition with recovered source text, or verified replay. Definition
+identities are corpus-local, not assumed universal IDs. In Python:
+
+```python
+from pathlib import Path
+from ahbg.integration.uchc import UchcSession, UchcSettings
+
+with UchcSession(UchcSettings(Path("/artifacts/construct.db"))) as uchc:
+    frame = uchc.resolve_text("alpha letter alpha", source_id="ahbg:probe")
+    frame.require_complete()
+    assert frame.recover_utf8() == b"alpha letter alpha"
+    assert uchc.replay(frame.to_bytes()) == frame
+    all_candidates = uchc.definition_candidates(frame)
+    assert all_candidates
+    print(uchc.capabilities)
+```
+
+## Structural profile (separate exact wheel)
+
+The **newer** UCHC `0.1.0a2` is also independently consumable. Its real
+`StructuralField` performs text construction, admitted word/definition
+recovery, exact record replay, and registered ordered-text/sentence composition.
+It preserves both definition constituent topologies and definition succession.
+It never supplies missing UCNS geometric displacement.
+
+The exact candidate identities are in
+[`UCHC_STRUCTURAL.json`](UCHC_STRUCTURAL.json): UCHC source
+`c18d984438bc30764edb05fd5ccc05691958a24e`, wheel hash
+`7f05fbbb...`, complete 711,983,104-byte structural database hash
+`13ba2411...`, logical receipt `26ab095f...`. The consumer verifies the
+**full** stored identities, not the abbreviated identifiers printed here.
+
+Build the full structural field through the exact wheel as specified in
+[`ahbg-uchc-structural.yml`](../../.github/workflows/ahbg-uchc-structural.yml),
+then run:
+
+```bash
+PYTHONPATH=.:libs/ucns/src python -m ahbg.runtime play \
+  --agent a0 --turns 3 --out /tmp/ahbg-uchc-structural \
+  --uchc-structural-field /artifacts/structural-field
+```
+
+Native Python surface:
+
+```python
+from pathlib import Path
+from ahbg.integration.uchc_structural import (
+    UchcStructuralSession, UchcStructuralSettings
+)
+
+with UchcStructuralSession(
+    UchcStructuralSettings(Path("/artifacts/structural-field"))
+) as uchc:
+    graph = uchc.construct("Dr. creates geometry.")
+    assert uchc.replay(graph) == graph
+    word = uchc.word("geometry")
+    relation = uchc.compose(graph, relation="ordered-text")
+```
+
+The input and structural profiles use **different pinned wheel versions and
+different databases**. One Python process selects exactly one; attempting to
+activate both fails explicitly. Multiple profiles can be compared through
+separately installed processes without redefining their geometric authority.
+
+## Runtime integration
+
+Set `RuntimeConfig.uchc_database` (or `--uchc-database`) to activate native
+input evidence, or `uchc_structural_field` (or `--uchc-structural-field`) for the
+separately pinned structural profile; leave both unset to run AHBG without an
+installed UCHC wheel.
+An optional `uchc_lock` selects an explicitly trusted artifact lock.
+`uchc_require_complete=True` rejects unadmitted glyphs/words rather than
+concealing them. `uchc_max_text_bytes` is an optional explicit memory bound:
+oversized inputs fail rather than truncate. The default does not impose a
+hidden text-length limit.
+
+Each inbox message containing a `text` field is resolved in original order.
+No normalization, case folding, punctuation erasure, or inferred translation.
+A message's exact source-scoped native input frame and receipt appear in
+`observation.language_evidence` for a harness turn, alongside the unmodified
+`observation.inbox`. These are then persisted in
+`result.json.turn_records[].uchc_evidence`; the immutable UCHC wheel,
+database and lock identities appear in `result.json.provenance.uchc`.
+No modification to UCNS geometry, legal actions, game transitions, agent
+capabilities, or reward signals occurs.
+
+All definitions are available via native
+`session.word`, `session.definition`, `session.recover_definition`, and
+`session.definition_candidates`; the inline frame preserves source-order
+definition IDs and all native word identities. Semantic selection is not
+licensed. Unknown input is retained as `PARTIAL` unless strict admission is
+explicitly enabled, which raises `UchcConsumerError`.
+
+## Local HTTP and mobile access
+
+AHBG's built-in HTTP bridge can now expose the same UCHC package selected by
+its **operator**. Clients never choose wheel paths, source commits or a corpus.
+
+```bash
+PYTHONPATH=.:libs/ucns/src python -m ahbg.runtime.server \
+  --port 8765 --uchc-database /artifacts/construct.db
+
+# Or run the separate a2 structural profile instead:
+PYTHONPATH=.:libs/ucns/src python -m ahbg.runtime.server \
+  --port 8765 --uchc-structural-field /artifacts/structural-field
+```
+
+`GET /uchc/capabilities` returns exact supported operations and provenance.
+`POST /uchc/query` with a named supported native operation returns its real
+source-bound results (English text, UTF-8, word, definition, definition
+candidates, replay, structural construction, and allowed compositions).
+
+`POST /session/{id}/language` accepts
+`{"text":"original text"}`, builds native evidence and includes it in the
+next agent observation alongside the unchanged raw message. Its source-bound
+evidence is also appended to `language.jsonl` next to the persisted game
+state, with full UCHC artifact identity. The source evidence is read-only
+with respect to game rules/actions.
+
+HTTP UCHC is restricted to **loopback binding**, because this adapter does not
+provide authorization for remote callers. Inputs have an explicit 64 KiB HTTP
+transport ceiling; malformed operations and unsupported semantic inference
+fail with a request error instead of inventing an answer.
+
+## Rejection and proof
+
+- Missing UCHC wheel, editable/source-shadowed installation, wrong version,
+  altered installed files or wheel hash: refuse before game initialization.
+- Wrong complete construct SHA-256, logical receipt, schema or integrity:
+  refuse before game initialization.
+- Unexpected input shape, non-scalar Unicode, incomplete strict admission,
+  stale frame, mismatched record, unsupported/unpublished operation or
+  altered replay: refuse with an explicit error.
+- Neither a passing test nor a matching hash proves external authentication,
+  semantic truth, sense choice, neural inference, cross-origin Hilbert geometry,
+  or consciousness.
+
+Fast wiring gate:
+`PYTHONPATH=.:libs/ucns/src python -m unittest discover -s ahbg/runtime/tests -q`
+
+Real input producer acceptance gate:
+`.github/workflows/uchc-input.yml`, including
+`ahbg/integration/tests/test_uchc_installed.py` against the **complete**
+source-pinned corpus. Structural acceptance independently executes
+`.github/workflows/ahbg-uchc-structural.yml` against the distinct complete
+UCHC `0.1.0a2` field. A mocked reader alone is not sufficient evidence.
+
+## hmmm
+
+UCHC `0.1.0a2` structural admission now has its own independent AHBG
+consumer and complete-corpus gate. The new ordinal construction, polyglot
+label layer, binary producer and Hilbert frame bridge still have separate
+implementation and/or publication gates. No unfinished machinery may be
+silently substituted for either pinned candidate package. AHBG may adopt
+each only after its source and wheel/producer receipt, native semantics and
+full-corpus or full-domain replay have been verified, with an explicit lock
+migration. Independent UCHC graduation remains incomplete.