Add PCNtoolkit conformance and held-out validation

.Rbuildignore

@@ -7,6 +7,7 @@
 ^\.mote$
 ^AGENTS\.md$
 ^CLAUDE\.md$
+^CONTRIBUTING\.md$
 ^\.claude$
 ^docs$
 ^_pkgdown\.yml$

.gitattributes

@@ -0,0 +1 @@
+tests/fixtures/pcntoolkit/**/*.csv text eol=lf

.github/workflows/pcntoolkit-validation.yml

@@ -0,0 +1,166 @@
+name: PCNtoolkit validation
+
+on:
+  pull_request:
+    paths:
+      - "R/**"
+      - "tests/**"
+      - "tools/pcntoolkit/**"
+      - "vignettes/pcntoolkit.Rmd"
+      - "DESCRIPTION"
+      - ".github/workflows/pcntoolkit-validation.yml"
+  push:
+    branches: [main]
+    paths:
+      - "R/**"
+      - "tests/**"
+      - "tools/pcntoolkit/**"
+      - "vignettes/pcntoolkit.Rmd"
+      - "DESCRIPTION"
+      - ".github/workflows/pcntoolkit-validation.yml"
+  schedule:
+    - cron: "17 6 * * 1"
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tier:
+        description: Validation tier to run
+        required: true
+        default: weekly
+        type: choice
+        options:
+          - weekly
+          - release
+
+permissions:
+  contents: read
+
+jobs:
+  offline-oracles:
+    name: Offline semantic and fitted oracles
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: |
+            any::devtools
+            local::.
+          needs: check
+      - name: Run checked-in oracles without Python or network access
+        run: >-
+          Rscript -e 'devtools::test(filter =
+          "pcntoolkit-(fixtures|semantics|concordance|superiority|hbr-site)",
+          stop_on_failure = TRUE)'
+
+  weekly-comparator:
+    name: Regenerate PCNtoolkit fixture and evidence
+    if: >-
+      github.event_name == 'schedule' ||
+      github.event_name == 'release' ||
+      (github.event_name == 'workflow_dispatch' &&
+       (inputs.tier == 'weekly' || inputs.tier == 'release'))
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.13"
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: local::.
+          needs: check
+      - name: Regenerate pinned PCNtoolkit 1.3.0 fixture
+        run: uv run tools/pcntoolkit/generate_fixtures.py --output /tmp/pcntoolkit-v1.3.0
+      - name: Reject unreviewed comparator drift
+        run: >-
+          Rscript tools/pcntoolkit/check_fixture_drift.R
+          tests/fixtures/pcntoolkit/v1.3.0 /tmp/pcntoolkit-v1.3.0
+      - name: Render machine-readable evidence
+        run: >-
+          Rscript tools/pcntoolkit/render_evidence.R
+          evidence/pcntoolkit/v1.3.0
+          --fixture-root /tmp/pcntoolkit-v1.3.0
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pcntoolkit-weekly-evidence
+          path: evidence/pcntoolkit/v1.3.0
+
+  release-hbr-site:
+    name: Release HBR and site-transfer evidence
+    if: >-
+      github.event_name == 'release' ||
+      (github.event_name == 'workflow_dispatch' && inputs.tier == 'release')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.13"
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: local::.
+          needs: check
+      - name: Run HBR and PCNtoolkit transfer with convergence receipts
+        run: >-
+          uv run tools/pcntoolkit/run_hbr_site_evidence.py
+          --output evidence/hbr-site --draws 1500 --tune 1000
+          --chains 4 --cores 4 --nuts-sampler nutpie --target-accept 0.99
+      - name: Run Referent adaptation and per-site gates
+        run: >-
+          Rscript tools/pcntoolkit/run_site_transport_evidence.R
+          evidence/hbr-site evidence/hbr-site/referent
+      - name: Enforce convergence and every-site gates
+        run: >-
+          Rscript tools/pcntoolkit/validate_hbr_site_evidence.R
+          evidence/hbr-site evidence/hbr-site/referent
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: pcntoolkit-release-hbr-site-evidence
+          path: evidence/hbr-site
+
+  release-scenario-matrix:
+    name: Release replicated scenario-matrix evidence
+    if: >-
+      github.event_name == 'release' ||
+      (github.event_name == 'workflow_dispatch' && inputs.tier == 'release')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.13"
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: local::.
+          needs: check
+      - name: Generate independent PCNtoolkit comparison replicates
+        run: >-
+          uv run tools/pcntoolkit/generate_release_superiority.py
+          --output evidence/release-superiority --replicates 20
+          --seed-start 20260924
+          --scenarios linear_gaussian,nonlinear_heteroskedastic,skew_heavy,unequal_site,covariate_shift
+      - name: Fit Referent models and enforce scenario-specific held-out gates
+        run: >-
+          Rscript tools/pcntoolkit/run_release_superiority.R
+          evidence/release-superiority evidence/release-superiority
+          499 4999 2000
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: pcntoolkit-release-scenario-matrix-evidence
+          path: evidence/release-superiority

