Complete memory comparisons and accelerate benchmark development

.github/workflows/ci.yml

@@ -29,16 +29,66 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+      - name: Install Node.js 24.19.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "24.19.0"
       - name: Install Bun
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
         with:
           bun-version: 1.3.14
+      - name: Verify governed source revision
+        env:
+          OH_EXPECTED_SHA: ${{ github.sha }}
+          OH_PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          OH_PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          OH_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          node --input-type=module <<'NODE'
+          import { execFileSync } from "node:child_process";
+          const git = (...args) => execFileSync("git", args, { encoding: "utf8" }).trim();
+          const checked = git("rev-parse", "HEAD");
+          const head = process.env.OH_PR_HEAD_SHA || null;
+          const eventBase = process.env.OH_PR_BASE_SHA || null;
+          let base = null;
+          if (head !== null) {
+            const ref = `refs/heads/${process.env.OH_PR_BASE_REF || ""}`;
+            git("check-ref-format", ref);
+            const lines = git("ls-remote", "--exit-code", "origin", ref).split("\n");
+            const [sha, actualRef] = lines[0].split("\t");
+            if (lines.length !== 1 || actualRef !== ref || !/^[a-f0-9]{40}$/.test(sha)) {
+              throw new Error("Cannot resolve the current governed base ref");
+            }
+            base = sha;
+          }
+          if (checked !== process.env.OH_EXPECTED_SHA) throw new Error("Unexpected CI checkout");
+          const parents = git("cat-file", "-p", "HEAD").split("\n\n")[0].split("\n")
+            .filter(line => line.startsWith("parent ")).map(line => line.slice(7));
+          if (head !== null && (parents.length !== 2 || parents[0] !== base || parents[1] !== head)) {
+            throw new Error("PR merge checkout does not bind the governed head and base");
+          }
+          console.log(JSON.stringify({ checked, head, base, eventBase, node: process.version }));
+          NODE
       - name: Install dependencies
         run: bun install --frozen-lockfile --ignore-scripts
+      - name: Install Python for benchmark custody tests
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.14'
+      - name: Check benchmark audit and supervisor tools
+        run: |
+          python -B -m unittest discover -s tests -p 'test_*supervisor.py'
+          python -B -m unittest discover -s tests -p 'test_gateway_v5_audit_helpers.py'
+          python -B -m unittest discover -s tests -p 'test_gateway_v6_*.py'
       - name: Run complete check
         run: bun run check
       - name: Require a reproducible generated tree
-        run: git diff --exit-code
+        run: |
+          git diff --exit-code
+          if [ -n "$(git ls-files --others --exclude-standard)" ]; then
+            git status --short
+            exit 1
+          fi
       - name: Inspect package contents
         run: bun pm pack --dry-run --ignore-scripts
 
@@ -51,10 +101,46 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+      - name: Install Node.js 24.19.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "24.19.0"
       - name: Install Bun
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
         with:
           bun-version: 1.3.14
+      - name: Verify governed source revision
+        env:
+          OH_EXPECTED_SHA: ${{ github.sha }}
+          OH_PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          OH_PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          OH_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          node --input-type=module <<'NODE'
+          import { execFileSync } from "node:child_process";
+          const git = (...args) => execFileSync("git", args, { encoding: "utf8" }).trim();
+          const checked = git("rev-parse", "HEAD");
+          const head = process.env.OH_PR_HEAD_SHA || null;
+          const eventBase = process.env.OH_PR_BASE_SHA || null;
+          let base = null;
+          if (head !== null) {
+            const ref = `refs/heads/${process.env.OH_PR_BASE_REF || ""}`;
+            git("check-ref-format", ref);
+            const lines = git("ls-remote", "--exit-code", "origin", ref).split("\n");
+            const [sha, actualRef] = lines[0].split("\t");
+            if (lines.length !== 1 || actualRef !== ref || !/^[a-f0-9]{40}$/.test(sha)) {
+              throw new Error("Cannot resolve the current governed base ref");
+            }
+            base = sha;
+          }
+          if (checked !== process.env.OH_EXPECTED_SHA) throw new Error("Unexpected CI checkout");
+          const parents = git("cat-file", "-p", "HEAD").split("\n\n")[0].split("\n")
+            .filter(line => line.startsWith("parent ")).map(line => line.slice(7));
+          if (head !== null && (parents.length !== 2 || parents[0] !== base || parents[1] !== head)) {
+            throw new Error("PR merge checkout does not bind the governed head and base");
+          }
+          console.log(JSON.stringify({ checked, head, base, eventBase, node: process.version }));
+          NODE
       - name: Require an exact public specification mirror
         run: diff -qr spec site/public/spec
       - name: Install site dependencies

