Harden Engine authority and preserve trusted regression evidence

.github/CODEOWNERS

@@ -1,5 +1,5 @@
 # Control-plane changes require explicit owner review under branch protection.
-/*.md @robertohluna @MichaelFractal @PAMF2
+*.md @robertohluna @MichaelFractal @PAMF2
 /skills/ @robertohluna @MichaelFractal @PAMF2
 /AGENTS.md @robertohluna @MichaelFractal @PAMF2
 /CLAUDE.md @robertohluna @MichaelFractal @PAMF2
@@ -13,3 +13,4 @@
 /wiring/ @robertohluna @MichaelFractal @PAMF2
 /scripts/ @robertohluna @MichaelFractal @PAMF2
 /.github/ @robertohluna @MichaelFractal @PAMF2
+/evidence/control-plane/ @robertohluna @MichaelFractal @PAMF2

.github/control-plane/Dockerfile

@@ -0,0 +1,5 @@
+FROM python:3.12-slim
+RUN apt-get update \
+    && apt-get install --yes --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+ENV PYTHONDONTWRITEBYTECODE=1 GIT_OPTIONAL_LOCKS=0

.github/workflows/agent-control-plane.yml

@@ -14,12 +14,50 @@ jobs:
   agent-control-plane-integrity:
     name: agent-control-plane-integrity
     runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: candidate
     steps:
-      - uses: actions/checkout@v4
+      - name: Check out candidate without persisted credentials
+        uses: actions/checkout@v4
+        with:
+          path: candidate
+          persist-credentials: false
+      - name: Check out previously trusted commit
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha || github.event.before || github.sha }}
+          path: trusted
+          persist-credentials: false
+      - name: Evaluate inside a container with read-only source mounts
+        env:
+          TRUSTED_EVENT_SHA: ${{ github.event.pull_request.base.sha || github.event.before || github.sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          runner=../trusted/scripts/run_trusted_control_plane.sh
+          if [[ ! -f "$runner" ]]; then
+            # Initial installation is proposed policy requiring independent owner review.
+            # The existing base validator and tests still run unchanged.
+            runner=scripts/run_trusted_control_plane.sh
+          fi
+          bash "$runner" ../trusted . "$TRUSTED_EVENT_SHA" ../control-plane-artifacts
+      - name: Retain trusted verdict before running candidate code on the host
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: trusted-control-plane-evidence
+          path: control-plane-artifacts/trusted-control-plane.json
+          if-no-files-found: error
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - name: Validate authority graph
+      - name: Validate candidate authority
         run: python3 scripts/agent_control_plane.py
-      - name: Adversarial authority regressions
-        run: python3 -m unittest discover -s scripts/tests -p 'test_agent_control_plane.py'
+      - name: Authority and trusted-harness regressions
+        run: python3 -m unittest discover -s scripts/tests -p 'test_*control_plane.py'
+      - name: Fresh-agent evaluator regressions
+        run: python3 -m unittest discover -s scripts/tests -p 'test_fresh_agent_review.py'
+      - name: Authenticated wrapper routing regressions
+        run: python3 -m unittest discover -s scripts/tests -p 'test_optimal_wrapper.py'

AGENTS.md

@@ -18,6 +18,21 @@ Never push Engine changes to `robertohluna/OptimalEngine`.
 Do not assume an embedded copy inside another app is newer.
 Check `git status`, branch, remotes, and the running process before making changes.
 
+## Authority, Runtime Identity, And Credentials
+
+Run `python3 scripts/agent_control_plane.py` before relying on current repository instructions.
+The registry classifies authority and historical evidence; it does not prove every prose claim or grant runtime access.
+Use [control-plane evidence and limits](docs/guides/agent-control-plane.md) when responding to a governance review.
+Use [release identity](docs/guides/versioning-and-releases.md) to compare the actual HTTP process with the intended build.
+A checked checkout or a passing health response alone does not attest a separate server or a completed authenticated session.
+
+HTTP clients need explicit operation grants and workspace scope.
+`read`/`write` do not imply `claims:review`, `topology:write`, or `admin`; an omitted scope list currently grants `*`.
+Authenticated tenant and Claim-review identities are bound to the key.
+See [API grants and migration](docs/guides/interfaces-and-publishing.md#api-grants-and-identity).
+Use `OPTIMAL_AUTH_REQUIRED=true` for shared deployments and verify missing credentials are rejected.
+Absent configuration retains trusted local development mode; CLI and direct database access remain privileged operator access.
+
 ## Local Boot
 
 Use the standard local path:

BOOT.md

@@ -33,6 +33,14 @@ Reality checks write diagnostic fixtures.
 Do not run them on live user data; use a separate disposable environment when testing fixtures.
 For an Engine embedded in OptimalOS, use the parent's `.system/oe boot` and `.system/oe storage_check` instead of starting another server.
 
+## Identify The Process And Its Trust Mode
+
+Run `python3 scripts/agent_control_plane.py` to validate the declared boot authority.
+Compare `GET /api/version` with the intended Engine commit and [contract](engine-contract.json) before attributing health results to a build.
+This comparison is separate from Canopy's checkout preflight; neither a clean working tree nor a health response proves a completed authenticated application session.
+For shared HTTP access, set `OPTIMAL_AUTH_REQUIRED=true` and follow [API grants and migration](docs/guides/interfaces-and-publishing.md#api-grants-and-identity).
+Use the [isolated fixture recipe](docs/guides/installation-and-deployment.md#isolated-fixture-verification) for reality checks.
+
 ## First Workspace
 
 Create a workspace when you know the shape:

CONTRIBUTING.md

@@ -68,7 +68,9 @@ Strict mode is on everywhere. No `any`. Explicit return types on public function
 2. **Name your branch** using the scope prefix convention (see Commit Messages below).
 3. **Write or update tests** — new behaviour needs coverage, bug fixes need a regression test.
 4. **Run the safety checks** locally before pushing:
-   `mix format --check-formatted && mix compile && mix test && mix optimal.reality_check`.
+   `mix format --check-formatted && mix compile && mix test`.
+   Run `python3 scripts/agent_control_plane.py` and its adversarial tests for control-plane changes.
+   Fixture-writing reality checks require the [isolated environment recipe](docs/guides/installation-and-deployment.md#isolated-fixture-verification), never a live user store.
 5. **Open a PR** against `main`. Keep the diff reviewable — aim for under 400 lines changed per PR. Split larger changes into a stack.
 6. **Describe what changed and why** in the PR body. Link any related issues.
 7. At least one maintainer approval is required before merge.

GETTING_STARTED.md

@@ -21,20 +21,21 @@ Requirements:
 macOS:
 
 ```bash
-brew install elixir node ffmpeg tesseract
+brew install elixir node ffmpeg tesseract snappy
 mix deps.get
 mix compile
 ```
 
 ## 2. Verify The Engine
 
 ```bash
-mix optimal.reality_check
+bin/optimal doctor
+bin/optimal health
 ```
 
-This checks the runtime spine: database migrations, topology tables, memory
-objects, retrieval paths, wiki/export pieces, tool/model records, and API
-surfaces.
+For a running service, also inspect `GET /api/stores/audit`.
+Do not start a second process against a live user store merely to run a diagnostic.
+The fixture-writing reality check belongs in a [disposable environment](docs/guides/installation-and-deployment.md#isolated-fixture-verification).
 
 ## 3. Create A Workspace
 
@@ -79,19 +80,22 @@ mix optimal.wiki render-tree --workspace sample
 
 ## 5. Use The Local Wrapper
 
-The `./optimal` wrapper is the clean surface for agents and humans:
+The checked-in `bin/optimal` wrapper is the source-checkout surface for agents and humans:
 
 ```bash
-./optimal status
-./optimal init my-workspace
-./optimal search "customer portal requirements"
-./optimal rag "prep me for the platform launch review"
+bin/optimal status
+bin/optimal setup my-workspace --name "My Workspace"
+bin/optimal find "customer portal requirements" --workspace default:my-workspace
+bin/optimal rag "prep me for the platform launch review" --workspace default:my-workspace
 ```
 
 An agent can use regular CLI tools (`ls`, `rg`, `cat`, `git`, `curl`) and the
 Optimal Engine CLI. MCP/tool servers are useful when authentication,
 schema-validation, remote resources, or audit justify the extra structure.
 
+Read [API grants and migration](docs/guides/interfaces-and-publishing.md#api-grants-and-identity) before using HTTP credentials.
+Local CLI access is trusted operator access; API-key scopes do not sandbox local processes.
+
 ## 6. Storage Model
 
 One local SQLite database is enough to start:

NOTES.md

@@ -36,3 +36,16 @@
 - 2026-09-08: Agent authority now has an explicit registry and adversarial structural validator.
 Historical architecture reports remain evidence and cannot own current concepts.
 Cross-repo execution compatibility and governed API authorization require runtime tests, not documentation assertions alone.
+
+- 2026-09-08: Current setup docs now separate read-only live health/storage audit from fixture-writing reality checks, with a single disposable verification recipe.
+- 2026-09-08: The authority index classifies historical evidence explicitly; directory membership and index links do not independently grant normative authority.
+- 2026-09-08: Canopy checkout preflight validates the source/task contract and does not attest a separately running Engine HTTP process or sandbox trusted local execution.
+- 2026-09-08: Reproduced and fixed the advertised OPTIMAL_AUTH_REQUIRED flag being ignored at runtime; literal true/false now override the configured auth setting, absence preserves it, and invalid values fail configuration.
+- 2026-09-08: Report fixtures A-G have distinct structural, runtime, and administrative evidence; natural-language contradictions, historical retrieval poisoning, and universal independent red-team closure are not established by the structural validator.
+- 2026-09-08: The wrapper health probe now forwards bearer credentials and refuses local-store fallback after a reachable HTTP failure; black-box tests cover authentication failures, denied writes, and intentional unconfigured default-local no-response fallback without using a real database.
+- 2026-09-08: CODEOWNERS now covers Markdown at every directory depth, including deployment guidance, so newly registered nested documents retain independent owner-review coverage.
+- 2026-09-08: Candidate-owned permissive validators and all-success tests reproduced a false green; the trusted harness now runs prior validator/test expectations and preserves exact hashed positive/negative evidence with additive supersession.
+- 2026-09-08: Initial ledger installation remains explicitly pending independent bootstrap review; existing base validator/tests still execute, while subsequent installed-baseline runs reject missing or rewritten evidence.
+
+- 2026-09-08: Real fresh-agent missing-authority reviews correctly stopped with validator exit 1, but the initial evaluator rejected Codex's terminal `status=failed` event.
+The exact event and causal lesson are retained under scripts/fixtures/fresh-agent, and a regression now verifies expected nonzero tool execution without changing the required permission or authority decisions.

OPTIONS.md

@@ -10,6 +10,10 @@ Use the repo wrapper for normal usage:
 bin/optimal <command>
 ```
 
+For API-backed wrapper commands, `OPTIMAL_ENGINE_API_KEY` authenticates both the availability probe and the operation.
+Reachable HTTP errors stop execution; only an unconfigured default-local probe with no HTTP response can select trusted local Mix fallback.
+Native commands remain local, so this wrapper is not a remote-only client or an isolation boundary.
+
 Use direct Mix tasks when you are developing the engine internals:
 
 ```bash
@@ -32,7 +36,11 @@ bin/optimal close "what changed and how verified"
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `OPTIMAL_ENGINE_API_URL` | `http://localhost:4200` | CLI API target. |
-| `OPTIMAL_ENGINE_API_KEY` | empty | Optional bearer token for HTTP calls. |
+| `OPTIMAL_ENGINE_API_KEY` | empty | Bearer token for wrapper/client HTTP calls; supplying it does not configure server authentication. |
+| `OPTIMAL_AUTH_REQUIRED` | configured auth setting, normally false | Literal `true` requires HTTP credentials; literal `false` enables trusted local mode; other values fail startup configuration. |
+| `OPTIMAL_API_ENABLED` | disabled outside development startup | Literal `true` enables the configured API listener; development launcher/config also enables it. |
+| `OPTIMAL_API_PORT` | `4200` | Port for an environment-enabled HTTP listener. |
+| `OPTIMAL_API_INTERFACE` | `127.0.0.1` | Bind address for an environment-enabled listener. |
 | `OPTIMAL_ENGINE_DB` | `.optimal/index.db` | Local SQLite store path. |
 | `OPTIMAL_ENGINE_CACHE` | `.optimal/cache` | Local cache path. |
 | `OPTIMAL_ENGINE_ROOT` | repo root | Engine root for source-checkout usage. |
@@ -89,9 +97,21 @@ They should not connect to Roberto's private engine unless explicitly configured
 | Production service | Hosted org or workspace | Service uses production secrets, scoped keys, and Postgres target when configured. |
 | Test mode | CI and unit tests | Use isolated temp stores and avoid private `.optimal/` data. |
 
+## Compatibility And API Grants
+
+The current source contract is application `0.3.1`, contract schema `1`, API `v1`, and migration `62`.
+The tracked [engine-contract.json](engine-contract.json) lists capabilities; [release identity](docs/guides/versioning-and-releases.md) explains the running build's SHA and version response.
+A checkout pin does not attest a separately running HTTP process.
+
+Ordinary `read`/`write` clients need separate `claims:review`, `topology:write`, or `admin` grants for privileged operations.
+Omitting scopes when minting a key currently grants `*`; choose grants explicitly.
+Follow [API grants and migration](docs/guides/interfaces-and-publishing.md#api-grants-and-identity) for tenant/reviewer binding and administrator-issued replacement keys.
+
 ## Safe Defaults
 
 Prefer repo-relative defaults.
 Prefer environment-driven config.
-Fail closed when scope or credentials are missing.
+Require credentials explicitly for untrusted HTTP access with `OPTIMAL_AUTH_REQUIRED=true`.
+The default local mode is trusted and permits anonymous requests; HTTP grants do not sandbox local CLI or SQL access.
+Applications must supply intended scope, while legacy API defaults remain documented compatibility behavior.
 Never silently share memory across tenants, organizations, or workspaces.

README.md

@@ -4,6 +4,10 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Elixir](https://img.shields.io/badge/Elixir-1.17+-4B275F.svg)](mix.exs)
 
+Current source contract: application `0.3.1`, API `v1`, contract schema `1`, expected migration `62`.
+See [engine-contract.json](engine-contract.json), [release identity](docs/guides/versioning-and-releases.md), and [document authority](docs/guides/agent-control-plane.md).
+A clean pinned checkout does not prove the identity of a separately running HTTP service.
+
 ## Verified Performance Snapshot
 
 The current Candidate Portfolio retrieves at least one gold evidence item for **96.094%** of 1,540 LoCoMo questions and retrieves **87.130%** of all gold evidence addresses at top 100.
@@ -762,7 +766,7 @@ In another terminal, verify the running engine:
 
 ```bash
 curl http://localhost:4200/api/health
-mix optimal.reality_check
+curl http://localhost:4200/api/stores/audit
 ```
 
 Use the checked-in `bin/optimal` command wrapper:
@@ -771,11 +775,13 @@ Use the checked-in `bin/optimal` command wrapper:
 bin/optimal --help
 bin/optimal doctor
 bin/optimal boot
-bin/optimal reality-check
+bin/optimal health
 ```
 
 That wrapper is for source checkouts.
-It delegates to `mix optimal.*` so native database dependencies load correctly.
+API-backed commands probe the configured endpoint with `OPTIMAL_ENGINE_API_KEY` and use HTTP when available.
+A reachable HTTP failure stops the command; only an unconfigured default-local probe with no HTTP response permits local Mix fallback.
+Native commands and that fallback use trusted local `mix optimal.*` access, so configure the local store deliberately.
 For production/API deployment, use the OTP release or container shape instead of treating the checkout wrapper as the server binary.
 
 There are three CLI surfaces:
@@ -803,10 +809,14 @@ apps, MCP servers, remote agents, or scripts that connect over HTTP/API, mint a
 scoped API key:
 
 ```bash
-bin/optimal auth mint --name "Business OS" --workspace default:my-workspace
-bin/optimal auth env --name "Local Agent" --workspace default:my-workspace
+bin/optimal auth mint --name "Business OS" --scope read --scope write --workspace default:my-workspace
+bin/optimal auth env --name "Local Agent" --scope read --scope write --workspace default:my-workspace
 ```
 
+Ordinary grants do not authorize Claim review, topology changes, or key administration.
+Use the [API grants and migration guide](docs/guides/interfaces-and-publishing.md#api-grants-and-identity) for those operations and authenticated tenant/reviewer binding.
+Local anonymous mode and direct CLI access remain trusted operator surfaces.
+
 Render wiki/export projections:
 
 ```bash
@@ -964,17 +974,16 @@ required native RocksDB library available.
 
 ## Verification
 
-Core reality check:
+Validate document authority before relying on instructions:
 
 ```bash
-mix optimal.reality_check
+python3 scripts/agent_control_plane.py
+python3 -m unittest discover -s scripts/tests -p 'test_agent_control_plane.py'
 ```
 
-Current verified result:
-
-```text
-126 probes, 126 ok, 0 warn, 0 fail
-```
+For live data use `/api/health` and `/api/stores/audit`.
+`mix optimal.reality_check` writes fixtures; use only the [isolated fixture recipe](docs/guides/installation-and-deployment.md#isolated-fixture-verification).
+The [control-plane evidence and limits](docs/guides/agent-control-plane.md) distinguishes structural CI, runtime regressions, and independent review.
 
 Focused topology/wiki path:
 
@@ -988,11 +997,7 @@ mix test test/wiki/service_test.exs \
   --seed 0
 ```
 
-Current result:
-
-```text
-19 tests, 0 failures
-```
+Use the result from your current checkout; this focused selection does not replace the full suite.
 
 Focused multimodal/memory path:
 

SYSTEM.md

@@ -59,8 +59,20 @@ policy
 principal
 ```
 
-If scope is missing or ambiguous, fail closed or ask for clarification.
-Never leak one workspace into another.
+Applications must supply the intended scope and resolve ambiguity before writing.
+Authenticated HTTP tenant identity is derived from the key, and conflicting tenant parameters are rejected.
+Workspace authorization and operation grants are separate checks; some legacy endpoints still default to the `default` workspace.
+This is a design obligation with compatibility defaults, not a claim that every missing scope field is rejected.
+Never intentionally share one workspace's records with another.
+
+## Enforced HTTP Trust Boundary
+
+`PermissionPlug` enforces operation grants after authentication and workspace checks.
+Ordinary writes cannot grant themselves Claim review, topology mutation, or API-key administration.
+Claim reviewers are bound to authenticated credentials; persisted evidence and lifecycle checks remain in Memory Core.
+See [API grants and migration](docs/guides/interfaces-and-publishing.md#api-grants-and-identity) for exact scope names and endpoint groups.
+Trusted anonymous local mode and wildcard keys remain privileged; direct Elixir and database access are outside HTTP authorization.
+See [control-plane evidence](docs/guides/agent-control-plane.md) for tests and limits rather than treating this system map as exploit proof.
 
 ## BusinessOS Boundary