.github/workflows/quality.yml

@@ -0,0 +1,85 @@
+name: R package quality
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "23 5 * * 2"
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  r-cmd-check:
+    name: R CMD check (${{ matrix.config.os }}, R ${{ matrix.config.r }})
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - {os: ubuntu-latest, r: "release"}
+          - {os: ubuntu-latest, r: "oldrel-1"}
+          - {os: macos-latest, r: "release"}
+          - {os: windows-latest, r: "release"}
+    runs-on: ${{ matrix.config.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: ${{ matrix.config.r }}
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+      - uses: r-lib/actions/check-r-package@v2
+        with:
+          args: 'c("--no-manual", "--as-cran")'
+          error-on: '"warning"'
+
+  scale-smoke:
+    name: Scale and bundle budgets
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: local::.
+          needs: check
+      - name: Enforce smoke budgets
+        run: Rscript tools/benchmarks/run_scale_benchmarks.R evidence/scale smoke
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: referent-scale-smoke
+          path: evidence/scale
+
+  scale-release:
+    name: Release-scale budgets
+    if: >-
+      github.event_name == 'schedule' ||
+      github.event_name == 'release' ||
+      github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: local::.
+          needs: check
+      - name: Enforce release budgets
+        run: Rscript tools/benchmarks/run_scale_benchmarks.R evidence/scale release
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: referent-scale-release
+          path: evidence/scale

.github/workflows/real-cohort-validation.yml

@@ -0,0 +1,38 @@
+name: Real-cohort validation
+
+on:
+  schedule:
+    - cron: "41 7 1 * *"
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  nhanes-external-cohort:
+    name: NHANES 2015-2016 to untouched 2013-2014
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: |
+            any::foreign
+            local::.
+          needs: check
+      - name: Run preregistered untouched-cycle confirmation
+        run: >-
+          Rscript tools/validation/run_nhanes_external_validation.R
+          evidence/nhanes-external
+          /tmp/nhanes-cache
+          confirmation
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: nhanes-external-validation-evidence
+          path: evidence/nhanes-external

.gitignore

@@ -10,6 +10,8 @@
 .omc/
 .claude/
 .mote/
+__pycache__/
+*.py[cod]
 tests/testthat/testthat-problems.rds
 tests/testthat/_problems/
 tmp/

.mote/FORMAT.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "store_id": "st-01M0TJWZ4KXA9B6H69WTA4KB7B",
+  "created_at": "2026-08-24T19:10:34.131119Z",
+  "default_ttl_s": {
+    "claim": 1800,
+    "reservation": 3600
+  }
+}

.mote/ops/20260824T191037.329963Z-p71889-c0000-r46ae-h63230f.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","kind":"session_start","label":"repair evidence trust claims and receipts","op":"20260824T191037.329963Z-p71889-c0000-r46ae-h63230f","pid":71889,"session_id":"sess-01M0TJX28HWYDEV2TV6FBA268D","ts":"2026-08-24T19:10:37.329963Z","ttl_s":14400,"v":1}

.mote/ops/20260824T191109.433408Z-p71972-c0000-ra8dd-h017ed6.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"create","op":"20260824T191109.433408Z-p71972-c0000-ra8dd-h017ed6","set":{"body":"Migration of the release-evidence repair from the mistakenly used Beads tracker. Frozen before inspecting any NHANES 2013-2014 outcomes: the 2017-2018 evaluation is post-hoc model-development evidence because it informed the demographic scale terms. Untouched confirmation will refit the already-fixed SHASH specification on NHANES 2015-2016 and evaluate NHANES 2013-2014 from DEMO_H.XPT and BMX_H.XPT. The frozen contract is adults age 18-79; outcomes height_cm, weight_kg, bmi, waist_cm; location s(age,k=8)+sex+race_ethnicity; scale s(age,k=5)+sex+race_ethnicity; intercept-only skew and tail; simple random sample without replacement of min(2000,population) using seed 20260824; total uncertainty with 1000 draws; unchanged acceptable_calibration rules, valid fits, held-out status, complete finite evidence, and minimum outcome n at least 500. No model, sample, seed, threshold, or wording may be changed after outcomes are observed; a failed confirmation remains a retained failure. Also make HBR/site evidence fail-closed by retaining raw tables, recording SHA-256 plus schema/row counts, and recomputing convergence, summaries, gates, and receipt verdicts rather than trusting booleans.","priority":1,"status":"open","title":"Repair evidence trust narrative and receipts"},"ts":"2026-08-24T19:11:09.433408Z","v":1}

