feat: add gated public archive query

.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
 
       - name: Python compile
         run: |
-          python -m py_compile semeai_gate_basic\gate.py semeai_gate_basic\api.py semeai_gate_basic\server.py semeai_gate_basic\skill_registry.py semeai_gate_basic\skill_registry_http.py semeai_gate_basic\__main__.py tools\run_benchmark.py tools\check_contract.py examples\existing_chatbot_integration.py examples\middleware_boundary.py tests\test_gate_basic.py tests\test_skill_registry.py
+          python -m py_compile semeai_gate_basic\gate.py semeai_gate_basic\api.py semeai_gate_basic\server.py semeai_gate_basic\public_archive.py semeai_gate_basic\skill_registry.py semeai_gate_basic\skill_registry_http.py semeai_gate_basic\__main__.py tools\run_benchmark.py tools\run_public_archive_pilot.py tools\check_contract.py examples\existing_chatbot_integration.py examples\middleware_boundary.py tests\test_gate_basic.py tests\test_public_archive.py tests\test_public_archive_pilot.py tests\test_skill_registry.py
 
       - name: Python tests
         env:

README.md

@@ -147,6 +147,18 @@ POST /v0/check
 The API writes receipt metadata to `outputs/api_receipts` by default and does
 not store raw prompt/answer text in receipts by default.
 
