diff --git a/.github/workflows/advanced-security.yml b/.github/workflows/advanced-security.yml
new file mode 100644
index 00000000..64c77eef
--- /dev/null
+++ b/.github/workflows/advanced-security.yml
@@ -0,0 +1,31 @@
+name: Advanced Security Audit
+on:
+ pull_request:
+ branches: [ coreason-develop, main ]
+
+permissions: read-all
+
+jobs:
+ dependency-review:
+ name: Dependency Review
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pull-requests: write
+ steps:
+ - name: Harden Runner
+ uses: step-security/harden-runner@c95a14d0e5bab51a9f56296a4eb0e416910cd350 # v2.19.1
+ with:
+ egress-policy: audit
+
+ - name: Checkout Repository
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+ - name: Dependency Review
+ uses: actions/dependency-review-action@3b139cfc5fae8b618d3eae3675e383bb1769c019 # v4.5.0
+ with:
+ comment-summary-in-pr: always
+ fail-on-severity: high
+ deny-licenses: AGPL-1.0, AGPL-3.0, GPL-1.0, GPL-2.0, GPL-3.0, LGPL-2.0, LGPL-2.1, LGPL-3.0
+
+
diff --git a/.github/workflows/bandit.yml b/.github/workflows/bandit.yml
new file mode 100644
index 00000000..4451c7da
--- /dev/null
+++ b/.github/workflows/bandit.yml
@@ -0,0 +1,36 @@
+name: Bandit Security Scan
+
+on:
+ push:
+ branches: [ "main" ]
+ pull_request:
+ branches: [ "main" ]
+ schedule:
+ - cron: '0 0 * * *'
+
+permissions: read-all
+
+jobs:
+ bandit:
+ name: Bandit Scan
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ security-events: write
+ actions: read
+ steps:
+ - name: "Checkout code"
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+ - name: "Install Bandit"
+ run: pip install bandit[sarif]
+
+ - name: "Run Bandit"
+ run: bandit -r . -f sarif -o bandit-results.sarif || true
+
+ - name: "Upload Bandit results"
+ uses: github/codeql-action/upload-sarif@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3.28.8
+ with:
+ sarif_file: 'bandit-results.sarif'
+
+
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index beaef9d9..6c50fc57 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,8 +7,7 @@ on:
- develop
pull_request:
-permissions:
- contents: read
+permissions: read-all
env:
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
@@ -21,6 +20,8 @@ jobs:
lint-and-audit:
runs-on: [self-hosted, hetzner, x64]
timeout-minutes: 30
+ permissions:
+ contents: read
env:
TEMPORAL_CI_NAMESPACE: ci-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
COMPOSE_PROJECT_NAME: ci-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
@@ -33,7 +34,7 @@ jobs:
run: sudo chown -R $(whoami):$(whoami) ${{ github.workspace }} || true
- name: Harden Runner
- uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
+ uses: step-security/harden-runner@c95a14d0e5bab51a9f56296a4eb0e416910cd350 # v2.19.3
with:
egress-policy: audit
@@ -102,6 +103,8 @@ jobs:
security-sast:
runs-on: [self-hosted, hetzner, x64]
timeout-minutes: 30
+ permissions:
+ contents: read
env:
TEMPORAL_CI_NAMESPACE: ci-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
COMPOSE_PROJECT_NAME: ci-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
@@ -114,7 +117,7 @@ jobs:
run: sudo chown -R $(whoami):$(whoami) ${{ github.workspace }} || true
- name: Harden Runner
- uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
+ uses: step-security/harden-runner@c95a14d0e5bab51a9f56296a4eb0e416910cd350 # v2.19.3
with:
egress-policy: audit
@@ -153,6 +156,8 @@ jobs:
if: always() && needs.lint-and-audit.result == 'success' && needs.security-sast.result == 'success'
runs-on: [self-hosted, hetzner, x64]
timeout-minutes: 30
+ permissions:
+ contents: read
env:
TEMPORAL_CI_NAMESPACE: ci-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
COMPOSE_PROJECT_NAME: ci-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
@@ -165,7 +170,7 @@ jobs:
run: sudo chown -R $(whoami):$(whoami) ${{ github.workspace }} || true
- name: Harden Runner
- uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
+ uses: step-security/harden-runner@c95a14d0e5bab51a9f56296a4eb0e416910cd350 # v2.19.3
with:
egress-policy: audit
@@ -219,6 +224,8 @@ jobs:
needs: [test]
runs-on: [self-hosted, hetzner, x64]
timeout-minutes: 30
+ permissions:
+ contents: read
env:
TEMPORAL_CI_NAMESPACE: ci-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
COMPOSE_PROJECT_NAME: ci-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
@@ -231,7 +238,7 @@ jobs:
run: sudo chown -R $(whoami):$(whoami) ${{ github.workspace }} || true
- name: Harden Runner
- uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
+ uses: step-security/harden-runner@c95a14d0e5bab51a9f56296a4eb0e416910cd350 # v2.19.3
with:
egress-policy: audit
@@ -282,3 +289,5 @@ jobs:
if [ -f "compose.yaml" ]; then docker compose down -v || true; fi
sudo chown -R $(whoami):$(whoami) ${{ github.workspace }}
shell: bash
+
+
diff --git a/.github/workflows/container-scan.yml b/.github/workflows/container-scan.yml
index 87f1ba76..c9b2325b 100644
--- a/.github/workflows/container-scan.yml
+++ b/.github/workflows/container-scan.yml
@@ -7,8 +7,7 @@ on:
branches: [ "develop", "main" ]
-permissions:
- contents: read
+permissions: read-all
jobs:
trivy:
@@ -41,3 +40,5 @@ jobs:
with:
sarif_file: 'trivy-results.sarif'
continue-on-error: true
+
+
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 32c3ca5f..a0900cc2 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -24,7 +24,7 @@ jobs:
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Harden Runner
- uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
+ uses: step-security/harden-runner@c95a14d0e5bab51a9f56296a4eb0e416910cd350 # v2.19.3
with:
egress-policy: audit
@@ -57,3 +57,5 @@ jobs:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+
+
diff --git a/.github/workflows/nightly-fuzzing.yml b/.github/workflows/nightly-fuzzing.yml
index b6dd0557..4df3dc88 100644
--- a/.github/workflows/nightly-fuzzing.yml
+++ b/.github/workflows/nightly-fuzzing.yml
@@ -5,8 +5,7 @@ on:
- cron: "0 3 * * *"
workflow_dispatch:
-permissions:
- contents: read
+permissions: read-all
env:
UV_PYTHON_PREFERENCE: "only-managed"
@@ -16,9 +15,11 @@ jobs:
hypothesis-fuzz:
runs-on: [self-hosted, hetzner, x64]
timeout-minutes: 30
+ permissions:
+ contents: read
steps:
- name: Harden Runner
- uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
+ uses: step-security/harden-runner@c95a14d0e5bab51a9f56296a4eb0e416910cd350 # v2.19.3
with:
egress-policy: audit
@@ -48,3 +49,5 @@ jobs:
name: hypothesis-examples
path: .hypothesis/
retention-days: 7
+
+
diff --git a/.github/workflows/osv-scanner.yml b/.github/workflows/osv-scanner.yml
new file mode 100644
index 00000000..32d9cee5
--- /dev/null
+++ b/.github/workflows/osv-scanner.yml
@@ -0,0 +1,21 @@
+name: OSV-Scanner
+on:
+ push:
+ branches: [main, coreason-develop]
+ pull_request:
+ branches: [main, coreason-develop]
+ schedule:
+ - cron: '0 0 * * 1'
+
+permissions: read-all
+
+jobs:
+ scan:
+ name: OSV-Scanner
+ permissions:
+ actions: read
+ security-events: write
+ contents: read
+ uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@764c91816374ff2d8fc2095dab36eecd42d61638" # v1.9.1
+
+
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 7db1b3c5..c7e0fd26 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -8,12 +8,7 @@ on:
release:
types: [published]
-permissions:
- contents: write
- id-token: write # Required for PyPI OIDC Trusted Publishing and Sigstore
- pages: write # Required for GitHub Pages deployment
- actions: read # Required for SBOM artifact access and download
- attestations: write # Required for SLSA build provenance
+permissions: read-all
env:
UV_PYTHON_PREFERENCE: "only-managed"
@@ -28,9 +23,15 @@ jobs:
runs-on: [self-hosted, hetzner, x64]
timeout-minutes: 30
environment: pypi
+ permissions:
+ contents: write
+ id-token: write # Required for PyPI OIDC Trusted Publishing and Sigstore
+ pages: write # Required for GitHub Pages deployment
+ actions: read # Required for SBOM artifact access and download
+ attestations: write # Required for SLSA build provenance
steps:
- name: Harden Runner
- uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
+ uses: step-security/harden-runner@c95a14d0e5bab51a9f56296a4eb0e416910cd350 # v2.19.3
with:
egress-policy: audit
@@ -114,7 +115,7 @@ jobs:
attestations: write
steps:
- name: Harden Runner
- uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
+ uses: step-security/harden-runner@c95a14d0e5bab51a9f56296a4eb0e416910cd350 # v2.19.3
with:
egress-policy: audit
@@ -175,3 +176,5 @@ jobs:
subject-name: ghcr.io/coreason-ai/coreason-runtime
subject-digest: ${{ steps.build-and-push.outputs.digest }}
push-to-registry: true
+
+
diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml
new file mode 100644
index 00000000..98ee6f22
--- /dev/null
+++ b/.github/workflows/scorecard.yml
@@ -0,0 +1,39 @@
+name: Scorecard supply-chain security
+on:
+ branch_protection_rule:
+ schedule:
+ - cron: '30 1 * * 6'
+ push:
+ branches: [ "main" ]
+
+permissions: read-all
+
+jobs:
+ analysis:
+ name: Scorecard analysis
+ runs-on: ubuntu-latest
+ permissions:
+ security-events: write
+ id-token: write
+ contents: read
+ actions: read
+
+ steps:
+ - name: "Checkout code"
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ persist-credentials: false
+
+ - name: "Run analysis"
+ uses: ossf/scorecard-action@62b2cac7ed8198b15735ed49ab1e5cf35480ba46 # v2.4.0
+ with:
+ results_file: results.sarif
+ results_format: sarif
+ publish_results: true
+
+ - name: "Upload results"
+ uses: github/codeql-action/upload-sarif@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3.28.8
+ with:
+ sarif_file: results.sarif
+
+
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
index 8e137e91..4ef62eea 100644
--- a/.github/workflows/security.yml
+++ b/.github/workflows/security.yml
@@ -9,16 +9,15 @@ on:
- cron: '0 0 * * *'
workflow_dispatch:
-permissions:
- contents: read
- security-events: write
- actions: read
+permissions: read-all
jobs:
secret-scan:
name: Secret Scanning
runs-on: [self-hosted, hetzner, x64]
timeout-minutes: 30
+ permissions:
+ contents: read
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
@@ -35,9 +34,13 @@ jobs:
name: Software Composition Analysis
runs-on: [self-hosted, hetzner, x64]
timeout-minutes: 30
+ permissions:
+ contents: read
+ security-events: write
+ actions: read
steps:
- name: Harden Runner
- uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
+ uses: step-security/harden-runner@c95a14d0e5bab51a9f56296a4eb0e416910cd350 # v2.19.3
with:
egress-policy: audit
@@ -86,3 +89,5 @@ jobs:
pip-audit-report.html
npm-audit.json
retention-days: 14
+
+
diff --git a/.github/workflows/trivy.yml b/.github/workflows/trivy.yml
new file mode 100644
index 00000000..af8fc6ff
--- /dev/null
+++ b/.github/workflows/trivy.yml
@@ -0,0 +1,37 @@
+name: Trivy Security Scan
+
+on:
+ push:
+ branches: [ "main", "coreason-develop", "feat/add-security-scans" ]
+ pull_request:
+ branches: [ "main", "coreason-develop" ]
+
+permissions: read-all
+
+jobs:
+ trivy:
+ name: Trivy Vulnerability Scanner
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ security-events: write
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ persist-credentials: false
+
+ - name: Run Trivy vulnerability scanner in repo mode
+ uses: aquasecurity/trivy-action@314ff8b43182423b84c50b1670b0e10f858f2d98
+ with:
+ scan-type: 'fs'
+ ignore-unfixed: true
+ format: 'sarif'
+ output: 'trivy-results.sarif'
+ severity: 'CRITICAL,HIGH'
+
+ - name: Upload Trivy scan results to GitHub Security tab
+ uses: github/codeql-action/upload-sarif@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3.35.5
+ with:
+ sarif_file: 'trivy-results.sarif'
diff --git a/.github/workflows/trufflehog.yml b/.github/workflows/trufflehog.yml
new file mode 100644
index 00000000..18af70ae
--- /dev/null
+++ b/.github/workflows/trufflehog.yml
@@ -0,0 +1,31 @@
+name: TruffleHog Secret Scan
+
+on:
+ push:
+ branches: [ "main", "coreason-develop", "feat/add-security-scans" ]
+ pull_request:
+ branches: [ "main", "coreason-develop" ]
+
+permissions: read-all
+
+jobs:
+ trufflehog:
+ name: TruffleHog Secret Scanner
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ fetch-depth: 0
+ persist-credentials: false
+
+ - name: TruffleHog OSS
+ uses: trufflesecurity/trufflehog@0fa069c12f0c7baf431041cd1e564a9c5058846c
+ with:
+ path: ./
+ base: "${{ github.event.repository.default_branch }}"
+ head: HEAD
+ extra_args: --debug --only-verified
diff --git a/.github/workflows/zap-dast.yml b/.github/workflows/zap-dast.yml
new file mode 100644
index 00000000..7ef7bb4d
--- /dev/null
+++ b/.github/workflows/zap-dast.yml
@@ -0,0 +1,38 @@
+name: OWASP ZAP DAST Scan
+
+on:
+ push:
+ branches: [ "main", "coreason-develop", "feat/add-security-scans" ]
+ pull_request:
+ branches: [ "main", "coreason-develop" ]
+ workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+ zap_scan:
+ name: OWASP ZAP Baseline Scan
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ issues: write
+ security-events: write
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ persist-credentials: false
+
+ # Note: In a real environment, you would start your application here
+ # e.g., docker-compose up -d
+ # For now, we will scan a placeholder/demo target or skip if no target is running.
+ # To fully enable, replace target with your staging URL.
+
+ - name: ZAP Baseline Scan
+ uses: zaproxy/action-baseline@f948cb8d66e25e330a23e64e3fc72a5c0018b16d # master
+ continue-on-error: true # DAST scans can be noisy, so we prevent failing the build initially
+ with:
+ target: 'https://coreason.ai/' # Placeholder target for the baseline
+ rules_file_name: '.zap/rules.tsv'
+ cmd_options: '-a'
diff --git a/README.md b/README.md
index af9be4b0..fe91f47b 100644
--- a/README.md
+++ b/README.md
@@ -1,98 +1,99 @@
-# 🧠 coreason-runtime
-
-[](https://pypi.org/project/coreason_runtime)
-[](https://github.com/CoReason-AI/coreason-runtime/actions/workflows/ci.yml)
-[](https://coreason-ai.github.io/coreason-runtime/)
-[](https://github.com/CoReason-AI/coreason-runtime/actions/workflows/docs.yml)
-[](https://pypi.org/project/coreason_runtime)
-[](https://pypi.org/project/coreason_runtime/)
-[](https://prosperitylicense.com/versions/3.0.0)
-[](https://coreason.ai)
-
-[](https://codecov.io/gh/CoReason-AI/coreason-runtime)
-[](https://mypy-lang.org/)
-[](https://github.com/astral-sh/ruff)
-[](https://github.com/pre-commit/pre-commit)
-[](https://github.com/PyCQA/bandit)
-
-[](https://github.com/astral-sh/uv)
-[](https://github.com/CoReason-AI/coreason-runtime/network/members)
-[](https://coreason.ai)
-
-**The official zero-trust, high-throughput kinetic execution engine for the `coreason-manifest` ontology.**
-
-`coreason-runtime` is a State-of-the-Art (SOTA) 2026 cybernetic execution engine. It abandons legacy, fragile "chain-of-thought" LLM scripting in favor of deterministic **Active Inference**, Topological Data Analysis (TDA), and strictly bounded Markov Decision Processes. It is the definitive implementation of the CoReason Tripartite Doctrine for Tier-1 Kinetic Execution.
-
-If `coreason-manifest` is the DNA of your multi-agent topologies, `coreason-runtime` is the biological cell that safely executes them.
-
----
-
-## 🚀 The Paradigm Shift
-
-Modern enterprise AI cannot rely on unbounded `while True` loops and raw Python `exec()`. The `coreason-runtime` enforces mathematical rigor at every boundary:
-
-* **Deterministic Orchestration:** Built on **Temporal**, Swarm executions are durably serialized. If a GPU dies or a network request fails, the Swarm pauses, rehydrates, and resumes exactly where it left off. No amnesia. No ghost processes.
-* **Zero-Trust WASM Sandboxing:** Kinetic actions (Tools) are executed inside isolated WebAssembly environments via **Extism**. Agents can execute complex IO without ever touching your host's root kernel or filesystem.
-* **Epistemic Vector Ledger:** Native, zero-copy integration with **LanceDB**. The runtime automatically projects the agent's latent state into an embedded vector memory layer.
-* **Embedded Medallion Analytics:** No need for heavy Spark clusters. Raw telemetry (SSE) is ingested via **dlt** and transformed into Silver/Gold analytical intelligence matrices using Rust-backed **Polars** directly inside the daemon.
-* **Human-in-the-Loop (HITL) Webhooks:** When an agent calculates high Variational Free Energy (epistemic uncertainty), it durably suspends its thread and emits an Oracle Request, waiting safely for a human expert to inject resolving priors via API.
-* **Bipartite Proposer-Verifier Protocol:** The runtime is physically isolated from local OS capability generation. To fabricate assets, the runtime strictly proposes topological models over air-gapped MCP boundaries to the remote Universal Asset Forge (`coreason-meta-engineering`).
-
----
-
-## ⚡ Installation
-
-We utilize `uv` for ultra-fast, deterministic resolution. Ensure you are running Python 3.14+.
-
-```bash
-uv add coreason-runtime
-```
-
-*Note: For bare-metal enterprise deployment with SGLang GPU passthrough, refer to our [Docker Deployment Guide](docs/DEPLOYMENT.md).*
-
------
-
-## 🛠️ Quickstart
-
-The runtime is designed to be operated via its CLI or mounted as an API edge.
-
-### 1\. Run a Local Swarm
-
-To execute a mathematically verified agentic topology, simply pass the JSON/YAML manifest to the runtime:
-
-```bash
-coreason run ./my_swarm_manifest.json
-```
-
-### 2\. Boot the API Edge & Telemetry Broker
-
-To boot the runtime as a continuous daemon (exposing the CRDT State Sync, Schema Projection, and Server-Sent Events telemetry):
-
-```bash
-coreason serve --port 8000
-```
-
-Your frontend IDE can now connect to `http://localhost:8000/api/v1/telemetry/stream` to visualize the active inference loops in real-time.
-
------
-
-## 🏗️ Architecture
-
-The runtime operates across five isolated computational boundaries under the CoReason Tripartite Doctrine:
-
-1. **The Orchestrator:** Temporal Python SDK running deterministic AST-scanned workflows.
-2. **The Cognitive Engine:** SGLang routing for sub-millisecond constrained tensor inference.
-3. **The Kinetic Sandbox:** Extism executing `.wasm` tools with zero-trust lattices.
-4. **The Epistemic Store:** LanceDB & Polars managing long-term vectors and ETL metrics.
-5. **The Universal Asset Forge:** A decoupled MCP channel connecting strictly to the `coreason-meta-engineering` Fabrication Lines to physically synthesize assets via the Bipartite generation pipeline.
-
-For a deep dive into the cybernetic loop, read the [Architecture Documentation](docs/architecture.md).
-
------
-
-## 📜 License
-
-This software is proprietary and dual-licensed under the **Prosperity Public License 3.0**.
-Commercial use beyond a 30-day trial requires a separate commercial license. See the `LICENSE` file for details.
-
-Copyright (c) 2026 CoReason, Inc.
+# 🧠 coreason-runtime
+
+[](https://pypi.org/project/coreason_runtime)
+[](https://github.com/CoReason-AI/coreason-runtime/actions/workflows/ci.yml)
+[](https://coreason-ai.github.io/coreason-runtime/)
+[](https://github.com/CoReason-AI/coreason-runtime/actions/workflows/docs.yml)
+[](https://pypi.org/project/coreason_runtime)
+[](https://pypi.org/project/coreason_runtime/)
+[](https://prosperitylicense.com/versions/3.0.0)
+[](https://coreason.ai)
+
+[](https://scorecard.dev/viewer/?uri=github.com/CoReason-AI/coreason-runtime)
+[](https://codecov.io/gh/CoReason-AI/coreason-runtime)
+[](https://mypy-lang.org/)
+[](https://github.com/astral-sh/ruff)
+[](https://github.com/pre-commit/pre-commit)
+[](https://github.com/PyCQA/bandit)
+
+[](https://github.com/astral-sh/uv)
+[](https://github.com/CoReason-AI/coreason-runtime/network/members)
+[](https://coreason.ai)
+
+**The official zero-trust, high-throughput kinetic execution engine for the `coreason-manifest` ontology.**
+
+`coreason-runtime` is a State-of-the-Art (SOTA) 2026 cybernetic execution engine. It abandons legacy, fragile "chain-of-thought" LLM scripting in favor of deterministic **Active Inference**, Topological Data Analysis (TDA), and strictly bounded Markov Decision Processes. It is the definitive implementation of the CoReason Tripartite Doctrine for Tier-1 Kinetic Execution.
+
+If `coreason-manifest` is the DNA of your multi-agent topologies, `coreason-runtime` is the biological cell that safely executes them.
+
+---
+
+## 🚀 The Paradigm Shift
+
+Modern enterprise AI cannot rely on unbounded `while True` loops and raw Python `exec()`. The `coreason-runtime` enforces mathematical rigor at every boundary:
+
+* **Deterministic Orchestration:** Built on **Temporal**, Swarm executions are durably serialized. If a GPU dies or a network request fails, the Swarm pauses, rehydrates, and resumes exactly where it left off. No amnesia. No ghost processes.
+* **Zero-Trust WASM Sandboxing:** Kinetic actions (Tools) are executed inside isolated WebAssembly environments via **Extism**. Agents can execute complex IO without ever touching your host's root kernel or filesystem.
+* **Epistemic Vector Ledger:** Native, zero-copy integration with **LanceDB**. The runtime automatically projects the agent's latent state into an embedded vector memory layer.
+* **Embedded Medallion Analytics:** No need for heavy Spark clusters. Raw telemetry (SSE) is ingested via **dlt** and transformed into Silver/Gold analytical intelligence matrices using Rust-backed **Polars** directly inside the daemon.
+* **Human-in-the-Loop (HITL) Webhooks:** When an agent calculates high Variational Free Energy (epistemic uncertainty), it durably suspends its thread and emits an Oracle Request, waiting safely for a human expert to inject resolving priors via API.
+* **Bipartite Proposer-Verifier Protocol:** The runtime is physically isolated from local OS capability generation. To fabricate assets, the runtime strictly proposes topological models over air-gapped MCP boundaries to the remote Universal Asset Forge (`coreason-meta-engineering`).
+
+---
+
+## ⚡ Installation
+
+We utilize `uv` for ultra-fast, deterministic resolution. Ensure you are running Python 3.14+.
+
+```bash
+uv add coreason-runtime
+```
+
+*Note: For bare-metal enterprise deployment with SGLang GPU passthrough, refer to our [Docker Deployment Guide](docs/DEPLOYMENT.md).*
+
+-----
+
+## 🛠️ Quickstart
+
+The runtime is designed to be operated via its CLI or mounted as an API edge.
+
+### 1\. Run a Local Swarm
+
+To execute a mathematically verified agentic topology, simply pass the JSON/YAML manifest to the runtime:
+
+```bash
+coreason run ./my_swarm_manifest.json
+```
+
+### 2\. Boot the API Edge & Telemetry Broker
+
+To boot the runtime as a continuous daemon (exposing the CRDT State Sync, Schema Projection, and Server-Sent Events telemetry):
+
+```bash
+coreason serve --port 8000
+```
+
+Your frontend IDE can now connect to `http://localhost:8000/api/v1/telemetry/stream` to visualize the active inference loops in real-time.
+
+-----
+
+## 🏗️ Architecture
+
+The runtime operates across five isolated computational boundaries under the CoReason Tripartite Doctrine:
+
+1. **The Orchestrator:** Temporal Python SDK running deterministic AST-scanned workflows.
+2. **The Cognitive Engine:** SGLang routing for sub-millisecond constrained tensor inference.
+3. **The Kinetic Sandbox:** Extism executing `.wasm` tools with zero-trust lattices.
+4. **The Epistemic Store:** LanceDB & Polars managing long-term vectors and ETL metrics.
+5. **The Universal Asset Forge:** A decoupled MCP channel connecting strictly to the `coreason-meta-engineering` Fabrication Lines to physically synthesize assets via the Bipartite generation pipeline.
+
+For a deep dive into the cybernetic loop, read the [Architecture Documentation](docs/architecture.md).
+
+-----
+
+## 📜 License
+
+This software is proprietary and dual-licensed under the **Prosperity Public License 3.0**.
+Commercial use beyond a 30-day trial requires a separate commercial license. See the `LICENSE` file for details.
+
+Copyright (c) 2026 CoReason, Inc.