##############################################################################################
#                                                                                            #
#              ___                  _    _ _ _ _          ___     _        _                 #
#             | _ \_ _ _____ ____ _| |__(_) (_) |_ _  _  | __|_ _| |__ _ _(_)__              #
#             |  _/ '_/ _ \ V / _` | '_ \ | | |  _| || | | _/ _` | '_ \ '_| / _|             #
#             |_| |_| \___/\_/\__,_|_.__/_|_|_|\__|\_, | |_|\__,_|_.__/_| |_\__|             #
#                                                   |__/                                     #
#                                                                                            #
##############################################################################################

Provability Fabric

Formal specs, runtime policy, and evidence trails — Lean specifications and proofs where present, fail-closed crypto by default, and auditable evidence in one open stack.

_{Guarantees are conditional on configured trust roots and deployment policy. Lean in-repo does not mean every production path is proven end-to-end. See Evidence non-claims and deployment trust.}

Documentation · Contributing · Security · CI reference

---

Why this project

Provability Fabric ties specifications and proofs to what actually runs. You get Lean-backed bundles, sidecars and admission control that enforce policy, and trails you can replay and verify as structured evidence instead of informal logging alone.

Pillar	What it gives you
Prove	Specifications and Lean proofs live next to agent bundles so claims stay checkable against formal artifacts.
Enforce	Rust and Go runtimes, WASM sandboxing, and tooling brokers limit what agents can do at execution time.
Audit	Evidence formats, ledgers, and replay-oriented workflows support end-to-end accountability.

---

Repository layout

Intentional top-level surface (everything else is product code under these trees):

Path	Why it stays
core/	CLI, SDKs, Lean libs, policy kernel
runtime/	Sidecar, ledger, brokers, admission
adapters/	Framework / protocol adapters
services/, console/	Platform — Compose-backed Go APIs (default profile) and admin console (--profile full)

| proofs/, spec-templates/, bundles/ | Lean policy proofs and agent bundles | | schemas/, config/, api/, specs/ | Schemas, protos, evidence specs | | cmd/, releaser/ | Specdoc CLI; Nix supply-chain reproducibility helper | | artifact/ | Checked-in DFA export outputs and golden cases | | charts/, ops/ | Helm (charts/pf-enforce); Compose Grafana/Prometheus + retention under ops/ | | external/ | CERT-V1 / TRACE-REPLAY-KIT submodules | | bench/, experiments/, benchmarks/ | SWE-bench / eval / PCS admission | | examples/, demos/, testbed/ | CI-backed evidence walkthroughs (evidence-*, forensic-*, runtime-*) and MCP fraud demo | | tests/, tools/, scripts/, docs/ | Verification, tooling, docs | | CLA/, .github/ | CLA config; CI workflows and shared actions |

Root config stays thin: README, CONTRIBUTING, LICENSE, Makefile, justfile, Cargo.toml, package.json, go.work.example, docker-compose.yml, mkdocs.yml, Lean toolchain files.

Compact tree (click to expand)

provability-fabric/
├── core/              # CLI, SDKs, Lean libs
├── runtime/           # Rust / Go / Node services
├── adapters/          # Integration adapters
├── services/ console/   # Platform APIs + admin UI
├── proofs/            # Canonical Policy.lean package
├── charts/            # Helm (pf-enforce)
├── ops/               # Observability + retention only
├── schemas/ config/ api/ specs/
├── cmd/ releaser/ artifact/
├── examples/ demos/ testbed/
├── bench/ experiments/ benchmarks/
├── tests/ tools/ scripts/ docs/
├── CLA/
├── Cargo.toml
├── Makefile
└── lean-toolchain

Rust workspace

Toolchain: rust-toolchain.toml (stable, clippy, rustfmt).

cargo build
cargo test --workspace
cargo clippy --workspace -- -D warnings

Members include: runtime/attestor, runtime/kms-proxy, runtime/tool-broker, runtime/sidecar-watcher, runtime/labeler, runtime/wasm-sandbox, adapters/http-get, adapters/file-read. Optional or standalone crates (Hyperscan, protoc, fuzz, etc.) are documented in the root Cargo.toml and per-crate READMEs.

How pieces fit together

• Minimal (CLI + bundles): core/cli/pf, bundles/, config/. See Reuse and extend.
• Full platform: Go services under services/, admin console, ledger, gateway — use Docker Compose (make platform-up / make full-up). See local workflows.
• CLI-only forks: Can omit services/, console/, bench/, experiments/, and demos/.

---

Ecosystem standards

Adopt shared schemas, replay tooling, and CI patterns alongside this repo:

• CERT-V1 — schema and verifiers
• TRACE-REPLAY-KIT — runner and oracles
• morph-lean-ci — sharded Lean CI
• morph-replay-runner — branch replays
• mcp-sidecar-demo — permissions, epochs, IFC

In-repo: docs/specs/standards.md, docs/evidence/overview.md, docs/evidence/replay.md.

Proof-Carrying Science (PCS)

Verify lab and computation workflows with the pf CLI and frozen release fixtures.

git clone https://github.com/SentinelOps-CI/pcs-core ../pcs-core
export PCS_CORE_PATH=../pcs-core
make demo-pcs
make test-pcs-full    # full local gate; see docs/pcs/release-checklist.md

Full PCS documentation lives at docs/pcs/README.md.

---

Quick start

Canonical path (3 clicks): Getting started (15 min) → Local workflows → Deployment guide when you need production trust-chain env.

Prefer Make / Compose targets from those docs over ad-hoc scripts. Longer product concepts: guides/getting-started.md.

Option 1 — Install script

git clone --recurse-submodules https://github.com/SentinelOps-CI/provability-fabric
cd provability-fabric
make dev-standards   # optional: verify CERT-V1 + TRACE-REPLAY-KIT pins