AGENTS.md

@@ -30,15 +30,17 @@
 - `bun run check:effect` is part of the required aggregate gate. New production Effect modules need an explicit role in `scripts/check-effect-architecture.ts`. Review changes to that policy or checker independently; do not suppress diagnostics, erase expected failures, or move I/O into lifecycle programs to bypass a boundary.
 - Update narrative specifications, machine-readable manifests and schemas, implementation, and regression evidence together when a public contract changes.
 - Keep the Agent Skill concise and self-contained. It may guide reads and writes, but it cannot broaden a user's authorization or silently choose a database, space, sync destination, or destructive operation.
-- Rebuild `dist/` after source changes. Run `bun run check`, confirm the build leaves tracked files clean, and exercise the packed root, subpaths, and `oh --help` before handoff.
-- Run `bun run test:benchmarks` for benchmark changes. Use `bun run bench:memory --help` for isolated experiments; keep dataset labels outside ingestion, tune only on development groups, and distinguish state correctness, evidence recall, and reader scores. Paid calls require explicit limits and either a benchmark-only key or an explicitly selected Vercel project OIDC token; preserve the shared spending ledger across readers, transports, and judges. Keep Gateway aliases distinct from verified snapshots, and give gold references only to the separate judge.
+- Rebuild `dist/` after production source changes. Require the complete `bun run check`, reproducible generated tree, and packed root/subpath/`oh --help` checks before source admission. For pull requests, fresh successful CI on the exact governed head and current base may supply that source aggregate under the conditions in [CONTRIBUTING.md](CONTRIBUTING.md#validate-a-pull-request). Run focused local checks first; do not repeat equivalent local source aggregates when those CI conditions hold. Keep private benchmark, coupled-run, provider, authenticated, native, installation, release and deployment evidence separate whenever CI does not execute it. Use the local aggregate when CI is unavailable or equivalence is uncertain.
+- Run focused changed-area tests for benchmark changes. `bun run test:benchmarks` remains the complete benchmark-only subset; qualified PR CI already runs every test in that subset through `bun run check`, so a duplicate local subset run is not required. Use `bun run bench:memory --help` for isolated experiments; keep dataset labels outside ingestion, tune only on development groups, and distinguish state correctness, evidence recall, and reader scores. Paid calls require explicit limits and either a benchmark-only key or an explicitly selected Vercel project OIDC token; preserve the shared spending ledger across readers, transports, and judges. Keep Gateway aliases distinct from verified snapshots, and give gold references only to the separate judge.
 - Enable GitHub release immutability and configure npm trusted publishing for `.github/workflows/release.yml` before the next stable release. Release only a new annotated `v*` tag at exact current `main`. Build one npm tarball, test those unchanged bytes on Linux and macOS, publish them through npm OIDC with provenance, then attach that same tarball and `SHA256SUMS` to the immutable GitHub Release. Never move or reuse a release tag.
 
 <!-- hra-local-efficiency:start -->
 - Treat the user's request to change this repository as standing authorization for routine task-owned commits, pushes, pull requests, merges, releases, deployments, and production verification after the gates applicable to that action pass. Do not ask for duplicate confirmation. Build confidence through relevant automated checks, bounded diagnostics, and independent review, not another human approval. Passing checks does not expand task scope or authority.
 - Separate artifact admission from live qualification and operational activation. Use applicable automated source, security, package/install, and provenance evidence for artifact admission; live provider qualification is not a universal publication prerequisite. Preserve explicit live acceptance criteria and require relevant live evidence for claims that depend on it. If publication or an artifact's install, upgrade, or default-use path activates risky unqualified behavior, keep that behavior guarded or disabled, or obtain bounded relevant evidence before shipping or activation.
 - Use the repository's documented delivery workflow and preserve the identity, target, capacity, migration, and recovery guards applicable to operational activation. Replace an obsolete gate through a reviewed source and policy change with corresponding tests, never an ad hoc skip. Preserve every runtime-enforced approval, access control, branch protection, environment rule, safety policy, and required final gate. Ask for user input only when delivery needs a material product decision, missing credentials or authority, unavoidable interactive authentication, an irreversibly destructive action outside task scope, or resolution of a failure that cannot be handled safely and autonomously.
-- Prefer short-lived repository workload identities such as OIDC trusted publishing, GitHub Apps, and narrowly scoped machine identities. Do not add long-lived personal tokens, weaken two-factor authentication, or bypass provider controls to eliminate an interactive prompt. Batch unavoidable human-gated production promotions into intentional stable releases while agents publish validated prerelease or beta channels through workload identities when the repository supports them.
+- Preserve production and user data throughout delivery. Inspect the exact account, environment, deployment, and data target before writes. For data changes, inspect a dry run or equivalent migration plan and validate the recovery path before any effect that could lose or corrupt data. Prefer additive, backward-compatible migrations and bounded batches. Record mutation intent, use idempotency or conditional writes, and reconcile uncertain results before retrying. Verify deployed identity, health, and relevant data invariants after delivery. Routine delivery never authorizes resetting, truncating, dropping, or overwriting user data; stop the unsafe operation if preservation or recovery cannot be established.
+- Prefer short-lived repository workload identities such as OIDC trusted publishing, GitHub Apps, and narrowly scoped machine identities. Use unattended stable publication and production promotion when supported by the provider and repository. Establish supported machine authority once and verify it with a non-publishing preflight where available; routine releases should not require recurring interactive authentication or conversational approval. Retain account two-factor authentication and provider controls, including required authentication for approval of an exact staged artifact; do not add long-lived personal tokens to eliminate an interactive prompt.
+- Keep delivery gates proportional to the failure they prevent. Prefer required checks on the current integration candidate, independent agent review, and atomic or conditional integration. Add a merge queue or another approval stage only for a demonstrated coordination or safety need. Replace redundant queues, serial waits, and duplicate checks through reviewed policy changes while retaining evidence for the integrated result.
 - Preserve useful reasoning fan-out, but avoid unnecessary checkout fan-out. Prefer subagents in the current task for bounded research, review, diagnosis, and focused checks when they can safely share one working tree; create a separate task or worktree only for independently deliverable divergent edits, an isolated verification tree, or a different execution environment.
 - Give each expensive focused validation command and external wait one owner. The integration owner reviews that evidence and runs the repository-required aggregate or final gate once after convergence. Reuse evidence only for the exact Git tree, command, lockfiles, toolchain, relevant environment, and validity period, and never to skip a required final integration, merge, release, deployment, or production-verification gate.
 - On Hraness development machines, use `$hra-local-efficiency` and the installed host scheduler for heavyweight top-level commands when available. Keep ordinary work in the compute lane; give authenticated browser/dev-server/Chromium work one `browser-auth` owner and Mac-only validation one `mac-native` owner.

CONTRIBUTING.md

@@ -58,3 +58,29 @@ you ran. Keep generated `dist/` changes in the same commit as their source.
 Avoid unrelated formatting or dependency updates.
 
 Use the private process in [SECURITY.md](SECURITY.md) for vulnerabilities.
+
+## Validate a pull request
+
+Run focused checks for the changed behavior locally and obtain independent diff
+review. Keep source changes and any required generated `dist/` updates together.
+The complete test suite in `bun run check` includes every test selected by
+`bun run test:benchmarks`, along with strict typing, Effect boundaries, builds,
+Node portability, and packed-package root, subpath and CLI smoke checks.
+
+Fresh PR CI may serve as the final source aggregate when both `Check` operating
+systems, `Site`, and all other required checks succeed for the exact final head
+and current base. The workflow records and verifies the tested merge commit and
+its head/base parents, pins Bun 1.3.14 and Node.js 24.19.0, installs the frozen
+lockfiles, runs the full checks, and rejects changed tracked or new untracked
+files after the build. Record the run URLs, tested merge SHA, head SHA, base SHA
+and conclusions in the PR. Check that neither head nor base has changed before
+admission; a superseded, cancelled or stale run is insufficient. One owner waits
+for CI. An equivalent local aggregate need not run again while CI is pending.
+
+CI does not replace private dataset comparisons, coupled performance runs,
+paid/provider accounting, authenticated behavior, native capabilities or
+installation checks it does not execute. Preserve those task-specific receipts
+and their exact input/source identities. These source-gate rules do not change
+release, deployment, production verification or runtime approval requirements.
+If CI is unavailable or its coverage is uncertain, run the complete local
+aggregate through the repository and host schedulers before admission.