.mote/ops/20260824T191109.452863Z-p71972-c0001-r3cc6-h9bc218.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"tag_add","op":"20260824T191109.452863Z-p71972-c0001-r3cc6-h9bc218","tag":"evidence","ts":"2026-08-24T19:11:09.452863Z","v":1}

.mote/ops/20260824T191109.467267Z-p71972-c0002-reb69-hb5fab0.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"tag_add","op":"20260824T191109.467267Z-p71972-c0002-reb69-hb5fab0","tag":"nhanes","ts":"2026-08-24T19:11:09.467267Z","v":1}

.mote/ops/20260824T191109.477236Z-p71972-c0003-r3d83-h12ff97.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"tag_add","op":"20260824T191109.477236Z-p71972-c0003-r3d83-h12ff97","tag":"pcntoolkit","ts":"2026-08-24T19:11:09.477236Z","v":1}

.mote/ops/20260824T191125.993650Z-p72671-c0000-rd0ef-hb2e2f2.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"reserve_open","mode":"exclusive","op":"20260824T191125.993650Z-p72671-c0000-rd0ef-hb2e2f2","paths":["AGENTS.md",".beads/issues.jsonl",".github/workflows/real-cohort-validation.yml",".github/workflows/pcntoolkit-validation.yml","README.md","NEWS.md","docs/design/pcntoolkit-validation-contract.md","docs/evidence/nhanes","docs/evidence/pcntoolkit/v1.3.0","tools/validation/run_nhanes_external_validation.R","tools/pcntoolkit/run_hbr_site_evidence.py","tools/pcntoolkit/run_site_transport_evidence.R","tools/pcntoolkit/validate_hbr_site_evidence.R","inst/pcntoolkit/run_hbr_site_evidence.py","inst/pcntoolkit/validate_hbr_site_evidence.R","tests/testthat/test-real-cohort-workflow.R","tests/testthat/test-pcntoolkit-hbr-site.R"],"reservation_id":"rv-01M0TJYHS9PWVY0Z1VQB4X3A6V","ts":"2026-08-24T19:11:25.993650Z","ttl_s":3600,"v":1}

.mote/ops/20260824T191126.005062Z-p72671-c0001-rf4fd-h375d61.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"claim","op":"20260824T191126.005062Z-p72671-c0001-rf4fd-h375d61","to":"codex-referent-evidence-20260824","ts":"2026-08-24T19:11:26.005062Z","ttl_s":1800,"v":1}

.mote/ops/20260824T191126.016001Z-p72671-c0002-r3956-hd70e73.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","expect":{"status":"20260824T191109.433408Z-p71972-c0000-ra8dd-h017ed6"},"kind":"patch","op":"20260824T191126.016001Z-p72671-c0002-r3956-hd70e73","set":{"status":"doing"},"ts":"2026-08-24T19:11:26.016001Z","v":1}

.mote/ops/20260824T191126.025965Z-p72671-c0003-r9bf4-h73fd16.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"note","note_kind":"progress","op":"20260824T191126.025965Z-p72671-c0003-r9bf4-h73fd16","text":"Frozen untouched confirmation design recorded; starting narrative, Mote migration, and fail-closed receipt repair","ts":"2026-08-24T19:11:26.025965Z","v":1}

.mote/ops/20260824T191253.844480Z-p72878-c0000-r512f-h2c8bcb.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"reserve_open","mode":"exclusive","op":"20260824T191253.844480Z-p72878-c0000-r512f-h2c8bcb","paths":["tools/pcntoolkit/generate_fixtures.py"],"reservation_id":"rv-01M0TK17JME59Y18BN5S09HEV1","ts":"2026-08-24T19:12:53.844480Z","ttl_s":3600,"v":1}

