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:

Finite types / enumerations
- no open string matching in the core
- strings are boundary I/O only
Invariants + cost functions
- any logic that decides ACCEPT/REJECT/QUARANTINE/PROMOTE
Provenance + attestation policy
- required provenance fields
- deterministic hashing / chain rules
- receipt typing
Surface/tool manifests
- the list of supported tool names for an MCP surface
- the mapping from tool name → schema/behavior class
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

3.5 KiB Raw Blame History