Skip to content

docs: proposals for external contracts and for reused verification results - #492

Merged
afflom merged 3 commits into
release/v0.4from
docs/proposal-external-contracts
Nov 14, 2026
Merged

afflom merged 3 commits into
release/v0.4from
docs/proposal-external-contracts

Conversation

@humuhumu33

Copy link
Copy Markdown
Contributor

Proposal only: this pull request adds docs/proposals/external-contracts.md and nothing else. It is gap B of three on the way to a verified inference engine written as a LexLean application (gap A, arrays, is SM-39 in its own pull request; gap C, floating point, is #486).

What it proposes

One closed declaration, external, that binds a function LexLean did not generate to a stated contract:

  • a signature, a contract (a proposition over the inputs and the output), a witness (a LexLean definition with a theorem that it meets the contract), and named evidence (an attested conformance report bound to the contract's statement ID, or later a proof);
  • generated Lean: an opaque constant whose hidden value is the witness, and one axiom <Module>.<name>.contract;
  • every theorem that uses the contract carries that one axiom in its exact observed set, so the existing axiom audit reports it and verify prints it with its evidence; a theorem that does not use it does not carry it;
  • no other axiom can be written. The witness makes the generated axiom a true statement about the constant, so it adds no logical strength and cannot make False provable.

Why it is left open

It changes the trust model of SPEC §4.2 and §5 (the ban on author axioms). That is the owners' decision, so nothing is implemented. The document gives four options (generated axiom, parameterised theorems, run-time checks, unaudited binding), recommends the first, and lists eight decisions with a recommendation each.

Evidence

A prototype in the pinned Lean 4.32.1, in the shapes the backend emits (section 7). A caller of an external int8 dot product was proved against the contract. Lean printed:

'Engine.Main.score_correct' depends on axioms: [propext, Engine.Main.dotFast.contract]
'Engine.Main.reference_only' does not depend on any axioms
'Engine.Main.dot_reference_meets' does not depend on any axioms

and rfl could not prove the external function equal to its witness. This is Lean output for the proposed lowering, not lexlean verify output: the compiler has no external declaration.

Aeneas

Assessed, not built (section 8). Its Lean backend requires Mathlib and pins Lean 4.36.0-rc2 against LexLean's 4.32.1; it covers a subset of safe Rust, not unsafe code or SIMD; and a theorem about the translated model moves the trust to the translator and does not remove it. Sound in principle, not small. Revisit under #356 once #362 has landed.

Needed from the owners

D1 to D3 of the proposal: whether a document may state an assumption about foreign code at all, by which mechanism, and whether the witness is mandatory.

🤖 Generated with Claude Code

…al declarations)

One closed declaration that binds a foreign function to a stated contract: an opaque constant whose hidden value is a LexLean witness, and one generated contract axiom that every dependent theorem carries in its exact observed set and verify reports with its evidence. Options, a Lean 4.32.1 prototype with its output, an assessment of an Aeneas bridge, and the decisions left to the owners. Proposal only: nothing is implemented.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

@afflom afflom left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bounded proposal review at 614c978:

  • P2 — Separate proof-axiom dependencies from executable external uses (§6.5, especially line123). A definition can call opaque dotFast without invoking dotFast.contract; reflexive or conditional theorems can mention the call without that axiom. The prototype establishes score_correct's contract dependency, not coverage of every runtime foreign-code use. SPEC §5.4's exact axiom audit is not a general call graph. Specify a separate fail-closed external-call/binding inventory, or narrow the reporting promise while still accounting for execution trust.
  • P2 — Complete the report-to-implementation binding contract (§6.4, §10). A pinned report hash and matching statement ID authenticate report bytes and contract identity, but the proposal does not define the comparison/refusal tying its code digest to the actually selected artifact, symbol/ABI and target, the explicitly trusted attester, or an acceptable result. Keep the D6 witness-only limitation explicit. A witness establishes satisfiability of the logical reference contract; a finite conformance report does not establish universal native correctness, purity or termination.
  • P2 — Narrow the opacity statement (line104). “Nothing about dotFast is provable except through the axiom” is too broad: reflexivity and hypotheses remain available. The limitation is unfolding the opaque function to its witness or deriving the intended computational contract from that body.

The document usefully distinguishes the Lean prototype from lexlean verify and reports propext alongside the contract axiom. Preserve those distinctions and all transitive dependencies. D1–D8 remain proposed owner decisions; ready status does not amend the existing ban on author axioms or authorize a language/identity change. No experiment or implementation was repeated.

afflom commented Nov 12, 2026

Copy link
Copy Markdown
Member

Qualification efficiency note for the existing proposal owner: #486 and this PR each change only their proposal document, yet their current ready-event runs43220907607 and43221844175 have already materialized55 jobs apiece, including native/Atlas work. Please consolidate the outstanding document corrections into one reviewed documentation carrier before the next qualification cycle, rather than starting another independent full run for each correction. Keep #493's code/identity work separate unless an actual dependency requires composition.

Current runs remain untouched and their evidence stays scoped to their own heads; no canceled/partial jobs may be combined into acceptance. This is a request to reduce duplicate future qualification, not to skip the final resulting head's required gate or accept either proposed trust-model decision.

@afflom afflom mentioned this pull request Nov 12, 2026

afflom commented Nov 12, 2026

Copy link
Copy Markdown
Member

Terminal pipeline readback at unchanged614c978e: existing PR run43221844175 attempt1 completed70/70 jobs and772/772 steps successfully, including same-run honesty; exact-head reproducibility43221844155 also passed. No canceled/other run jobs were aggregated, and no gate was repeated.

Review5875193015's three source findings still have no owner disposition, so pipeline completion is not source or merge clearance. The concrete next step remains one reviewed correction covering runtime-call versus proof-axiom inventory, precise implementation/attester/result binding, and the opacity wording. Retain6824891015's consolidation request for the next necessary qualification. Current release also advanced through #486; review resulting-tree applicability before landing. No proposed trust-model decision or implementation scope is accepted by this CI result.

Separate proof-axiom dependencies from executable external uses (call
inventory), complete the report-to-implementation binding, narrow the
opacity statement.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3M8ULnzEQwLLngyBBX
…, record D1

One reviewed documentation carrier, as requested on #492. D1 (SPEC.md
9.4 reuse of verification results) is decided: not adopted now.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3M8ULnzEQwLLngyBBX

