mirror of
https://github.com/allaunthefox/Research-Stack.git
synced 2026-07-31 03:05:21 +00:00
134 lines
3.5 KiB
Markdown
134 lines
3.5 KiB
Markdown
# LEAN_FIRST_BOUNDARY — Lean-first compliance contract
|
|
|
|
**Status:** Canonical enforcement doc
|
|
|
|
> **Lean is the source of truth. Everything else is a shim.**
|
|
|
|
This document is the short, contributor-facing boundary contract referenced by
|
|
AGENTS.md and all architecture/spec files.
|
|
|
|
---
|
|
|
|
## 1) Definitions
|
|
|
|
### 1.1 Canonical
|
|
|
|
"Canonical" means:
|
|
|
|
- the semantics are defined in Lean under `0-Core-Formalism/lean/Semantics/`
|
|
- `lake build` is the authority gate for formal claims
|
|
- invariants/cost functions/typed residual policies are Lean-owned
|
|
|
|
### 1.2 Shim / adapter
|
|
|
|
"Shim" means:
|
|
|
|
- boundary-only code in Python/Rust/JS/etc.
|
|
- allowed to do I/O, parsing, serialization, DB connections, subprocess spawn
|
|
- forbidden to define semantics
|
|
|
|
---
|
|
|
|
## 2) What belongs in Lean (required)
|
|
|
|
Lean MUST own:
|
|
|
|
1. **Finite types / enumerations**
|
|
- no open string matching in the core
|
|
- strings are boundary I/O only
|
|
|
|
2. **Invariants + cost functions**
|
|
- any logic that decides ACCEPT/REJECT/QUARANTINE/PROMOTE
|
|
|
|
3. **Provenance + attestation policy**
|
|
- required provenance fields
|
|
- deterministic hashing / chain rules
|
|
- receipt typing
|
|
|
|
4. **Surface/tool manifests**
|
|
- the list of supported tool names for an MCP surface
|
|
- the mapping from tool name → schema/behavior class
|
|
|
|
5. **Validators**
|
|
- any configuration payload (yaml/json/env inputs) must be validated by Lean
|
|
- missing required fields must be rejected or typed as residuals
|
|
- never silently default “unknown” into a guessed value
|
|
|
|
---
|
|
|
|
## 3) What belongs in shims (allowed)
|
|
|
|
Shims MAY do:
|
|
|
|
- read env vars / config files
|
|
- JSON/YAML parsing
|
|
- open sqlite/postgres connections
|
|
- call subprocesses (including Lean executables)
|
|
- transport: HTTP/MCP stdio plumbing
|
|
- emit logs
|
|
|
|
Shims MUST NOT:
|
|
|
|
- compute or approximate a cost function
|
|
- decide lawfulness
|
|
- guess missing fields (no “conservative defaults”)
|
|
- introduce new invariants
|
|
- implement branching that changes semantics (routing must be driven by Lean-owned tags/enums)
|
|
|
|
---
|
|
|
|
## 4) Float prohibition summary
|
|
|
|
- New core logic must not use `Float`.
|
|
- Use fixed-point:
|
|
- Q0_16 for dimensionless scalars
|
|
- Q16_16 only when range/precision is proven necessary
|
|
|
|
If a shim accepts float input from the outside world, it must convert at the
|
|
boundary and pass fixed-point values onward.
|
|
|
|
---
|
|
|
|
## 5) Receipts vs rejection
|
|
|
|
When adapter input is malformed or underspecified:
|
|
|
|
- **Preferred:** reject with a typed reason (Lean)
|
|
- **Alternative (when required):** accept as a *workbench_projection* artifact
|
|
but emit an explicit receipt describing:
|
|
- what was missing
|
|
- what was assumed
|
|
- what must be repaired to become receipt_backed
|
|
|
|
No silent repair.
|
|
|
|
---
|
|
|
|
## 6) Quick examples
|
|
|
|
### 6.1 BAD shim behavior
|
|
|
|
- A Python script reads `nodes.yaml`, sees missing CPU/RAM, and fills defaults.
|
|
- A Rust MCP server hardcodes tool names as strings.
|
|
|
|
### 6.2 GOOD shim behavior
|
|
|
|
- A shim reads `nodes.yaml`, passes JSON to a Lean validator, and exits nonzero
|
|
with a Lean-produced error if required fields are missing.
|
|
- A shim queries Lean for the canonical MCP tool manifest and exposes exactly
|
|
those tools.
|
|
|
|
---
|
|
|
|
## 7) Enforcement
|
|
|
|
- Any PR that introduces semantics in non-Lean code is an invariant violation.
|
|
- Any PR that adds new dependencies without explicit approval is rejected.
|
|
- Any PR that adds open-ended string parsing in the core is rejected.
|
|
|
|
---
|
|
|
|
## 8) References
|
|
|
|
- `6-Documentation/docs/AGENTS.md`
|
|
- `0-Core-Formalism/lean/Semantics/Semantics/JsonLSurfaceConnector.lean`
|