.mote/ops/20260824T191455.230717Z-p74607-c0000-r3815-h06355e.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"note","note_kind":"decision","op":"20260824T191455.230717Z-p74607-c0000-r3815-h06355e","text":"Untouched NHANES 2013-2014 design was committed and published before execution at b1301a4e0426eb5b5a83935059053131331670d9; local, tracking, and live remote SHAs matched.","ts":"2026-08-24T19:14:55.230717Z","v":1}

.mote/ops/20260824T192238.007685Z-p78868-c0000-r9c07-hb1f2c9.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"note","note_kind":"progress","op":"20260824T192238.007685Z-p78868-c0000-r9c07-hb1f2c9","text":"First and only execution of the preregistered NHANES 2013-2014 confirmation passed: 5592 eligible evaluation participants, fixed n=2000 sample, minimum outcome n=1892, all fits valid, full calibration gate true. No model, sample, seed, or threshold was changed.","ts":"2026-08-24T19:22:38.007685Z","v":1}

.mote/ops/20260824T195846.562562Z-p22442-c0000-r14ff-h12b8ff.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"note","note_kind":"progress","op":"20260824T195846.562562Z-p22442-c0000-r14ff-h12b8ff","text":"The earlier first-and-only note described the state immediately after the untouched first execution. A later verification replay, performed without changing the model, sample, seed, thresholds, or retained outputs, matched all five confirmation tables and receipt byte-for-byte. HBR and site receipts now hash every raw and derived table and independently recompute fixed controls, exact draw identities, convergence, prediction completeness, site summaries, candidate selection, and all gates; adversarial tests reject hash drift, false verdicts, and coherently re-signed omissions. Final devtools test passed with only two environment-version warnings; final source-tarball check: 0 errors, 0 warnings, 1 New submission note.","ts":"2026-08-24T19:58:46.562562Z","v":1}

.mote/ops/20260824T195851.644398Z-p22447-c0000-r2c28-h360f82.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"note","note_kind":"note","op":"20260824T195851.644398Z-p22447-c0000-r2c28-h360f82","text":"Completed narrative correction, prior Mote and Git registration, untouched NHANES confirmation, cryptographically bound HBR and site evidence, independent gate recomputation, tamper tests, full tests, and clean release check.","ts":"2026-08-24T19:58:51.644398Z","v":1}

.mote/ops/20260824T195851.657809Z-p22447-c0001-r4d90-hb40ff6.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","expect":{"status":"20260824T191126.016001Z-p72671-c0002-r3956-hd70e73"},"kind":"close","op":"20260824T195851.657809Z-p22447-c0001-r4d90-hb40ff6","ts":"2026-08-24T19:58:51.657809Z","v":1}

.mote/ops/20260824T195851.670052Z-p22447-c0002-r89c4-h60a6ec.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","kind":"reserve_close","op":"20260824T195851.670052Z-p22447-c0002-r89c4-h60a6ec","reservation_id":"rv-01M0TJYHS9PWVY0Z1VQB4X3A6V","ts":"2026-08-24T19:58:51.670052Z","v":1}

.mote/ops/20260824T195851.680743Z-p22447-c0003-r1884-h9fcc08.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","kind":"reserve_close","op":"20260824T195851.680743Z-p22447-c0003-r1884-h9fcc08","reservation_id":"rv-01M0TK17JME59Y18BN5S09HEV1","ts":"2026-08-24T19:58:51.680743Z","v":1}

.mote/ops/20260824T195851.690889Z-p22447-c0004-r8f94-h2010b4.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","entity":"referent-32n","kind":"release","op":"20260824T195851.690889Z-p22447-c0004-r8f94-h2010b4","ts":"2026-08-24T19:58:51.690889Z","v":1}

.mote/ops/20260824T195904.821615Z-p22592-c0000-r0444-h5900ab.json

@@ -0,0 +1 @@
+{"actor":"codex-referent-evidence-20260824","kind":"session_end","op":"20260824T195904.821615Z-p22592-c0000-r0444-h5900ab","session_id":"sess-01M0TJX28HWYDEV2TV6FBA268D","ts":"2026-08-24T19:59:04.821615Z","v":1}