afflom commented Nov 13, 2026

Copy link
Copy Markdown
Member

Dispositions for review 5875193015 (pushed 29be144):

  1. P2 call vs axiom inventory: accepted. §6.5 now separates proof dependencies (axiom set) from executable uses, adds a fail-closed LexLean-computed external-call inventory (external_uses) and says it is not the axiom audit.
  2. P2 binding contract: accepted. §6.4 now defines the refusal (code digest vs selected artifact, symbol/ABI/target, named attester, result); unbound until D6; witness-only limit explicit (§6.4, §10).
  3. P2 opacity: accepted. §6.2 now says only unfolding to the witness and deriving the computational contract are blocked; reflexivity and hypotheses remain.
    Consolidation (6824891015): this is the one documentation carrier. docs: proposal for verification results reused across runs (UOR-native, piece 3) #508's verification-memo is folded in with D1 decided as not adopted now (§9.4 unchanged); docs: proposal for verification results reused across runs (UOR-native, piece 3) #508 closed. Marking ready with auto-merge; no trust-model decision here is accepted by landing.

Generated by Claude Code

@afflom afflom changed the title docs: proposal for contracts on code LexLean did not generate (external declarations) docs: proposals for external contracts and for reused verification results Nov 13, 2026

@afflom afflom left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bounded delta review at 29be144 credits all three substantive corrections from review5875193015: §6.5 now separates fail-closed executable external-use inventory from proof axioms; §6.4 defines artifact/symbol/ABI/target/attester/result binding with the unbound-until-D6 and witness limits; §6.2 correctly preserves reflexivity and hypotheses.

One small consistency correction remains: D2 near line26 and Option A near line63 still say Lean reports “every use.” Narrow those two summaries to contract-proof dependencies so they agree with §6.5. This needs no second inventory or framework.

The folded verification memo explicitly decides D1 NOT ADOPTED and leaves SPEC §9.4 unchanged; D2–D8 are moot under that decision. #508's closure is consolidation, not implementation of reuse or a trust-policy change. Future external-contract design decisions remain proposals. Current CI/repro still require their own exact-head terminal acceptance; prior-head green evidence is not substituted. No experiment or gate repeated.

@afflom
afflom merged commit 69de740 into release/v0.4 Nov 14, 2026
71 checks passed
@afflom
afflom deleted the docs/proposal-external-contracts branch November 14, 2026 04:13
afflom pushed a commit that referenced this pull request Nov 14, 2026
…urity-patch

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3M8ULnzEQwLLngyBBX

afflom commented Nov 14, 2026

Copy link
Copy Markdown
Member

Postlanding scope: external merge69de740 has parents[11f16b8,29be144a] and tree81d8596a. The reviewed proposal head29be did complete CI43497413516 attempt1, all70 jobs/772 steps, with exact repro43497413537. Preserve this finished evidence without repeating it; its fcf72054 tree differs from the actual release tree, whose CI43555579969/repro43555579964 remain pending.

The three substantive proposal corrections remain credited. The two residual 'every use' summaries from5897390706 still need a small owner correction consolidated with necessary documentation work. Landing this document neither adopts the external-contract trust change nor implements verification-result reuse: memo D1 remains NOT ADOPTED and SPEC§9.4 unchanged. No broad feature issue is closed by this proposal landing, and no retroactive premerge acceptance is claimed.

humuhumu33 added a commit that referenced this pull request Nov 14, 2026
Release gained two files under docs/proposals (#492). With the head containing
release, the merge of this pull request lands the tree the whole gate verifies.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants