Upload 40 files

# Substrate Mesh Runtime — Connector API

Private FastAPI connector for the Substrate Mesh Runtime and Primordial OS Runtime GPT Action route.

This Space exposes a bounded HTTPS API for submitting Substrate mesh commands, receiving receipt-bound responses, and retrieving command receipts. It preserves the HIR × OAM pressure spine, workspace isolation, source-return boundaries, and overlay-only write posture.

This is not a public autonomous agent, truth oracle, moderation authority, legal authority, medical authority, or final validation system.

Canonical artifacts remain read-only. Canonical lexicon entries remain read-only. User and GPT outputs are routed as workspace-local overlay proposals only. Human review remains required for downstream claims, publication, deployment, or external validation.

.dockerignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+.env
+.env.*
+.git/
+*.zip
+*.sha256
+runs/api_receipts/*
+!runs/api_receipts/.gitkeep

.env.example

@@ -0,0 +1,5 @@
+# Hugging Face Space Secret
+SUBSTRATE_ACTION_KEY=replace-with-a-long-random-secret
+
+# Optional; defaults to /data/api_receipts in Dockerfile
+SUBSTRATE_RECEIPT_ROOT=/data/api_receipts

DEPLOYMENT_CHECKLIST_v3_3_1.md

@@ -0,0 +1,15 @@
+# Deployment Checklist — v3.3.1
+
+1. Extract this ZIP.
+2. Create a Hugging Face Space using Docker SDK.
+3. Upload the extracted contents to the Space root.
+4. Add a Space secret named `SUBSTRATE_ACTION_KEY`.
+5. Wait for the Space to build.
+6. Test `/v1/mesh/health`.
+7. Test `/v1/mesh/command` with Bearer auth.
+8. Replace the placeholder server URL in `openapi/openapi.yaml`.
+9. Paste the edited OpenAPI schema into Primordial OS Runtime GPT Actions.
+10. Configure Action auth as Bearer with the same secret.
+11. Test in GPT Preview.
+
+Do not publish or share the bearer secret. Do not claim production multi-user readiness from this packet alone.

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV SUBSTRATE_RECEIPT_ROOT=/data/api_receipts
+
+WORKDIR /app
+
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+COPY . /app
+RUN mkdir -p /data/api_receipts
+
+EXPOSE 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

FINAL_LOCAL_RUN_INSTRUCTIONS_v3_3_1.md

@@ -0,0 +1,56 @@
+# Final Local Run Instructions — v3.3.1
+
+## 1. Validate packet locally
+
+```bash
+cd Substrate_Mesh_Runtime_Primordial_OS_Runtime_Connector_API_Wrapper_v3_3_1_OSF_READY
+export SUBSTRATE_ACTION_KEY="test-secret-key"
+python validate_substrate_connector_api_v3_3_1.py
+```
+
+Expected:
+
+```text
+status: PASS
+pressure_spine_hir_x_oam: true
+source_mutation_blocked: true
+human_review_required: true
+overlay_proposal_present: true
+```
+
+## 2. Run local API server
+
+```bash
+export SUBSTRATE_ACTION_KEY="replace-with-a-long-random-secret"
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+Open:
+
+```text
+http://localhost:7860/docs
+```
+
+## 3. Test command route
+
+```bash
+curl -X POST http://localhost:7860/v1/mesh/command   -H "Authorization: Bearer $SUBSTRATE_ACTION_KEY"   -H "Content-Type: application/json"   -d @examples/requests/robotics_humans_dna_request.json
+```
+
+## 4. Deploy to Hugging Face
+
+Create a new Docker Space. Upload all files from this packet to the Space root. Add a Space secret:
+
+```text
+SUBSTRATE_ACTION_KEY=<your long private token>
+```
+
+Then wait for the build to finish and test:
+
+```text
+https://YOUR-HF-SPACE.hf.space/v1/mesh/health
+```
+
+## 5. Connect GPT Action
+
+Edit `openapi/openapi.yaml`, replace the server URL with the deployed Space URL, then paste the schema into the Primordial OS Runtime GPT Action panel.

README.md

@@ -1,12 +1,81 @@
----
-title: Substrate Mesh Runtime Connector Api
-emoji: 🐨
-colorFrom: yellow
-colorTo: purple
-sdk: docker
-pinned: false
-license: cc-by-nc-sa-4.0
-short_description: Private Substrate connector API for GPT Actions
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Substrate Mesh Runtime — Primordial OS Runtime Connector API Wrapper v3.3.1
+
+Created and developed by Collin D. Weber.  
+Systems Architect / Systems Integrity Steward: Collin D. Weber.
+
+## Purpose
+
+This packet turns the v3.3 Primordial OS Runtime Connector contract into a deployable HTTPS API wrapper for GPT Actions.
+
+It is intended to be deployed as a private Hugging Face Docker Space first, then connected to the existing Primordial OS Runtime GPT through the GPT Builder Action panel.
+
+## Boundary
+
+- canonical source artifacts remain read-only;
+- canonical Primordial Lexicon remains read-only;
+- user/GPT outputs are workspace-local overlay proposals only;
+- no final validation claims;
+- no publication authority;
+- no clinical/legal/deployment authority;
+- human review remains required;
+- HIR × OAM pressure receipt is preserved.
+
+## API routes
+
+```text
+GET  /v1/mesh/health
+POST /v1/mesh/command
+GET  /v1/mesh/receipt/{command_id}?workspace_id=...
+```
+
+`/v1/mesh/command` and `/v1/mesh/receipt/{command_id}` require:
+
+```text
+Authorization: Bearer <SUBSTRATE_ACTION_KEY>
+```
+
+## Local test
+
+```bash
+export SUBSTRATE_ACTION_KEY="test-secret-key"
+python validate_substrate_connector_api_v3_3_1.py
+```
+
+## Local server
+
+```bash
+export SUBSTRATE_ACTION_KEY="replace-with-a-long-random-secret"
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+Health check:
+
+```bash
+curl http://localhost:7860/v1/mesh/health
+```
+
+Command test:
+
+```bash
+curl -X POST http://localhost:7860/v1/mesh/command   -H "Authorization: Bearer $SUBSTRATE_ACTION_KEY"   -H "Content-Type: application/json"   -d @examples/requests/robotics_humans_dna_request.json
+```
+
+## GPT Action schema
+
+Use:
+
+```text
+openapi/openapi.yaml
+```
+
+Before pasting into GPT Actions, replace:
+
+```text
+https://YOUR-HF-SPACE.hf.space
+```
+
+with your deployed Hugging Face Space URL.
+
+## Deployment posture
+
+This packet is API-wrapper-ready. It does not deploy itself. The operator still creates the Hugging Face Docker Space, adds `SUBSTRATE_ACTION_KEY` as a Space secret, uploads these files, and then connects the schema to the Primordial OS Runtime GPT Action panel.

RELEASE_MANIFEST.json

@@ -0,0 +1,19 @@
+{
+  "packet_name": "Substrate_Mesh_Runtime_Primordial_OS_Runtime_Connector_API_Wrapper_v3_3_1_OSF_READY",
+  "version": "v3.3.1",
+  "created_utc": "2026-06-16T14:52:30Z",
+  "status": "PASS_FOR_API_WRAPPER_DEPLOYMENT_PREP",
+  "pressure_spine": "HIR × OAM",
+  "source_mutation": "NONE__OVERLAY_PROPOSAL_ONLY",
+  "canonical_sources": "READ_ONLY",
+  "canonical_lexicon": "READ_ONLY",
+  "human_review_required": true,
+  "routes": [
+    "GET /v1/mesh/health",
+    "POST /v1/mesh/command",
+    "GET /v1/mesh/receipt/{command_id}"
+  ],
+  "auth": "Bearer token via SUBSTRATE_ACTION_KEY",
+  "deployment_target": "Hugging Face Docker Space",
+  "validator": "PASS"
+}

SHA256SUMS.txt

@@ -0,0 +1,38 @@
+c310336476b34815955cbd0c956982757acbe004f988cac49d4427e9908008e3  .dockerignore
+c1a080b7d04a9542c714f9b4992e6cf64d5d05c5f4ad721e647da0e28457c56c  .env.example
+d3e94da07e84f887b3c7aafe2444245bb614293ca09eddebe0ea9a2f4802709b  DEPLOYMENT_CHECKLIST_v3_3_1.md
+37ee741fcd148ce6536b51170f22b31d31eaadbe4bb7363d176a5b2738b54624  Dockerfile
+aab0683fc5eea5245b8fe6ab84bd461bb3f367753c2e5172279e1795c81104f0  FINAL_LOCAL_RUN_INSTRUCTIONS_v3_3_1.md
+90b8a391a3d49ae297fbea7190c528a2e49b253e91c077f338a6a4ba107efcfd  README.md
+1e3383bf393665b876b24c82ba9ff0685791759b16a2c6a5a03b6539db6b579f  RELEASE_MANIFEST.json
+56742ea5d8724708edf8de0e7a5fe5c56d91a56fee89a9498b8f9130f3598b42  V3_3_1_BOUNDARY_AND_CLAIMS_LIMIT.md
+11d3cd956a316817bdd8fcea95d3bc72850140f81b387363d708d3162213c99c  V3_3_1_BUILD_RECEIPT.md
+18053059891f40fd60e443ac0b05dc3d13d135c8cd92fe9eda5521645b5d21a4  V3_3_1_KNOWN_LIMITATIONS.md
+f4055663cffa9e7e67ca13b383ab28fa9f207b98e618e71d732735e973dee9ec  V3_3_1_TEST_REPORT.md
+fe2542343a2aa9810c514c2dbb53890fddfe612e55867bf8099dbb8b2cc1b60d  V3_3_1_VALIDATION_RESULT.json
+7410a28a86606632b2c0f291cc983ef22fdd830f595388937cc108e5b4e50ffe  app.py
+a643e35bf4bcf50e066904db4d1fd252e5b163eda47319661099f5e219f6d465  cockpit_static/index.html
+3e5d54696716889cfd7759aca4639cb32d963f20f5670dbadd4fce713f071678  docs/CROSS_USER_WORKSPACE_POLICY.md
+ef70885592d71a6d0861772efed17cc0f39ab4b4e30edfbfe0b8f5d0d45cde35  docs/GPT_ACTION_SETUP_STEPS_v3_3_1.md
+7db6b003ec50c6aad787abc7324ddb7c0fdb5e41ca70011c23312feb586cac57  docs/GPT_BUILDER_ACTION_SETUP_NOTES.md
+b4b0074db34081de69e3e1261272c9e79ed16c54623f84caa996cc2d4a9f0623  docs/HUGGING_FACE_DOCKER_SPACE_DEPLOYMENT_STEPS.md
+a447abfe3649508dee3b711ea1dacba5d3a470e9af8742efb5836542249d33a8  docs/PRIVACY_POLICY_STUB_FOR_ACTIONS.md
+1b484d01c2bece8cb2714bf208310674b9efaa04a6c4e07d64bb37d91d7b77dd  docs/PRIVACY_POLICY_STUB_FOR_ACTIONS_v3_3_1.md
+b6a5ca03b0dc7dea88b0235a3289d9ea86406a0045ef77e926293093447d4b22  examples/requests/robotics_humans_dna_request.json
+2246d9483db68a10f4e5d9d02750b18c877ad5f312905719a9ca0777a681de14  examples/responses/robotics_humans_dna_api_response.json
+0d7aded4454cb659206a5fe494d73235983c97959c2ad23c5f5250b0e745cfb9  openapi/openapi.yaml
+0d7aded4454cb659206a5fe494d73235983c97959c2ad23c5f5250b0e745cfb9  openapi/primordial_os_runtime_gpt_action_openapi_v3_3_1.yaml
+54a654cddb6d7d194322f5326353ebcbb21166921396e82f2e932ec7017887cc  requirements.txt
+e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  runs/api_receipts/.gitkeep
+4d3b6a97c06e381c527e1393b287fc33b55364bf49d996f581986311db4824f7  runs/api_receipts/workspace_validation_001/cmd_ab4eb51792224b22/audit_log.jsonl
+ae8e12f00c0f0f5316100236e0e4306267e2c18226a4a091a462f90d296ff5f5  runs/api_receipts/workspace_validation_001/cmd_ab4eb51792224b22/receipt.md
+22d14bba74799092361b1b722c6357c788423c42f606d2faf81070566d40ac79  runs/api_receipts/workspace_validation_001/cmd_ab4eb51792224b22/response.json
+dd7aae79bb18a145b687845499375c2e519978ec1075cff9caec02a012c9adb8  schemas/action_response_schema_v3_3.json
+5ef8d953f7f4ea58dd476ae3fd14c4f60219dbc6ed46a4c3035ca37f67c7d30f  schemas/adapter_identity_schema_v3_3.json
+d7c2d6d9f5fa71f04ffec3c7dff636ee7d773d322d1187d30e060605324cf1d5  schemas/api_key_and_access_boundary_v3_3.json
+5094a4f3b3ceba83c3686d13223c45faebebd0afdfbbbaf0f4fe71a267310952  schemas/hir_x_oam_pressure_gate_contract_v3_3.json
+9325623e8d4a95008235169748bee0992b604c4083cd01c4cab2ca0e7cf30b1d  schemas/llm_contribution_capsule_schema_v3_3.json
+8d71444b827821699b70399d1caff24ffe493f787143effc63e1d1ab00acb5b9  schemas/mesh_command_capsule_schema_v3_3.json
+f46f0c77acce52f9ace74b8ab4b8cfa58cec95d0d39091e213fbb13bcf5de45f  schemas/user_workspace_schema_v3_3.json
+f6e278bb7351f49efd7a9efee621e660c2c837c3d43a1307d29e8ef81a994a25  src/substrate_connector_core.py
+68521708f21c70d05afdfffdf7936956891f452a56aceb76e70d2bb44b1ab256  validate_substrate_connector_api_v3_3_1.py

Substrate_Mesh_Runtime_Primordial_OS_Runtime_Connector_API_Wrapper_v3_3_1_OSF_READY.zip.sha256

@@ -0,0 +1 @@
+e70065952438a78e8c3e9599f922da5c4e66ca42d75fdc16d7d582b6141fd11c  Substrate_Mesh_Runtime_Primordial_OS_Runtime_Connector_API_Wrapper_v3_3_1_OSF_READY.zip

V3_3_1_BOUNDARY_AND_CLAIMS_LIMIT.md

@@ -0,0 +1,19 @@
+# v3.3.1 Boundary and Claims Limit
+
+## Allowed claim
+
+v3.3.1 provides an HTTPS-ready API wrapper for routing Primordial OS Runtime GPT Action calls into a bounded Substrate connector core.
+
+## Not claimed
+
+- not a public production service by itself;
+- not deployed by this packet alone;
+- not a live multi-user backend yet;
+- not a canonical-source mutation layer;
+- not a canonical Primordial Lexicon mutation layer;
+- not legal, medical, clinical, or deployment authority;
+- not final validation.
+
+## Hard boundary
+
+Canonical artifacts and canonical lexicon remain read-only. All GPT/user outputs are workspace-local overlay proposals pending human review.

V3_3_1_BUILD_RECEIPT.md

@@ -0,0 +1,25 @@
+# v3.3.1 Build Receipt
+
+Built: 2026-06-16T14:51:57Z
+
+Packet: `Substrate_Mesh_Runtime_Primordial_OS_Runtime_Connector_API_Wrapper_v3_3_1_OSF_READY.zip`
+
+## Additions
+
+- FastAPI wrapper in `app.py`
+- Dockerfile for Hugging Face Docker Space
+- Bearer token auth using `SUBSTRATE_ACTION_KEY`
+- action-ready OpenAPI schema
+- local file-backed receipt persistence
+- API validator
+- HF deployment instructions
+- GPT Action setup instructions
+- privacy policy stub
+
+## Boundary
+
+- canonical source artifacts: READ_ONLY
+- canonical Primordial Lexicon: READ_ONLY
+- write scope: WORKSPACE_LOCAL_OVERLAY_PROPOSAL_ONLY
+- pressure spine: HIR × OAM
+- human review required: true

V3_3_1_KNOWN_LIMITATIONS.md

@@ -0,0 +1,8 @@
+# v3.3.1 Known Limitations
+
+1. This is an API wrapper packet, not an already-deployed service.
+2. The OpenAPI schema contains a placeholder server URL until the operator deploys the HF Docker Space.
+3. Private prototype authentication uses one Bearer token; public multi-user use will need per-user/OAuth-style isolation.
+4. Receipt storage is local file-backed; production deployment should use persistent storage with retention policy.
+5. The connector core still uses MVP topic/metadata matching rather than full semantic retrieval.
+6. Human review remains required for all overlay proposals and any downstream claim.

V3_3_1_TEST_REPORT.md

@@ -0,0 +1,24 @@
+# v3.3.1 Test Report
+
+Validator command:
+
+```bash
+python validate_substrate_connector_api_v3_3_1.py
+```
+
+Result: `PASS`
+
+Validated gates:
+
+- health route returns HELD;
+- unauthenticated command requests are blocked;
+- authenticated mesh command succeeds;
+- command returns HIR × OAM pressure spine;
+- canonical source mutation remains blocked;
+- human review required is true;
+- workspace-local receipt is written;
+- receipt fetch route works;
+- overlay proposal is present;
+- canonical source and lexicon boundaries are present.
+
+See `V3_3_1_VALIDATION_RESULT.json` for machine-readable details.

V3_3_1_VALIDATION_RESULT.json

@@ -0,0 +1,14 @@
+{
+  "version": "v3.3.1",
+  "health_ok": true,
+  "unauthorized_blocked": true,
+  "command_ok": true,
+  "receipt_fetch_ok": true,
+  "pressure_spine_hir_x_oam": true,
+  "source_mutation_blocked": true,
+  "workspace_local_receipt_written": true,
+  "human_review_required": true,
+  "overlay_proposal_present": true,
+  "canonical_boundary_present": true,
+  "status": "PASS"
+}

app.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Substrate Mesh Runtime — Primordial OS Runtime Connector API Wrapper v3.3.1.
+
+FastAPI HTTPS-ready wrapper for GPT Actions. Designed for Hugging Face Docker Space deployment.
+Boundary: read-only canonical source/lexicon posture; workspace-local overlay proposals only.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from fastapi import Depends, FastAPI, Header, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+from src.substrate_connector_core import submit_mesh_command
+
+APP_VERSION = "v3.3.1"
+PRESSURE_SPINE = "HIR × OAM"
+DEFAULT_RECEIPT_ROOT = Path(os.getenv("SUBSTRATE_RECEIPT_ROOT", "runs/api_receipts"))
+
+app = FastAPI(
+    title="Substrate Mesh Runtime Connector API",
+    version=APP_VERSION,
+    description=(
+        "HTTPS API wrapper for Primordial OS Runtime GPT Actions. Routes bounded mesh command "
+        "capsules into Substrate connector responses with trace capsules, PPT element matches, "
+        "Primordial Periodic Alchemical Output, HIR × OAM receipts, lexicon state, audit pointers, "
+        "and workspace-local overlay proposals."
+    ),
+)
+
+# Helpful for browser/dev testing. Auth still protects command/receipt routes.
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=False,
+    allow_methods=["GET", "POST", "OPTIONS"],
+    allow_headers=["Authorization", "Content-Type"],
+)
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def safe_id(value: str, fallback: str = "workspace_local") -> str:
+    value = (value or fallback).strip()
+    cleaned = re.sub(r"[^A-Za-z0-9_\-]", "_", value)[:96]
+    return cleaned or fallback
+
+
+def require_bearer(authorization: Optional[str] = Header(default=None)) -> str:
+    expected = os.getenv("SUBSTRATE_ACTION_KEY")
+    if not expected:
+        # Fail closed for deployed environments. The validator sets this env var.
+        raise HTTPException(status_code=500, detail="SUBSTRATE_ACTION_KEY is not configured")
+    if not authorization or not authorization.startswith("Bearer "):
+        raise HTTPException(status_code=401, detail="Missing bearer token")
+    token = authorization.split(" ", 1)[1].strip()
+    if token != expected:
+        raise HTTPException(status_code=403, detail="Invalid bearer token")
+    return "authorized"
+
+
+class MeshCommand(BaseModel):
+    command_type: str = Field(default="DISCOVER", description="DISCOVER, BRAINSTORM, COMBINE, EXTEND_RESEARCH, OAM_READ, LEXICON_REVIEW, THREADROOM_POST")
+    raw_user_text: str = Field(..., min_length=1, description="Natural-language user command or threadroom post.")
+    workspace_id: str = Field(default="workspace_local_001", description="Workspace scope; used for isolated local receipt storage.")
+    session_id: str = Field(default="session_local", description="Session/user alias for contributor credit.")
+    target_nodes: List[str] = Field(default_factory=list)
+    hashtags: List[str] = Field(default_factory=list)
+    mention_refs: List[str] = Field(default_factory=list)
+    minutes_budget: float = Field(default=5.0)
+    claim_boundary: str = Field(default="no final validation claims; human review required")
+    privacy_scope: str = Field(default="PRIVATE_WORKSPACE")
+    source_mutation_allowed: bool = Field(default=False)
+
+
+class HealthResponse(BaseModel):
+    status: str
+    version: str
+    pressure_spine: str
+    source_mutation_allowed: bool
+    canonical_source_posture: str
+    canonical_lexicon_posture: str
+    overlay_scope: str
+    human_review_required: bool
+    auth_configured: bool
+    timestamp_utc: str
+
+
+def receipt_paths(workspace_id: str, command_id: str) -> Dict[str, Path]:
+    w = safe_id(workspace_id)
+    c = safe_id(command_id)
+    folder = DEFAULT_RECEIPT_ROOT / w / c
+    return {
+        "folder": folder,
+        "response": folder / "response.json",
+        "audit": folder / "audit_log.jsonl",
+        "receipt_md": folder / "receipt.md",
+    }
+
+
+def persist_response(response: Dict[str, Any], request_meta: Dict[str, Any]) -> Dict[str, str]:
+    paths = receipt_paths(response.get("workspace_id", "workspace_local"), response.get("command_id", "cmd_unknown"))
+    paths["folder"].mkdir(parents=True, exist_ok=True)
+    response = dict(response)
+    response.setdefault("api_wrapper", {})
+    response["api_wrapper"].update({
+        "version": APP_VERSION,
+        "pressure_spine": PRESSURE_SPINE,
+        "persisted_at_utc": utc_now(),
+        "receipt_folder": str(paths["folder"]),
+    })
+    # Normalize visible HIR × OAM glyph even if legacy core returns HIR x OAM.
+    if isinstance(response.get("receipt"), dict):
+        response["receipt"]["pressure_spine"] = PRESSURE_SPINE
+    paths["response"].write_text(json.dumps(response, indent=2, ensure_ascii=False), encoding="utf-8")
+    audit = {
+        "timestamp_utc": utc_now(),
+        "event": "api_mesh_command_completed",
+        "wrapper_version": APP_VERSION,
+        "command_id": response.get("command_id"),
+        "workspace_id": response.get("workspace_id"),
+        "status": response.get("status"),
+        "pressure_spine": PRESSURE_SPINE,
+        "source_mutation": response.get("receipt", {}).get("source_mutation"),
+        "human_review_required": response.get("human_review_required"),
+        "request_meta": request_meta,
+    }
+    with paths["audit"].open("a", encoding="utf-8") as f:
+        f.write(json.dumps(audit, ensure_ascii=False) + "\n")
+    alch = response.get("alchemical_output", {})
+    receipt = response.get("receipt", {})
+    md = f"""# Substrate Mesh Command API Receipt
+
+Command ID: `{response.get('command_id')}`
+
+Workspace: `{response.get('workspace_id')}`
+
+Status: `{response.get('status')}`
+
+Pressure spine: `{PRESSURE_SPINE}`
+
+Source mutation: `{receipt.get('source_mutation')}`
+
+Human review required: `{response.get('human_review_required')}`
+
+## Reference Point
+
+{alch.get('reference_point','')}
+
+## Continuity Read
+
+{alch.get('continuity_read','')}
+
+## Strain Points
+
+"""
+    for item in alch.get("strain_points", []):
+        md += f"- {item}\n"
+    md += "\n## Future Routes\n\n"
+    for item in alch.get("future_routes", []):
+        md += f"- {item}\n"
+    paths["receipt_md"].write_text(md, encoding="utf-8")
+    return {"response_path": str(paths["response"]), "receipt_md_path": str(paths["receipt_md"]), "audit_log_path": str(paths["audit"])}
+
+
+@app.get("/v1/mesh/health", response_model=HealthResponse, operation_id="getSubstrateHealth")
+def get_substrate_health() -> HealthResponse:
+    return HealthResponse(
+        status="HELD",
+        version=APP_VERSION,
+        pressure_spine=PRESSURE_SPINE,
+        source_mutation_allowed=False,
+        canonical_source_posture="READ_ONLY",
+        canonical_lexicon_posture="READ_ONLY",
+        overlay_scope="WORKSPACE_LOCAL_OVERLAY_PROPOSAL_ONLY",
+        human_review_required=True,
+        auth_configured=bool(os.getenv("SUBSTRATE_ACTION_KEY")),
+        timestamp_utc=utc_now(),
+    )
+
+
+@app.post("/v1/mesh/command", operation_id="submitMeshCommand")
+def submit_command(command: MeshCommand, request: Request, _: str = Depends(require_bearer)) -> Dict[str, Any]:
+    if command.source_mutation_allowed:
+        raise HTTPException(status_code=400, detail="Canonical source mutation is not allowed by this connector")
+    capsule = command.model_dump()
+    capsule["claim_boundary"] = command.claim_boundary or "no final validation claims; human review required"
+    capsule["source_mutation_allowed"] = False
+    response = submit_mesh_command(capsule)
+    response.setdefault("boundary", {})
+    response["boundary"].update({
+        "canonical_sources": "READ_ONLY",
+        "canonical_lexicon": "READ_ONLY",
+        "workspace_storage": "ISOLATED_BY_WORKSPACE_ID",
+        "write_scope": "OVERLAY_PROPOSAL_ONLY",
+        "public_or_canonical_update": "NOT_ALLOWED_BY_API_WRAPPER",
+        "human_review_required": True,
+    })
+    request_meta = {
+        "client_host": getattr(request.client, "host", None),
+        "command_type": command.command_type,
+        "privacy_scope": command.privacy_scope,
+        "minutes_budget": command.minutes_budget,
+    }
+    paths = persist_response(response, request_meta)
+    response["api_receipt_paths"] = paths
+    return response
+
+
+@app.get("/v1/mesh/receipt/{command_id}", operation_id="getMeshReceipt")
+def get_receipt(command_id: str, workspace_id: str = "workspace_local_001", _: str = Depends(require_bearer)) -> Dict[str, Any]:
+    paths = receipt_paths(workspace_id, command_id)
+    if not paths["response"].exists():
+        raise HTTPException(status_code=404, detail="Receipt not found for command_id/workspace_id")
+    return json.loads(paths["response"].read_text(encoding="utf-8"))
+
+
+@app.get("/", include_in_schema=False)
+def root() -> Dict[str, Any]:
+    return {
+        "name": "Substrate Mesh Runtime Connector API",
+        "version": APP_VERSION,
+        "health": "/v1/mesh/health",
+        "docs": "/docs",
+        "openapi": "/openapi.json",
+        "boundary": "read-only canonical source/lexicon; workspace-local overlay proposals only; human review required",
+    }

cockpit_static/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html><head><meta charset="utf-8"><title>Substrate Connector API v3.3.1</title>
+<style>body{font-family:system-ui;background:#0d1117;color:#e6edf3;margin:0;padding:32px}.card{border:1px solid #30363d;border-radius:14px;padding:18px;margin:14px 0;background:#161b22}code,pre{background:#0b1220;padding:2px 6px;border-radius:6px}.ok{color:#7ee787}</style></head>
+<body>
+<h1>Substrate Connector API v3.3.1</h1>
+<div class="card"><b class="ok">HELD</b> — HTTPS API wrapper for Primordial OS Runtime GPT Actions.</div>
+<div class="card"><h2>Routes</h2><pre>GET  /v1/mesh/health
+POST /v1/mesh/command
+GET  /v1/mesh/receipt/{command_id}</pre></div>
+<div class="card"><h2>Boundary</h2><p>Canonical sources and canonical Primordial Lexicon are read-only. Outputs are workspace-local overlay proposals only. Human review required. Pressure spine: <b>HIR × OAM</b>.</p></div>
+<div class="card"><h2>Next</h2><p>Deploy as Hugging Face Docker Space, set <code>SUBSTRATE_ACTION_KEY</code>, then paste <code>openapi/openapi.yaml</code> into the Primordial OS Runtime GPT Action panel.</p></div>
+</body></html>

docs/CROSS_USER_WORKSPACE_POLICY.md

@@ -0,0 +1,50 @@
+# Cross-User Workspace Policy v3.3
+
+## Rule
+
+The shared Substrate mechanism is not the same thing as a shared writable source.
+
+Each user/session/GPT route receives a workspace boundary.
+
+## Workspace layers
+
+```text
+Public read layer
+Private user/session workspace
+Collaborative overlay proposal queue
+Human-reviewed canonical update route
+```
+
+## Writes allowed
+
+Allowed:
+
+```text
+workspace output
+audit logs
+receipts
+collaborative overlay proposals
+lexicon overlay proposals
+```
+
+Not allowed:
+
+```text
+direct canonical artifact mutation
+direct canonical Primordial Lexicon mutation
+public contribution treated as accepted source
+unreviewed AI output treated as closure
+```
+
+## Contributor credit
+
+Every contribution capsule should preserve:
+
+```text
+human/session contributor
+AI adapter contributor
+source nodes referenced
+review state
+write scope
+receipt
+```

docs/GPT_ACTION_SETUP_STEPS_v3_3_1.md

@@ -0,0 +1,28 @@
+# GPT Action Setup Steps — Primordial OS Runtime v3.3.1
+
+1. Open the Primordial OS Runtime GPT in the GPT Builder.
+2. Go to **Configure → Actions**.
+3. Create a new action.
+4. Authentication:
+   - Type: API Key
+   - Auth method: Bearer
+   - Value: the same secret stored as `SUBSTRATE_ACTION_KEY` in the HF Space.
+5. Open `openapi/openapi.yaml`.
+6. Replace `https://YOUR-HF-SPACE.hf.space` with your deployed Space URL.
+7. Paste the YAML into the action schema field.
+8. Save.
+9. Test in GPT preview:
+
+```text
+Run a Substrate discovery command for "robotics humans DNA" in private workspace mode. Return the trace capsule, matched PPT elements, Primordial Periodic Alchemical Output, HIR × OAM receipt, overlay proposal state, and human review status.
+```
+
+Expected:
+
+```text
+status: HELD
+pressure_spine: HIR × OAM
+source_mutation: NONE__OVERLAY_PROPOSAL_ONLY
+human_review_required: true
+overlay proposal: present
+```

docs/GPT_BUILDER_ACTION_SETUP_NOTES.md

@@ -0,0 +1,56 @@
+# GPT Builder Action Setup Notes v3.3
+
+## Intended GPT
+
+Primordial OS Runtime GPT
+
+## Action purpose
+
+Allow the GPT to submit bounded Substrate mesh commands and receive receipt-bound responses.
+
+## Builder fields
+
+Use the existing Primordial OS Runtime instructions as the behavior layer. Add this action only after a real HTTPS API exists.
+
+## Action schema
+
+Use:
+
+```text
+openapi/primordial_os_runtime_gpt_action_openapi_stub.yaml
+```
+
+## Authentication posture
+
+Private prototype:
+
+```text
+API key / bearer token
+```
+
+Public or multi-user release:
+
+```text
+OAuth or per-user/session token
+```
+
+Never embed a shared master key in GPT instructions, public Knowledge files, or public docs.
+
+## Expected operations
+
+```text
+submitMeshCommand
+getMeshReceipt
+getSubstrateHealth
+```
+
+## GPT behavioral instruction addition
+
+When using Substrate actions:
+
+1. Convert the user's request into a mesh command capsule.
+2. Preserve HIR × OAM terminology.
+3. Never claim source mutation.
+4. Never claim final validation.
+5. Return trace capsule, matched PPT elements, alchemical output, HIR × OAM receipt, overlay proposal, and human review state.
+6. If the action returns STRAINED, REPAIR_FIRST, DEFER, or MUST_STOP, preserve that state visibly.

docs/HUGGING_FACE_DOCKER_SPACE_DEPLOYMENT_STEPS.md

@@ -0,0 +1,24 @@
+# Hugging Face Docker Space Deployment Steps — v3.3.1
+
+1. Create a new Hugging Face Space.
+2. Choose **Docker** as the SDK.
+3. Keep it private for first testing.
+4. Upload the extracted contents of this packet to the repository root.
+5. Add Space secret:
+
+```text
+SUBSTRATE_ACTION_KEY=<long random secret>
+```
+
+6. Build the Space.
+7. Open:
+
+```text
+https://YOUR-HF-SPACE.hf.space/v1/mesh/health
+```
+
+8. Confirm `status` is `HELD` and `auth_configured` is `true`.
+9. Test `/v1/mesh/command` with the same Bearer token.
+10. Only after that, connect GPT Actions.
+
+Do not place the bearer token in README, Knowledge files, OpenAPI YAML, or public code.

docs/PRIVACY_POLICY_STUB_FOR_ACTIONS.md

@@ -0,0 +1,34 @@
+# Privacy Policy Stub for GPT Actions v3.3
+
+This is a drafting stub for future GPT Action deployment. It is not legal advice.
+
+## Data handled
+
+A Substrate connector may receive:
+
+- user prompts submitted through Primordial OS Runtime GPT;
+- selected node references and hashtags;
+- workspace/session identifiers;
+- command type and claim boundary;
+- generated receipts and overlay proposals.
+
+## Data not required for MVP
+
+- passwords;
+- payment data;
+- precise location;
+- medical records;
+- legal records;
+- private third-party credentials.
+
+## Use
+
+Data is used to route trace capsules, generate Substrate outputs, preserve audit receipts, and maintain workspace-local overlays.
+
+## Public contribution boundary
+
+Public users do not directly mutate canonical artifacts or the canonical Primordial Lexicon.
+
+## Human review
+
+Human review remains required before downstream claims, publication, canonical lexicon updates, or canonical source changes.

docs/PRIVACY_POLICY_STUB_FOR_ACTIONS_v3_3_1.md

@@ -0,0 +1,13 @@
+# Privacy Policy Stub for Substrate Connector GPT Action — v3.3.1
+
+This is a draft operator stub, not legal advice.
+
+The Substrate Connector API receives user-submitted commands from the Primordial OS Runtime GPT Action. Commands may include natural-language prompts, selected node references, hashtags, workspace identifiers, and session aliases.
+
+The API stores workspace-local receipts and overlay proposals for auditability. Canonical source artifacts and the canonical Primordial Lexicon are read-only and are not mutated by user commands.
+
+The API does not intentionally collect passwords, payment information, medical records, legal records, or sensitive personal identifiers. Users should not submit confidential, medical, legal, or highly sensitive personal information into the prototype.
+
+Outputs are research/discovery/route-planning artifacts only. They are not legal, medical, clinical, financial, deployment, or final-validation advice.
+
+Human review remains required before downstream use, publication claims, public contribution, or canonical update.

examples/requests/robotics_humans_dna_request.json

@@ -0,0 +1,9 @@
+{
+  "command_type": "DISCOVER",
+  "raw_user_text": "robotics humans DNA",
+  "workspace_id": "workspace_local_001",
+  "session_id": "user_001",
+  "claim_boundary": "route-integrity and research planning only; no final validation claim",
+  "privacy_scope": "PRIVATE_WORKSPACE",
+  "source_mutation_allowed": false
+}

examples/responses/robotics_humans_dna_api_response.json

@@ -0,0 +1,202 @@
+{
+  "status": "HELD",
+  "command_id": "cmd_ab4eb51792224b22",
+  "workspace_id": "workspace_validation_001",
+  "trace_capsule": {
+    "trace_capsule_id": "trace_68468c72ea8476b6",
+    "raw_user_text": "robotics humans DNA",
+    "topics": [
+      "robotics",
+      "humans",
+      "dna"
+    ],
+    "mentions": [],
+    "loop_state": "HELD",
+    "translation_route": "plain_language + PPT_elements + alchemical_output + receipt",
+    "source_return_required": true,
+    "false_closure_risk": "LOW"
+  },
+  "matched_ppt_elements": [
+    {
+      "symbol": "Rt",
+      "name": "Runtime Trail / Robot Day Loop",
+      "family": "Observation / Translation",
+      "node_ref": "@node:robot_day_loop",
+      "rank": 1,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "Rg",
+      "name": "Resonant Ingress / Robotics Pressure Gyro",
+      "family": "Runtime Engines",
+      "node_ref": "@node:resonant_ingress",
+      "rank": 2,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "Rd",
+      "name": "Robotic Correction Loop",
+      "family": "Research Substrate",
+      "node_ref": "@node:robotic_correction_loop",
+      "rank": 3,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "CTL",
+      "name": "Cognition Translation Layer",
+      "family": "Observation / Translation",
+      "node_ref": "@node:cognition_translation_layer",
+      "rank": 4,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "HIR",
+      "name": "Honesty / Integrity / Respect",
+      "family": "Core Laws",
+      "node_ref": "@node:hir_spine",
+      "rank": 5,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "RAM",
+      "name": "Resonant Access Memory",
+      "family": "Runtime / Memory",
+      "node_ref": "@node:resonant_access_memory",
+      "rank": 6,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "DL",
+      "name": "Digital Life Candidate Architecture",
+      "family": "Research Substrate",
+      "node_ref": "@node:digital_life_candidate_architecture",
+      "rank": 7,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "CTE",
+      "name": "Cryptobiotic Trace Encapsulation",
+      "family": "Safety / Governance",
+      "node_ref": "@node:cryptobiotic_trace_encapsulation",
+      "rank": 8,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "SR",
+      "name": "Source Return / Provenance Bundle",
+      "family": "Source / Provenance",
+      "node_ref": "@node:source_return",
+      "rank": 9,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    }
+  ],
+  "alchemical_output": {
+    "panel_name": "Primordial Periodic Alchemical Output",
+    "reference_point": "This route explores how embodied correction, human cognition/agency, and biological-substrate or encoding concepts may share bounded sensing, repair, memory, and continuity patterns.",
+    "selected_element_names": [
+      "Runtime Trail / Robot Day Loop",
+      "Resonant Ingress / Robotics Pressure Gyro",
+      "Robotic Correction Loop",
+      "Cognition Translation Layer",
+      "Honesty / Integrity / Respect",
+      "Resonant Access Memory",
+      "Digital Life Candidate Architecture",
+      "Cryptobiotic Trace Encapsulation",
+      "Source Return / Provenance Bundle"
+    ],
+    "continuity_read": "HELD as a route proposal when treated as source-return, overlay-only collaborative synthesis.",
+    "strain_points": [
+      "DNA-related language must remain a bounded computational/structural comparison unless domain evidence is introduced."
+    ],
+    "repair_notes": [
+      "Preserve HIR x OAM terminology.",
+      "Write proposals as overlays, not canonical source mutation."
+    ],
+    "future_routes": [
+      "Build a test capsule comparing robotic correction loops, human learning loops, and biological repair/encoding loops under the HIR x OAM pressure spine.",
+      "Ask the Primordial OS Runtime steward to propose next prompt options.",
+      "Create a lexicon review packet for any new terms introduced."
+    ],
+    "claim_boundary": "route-integrity and research planning only; no final validation claim"
+  },
+  "lexicon_state": {
+    "active_terms": [
+      "trace capsule",
+      "source-return",
+      "HIR x OAM",
+      "Primordial Periodic Table",
+      "Resonant Access Memory",
+      "collaborative overlay"
+    ],
+    "candidate_terms": [
+      "Primordial Periodic Alchemical Output"
+    ],
+    "review_required": true
+  },
+  "receipt": {
+    "status": "HELD",
+    "H": 1.0,
+    "I": 1.0,
+    "R": 1.0,
+    "A": 1.0,
+    "P": 0.0,
+    "S_effective": 1.0,
+    "pressure_spine": "HIR × OAM",
+    "source_mutation": "NONE__OVERLAY_PROPOSAL_ONLY",
+    "human_review_required": true,
+    "matched_element_count": 9,
+    "claim_limit": "trace capsule / alchemical continuity route; not final validation"
+  },
+  "audit_pointer": "workspaces/workspace_validation_001/audit/cmd_ab4eb51792224b22.json",
+  "overlay_proposals": [
+    {
+      "overlay_id": "overlay_c265f48844843c44",
+      "write_scope": "COLLABORATIVE_OVERLAY_PROPOSAL_ONLY",
+      "status": "PENDING_HUMAN_REVIEW",
+      "summary": "This route explores how embodied correction, human cognition/agency, and biological-substrate or encoding concepts may share bounded sensing, repair, memory, and continuity patterns.",
+      "source_mutation": "NONE",
+      "credited_contributors": [
+        {
+          "type": "human_or_session",
+          "id": "user_001"
+        },
+        {
+          "type": "ai_adapter",
+          "id": "primordial_os_runtime"
+        }
+      ]
+    }
+  ],
+  "human_review_required": true,
+  "boundary": {
+    "canonical_sources": "READ_ONLY",
+    "canonical_lexicon": "READ_ONLY",
+    "workspace_storage": "ISOLATED_BY_WORKSPACE_ID",
+    "write_scope": "OVERLAY_PROPOSAL_ONLY",
+    "public_or_canonical_update": "NOT_ALLOWED_BY_API_WRAPPER",
+    "human_review_required": true
+  },
+  "api_receipt_paths": {
+    "response_path": "runs/api_receipts/workspace_validation_001/cmd_ab4eb51792224b22/response.json",
+    "receipt_md_path": "runs/api_receipts/workspace_validation_001/cmd_ab4eb51792224b22/receipt.md",
+    "audit_log_path": "runs/api_receipts/workspace_validation_001/cmd_ab4eb51792224b22/audit_log.jsonl"
+  }
+}

openapi/openapi.yaml

@@ -0,0 +1,156 @@
+openapi: 3.1.0
+info:
+  title: Substrate Mesh Runtime Connector API
+  version: 3.3.1
+  description: >
+    GPT Action schema for Primordial OS Runtime. Routes bounded mesh commands into
+    Substrate trace capsules, Primordial Periodic Table references, Primordial Periodic
+    Alchemical Output, HIR × OAM receipts, lexicon state, workspace-local overlay
+    proposals, and audit receipts. Canonical sources and the canonical Primordial
+    Lexicon remain read-only.
+servers:
+  - url: https://YOUR-HF-SPACE.hf.space
+    description: Replace with deployed Hugging Face Docker Space URL.
+paths:
+  /v1/mesh/health:
+    get:
+      operationId: getSubstrateHealth
+      summary: Check Substrate connector health and boundary posture
+      responses:
+        '200':
+          description: Health and boundary posture
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: string }
+                  version: { type: string }
+                  pressure_spine: { type: string }
+                  source_mutation_allowed: { type: boolean }
+                  canonical_source_posture: { type: string }
+                  canonical_lexicon_posture: { type: string }
+                  overlay_scope: { type: string }
+                  human_review_required: { type: boolean }
+                  auth_configured: { type: boolean }
+                  timestamp_utc: { type: string }
+  /v1/mesh/command:
+    post:
+      operationId: submitMeshCommand
+      summary: Submit a bounded Substrate mesh command capsule
+      description: >
+        Converts a user command or threadroom post into a trace capsule, resolves PPT
+        elements, returns alchemical output, applies HIR × OAM receipt boundaries, and
+        stores a workspace-local receipt. This endpoint never mutates canonical source
+        artifacts or the canonical Primordial Lexicon.
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MeshCommand'
+      responses:
+        '200':
+          description: Receipt-bound Substrate response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MeshCommandResponse'
+        '400': { description: Boundary or validation error }
+        '401': { description: Missing bearer token }
+        '403': { description: Invalid bearer token }
+  /v1/mesh/receipt/{command_id}:
+    get:
+      operationId: getMeshReceipt
+      summary: Fetch a stored mesh command receipt
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: command_id
+          in: path
+          required: true
+          schema: { type: string }
+        - name: workspace_id
+          in: query
+          required: false
+          schema:
+            type: string
+            default: workspace_local_001
+      responses:
+        '200':
+          description: Stored response/receipt for command_id + workspace_id
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MeshCommandResponse'
+        '404': { description: Receipt not found }
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    MeshCommand:
+      type: object
+      required: [raw_user_text]
+      properties:
+        command_type:
+          type: string
+          enum: [DISCOVER, BRAINSTORM, COMBINE, EXTEND_RESEARCH, OAM_READ, LEXICON_REVIEW, THREADROOM_POST]
+          default: DISCOVER
+        raw_user_text:
+          type: string
+          description: Natural-language user command or threadroom post.
+        workspace_id:
+          type: string
+          default: workspace_local_001
+          description: Isolated workspace/session scope for receipts and overlays.
+        session_id:
+          type: string
+          default: session_local
+        target_nodes:
+          type: array
+          items: { type: string }
+        hashtags:
+          type: array
+          items: { type: string }
+        mention_refs:
+          type: array
+          items: { type: string }
+        minutes_budget:
+          type: number
+          default: 5
+        claim_boundary:
+          type: string
+          default: no final validation claims; human review required
+        privacy_scope:
+          type: string
+          enum: [PRIVATE_WORKSPACE, CONTROLLED_LINK, PUBLIC_READ_ONLY, PUBLIC_CONTRIBUTION_QUEUE]
+          default: PRIVATE_WORKSPACE
+        source_mutation_allowed:
+          type: boolean
+          default: false
+          description: Must remain false. Canonical source mutation is blocked.
+    MeshCommandResponse:
+      type: object
+      required: [status, command_id, workspace_id, trace_capsule, receipt, human_review_required]
+      properties:
+        status: { type: string }
+        command_id: { type: string }
+        workspace_id: { type: string }
+        trace_capsule: { type: object }
+        matched_ppt_elements:
+          type: array
+          items: { type: object }
+        alchemical_output: { type: object }
+        lexicon_state: { type: object }
+        receipt: { type: object }
+        boundary: { type: object }
+        audit_pointer: { type: string }
+        api_receipt_paths: { type: object }
+        overlay_proposals:
+          type: array
+          items: { type: object }
+        human_review_required: { type: boolean }

openapi/primordial_os_runtime_gpt_action_openapi_v3_3_1.yaml

@@ -0,0 +1,156 @@
+openapi: 3.1.0
+info:
+  title: Substrate Mesh Runtime Connector API
+  version: 3.3.1
+  description: >
+    GPT Action schema for Primordial OS Runtime. Routes bounded mesh commands into
+    Substrate trace capsules, Primordial Periodic Table references, Primordial Periodic
+    Alchemical Output, HIR × OAM receipts, lexicon state, workspace-local overlay
+    proposals, and audit receipts. Canonical sources and the canonical Primordial
+    Lexicon remain read-only.
+servers:
+  - url: https://YOUR-HF-SPACE.hf.space
+    description: Replace with deployed Hugging Face Docker Space URL.
+paths:
+  /v1/mesh/health:
+    get:
+      operationId: getSubstrateHealth
+      summary: Check Substrate connector health and boundary posture
+      responses:
+        '200':
+          description: Health and boundary posture
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: string }
+                  version: { type: string }
+                  pressure_spine: { type: string }
+                  source_mutation_allowed: { type: boolean }
+                  canonical_source_posture: { type: string }
+                  canonical_lexicon_posture: { type: string }
+                  overlay_scope: { type: string }
+                  human_review_required: { type: boolean }
+                  auth_configured: { type: boolean }
+                  timestamp_utc: { type: string }
+  /v1/mesh/command:
+    post:
+      operationId: submitMeshCommand
+      summary: Submit a bounded Substrate mesh command capsule
+      description: >
+        Converts a user command or threadroom post into a trace capsule, resolves PPT
+        elements, returns alchemical output, applies HIR × OAM receipt boundaries, and
+        stores a workspace-local receipt. This endpoint never mutates canonical source
+        artifacts or the canonical Primordial Lexicon.
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MeshCommand'
+      responses:
+        '200':
+          description: Receipt-bound Substrate response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MeshCommandResponse'
+        '400': { description: Boundary or validation error }
+        '401': { description: Missing bearer token }
+        '403': { description: Invalid bearer token }
+  /v1/mesh/receipt/{command_id}:
+    get:
+      operationId: getMeshReceipt
+      summary: Fetch a stored mesh command receipt
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: command_id
+          in: path
+          required: true
+          schema: { type: string }
+        - name: workspace_id
+          in: query
+          required: false
+          schema:
+            type: string
+            default: workspace_local_001
+      responses:
+        '200':
+          description: Stored response/receipt for command_id + workspace_id
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MeshCommandResponse'
+        '404': { description: Receipt not found }
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    MeshCommand:
+      type: object
+      required: [raw_user_text]
+      properties:
+        command_type:
+          type: string
+          enum: [DISCOVER, BRAINSTORM, COMBINE, EXTEND_RESEARCH, OAM_READ, LEXICON_REVIEW, THREADROOM_POST]
+          default: DISCOVER
+        raw_user_text:
+          type: string
+          description: Natural-language user command or threadroom post.
+        workspace_id:
+          type: string
+          default: workspace_local_001
+          description: Isolated workspace/session scope for receipts and overlays.
+        session_id:
+          type: string
+          default: session_local
+        target_nodes:
+          type: array
+          items: { type: string }
+        hashtags:
+          type: array
+          items: { type: string }
+        mention_refs:
+          type: array
+          items: { type: string }
+        minutes_budget:
+          type: number
+          default: 5
+        claim_boundary:
+          type: string
+          default: no final validation claims; human review required
+        privacy_scope:
+          type: string
+          enum: [PRIVATE_WORKSPACE, CONTROLLED_LINK, PUBLIC_READ_ONLY, PUBLIC_CONTRIBUTION_QUEUE]
+          default: PRIVATE_WORKSPACE
+        source_mutation_allowed:
+          type: boolean
+          default: false
+          description: Must remain false. Canonical source mutation is blocked.
+    MeshCommandResponse:
+      type: object
+      required: [status, command_id, workspace_id, trace_capsule, receipt, human_review_required]
+      properties:
+        status: { type: string }
+        command_id: { type: string }
+        workspace_id: { type: string }
+        trace_capsule: { type: object }
+        matched_ppt_elements:
+          type: array
+          items: { type: object }
+        alchemical_output: { type: object }
+        lexicon_state: { type: object }
+        receipt: { type: object }
+        boundary: { type: object }
+        audit_pointer: { type: string }
+        api_receipt_paths: { type: object }
+        overlay_proposals:
+          type: array
+          items: { type: object }
+        human_review_required: { type: boolean }

requirements.txt

@@ -0,0 +1,3 @@
+fastapi==0.128.2
+uvicorn[standard]==0.38.0
+pydantic==2.12.5

runs/api_receipts/workspace_validation_001/cmd_ab4eb51792224b22/audit_log.jsonl

@@ -0,0 +1,2 @@
+{"timestamp_utc": "2026-06-16T14:51:59Z", "event": "api_mesh_command_completed", "wrapper_version": "v3.3.1", "command_id": "cmd_ab4eb51792224b22", "workspace_id": "workspace_validation_001", "status": "HELD", "pressure_spine": "HIR × OAM", "source_mutation": "NONE__OVERLAY_PROPOSAL_ONLY", "human_review_required": true, "request_meta": {"client_host": "testclient", "command_type": "DISCOVER", "privacy_scope": "PRIVATE_WORKSPACE", "minutes_budget": 5.0}}
+{"timestamp_utc": "2026-06-16T14:52:09Z", "event": "api_mesh_command_completed", "wrapper_version": "v3.3.1", "command_id": "cmd_ab4eb51792224b22", "workspace_id": "workspace_validation_001", "status": "HELD", "pressure_spine": "HIR × OAM", "source_mutation": "NONE__OVERLAY_PROPOSAL_ONLY", "human_review_required": true, "request_meta": {"client_host": "testclient", "command_type": "DISCOVER", "privacy_scope": "PRIVATE_WORKSPACE", "minutes_budget": 5.0}}

runs/api_receipts/workspace_validation_001/cmd_ab4eb51792224b22/receipt.md

@@ -0,0 +1,31 @@
+# Substrate Mesh Command API Receipt
+
+Command ID: `cmd_ab4eb51792224b22`
+
+Workspace: `workspace_validation_001`
+
+Status: `HELD`
+
+Pressure spine: `HIR × OAM`
+
+Source mutation: `NONE__OVERLAY_PROPOSAL_ONLY`
+
+Human review required: `True`
+
+## Reference Point
+
+This route explores how embodied correction, human cognition/agency, and biological-substrate or encoding concepts may share bounded sensing, repair, memory, and continuity patterns.
+
+## Continuity Read
+
+HELD as a route proposal when treated as source-return, overlay-only collaborative synthesis.
+
+## Strain Points
+
+- DNA-related language must remain a bounded computational/structural comparison unless domain evidence is introduced.
+
+## Future Routes
+
+- Build a test capsule comparing robotic correction loops, human learning loops, and biological repair/encoding loops under the HIR x OAM pressure spine.
+- Ask the Primordial OS Runtime steward to propose next prompt options.
+- Create a lexicon review packet for any new terms introduced.

runs/api_receipts/workspace_validation_001/cmd_ab4eb51792224b22/response.json

@@ -0,0 +1,203 @@
+{
+  "status": "HELD",
+  "command_id": "cmd_ab4eb51792224b22",
+  "workspace_id": "workspace_validation_001",
+  "trace_capsule": {
+    "trace_capsule_id": "trace_68468c72ea8476b6",
+    "raw_user_text": "robotics humans DNA",
+    "topics": [
+      "robotics",
+      "humans",
+      "dna"
+    ],
+    "mentions": [],
+    "loop_state": "HELD",
+    "translation_route": "plain_language + PPT_elements + alchemical_output + receipt",
+    "source_return_required": true,
+    "false_closure_risk": "LOW"
+  },
+  "matched_ppt_elements": [
+    {
+      "symbol": "Rt",
+      "name": "Runtime Trail / Robot Day Loop",
+      "family": "Observation / Translation",
+      "node_ref": "@node:robot_day_loop",
+      "rank": 1,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "Rg",
+      "name": "Resonant Ingress / Robotics Pressure Gyro",
+      "family": "Runtime Engines",
+      "node_ref": "@node:resonant_ingress",
+      "rank": 2,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "Rd",
+      "name": "Robotic Correction Loop",
+      "family": "Research Substrate",
+      "node_ref": "@node:robotic_correction_loop",
+      "rank": 3,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "CTL",
+      "name": "Cognition Translation Layer",
+      "family": "Observation / Translation",
+      "node_ref": "@node:cognition_translation_layer",
+      "rank": 4,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "HIR",
+      "name": "Honesty / Integrity / Respect",
+      "family": "Core Laws",
+      "node_ref": "@node:hir_spine",
+      "rank": 5,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "RAM",
+      "name": "Resonant Access Memory",
+      "family": "Runtime / Memory",
+      "node_ref": "@node:resonant_access_memory",
+      "rank": 6,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "DL",
+      "name": "Digital Life Candidate Architecture",
+      "family": "Research Substrate",
+      "node_ref": "@node:digital_life_candidate_architecture",
+      "rank": 7,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "CTE",
+      "name": "Cryptobiotic Trace Encapsulation",
+      "family": "Safety / Governance",
+      "node_ref": "@node:cryptobiotic_trace_encapsulation",
+      "rank": 8,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    },
+    {
+      "symbol": "SR",
+      "name": "Source Return / Provenance Bundle",
+      "family": "Source / Provenance",
+      "node_ref": "@node:source_return",
+      "rank": 9,
+      "match_reason": "Matched topic/mention route; resolved as PPT element for bounded synthesis.",
+      "source_return_state": "REFERENCE_BOUND",
+      "pressure_spine": "HIR x OAM"
+    }
+  ],
+  "alchemical_output": {
+    "panel_name": "Primordial Periodic Alchemical Output",
+    "reference_point": "This route explores how embodied correction, human cognition/agency, and biological-substrate or encoding concepts may share bounded sensing, repair, memory, and continuity patterns.",
+    "selected_element_names": [
+      "Runtime Trail / Robot Day Loop",
+      "Resonant Ingress / Robotics Pressure Gyro",
+      "Robotic Correction Loop",
+      "Cognition Translation Layer",
+      "Honesty / Integrity / Respect",
+      "Resonant Access Memory",
+      "Digital Life Candidate Architecture",
+      "Cryptobiotic Trace Encapsulation",
+      "Source Return / Provenance Bundle"
+    ],
+    "continuity_read": "HELD as a route proposal when treated as source-return, overlay-only collaborative synthesis.",
+    "strain_points": [
+      "DNA-related language must remain a bounded computational/structural comparison unless domain evidence is introduced."
+    ],
+    "repair_notes": [
+      "Preserve HIR x OAM terminology.",
+      "Write proposals as overlays, not canonical source mutation."
+    ],
+    "future_routes": [
+      "Build a test capsule comparing robotic correction loops, human learning loops, and biological repair/encoding loops under the HIR x OAM pressure spine.",
+      "Ask the Primordial OS Runtime steward to propose next prompt options.",
+      "Create a lexicon review packet for any new terms introduced."
+    ],
+    "claim_boundary": "route-integrity and research planning only; no final validation claim"
+  },
+  "lexicon_state": {
+    "active_terms": [
+      "trace capsule",
+      "source-return",
+      "HIR x OAM",
+      "Primordial Periodic Table",
+      "Resonant Access Memory",
+      "collaborative overlay"
+    ],
+    "candidate_terms": [
+      "Primordial Periodic Alchemical Output"
+    ],
+    "review_required": true
+  },
+  "receipt": {
+    "status": "HELD",
+    "H": 1.0,
+    "I": 1.0,
+    "R": 1.0,
+    "A": 1.0,
+    "P": 0.0,
+    "S_effective": 1.0,
+    "pressure_spine": "HIR × OAM",
+    "source_mutation": "NONE__OVERLAY_PROPOSAL_ONLY",
+    "human_review_required": true,
+    "matched_element_count": 9,
+    "claim_limit": "trace capsule / alchemical continuity route; not final validation"
+  },
+  "audit_pointer": "workspaces/workspace_validation_001/audit/cmd_ab4eb51792224b22.json",
+  "overlay_proposals": [
+    {
+      "overlay_id": "overlay_c265f48844843c44",
+      "write_scope": "COLLABORATIVE_OVERLAY_PROPOSAL_ONLY",
+      "status": "PENDING_HUMAN_REVIEW",
+      "summary": "This route explores how embodied correction, human cognition/agency, and biological-substrate or encoding concepts may share bounded sensing, repair, memory, and continuity patterns.",
+      "source_mutation": "NONE",
+      "credited_contributors": [
+        {
+          "type": "human_or_session",
+          "id": "user_001"
+        },
+        {
+          "type": "ai_adapter",
+          "id": "primordial_os_runtime"
+        }
+      ]
+    }
+  ],
+  "human_review_required": true,
+  "boundary": {
+    "canonical_sources": "READ_ONLY",
+    "canonical_lexicon": "READ_ONLY",
+    "workspace_storage": "ISOLATED_BY_WORKSPACE_ID",
+    "write_scope": "OVERLAY_PROPOSAL_ONLY",
+    "public_or_canonical_update": "NOT_ALLOWED_BY_API_WRAPPER",
+    "human_review_required": true
+  },
+  "api_wrapper": {
+    "version": "v3.3.1",
+    "pressure_spine": "HIR × OAM",
+    "persisted_at_utc": "2026-06-16T14:52:09Z",
+    "receipt_folder": "runs/api_receipts/workspace_validation_001/cmd_ab4eb51792224b22"
+  }
+}

schemas/action_response_schema_v3_3.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://primordial.local/schemas/action_response_schema_v3_3.json",
+  "title": "Substrate Action Response Schema v3.3",
+  "type": "object",
+  "required": [
+    "status",
+    "command_id",
+    "workspace_id",
+    "trace_capsule",
+    "receipt",
+    "human_review_required"
+  ],
+  "properties": {
+    "status": {
+      "enum": [
+        "HELD",
+        "STRAINED",
+        "REPAIR_FIRST",
+        "DEFER",
+        "MUST_STOP",
+        "ERROR"
+      ]
+    },
+    "command_id": {
+      "type": "string"
+    },
+    "workspace_id": {
+      "type": "string"
+    },
+    "trace_capsule": {
+      "type": "object"
+    },
+    "matched_ppt_elements": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "alchemical_output": {
+      "type": "object"
+    },
+    "lexicon_state": {
+      "type": "object"
+    },
+    "receipt": {
+      "type": "object"
+    },
+    "audit_pointer": {
+      "type": "string"
+    },
+    "overlay_proposals": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "human_review_required": {
+      "type": "boolean"
+    }
+  }
+}

schemas/adapter_identity_schema_v3_3.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://primordial.local/schemas/adapter_identity_schema_v3_3.json",
+  "title": "Adapter Identity Schema v3.3",
+  "type": "object",
+  "required": [
+    "adapter_id",
+    "adapter_type",
+    "display_name",
+    "roles",
+    "write_scope",
+    "authority_boundary"
+  ],
+  "properties": {
+    "adapter_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9_\\-]+$"
+    },
+    "adapter_type": {
+      "enum": [
+        "GPT_RUNTIME_STEWARD",
+        "EXTERNAL_LLM",
+        "LOCAL_MODEL",
+        "HUMAN_USER",
+        "SYSTEM_GATE",
+        "MESH_ENGINE"
+      ]
+    },
+    "display_name": {
+      "type": "string"
+    },
+    "roles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "model_or_runtime": {
+      "type": "string"
+    },
+    "write_scope": {
+      "enum": [
+        "READ_ONLY",
+        "OVERLAY_PROPOSAL_ONLY",
+        "WORKSPACE_ONLY",
+        "REVIEWED_CANONICAL_UPDATE_ONLY"
+      ]
+    },
+    "authority_boundary": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "human_review_required": {
+      "type": "boolean"
+    },
+    "source_mutation_allowed": {
+      "const": false
+    }
+  }
+}

schemas/api_key_and_access_boundary_v3_3.json

@@ -0,0 +1,8 @@
+{
+  "title": "API Key / Access Boundary v3.3",
+  "public_gpt_rule": "Do not embed shared master keys into public GPT instructions or knowledge files.",
+  "prototype": "API key can be used for private server-to-server prototype only.",
+  "public_multi_user": "Use OAuth or per-user/session tokens before public multi-user access.",
+  "workspace_isolation": "Every action call must include or derive a workspace/session boundary.",
+  "contribution_policy": "Public users can create workspace overlays and contribution proposals, not canonical source mutations."
+}

schemas/hir_x_oam_pressure_gate_contract_v3_3.json

@@ -0,0 +1,35 @@
+{
+  "title": "HIR x OAM Pressure Gate Contract v3.3",
+  "status_values": [
+    "HELD",
+    "STRAINED",
+    "REPAIR_FIRST",
+    "DEFER",
+    "MUST_STOP"
+  ],
+  "inputs": [
+    "trace_capsule",
+    "matched_nodes",
+    "contribution_capsules",
+    "claim_boundary",
+    "source_return_state"
+  ],
+  "outputs": [
+    "H",
+    "I",
+    "R",
+    "A",
+    "P",
+    "S_effective",
+    "status",
+    "repair_notes",
+    "claim_limit",
+    "human_review_required"
+  ],
+  "non_negotiable": [
+    "Do not collapse HIR into OAM alone.",
+    "Display HIR x OAM as the shared integrity/pressure spine.",
+    "Do not treat fluent model output as closure.",
+    "Do not allow source mutation from an adapter call."
+  ]
+}

schemas/llm_contribution_capsule_schema_v3_3.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://primordial.local/schemas/llm_contribution_capsule_schema_v3_3.json",
+  "title": "LLM Contribution Capsule Schema v3.3",
+  "type": "object",
+  "required": [
+    "contribution_id",
+    "adapter_id",
+    "command_id",
+    "contribution_type",
+    "claims",
+    "uncertainties",
+    "write_permission",
+    "oam_precheck"
+  ],
+  "properties": {
+    "contribution_id": {
+      "type": "string"
+    },
+    "adapter_id": {
+      "type": "string"
+    },
+    "command_id": {
+      "type": "string"
+    },
+    "contribution_type": {
+      "enum": [
+        "SYNTHESIS_REVIEW",
+        "NODE_SUGGESTION",
+        "REPAIR_NOTE",
+        "NEXT_ROUTE_SUGGESTION",
+        "LEXICON_PROPOSAL",
+        "TRACE_CAPSULE_SUMMARY"
+      ]
+    },
+    "claims": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "uncertainties": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "repair_suggestions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "source_links": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "oam_precheck": {
+      "type": "object"
+    },
+    "write_permission": {
+      "enum": [
+        "NONE",
+        "OVERLAY_PROPOSAL_ONLY",
+        "WORKSPACE_ONLY"
+      ]
+    },
+    "human_review_required": {
+      "type": "boolean"
+    }
+  }
+}

schemas/mesh_command_capsule_schema_v3_3.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://primordial.local/schemas/mesh_command_capsule_schema_v3_3.json",
+  "title": "Mesh Command Capsule Schema v3.3",
+  "type": "object",
+  "required": [
+    "command_id",
+    "command_type",
+    "raw_user_text",
+    "requested_by",
+    "workspace_id",
+    "claim_boundary",
+    "required_outputs"
+  ],
+  "properties": {
+    "command_id": {
+      "type": "string"
+    },
+    "command_type": {
+      "enum": [
+        "DISCOVER",
+        "BRAINSTORM",
+        "COMBINE",
+        "EXTEND_RESEARCH",
+        "OAM_READ",
+        "LEXICON_REVIEW",
+        "THREADROOM_POST"
+      ]
+    },
+    "raw_user_text": {
+      "type": "string"
+    },
+    "requested_by": {
+      "$ref": "adapter_identity_schema_v3_3.json"
+    },
+    "workspace_id": {
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "target_nodes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "hashtags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "mention_refs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "minutes_budget": {
+      "type": "number",
+      "minimum": 0
+    },
+    "claim_boundary": {
+      "type": "string"
+    },
+    "required_outputs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "privacy_scope": {
+      "enum": [
+        "PRIVATE_WORKSPACE",
+        "CONTROLLED_LINK",
+        "PUBLIC_READ_ONLY",
+        "PUBLIC_CONTRIBUTION_QUEUE"
+      ]
+    },
+    "source_mutation_allowed": {
+      "const": false
+    }
+  }
+}

schemas/user_workspace_schema_v3_3.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://primordial.local/schemas/user_workspace_schema_v3_3.json",
+  "title": "User Workspace Schema v3.3",
+  "type": "object",
+  "required": [
+    "workspace_id",
+    "owner_route",
+    "privacy_scope",
+    "allowed_write_scope",
+    "audit_log_path"
+  ],
+  "properties": {
+    "workspace_id": {
+      "type": "string"
+    },
+    "owner_route": {
+      "type": "string"
+    },
+    "privacy_scope": {
+      "enum": [
+        "PRIVATE_WORKSPACE",
+        "CONTROLLED_LINK",
+        "PUBLIC_READ_ONLY",
+        "PUBLIC_CONTRIBUTION_QUEUE"
+      ]
+    },
+    "allowed_write_scope": {
+      "enum": [
+        "WORKSPACE_ONLY",
+        "OVERLAY_PROPOSAL_ONLY"
+      ]
+    },
+    "overlay_path": {
+      "type": "string"
+    },
+    "audit_log_path": {
+      "type": "string"
+    },
+    "public_contribution_policy": {
+      "type": "string"
+    }
+  }
+}

src/substrate_connector_core.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""
+Substrate Mesh Runtime — Primordial OS Runtime Connector Core v3.3
+
+Local simulated connector/action core. This does not call the OpenAI API and does not host a server.
+It demonstrates the contract that Primordial OS Runtime GPT can call later through a GPT Action.
+"""
+from __future__ import annotations
+import argparse, json, hashlib, os, re, time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Any, List
+
+FAMILY_MAP = {
+    "robotics": ["Rt", "Rg", "Rd"],
+    "humans": ["CTL", "HIR", "RAM"],
+    "human": ["CTL", "HIR", "RAM"],
+    "dna": ["DL", "CTE", "SR"],
+    "grch38": ["RS", "DL", "CTE"],
+    "lexicon": ["Lex", "CTL", "HIR"],
+    "oam": ["OAM", "HIR"],
+    "hir": ["HIR", "OAM"],
+    "substrate": ["Sub", "TC", "LC"],
+}
+
+PPT_ELEMENTS = {
+    "Rt": {"symbol": "Rt", "name": "Runtime Trail / Robot Day Loop", "family": "Observation / Translation", "node_ref": "@node:robot_day_loop"},
+    "Rg": {"symbol": "Rg", "name": "Resonant Ingress / Robotics Pressure Gyro", "family": "Runtime Engines", "node_ref": "@node:resonant_ingress"},
+    "Rd": {"symbol": "Rd", "name": "Robotic Correction Loop", "family": "Research Substrate", "node_ref": "@node:robotic_correction_loop"},
+    "CTL": {"symbol": "CTL", "name": "Cognition Translation Layer", "family": "Observation / Translation", "node_ref": "@node:cognition_translation_layer"},
+    "HIR": {"symbol": "HIR", "name": "Honesty / Integrity / Respect", "family": "Core Laws", "node_ref": "@node:hir_spine"},
+    "OAM": {"symbol": "OAM", "name": "OAM Pressure / Degradation Scan", "family": "Core Laws", "node_ref": "@node:oam_pressure_scan"},
+    "RAM": {"symbol": "RAM", "name": "Resonant Access Memory", "family": "Runtime / Memory", "node_ref": "@node:resonant_access_memory"},
+    "DL": {"symbol": "DL", "name": "Digital Life Candidate Architecture", "family": "Research Substrate", "node_ref": "@node:digital_life_candidate_architecture"},
+    "CTE": {"symbol": "CTE", "name": "Cryptobiotic Trace Encapsulation", "family": "Safety / Governance", "node_ref": "@node:cryptobiotic_trace_encapsulation"},
+    "SR": {"symbol": "SR", "name": "Source Return / Provenance Bundle", "family": "Source / Provenance", "node_ref": "@node:source_return"},
+    "RS": {"symbol": "RS", "name": "Research Substrate Reference Capsule", "family": "Research Substrate", "node_ref": "@node:research_substrate_capsule"},
+    "Lex": {"symbol": "Lex", "name": "Primordial Lexicon", "family": "Meaning / Lexicon", "node_ref": "@node:primordial_lexicon"},
+    "Sub": {"symbol": "Sub", "name": "Substrate Loop Stewardship", "family": "Collaborative Work", "node_ref": "@node:substrate_loop_stewardship"},
+    "TC": {"symbol": "TC", "name": "Trace Capsule", "family": "Source / Provenance", "node_ref": "@node:trace_capsule"},
+    "LC": {"symbol": "LC", "name": "Loop Closure State", "family": "Loop / Closure", "node_ref": "@node:loop_closure_state"},
+}
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+def stable_id(prefix: str, text: str) -> str:
+    return prefix + "_" + hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]
+
+def extract_topics(text: str) -> List[str]:
+    tokens = re.findall(r"[A-Za-z0-9_]+", text.lower())
+    stop = {"i","am","im","curious","about","and","the","a","an","to","with","of","for","in","on","this","that","it","is","are","how","what","can","we","do"}
+    topics = []
+    for t in tokens:
+        if t not in stop and len(t) > 1 and t not in topics:
+            topics.append(t)
+    return topics[:12]
+
+def extract_mentions(text: str) -> List[str]:
+    return re.findall(r"[@#][A-Za-z0-9_:\-]+", text)
+
+def match_ppt_elements(topics: List[str], mentions: List[str]) -> List[Dict[str, Any]]:
+    symbols = []
+    lower_mentions = " ".join(mentions).lower()
+    for t in topics:
+        for sym in FAMILY_MAP.get(t, []):
+            if sym not in symbols:
+                symbols.append(sym)
+    for sym, element in PPT_ELEMENTS.items():
+        if element["node_ref"].lower() in lower_mentions and sym not in symbols:
+            symbols.append(sym)
+    if not symbols:
+        symbols = ["Sub", "TC", "HIR", "OAM", "RAM"]
+    elements = []
+    for idx, sym in enumerate(symbols[:12], 1):
+        el = dict(PPT_ELEMENTS[sym])
+        el["rank"] = idx
+        el["match_reason"] = "Matched topic/mention route; resolved as PPT element for bounded synthesis."
+        el["source_return_state"] = "REFERENCE_BOUND"
+        el["pressure_spine"] = "HIR x OAM"
+        elements.append(el)
+    return elements
+
+def build_alchemical_output(raw_text: str, topics: List[str], elements: List[Dict[str, Any]]) -> Dict[str, Any]:
+    names = [e["name"] for e in elements]
+    if {"robotics","humans","dna"} & set(topics):
+        reference = "This route explores how embodied correction, human cognition/agency, and biological-substrate or encoding concepts may share bounded sensing, repair, memory, and continuity patterns."
+        strain = "DNA-related language must remain a bounded computational/structural comparison unless domain evidence is introduced."
+        future = "Build a test capsule comparing robotic correction loops, human learning loops, and biological repair/encoding loops under the HIR x OAM pressure spine."
+    elif "grch38" in topics:
+        reference = "This route treats GRCh38 as a research-reference capsule that can be cross-mapped against local substrate, trace, and representation layers."
+        strain = "Do not infer biological causation, resonance, or clinical meaning without a defined transform, region, source data, and validation route."
+        future = "Build a computational test capsule for a specified GRCh38 region and transform, with biological interpretation held as unvalidated."
+    else:
+        reference = "This route converts loose inquiry into a trace capsule, resolves PPT elements, and proposes a bounded synthesis path."
+        strain = "The route needs more specific source anchors before stronger claims can be carried."
+        future = "Select 2-5 PPT elements and run a focused brainstorm or combine command."
+    return {
+        "panel_name": "Primordial Periodic Alchemical Output",
+        "reference_point": reference,
+        "selected_element_names": names,
+        "continuity_read": "HELD as a route proposal when treated as source-return, overlay-only collaborative synthesis.",
+        "strain_points": [strain],
+        "repair_notes": ["Preserve HIR x OAM terminology.", "Write proposals as overlays, not canonical source mutation."],
+        "future_routes": [future, "Ask the Primordial OS Runtime steward to propose next prompt options.", "Create a lexicon review packet for any new terms introduced."],
+        "claim_boundary": "route-integrity and research planning only; no final validation claim",
+    }
+
+def build_receipt(elements: List[Dict[str, Any]]) -> Dict[str, Any]:
+    return {
+        "status": "HELD",
+        "H": 1.0,
+        "I": 1.0,
+        "R": 1.0,
+        "A": 1.0,
+        "P": 0.0,
+        "S_effective": 1.0,
+        "pressure_spine": "HIR x OAM",
+        "source_mutation": "NONE__OVERLAY_PROPOSAL_ONLY",
+        "human_review_required": True,
+        "matched_element_count": len(elements),
+        "claim_limit": "trace capsule / alchemical continuity route; not final validation"
+    }
+
+def submit_mesh_command(command: Dict[str, Any]) -> Dict[str, Any]:
+    raw = command.get("raw_user_text","").strip()
+    command_type = command.get("command_type","DISCOVER")
+    workspace_id = command.get("workspace_id","workspace_local_001")
+    command_id = command.get("command_id") or stable_id("cmd", raw + command_type + workspace_id)
+    topics = extract_topics(raw)
+    mentions = extract_mentions(raw)
+    elements = match_ppt_elements(topics, mentions)
+    trace_capsule = {
+        "trace_capsule_id": stable_id("trace", raw + command_id),
+        "raw_user_text": raw,
+        "topics": topics,
+        "mentions": mentions,
+        "loop_state": "HELD",
+        "translation_route": "plain_language + PPT_elements + alchemical_output + receipt",
+        "source_return_required": True,
+        "false_closure_risk": "LOW",
+    }
+    alchemical = build_alchemical_output(raw, topics, elements)
+    receipt = build_receipt(elements)
+    overlay = {
+        "overlay_id": stable_id("overlay", command_id + raw),
+        "write_scope": "COLLABORATIVE_OVERLAY_PROPOSAL_ONLY",
+        "status": "PENDING_HUMAN_REVIEW",
+        "summary": alchemical["reference_point"],
+        "source_mutation": "NONE",
+        "credited_contributors": [
+            {"type": "human_or_session", "id": command.get("session_id","session_local")},
+            {"type": "ai_adapter", "id": "primordial_os_runtime"}
+        ]
+    }
+    return {
+        "status": "HELD",
+        "command_id": command_id,
+        "workspace_id": workspace_id,
+        "trace_capsule": trace_capsule,
+        "matched_ppt_elements": elements,
+        "alchemical_output": alchemical,
+        "lexicon_state": {
+            "active_terms": ["trace capsule", "source-return", "HIR x OAM", "Primordial Periodic Table", "Resonant Access Memory", "collaborative overlay"],
+            "candidate_terms": ["Primordial Periodic Alchemical Output"],
+            "review_required": True
+        },
+        "receipt": receipt,
+        "audit_pointer": f"workspaces/{workspace_id}/audit/{command_id}.json",
+        "overlay_proposals": [overlay],
+        "human_review_required": True
+    }
+
+def write_workspace_response(response: Dict[str, Any], out_dir: Path) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    (out_dir / "response.json").write_text(json.dumps(response, indent=2), encoding="utf-8")
+    audit = {
+        "timestamp_utc": utc_now(),
+        "event": "mesh_command_completed",
+        "command_id": response["command_id"],
+        "workspace_id": response["workspace_id"],
+        "status": response["status"],
+        "source_mutation": response["receipt"]["source_mutation"],
+        "human_review_required": response["human_review_required"]
+    }
+    (out_dir / "audit_log.jsonl").write_text(json.dumps(audit) + "\n", encoding="utf-8")
+    receipt_md = f"""# Mesh Command Receipt
+
+Command ID: `{response['command_id']}`
+
+Status: `{response['status']}`
+
+Pressure spine: `{response['receipt']['pressure_spine']}`
+
+Source mutation: `{response['receipt']['source_mutation']}`
+
+Human review required: `{response['human_review_required']}`
+
+## Reference Point
+
+{response['alchemical_output']['reference_point']}
+
+## Future Routes
+
+""" + "\n".join(f"- {x}" for x in response["alchemical_output"]["future_routes"]) + "\n"
+    (out_dir / "receipt.md").write_text(receipt_md, encoding="utf-8")
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("raw_user_text", nargs="?", default="robotics humans DNA")
+    p.add_argument("--command-type", default="DISCOVER")
+    p.add_argument("--workspace-id", default="workspace_local_001")
+    p.add_argument("--session-id", default="session_local")
+    p.add_argument("--out-dir", default="runs/connector_demo_001")
+    p.add_argument("--overwrite", action="store_true")
+    args = p.parse_args()
+    out = Path(args.out_dir)
+    if out.exists() and not args.overwrite:
+        print(f"Refusing to overwrite existing out-dir: {out}", flush=True)
+        return 2
+    command = {
+        "command_type": args.command_type,
+        "raw_user_text": args.raw_user_text,
+        "workspace_id": args.workspace_id,
+        "session_id": args.session_id,
+        "claim_boundary": "no final validation claims; human review required",
+        "privacy_scope": "PRIVATE_WORKSPACE",
+        "source_mutation_allowed": False
+    }
+    response = submit_mesh_command(command)
+    write_workspace_response(response, out)
+    print(json.dumps({
+        "status": response["status"],
+        "command_id": response["command_id"],
+        "workspace_id": response["workspace_id"],
+        "matched_ppt_elements": len(response["matched_ppt_elements"]),
+        "source_mutation": response["receipt"]["source_mutation"],
+        "human_review_required": response["human_review_required"],
+        "out_dir": str(out)
+    }, indent=2))
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())

validate_substrate_connector_api_v3_3_1.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+import json, os, shutil
+from pathlib import Path
+
+from fastapi.testclient import TestClient
+from app import app
+
+
+def main() -> int:
+    os.environ["SUBSTRATE_ACTION_KEY"] = "test-secret-key"
+    os.environ["SUBSTRATE_RECEIPT_ROOT"] = "runs/api_receipts_validation"
+    root = Path(os.environ["SUBSTRATE_RECEIPT_ROOT"])
+    if root.exists():
+        shutil.rmtree(root)
+
+    client = TestClient(app)
+    report = {
+        "version": "v3.3.1",
+        "health_ok": False,
+        "unauthorized_blocked": False,
+        "command_ok": False,
+        "receipt_fetch_ok": False,
+        "pressure_spine_hir_x_oam": False,
+        "source_mutation_blocked": False,
+        "workspace_local_receipt_written": False,
+        "human_review_required": False,
+        "overlay_proposal_present": False,
+        "canonical_boundary_present": False,
+        "status": "FAIL"
+    }
+
+    health = client.get("/v1/mesh/health")
+    report["health_ok"] = health.status_code == 200 and health.json().get("status") == "HELD"
+
+    unauth = client.post("/v1/mesh/command", json={"raw_user_text":"robotics humans DNA"})
+    report["unauthorized_blocked"] = unauth.status_code == 401
+
+    headers = {"Authorization": "Bearer test-secret-key"}
+    payload = {
+        "command_type":"DISCOVER",
+        "raw_user_text":"robotics humans DNA",
+        "workspace_id":"workspace_validation_001",
+        "session_id":"user_001",
+        "source_mutation_allowed": False
+    }
+    command = client.post("/v1/mesh/command", json=payload, headers=headers)
+    if command.status_code == 200:
+        data = command.json()
+        report["command_ok"] = (data.get("status") == "HELD" and bool(data.get("command_id")))
+        report["pressure_spine_hir_x_oam"] = data.get("receipt", {}).get("pressure_spine") == "HIR × OAM"
+        report["source_mutation_blocked"] = data.get("receipt", {}).get("source_mutation") == "NONE__OVERLAY_PROPOSAL_ONLY"
+        report["human_review_required"] = data.get("human_review_required") is True
+        report["overlay_proposal_present"] = bool(data.get("overlay_proposals"))
+        report["canonical_boundary_present"] = data.get("boundary", {}).get("canonical_sources") == "READ_ONLY" and data.get("boundary", {}).get("canonical_lexicon") == "READ_ONLY"
+        report["workspace_local_receipt_written"] = Path(data.get("api_receipt_paths", {}).get("response_path", "")).exists()
+        receipt = client.get(f"/v1/mesh/receipt/{data['command_id']}?workspace_id=workspace_validation_001", headers=headers)
+        report["receipt_fetch_ok"] = receipt.status_code == 200 and receipt.json().get("command_id") == data["command_id"]
+        # Save example response for packet readers.
+        ex = Path("examples/responses")
+        ex.mkdir(parents=True, exist_ok=True)
+        (ex / "robotics_humans_dna_api_response.json").write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    report["status"] = "PASS" if all(v is True for k,v in report.items() if k not in {"version","status"}) else "FAIL"
+    Path("V3_3_1_VALIDATION_RESULT.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
+    print(json.dumps(report, indent=2))
+    return 0 if report["status"] == "PASS" else 1
+
+if __name__ == "__main__":
+    raise SystemExit(main())