# Linux / macOS
./scripts/install.sh
./scripts/test-new-user.sh

# Windows (Command Prompt is recommended for install scripts)
scripts\install.bat
scripts\test-new-user.bat

Git Bash on Windows can mis-handle paths and execution; prefer cmd or PowerShell for install.bat / test-new-user.bat. For Git Bash issues: bash scripts/windows-troubleshoot.sh.

Option 2 — Compose (Make wrappers)

make install-dev
make platform-up          # or: make ledger-up / make full-up
make compose-smoke

See local-workflows.md for the launch matrix, ports, and console (make full-up / --profile full). Docs: make docs-serve (port 8002).

Option 3 — Build the CLI from source

git clone --recurse-submodules https://github.com/SentinelOps-CI/provability-fabric
cd provability-fabric
make dev-standards   # optional: verify CERT-V1 + TRACE-REPLAY-KIT pins

cd core/cli/pf
go build -o pf .    # Windows: pf.exe
export PATH="$PATH:$(pwd)"          # Linux / macOS
# Windows (cmd):  set PATH=%PATH%;%CD%
# Windows (PS):   $env:PATH += ";$PWD"

cd ../../..
./pf init my-agent                  # Windows: pf.exe init my-agent

cd spec-templates/v1/proofs
lake build                          # requires Lean 4
cd ../../..

python tests/trust_fire_orchestrator.py

Kubernetes: use Helm charts under charts/ and runtime/admission-controller/deploy/ with values suited to your cluster.

---

Prerequisites

Profile	You need
Minimal	Go 1.23+ (core/cli/pf/go.mod). Lean optional for proofs. No Docker/Node/Rust required for bare CLI.
CLI + Rust runtime	Go + Rust (see rust-toolchain.toml). Docker/Node optional.
Full stack	Go, Python 3.8+, Node 18+, Rust, Docker; Lean and kubectl optional.

Data retention manager (if used): PostgreSQL, S3, BigQuery, and Python deps (psycopg2-binary, boto3, google-cloud-bigquery, pandas, pyarrow, pyyaml) as required by your deployment.

---

Architecture

High-level flow: specifications and external verifiers feed bundles; admission and sidecars enforce policy at runtime; the ledger and APIs expose state for operators and integrators.

flowchart TD
    A[Agent specification] --> B[Lean proof generation]
    B --> C[Specification bundle]
    C --> D[Admission controller]
    D --> E[Container deployment]
    E --> F[Sidecar watcher]
    F --> G[Runtime monitoring]
    G --> H[Constraint enforcement]

    I[Neural network] --> J[Marabou adapter]
    J --> K[Verification proof]
    K --> C

    L[Hybrid system] --> M[DryVR adapter]
    M --> N[Reach set]
    N --> C

    GNN[GPU neural network] --> ABC["α-β-CROWN adapter"]
    ABC --> GPUP[GPU verification proof]
    GPUP --> C

    C --> TL[Transparency ledger]
    TL --> GQL[GraphQL API]

Loading

Major surfaces: specification bundles (YAML + proofs), runtime guards (sidecars), solver adapters (e.g. Marabou, DryVR, α-β-CROWN), platform APIs + admin console, WebSocket updates, and JWT-based auth where enabled.

---

Contributing

Contributions are welcome. Start with CONTRIBUTING.md and Community governance.

Typical dev loop:

git clone --recurse-submodules https://github.com/SentinelOps-CI/provability-fabric
cd provability-fabric
make dev-standards   # optional: verify CERT-V1 + TRACE-REPLAY-KIT pins

cd core/cli/pf && go build -o pf . && cd ../..
# Optional: cmd/specdoc and other Go tools as needed

# Python test deps (install where requirements.txt exists), for example:
#   pip install -r tests/integration/requirements.txt
#   pip install -r tests/proof-fuzz/requirements.txt
#   pip install -r tools/compliance/requirements.txt
#   pip install -r tools/insure/requirements.txt
#   pip install -r tools/proofbot/requirements.txt

cd console && npm install && npm start   # optional UI at http://localhost:3000
cd ..

python tests/trust_fire_orchestrator.py

---

Troubleshooting

Symptom	What to check
pf not found	Build core/cli/pf and add it to PATH (pf.exe on Windows).
lake build fails	Run from the correct proofs directory; install Lean 4.
Python errors	Run scripts from the repository root unless a doc says otherwise.
K8s YAML / Helm	Many deployables are Helm templates, not raw kubectl apply files.
Windows paths	Prefer forward slashes in Git Bash; use cmd for .bat installers.
“Device or resource busy�	Close editors/explorers holding files; retry.
UI / Heroicons	Match icon names to your package.json / TypeScript setup (see console/tsconfig.json).

Windows: Use pf.exe and Command Prompt for install scripts when Git Bash misbehaves. More detail: bash scripts/windows-troubleshoot.sh.

---

Security

Report vulnerabilities per SECURITY.md.

The default branch is protected by workflows including dependency review (PRs), cargo-deny (deny.toml), actionlint, SBOM jobs, and OpenSSF Scorecard. Enable the dependency graph where GitHub features require it. Overview: CONTRIBUTING.md, .github/WORKFLOWS.md, docs/reference/ci-reference.md.

---

License

Apache License 2.0 — see LICENSE.

---

Acknowledgments

• Lean 4 — interactive theorem proving
• Marabou — neural network verification
• DryVR — hybrid systems
• α-β-CROWN — GPU-accelerated NN verification
• Sigstore — signing and transparency
• Memurai — Redis-compatible server for Windows

---

_{Provability Fabric — specifications, enforcement, and evidence for trustworthy agents.}