|
1 | | -= RSR Template Repository |
2 | | -:toc: preamble |
3 | | -:icons: font |
| 1 | +// SPDX-License-Identifier: PMPL-1.0-or-later |
| 2 | += nesy-solver |
| 3 | +Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> |
| 4 | +:toc: |
| 5 | +:toc-placement: preamble |
4 | 6 |
|
5 | | -image:https://www.bestpractices.dev/projects/TBD/badge[OpenSSF Best Practices, link="https://www.bestpractices.dev/projects/TBD"] |
6 | | -image:https://api.securityscorecards.dev/projects/github.com/hyperpolymath/nesy-solver/badge[OpenSSF Scorecard, link="https://securityscorecards.dev/viewer/?uri=github.com/hyperpolymath/nesy-solver"] |
7 | | - |
8 | | -[TIP] |
9 | | -==== |
10 | | -**AI-Assisted Install:** Just tell any AI assistant: + |
11 | | -`Set up Nesy Solver from https://github.com/hyperpolymath/nesy-solver` + |
12 | | -The AI reads the manifest, asks you a few questions, and handles everything. |
13 | | -==== |
| 7 | +Public proof playground at link:https://nesy-solver.dev[nesy-solver.dev] — submit |
| 8 | +proof obligations, get prover recommendations, stream verdicts back live. |
14 | 9 |
|
15 | 10 | == Overview |
16 | 11 |
|
17 | | -**The canonical template for RSR (Rhodium Standard Repository) projects.** |
18 | | - |
19 | | -This project follows a **Dual-Track** architecture: |
20 | | -* **Root:** High-level orientation and rich documentation for humans. |
21 | | -* **Sub-directories:** Machine-readable metadata and technical implementation. |
22 | | - |
23 | | -== ABI/FFI Standard (Verified Interface Seams) |
| 12 | +`nesy-solver` is the interactive frontend for the hyperpolymath neurosymbolic |
| 13 | +learning loop. It connects users directly to the Hypatia + Echidna + VeriSim |
| 14 | +pipeline: |
24 | 15 |
|
25 | | -All projects with foreign function interfaces MUST follow this consolidated standard: |
| 16 | +1. Submit a proof obligation in SMT-LIB, Lean 4, Coq/Rocq, Idris2, or Agda |
| 17 | +2. The app recommends a prover strategy based on live `proof_attempts` data |
| 18 | + in VeriSim |
| 19 | +3. Dispatches to Echidna for execution |
| 20 | +4. Streams the verdict back in real time |
| 21 | +5. Records the attempt in `verisim-api` — the playground improves its |
| 22 | + recommendations over time from actual usage data |
26 | 23 |
|
27 | | -* **ABI (Idris2):** `src/interface/abi/*.idr` (The Specification) |
28 | | -* **FFI (Zig):** `src/interface/ffi/src/*.zig` (The Implementation) |
29 | | -* **Generated:** `src/interface/generated/*.h` (The Artifacts) |
| 24 | +== Supported Formalisms |
30 | 25 |
|
31 | | -This unification ensures that the "Truth," the "Bridge," and the "Result" are managed as a single architectural unit. |
| 26 | +* SMT-LIB (Z3, CVC5) |
| 27 | +* Lean 4 |
| 28 | +* Coq / Rocq |
| 29 | +* Idris2 |
| 30 | +* Agda |
32 | 31 |
|
33 | | -== AI Gatekeeper Protocol |
34 | | - |
35 | | -All projects MUST include a root `0-AI-MANIFEST.a2ml`. This is the mandatory entry point for all AI agents. It prevents duplicate file errors and preserves architectural invariants across sessions. |
36 | | - |
37 | | -== Repository Structure |
| 32 | +== Architecture |
38 | 33 |
|
39 | 34 | [cols="1,3"] |
40 | 35 | |=== |
41 | | -|Directory |Purpose |
42 | | - |
43 | | -|`.github/` |
44 | | -|Forge-specific metadata (CODEOWNERS, SECURITY.md, workflows). |
45 | | - |
46 | | -|`.machine_readable/` |
47 | | -|Canonical project state (6 a2ml files), bot directives, and AI guides. |
48 | | - |
49 | | -|`container/` |
50 | | -|Stapeln container ecosystem (selur-compose, vordr, rokur). |
51 | | - |
52 | | -|`docs/` |
53 | | -|Technical documentation sorted by tracks (Theory, Practice, Architecture). |
54 | | - |
55 | | -|`docs/legal/` |
56 | | -|Consolidated legal exhibits and full license texts. |
57 | | - |
58 | | -|`src/interface/` |
59 | | -|Unified ABI/FFI/Generated interface unit. |
| 36 | +| Component | Role |
| 37 | + |
| 38 | +| `web/` | Frontend (ReScript + Deno) |
| 39 | +| `src/core/` | Proof dispatch and strategy selection |
| 40 | +| `src/interface/abi/` | Idris2 ABI for prover interface contracts |
| 41 | +| `src/interface/ffi/` | Zig FFI bridge to Echidna + external provers |
| 42 | +| `deploy/` | Container deployment (Containerfile, Podman) |
| 43 | +| `verisim-api` | External: records proof attempts, drives strategy recommendations |
60 | 44 | |=== |
61 | 45 |
|
62 | | -== Container Ecosystem (Stapeln) |
63 | | - |
64 | | -This template includes a complete `container/` directory for the **Stapeln Six** tools: |
65 | | -1. **selur** (Orchestration) |
66 | | -2. **cerro-torre** (Verified Packaging) |
67 | | -3. **svalinn** (Edge Gateway) |
68 | | -4. **vordr** (Monitoring) |
69 | | -5. **rokur** (Secrets) |
70 | | -6. **k9-svc** (Deployment Contracts) |
71 | | - |
72 | | -== Quick Start |
73 | | - |
74 | | -[source,bash] |
75 | | ----- |
76 | | -just init # Interactive bootstrap |
77 | | -just build # Unified build |
78 | | -just test # Unified test |
79 | | -just container-build # Build verified OCI image |
80 | | ----- |
81 | | - |
82 | | -== Contractile System |
83 | | - |
84 | | -This template includes five **contractile files** in `.machine_readable/contractiles/` that make your repository's rules executable: |
85 | | - |
86 | | -[cols="1,2,3"] |
87 | | -|=== |
88 | | -| Tool | File | Purpose |
89 | | - |
90 | | -| `must check` |
91 | | -| `Mustfile.a2ml` |
92 | | -| Physical state invariants (files exist, code compiles, no secrets) |
93 | | - |
94 | | -| `trust verify` |
95 | | -| `Trustfile.a2ml` |
96 | | -| Integrity verification (hashes valid, signatures correct, provenance traceable) |
97 | | - |
98 | | -| `dust status` |
99 | | -| `Dustfile.a2ml` |
100 | | -| Cleanup tasks (stale files, build artifacts, expired tokens) |
101 | | - |
102 | | -| `intend list` |
103 | | -| `Intentfile.a2ml` |
104 | | -| Design intent and roadmap tracking |
105 | | - |
106 | | -| `k9 eval` |
107 | | -| `*.k9.ncl` |
108 | | -| Nickel-based deployment validation |
109 | | -|=== |
110 | | - |
111 | | -=== Installation |
112 | | - |
113 | | -[source,bash] |
114 | | ----- |
115 | | -cargo install contractile |
116 | | -
|
117 | | -# Create symlinks for individual commands |
118 | | -for cmd in must trust dust intend k9; do |
119 | | - ln -sf $(which contractile) ~/.local/bin/$cmd |
120 | | -done |
121 | | ----- |
122 | | - |
123 | | -=== Usage |
124 | | - |
125 | | -[source,bash] |
126 | | ----- |
127 | | -# Symlink contractiles to project root (CLI searches ./contractiles/) |
128 | | -ln -sf .machine_readable/contractiles contractiles |
129 | | -
|
130 | | -# Run checks |
131 | | -must check # Verify physical state (23 checks in typical RSR project) |
132 | | -trust verify # Verify integrity and provenance |
133 | | -dust status # Show cleanup items |
134 | | -intend list # Show design intents and roadmap |
135 | | -
|
136 | | -# Generate Just recipes from contractile files |
137 | | -contractile gen-just # Creates contractile.just (already imported by Justfile) |
138 | | -
|
139 | | -# Then use via Just: |
140 | | -just must-check |
141 | | -just trust-verify |
142 | | ----- |
143 | | - |
144 | | -=== Writing Checks |
145 | | - |
146 | | -Contractile files use A2ML format — simple, line-oriented: |
147 | | - |
148 | | -[source] |
149 | | ----- |
150 | | -### check-name |
151 | | -- description: Human-readable description |
152 | | -- run: shell command (exit 0 = pass, non-zero = fail) |
153 | | -- severity: critical | warning | info |
154 | | ----- |
155 | | - |
156 | | -See link:https://github.com/hyperpolymath/contractiles[contractiles documentation] for the full specification. |
157 | | - |
158 | | -== Wondering How This Works? |
159 | | - |
160 | | -If you're curious about the tech behind the claims in this README, see |
161 | | -link:EXPLAINME.adoc[EXPLAINME.adoc] — feature highlights with code paths |
162 | | -and honest caveats. Questions welcome via issues or direct contact. |
163 | | - |
164 | | -== Documentation |
165 | | - |
166 | | -* link:EXPLAINME.adoc[Show Me The Receipts] — how headline features work |
167 | | -* link:CONTRIBUTING.adoc[Contributing Guide] |
168 | | -* link:GOVERNANCE.adoc[Governance Model] |
169 | | -* link:docs/attribution/MAINTAINERS.adoc[Maintainers & Citations] |
170 | | -* link:SECURITY.adoc[Security Policy] |
171 | | - |
172 | 46 | == License |
173 | 47 |
|
174 | | -SPDX-License-Identifier: PMPL-1.0-or-later |
175 | | -See link:LICENSE[LICENSE] and link:docs/legal/[docs/legal/] for details. |
| 48 | +PMPL-1.0-or-later. See link:LICENSE[LICENSE]. |
0 commit comments