+The bounded PUBLIC-only Axiom archive path is:
+
+```text
+POST /v0/archive/query
+```
+
+It retrieves from a frozen public index, creates a deterministic candidate, and
+passes that candidate through the existing Gate. Only `SHOW` returns the exact
+candidate as `releasedAnswer`; `REVIEW` and `BLOCK` return `null` without a
+post-Gate fallback. See
+[public archive agent v0.1](docs/public_archive_agent_v0_1.md).
+
 Early account backend:
 
 ```text
@@ -310,6 +322,8 @@ not admitted memory by default. See [ecosystem contract](docs/ecosystem_contract
 - [Operator TXID activation runbook](docs/operator_txid_activation_runbook.md) — verify payment + activate
 - [Architecture ADR v0.1](docs/architecture_adr_v0_1.md) — decisions + technical debt
 - [Governed Workspace Skill Registry v0.1](docs/skill_registry_v0_1.md) — bounded candidate evidence, operator decisions, and separate skill receipts
+- [Public archive agent v0.1](docs/public_archive_agent_v0_1.md) — PUBLIC-only retrieval, candidate, Gate, and receipt boundary
+- [Public archive pilot v0.1](docs/public_archive_pilot_v0_1.md) — fixed local dry run and held human-evaluation protocol
 
 ## Publish / SaaS Path
 

docs/public_archive_agent_v0_1.md

@@ -0,0 +1,64 @@
+# Public archive agent v0.1
+
+`POST /v0/archive/query` is a deterministic, PUBLIC-only archive query path for
+the Axiom shell. It performs four bounded steps:
+
+```text
+question
+-> frozen public evidence index
+-> deterministic candidate
+-> existing SemeAI Gate
+-> exact candidate for SHOW, otherwise null
+```
+
+It does not call an LLM, network service, private archive, raw archive, or
+online-ingestion source.
+
+## Request
+
+```json
+{
+  "question": "What is the Gate release authority?",
+  "routeContext": "gate",
+  "limit": 5
+}
+```
+
+`question` is required and limited to 256 characters. `limit` is optional and
+must be from 1 through 8.
+
+## Authority boundary
+
+- Retrieval is not truth.
+- Retrieved evidence is marked `UNTRUSTED_DATA`.
+- Generation creates a candidate, not a released answer.
+- The existing SaC/PoR Gate remains the final release authority.
+- Public actions remain `SHOW`, `REVIEW`, and `BLOCK`; their internal states
+  remain `PROCEED`, `NEEDS_REVIEW`, and `SILENCE`.
+- `SILENCE` means release denied, execution withheld, and audit preserved.
+- `releasedAnswer` is the exact candidate only for `SHOW`; it is `null` for
+  `REVIEW` or `BLOCK`.
+- No fallback or warning text substitutes for a held candidate.
+- The release-decision receipt ID is returned as both `decisionReceiptId` and
+  legacy-compatible `receipt_id`.
+- The persisted decision receipt carries an allowlisted `candidate_trace` with
+  candidate ID/hash, route context, and public source IDs. This trace metadata
+  is explicitly not Gate authority and stores no raw question or answer.
+- `executionReceiptId` remains separate and `null` because this endpoint does
+  not execute a downstream action.
+
+When retrieval finds no matching evidence, no candidate is generated and the
+Gate is not invoked. The response states that condition without manufacturing
+an answer or receipt.
+
+## Frozen index
+
+The packaged `semeai_gate_basic/data/axiom_public_evidence.json` mirrors the
+public-site index with SHA-256
+`b2c681a99141ca69125cf3704f3517a00ef8770575cf7ac69371f0ae7a29b9cf`.
+Runtime validation rejects private entries, raw-archive inclusion, online
+ingestion, duplicate source IDs, incomplete provenance, or authority drift.
+
+The public endpoint shares the process-local public-demo abuse guard. It does
+not count against Workspace quota and stores only a short hash of the client
+identity in memory for the active rate-limit window.

docs/public_archive_pilot_v0_1.md

@@ -0,0 +1,39 @@
+# Axiom public archive pilot v0.1
+
+The first bounded pilot has two deliberately separate layers.
+
+## Local contract dry run
+
+Run:
+
+```powershell
+python tools\run_public_archive_pilot.py `
+  --json-output outputs\axiom_public_pilot.json `
+  --markdown-output outputs\axiom_public_pilot.md
+```
+
+The six fixed tasks cover Gate authority, Skill Forge admission state,
+Repository Evidence Benchmark, Engineering Book receipts, Genesis historical
+admission, and truthful no-evidence behavior. The runner measures local latency,
+source coverage, citation identity, exact candidate/released-answer equality,
+Gate mapping, decision-receipt creation, and absence of an execution receipt.
+
+The output is explicitly labeled `DRY_RUN_NOT_HUMAN_EVALUATION`. It makes no
+claim about production deployment, real-user usability, or private Workspace
+behavior.
+
+## Human pilot (held for release and participants)
+
+After both draft PRs pass independent release authority and production smoke,
+run the same tasks with 3–5 participants. Record:
+
+- whether the participant finds an evidence-backed answer;
+- whether they can identify the cited source and its provenance;
+- whether they correctly distinguish the candidate, Gate decision, and release;
+- whether they understand that `SILENCE` preserves the audit;
+- completion time and any route-context ambiguity;
+- every no-evidence, wrong-source, stale-context, or citation failure.
+
+Do not retain raw participant questions beyond the approved pilot retention
+contract. A human pilot result must remain a separate admitted artifact; the
+local dry run does not auto-admit it.

pyproject.toml

@@ -16,7 +16,7 @@ license = { text = "Apache-2.0" }
 include = ["semeai_gate_basic*"]
 
 [tool.setuptools.package-data]
-semeai_gate_basic = ["*.js"]
+semeai_gate_basic = ["*.js", "data/*.json"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

semeai_gate_basic/__init__.py

@@ -7,6 +7,12 @@
     validate_gate_response,
 )
 from .api import API_VERSION, check_api_answer
+from .public_archive import (
+    build_archive_candidate,
+    load_public_index,
+    release_public_archive_answer,
+    retrieve_public_evidence,
+)
 
 __all__ = [
     "ACTION_TO_INTERNAL",
@@ -15,6 +21,10 @@
     "SCHEMA_VERSION",
     "check_api_answer",
     "check_ai_answer",
+    "build_archive_candidate",
+    "load_public_index",
+    "release_public_archive_answer",
+    "retrieve_public_evidence",
     "validate_gate_request",
     "validate_gate_response",
 ]

semeai_gate_basic/api.py

@@ -166,6 +166,17 @@ def api_health(*, env: Mapping[str, str] | None = None) -> dict[str, Any]:
                 "/v0/operator/workspaces/{workspace_id}/skills/{skill_record_id}/decision"
             ),
         },
+        "public_archive": {
+            "endpoint": "/v0/archive/query",
+            "index_visibility": "PUBLIC_ONLY",
+            "private_archive_included": False,
+            "raw_archive_included": False,
+            "online_ingestion_enabled": False,
+            "retrieval_is_truth": False,
+            "candidate_is_released_answer": False,
+            "release_authority": "SaC/PoR Gate",
+            "decision_and_execution_receipts_are_distinct": True,
+        },
         "email_verification": {
             **_email_status(values),
             "required": True,