From e1934945588a701475b8530405e7970e5deaaba8 Mon Sep 17 00:00:00 2001 From: humuhumu33 <68450279+humuhumu33@users.noreply.github.com> Date: Tue, 27 Oct 2026 10:58:12 +0000 Subject: [PATCH 01/10] docs: restyle the README and add the repository logo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README is reorganized for a reader arriving cold: a centered header with the logo, the one-line value proposition, the document links and the state badges, then Quickstart (container, binary, source, the §29 literal), How LexLean works (pipeline plus the command table with what each command may claim), Why LexLean, When to use LexLean, the capability register table, the examples, the gate, the evidence rules, the documented deviations, the layout and the license. The gate-relevant content is unchanged: the capability table keeps its exact header, its three cells, its `build` level cell and its 35 rows, so every one of the 457 registered IDs is still claimed exactly once by the row that owns it, and the register-size and honesty-level sentences are still stated. No dash is used as punctuation anywhere in the prose, and no list uses a hyphen marker; hyphens remain only where they are part of an identifier, a path, a command or a table separator, because those are machine-checked tokens. assets/lexlean-logo.svg is new: a QED tombstone with a check mark beside a monospace wordmark, in the repository's own purple, legible on light and dark renderings. SPEC.md §7 lists it, so the added file has the defined role §7 requires. --- README.md | 284 +++++++++++++++++++++++----------------- SPEC.md | 2 + assets/lexlean-logo.svg | 16 +++ 3 files changed, 185 insertions(+), 117 deletions(-) create mode 100644 assets/lexlean-logo.svg diff --git a/README.md b/README.md index 34c5689ff0..e4dd959194 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,82 @@ -# LexLean +
+ + LexLean + -A closed-lexicon LaTeX-to-Lean 4 compiler whose canonical document and prose-free Lean program are generated from one semantic representation. +
-The complete normative contract is [SPEC.md](SPEC.md) (`LEXLEAN-SPEC-1`). Every capability below is a claim in [`model/ids.toml`](model/ids.toml), carried at honesty level `build`: constructed here and validated against its oracle by the test named `conformance_`. The generated register is [CONFORMANCE.md](CONFORMANCE.md); the closed diagnostic registry is [ERRORS.md](ERRORS.md); the falsifiability evidence is in [VERIFICATION.md](VERIFICATION.md). +

One controlled-language document in. The canonical paper, a kernel-checked Lean 4 program, and a certified Rust package out.

-## What it does +

+ Spec + · + Conformance + · + Diagnostics + · + Evidence + · + Changelog + · + MNIST model +

-LexLean compiles `.lex.tex` modules written in a closed controlled language: every word, symbol, and control must be declared by a versioned lexicon package, every sentence parses under a fixed grammar, and one typed intermediate representation generates both the canonical LaTeX document and the prose-free Lean 4 program. Verification compiles the generated Lean under the pinned `leanprover/lean4:v4.32.1` toolchain, replays every module with `leanchecker`, audits axioms with exact `#print axioms` parsing, and publishes a content-addressed attestation. +

+ Latest release + Acceptance gate + Pinned Lean toolchain + Conformance register size + License +

-```text -lexlean init --name my-doc --module-prefix MyDoc -lexlean lock -lexlean check -lexlean build -lexlean verify -``` +

LexLean compiles .lex.tex modules written in a closed controlled language: every word, symbol, and control must be declared by a versioned lexicon package, every sentence parses under a fixed grammar, and one typed intermediate representation generates both the canonical LaTeX document and the prose-free Lean 4 program.

-## Install +

lexlean verify compiles the generated Lean under the pinned leanprover/lean4:v4.32.1 toolchain, replays every module with leanchecker, audits axioms by parsing #print axioms exactly, and publishes a content-addressed attestation.

-`lexlean verify` runs the pinned `leanprover/lean4:v4.32.1` toolchain, so the -published container image carries both and is the shortest path to a run that -can actually verify: +

Evidence, not belief. check and build never claim verification. Only verify runs Lean, and whatever it cannot check is reported as not validated, never passed in silence.

+
+ +## Quickstart + +### Run in the container + +`lexlean verify` runs the pinned toolchain, so the published image carries the compiler and `leanprover/lean4:v4.32.1` together. This is the shortest path to a run that can actually verify: ```text -docker pull ghcr.io//lexlean: -docker run --rm -v "$PWD:/work" ghcr.io//lexlean: verify +docker pull ghcr.io/uor-foundation/lexlean:0.4.0 +docker run --rm -v "$PWD:/work" ghcr.io/uor-foundation/lexlean:0.4.0 verify ``` -`release.yml` publishes the image for a tagged release under the repository's -owner, with the tag's version as the image tag. The only tag so far is -`v0.1.0`, whose image is `ghcr.io/afflom/lexlean:0.1.0`. +The image is around 4 GB, nearly all of it the pinned toolchain's compiled library: the part `verify` needs, and the part a smaller image would have to leave out. -The image is around 4 GB, nearly all of it the pinned toolchain's compiled -library — the part `verify` needs and the part a smaller image would have to -leave out. +### Or install a binary -Each [release](https://github.com/UOR-Foundation/LexLean/releases) also attaches one -binary per supported host (SPEC.md §8.3), the packaged crate, a CycloneDX bill -of materials, `checksums.txt` over every other asset, and the `just vv` -evidence for the tagged commit. A binary alone can `init`, `lock`, `fmt`, -`check`, and `build`; `verify` additionally needs the pinned toolchain -installed through [elan](https://github.com/leanprover/elan). +Each [release](https://github.com/UOR-Foundation/LexLean/releases) attaches one binary per supported host (SPEC.md §8.3), the packaged crate, a CycloneDX bill of materials, `checksums.txt` over every other asset, and the `just vv` evidence for the tagged commit. + +```text +tar -xzf lexlean-0.4.0-binaries.tar.gz +sha256sum -c checksums.txt +``` -From source, with the prerequisites below: +A binary alone can `init`, `lock`, `fmt`, `check`, and `build`. `verify` additionally needs the pinned toolchain installed through [elan](https://github.com/leanprover/elan). From source, with the prerequisites in [Building and running the gate](#building-and-running-the-gate): ```text cargo install --locked --path crates/lexlean ``` -Versions follow SPEC.md §30.1 and are recorded in [CHANGELOG.md](CHANGELOG.md). -§2.3 fixes `0.1.0` as the initial implementation version and `1.0.0` as the -first release satisfying the complete specification, so a `0.1.0` tag does not -claim the §30 release criterion — `cargo xtask release-check` reads that -criterion and says exactly which parts of it do not hold. +The complete normative contract is [SPEC.md](SPEC.md) (`LEXLEAN-SPEC-1`). The generated register is [CONFORMANCE.md](CONFORMANCE.md), the closed diagnostic registry is [ERRORS.md](ERRORS.md), and the falsifiability evidence is in [VERIFICATION.md](VERIFICATION.md). -## The literal example +### Write, build, verify -[examples/nat-add-zero/src/Main.lex.tex](examples/nat-add-zero/src/Main.lex.tex) is the complete SPEC.md §29 document: +```text +lexlean init --name my-doc --module-prefix MyDoc +lexlean lock +lexlean check +lexlean build +lexlean verify +``` + +The document is plain controlled language. This is the complete SPEC.md §29 example, committed as [examples/nat-add-zero/src/Main.lex.tex](examples/nat-add-zero/src/Main.lex.tex): ```latex \begin{lexlean}{Main} @@ -73,7 +93,7 @@ Close the goal by reflexivity. \end{lexlean} ``` -From one linked representation it generates the prose-free Lean module +From that one source LexLean generates the prose-free Lean module ```lean module @@ -87,77 +107,60 @@ public theorem add_zero (llv0 : Nat) : Eq (Nat.add llv0 0) llv0 := by end LexLeanExample.Main ``` -and the canonical LaTeX document, regenerated from IR rather than copied ("The goal follows by reflexivity."), plus source maps, coverage, and a manifest — all byte-reproducible across directories. `lexlean verify` then compiles the module under the pinned toolchain, replays it with `leanchecker`, parses `#print axioms` exactly, and records the empty observed axiom set in a content-addressed attestation. - -The larger [native Atlas source graph](examples/uor-atlas/src/Atlas.lex.tex) is -rooted by `Atlas.lex.tex` and uses the generic closed-core form for lossless -formal-library migration. Its module-local typed expression DAGs, declarations, -definition bodies, proofs, inductive metadata, instances, and explicit axiom -policies are linked semantic data. The same values generate readable canonical -LaTeX and reconstruct kernel-checked Lean declarations. The one-time conversion -and exact comparison are recorded in -[MIGRATION.md](examples/uor-atlas/MIGRATION.md); the independently authored -implementation is absent from the release tree. `VR-19` permanently requires -one generated Lean module per native source module, public imports confined to -`Init` and the generated graph, only the generic `Lean` backend-support import, -and no second Atlas implementation. +and the canonical LaTeX document, regenerated from the linked representation rather than copied (the prose reads "The goal follows by reflexivity."), plus source maps, coverage, and a manifest, all byte-reproducible across directories. `verify` then compiles the module under the pinned toolchain, replays it with `leanchecker`, parses `#print axioms` exactly, and records the empty observed axiom set in a content-addressed attestation. -Language-1.1 semantic modules use the closed-core backend's fixed finite Lean -budgets (`maxRecDepth = 100000`, `maxHeartbeats = 1000000000`) so complete -nested byte-data declarations are not restricted by interactive defaults. -Project child timeout/output limits and full kernel/axiom verification remain -mandatory. These are generated backend settings, not caller-provided options. +## How LexLean works -## Source packages - -A language-1.2 project imports the modules of another project of its workspace without copying them: `[[source_package]]` in `lexlean.toml` names a member directory listed by `lexlean-workspace.toml`, `lexlean.lock` pins the package by the digest of its manifest and source files, every command recomputes the pin, imports are closed to the project's own modules and the declared packages, and `verify` replays the package's modules under its module prefix with the package as their origin (SPEC.md §10.5, `PK-01`..`PK-05`; the workspace the cases use is [tests/packages/workspace](tests/packages/workspace/)). +```text +your document (.lex.tex, closed lexicon) + | + v +one typed semantic representation <- the single source of truth + | + +----+----------------+ + v v +canonical LaTeX prose-free Lean 4 +(paper or PDF) (kernel-checked, exact axiom audit) + | + v + production compilation + | + v + certified Rust package + + certificates A / B / E + attestation + (replays offline, without the source) +``` -## Examples that verify under the pinned toolchain +| Command | What it does | What it may claim | +| --- | --- | --- | +| `lexlean init` | Scaffolds a project | nothing | +| `lexlean lock` | Pins lexicons and dependencies in a canonical lock file | nothing | +| `lexlean check` | Lexical closure, grammar, typing, diagnostics | never verification | +| `lexlean build` | Generates Lean, LaTeX, source maps, manifests | never verification | +| `lexlean verify` | Compiles under the pinned toolchain, replays with `leanchecker`, audits axioms, attests | the only verified claim | +| `lexlean production build` | Exports certified Rust packages with their certificates | kernel-checked preservation | +| `lexlean migrate --to 1.2` | Upgrades a language-1.1 project, proved in a scratch copy first | writes nothing on refusal | -The [compiler/](compiler/) project defines the production realization calculus (SPEC.md §17.14) in LexLean and passes the same gates as an example; its hand-constructed target programs live under [compiler/fixtures/](compiler/fixtures/). Its `Gnaf` module states GNAF requests over that calculus (SPEC.md §17.15): the complete-system universe, machine contract, and objective order, all fixed before any optimizer, with a kernel-checked theorem that the universe is complete. The requests themselves live under [compiler/gnaf/](compiler/gnaf/), and [compiler/gnaf.manifest.json](compiler/gnaf.manifest.json) is the dependency manifest UOR-GNAF §20 requires. Its `Certification` module checks GNAF certificates (SPEC.md §17.18) under [compiler/certificates/](compiler/certificates/): a global optimum, an argmin, or a complete Pareto frontier is certified from evidence for every system of the universe rather than by enumerating it, with the soundness of the checker proved in [compiler/proofs/](compiler/proofs/); local normality, correctness, and representation-minimality are separate, weaker statuses, and an incomplete certificate names its first open obligation. The target fixtures' Rust packages (§17.16) live under [compiler/rust/](compiler/rust/). +A language-1.2 project can also import the modules of a locked, content-addressed package of its workspace instead of copying them: `[[source_package]]` in `lexlean.toml` names a member directory listed by `lexlean-workspace.toml`, `lexlean.lock` pins the package by the digest of its manifest and source files, every command recomputes the pin, imports are closed to the project's own modules and the declared packages, and `verify` replays the package's modules under its module prefix with the package as their origin (SPEC.md §10.5, `PK-01`..`PK-05`; the workspace the cases use is [tests/packages/workspace](tests/packages/workspace/)). -Every directory under [examples/](examples/) is discovered by the example gate (`EX-08`) and must format, lock, check, build, and verify with real Lean 4.32.1 (`cargo xtask verify-examples`). Its platform-independent build outputs and its normalized verification records are committed under `expected/` and compared byte for byte by the golden gate (§28.3) and the example gate (§29.5); that those bytes are also independent of where the build ran is the separate claim of `AR-13` and `EX-06`. +Language-1.1 semantic modules use the closed-core backend's fixed finite Lean budgets (`maxRecDepth = 100000`, `maxHeartbeats = 1000000000`) so complete nested byte-data declarations are not restricted by interactive defaults. Project child timeout and output limits and full kernel and axiom verification remain mandatory. These are generated backend settings, not caller-provided options. -| Example | What it exercises | -| --- | --- | -| [nat-add-zero](examples/nat-add-zero/) | The literal SPEC.md §29 document (`EX-01`..`EX-06`). | -| [peano-arithmetic](examples/peano-arithmetic/) | Five modules with explicit imports, a local path glossary of proof constants from `Init` (`Nat.add_comm`, `Nat.le_trans`, `Eq.symm`, universe-polymorphic `rfl`, ...), label words, document-denoted definitions of all three kinds (`count`, `double`, `even`, `positive`, `divides`), noun-of and binary-noun-of frames (`the successor of`, `the sum of ... and ...`), sections with inherited parameters and references to parameterized declarations, and every §16 proof form: `Assume`, `Apply`, `Close the goal with`/`by reflexivity`, witnesses, left/right, multi-rule `rewrite` at the goal, `constructor`, `cases` on naturals and on hypotheses (`And`, `Exists`), `induction`, and `calculate`; theorems under `\noaxioms`, `\allowaxioms{propext}`, and `\exactaxioms{Classical.choice;Quot.sound;propext}` whose observed axiom sets are audited exactly. | -| [propositional-logic](examples/propositional-logic/) | Reasoning over `Prop`-typed locals with a `proposition` type noun defined as the sort: commutativity and associativity of conjunction and disjunction, disjunction elimination, double negation, De Morgan, explosion, biconditionals, and classical double-negation elimination under an exact axiom policy — through cases on `And`/`Or`/`Iff` hypotheses, `constructor`, and `Apply`. | -| [list-induction](examples/list-induction/) | Universe-polymorphic `List` with an eliminator descriptor: type-valued section parameters, `List.nil`/`List.cons`, an infix `⧺` for `List.append`, structural induction over lists using earlier document lemmas as rewrite rules, and nested noun phrases (`the length of ... equals the sum of the length of ... and the length of ...`). | -| [semantic-1.1](examples/semantic-1.1/) | A source-Lean-free, multi-module language-1.1 project covering every closed type, declaration, term, instance, structural-recursion, match, Boolean/Nat validation, proof variant, portable integer width, byte/string form, primitive operation, and cross-module kernel reduction. | -| [language-1.2](examples/language-1.2/) | The language-1.2 contract (SPEC.md §17.12): a `lexlean/semantic-module/2` module whose definition and theorem statement use the 1.2-only typed `let` term, lowered to Lean `let` and verified with an empty observed axiom set. | -| [recursive-data](examples/recursive-data/) | Language-1.2 recursive data (SPEC.md §17.12) across two modules: a self-recursive parameterized `Tree`, a nested `Rose` through `List`, the mutual `Expr`/`Stmt` group, a parameterized result-like `Outcome`, products and pairs in a structure; structural recursion and induction with one hypothesis per recursive field, under exact axiom policies. | -| [higher-order](examples/higher-order/) | Language-1.2 first-class functions (SPEC.md §17.12): generic `mapList`, `foldList`, and `compose`; lambdas with explicit captures; definition references across modules; a visitor record of functions over an arithmetic AST agreeing with direct evaluation; a generic induction theorem applied at `Nat`; executable definitions passing only non-escaping closures. | -| [recursion](examples/recursion/) | Language-1.2 recursion (SPEC.md §17.12): mutual structural groups over a nested rose tree, the mutual `Expr`/`Stmt` syntax, and the naturals, each lowered with `termination_by structural`; three well-founded normalizations (`countdown`, `reduce`, a bounded `search`) whose per-call decrease obligations are proved by `linear_arithmetic` and bound as explicit evidence; closed values computed by kernel reduction under exact axiom policies. | -| [collections](examples/collections/) | Language-1.2 ordered collections (SPEC.md §17.12): a String-keyed compiler symbol table built by an executable fold, a call graph whose reachability and least-first topological order the kernel computes, a cyclic graph with no order, a reasoning-state fixed point (the ancestor closure of a parent relation) reached by bounded iteration, and reordered literals that are equal by construction. | -| [production](examples/production/) | Language-1.2 production eligibility (SPEC.md §17.13): six declared roots across two modules beside formal-only theorems and a proposition-valued definition; an effect-free fixed-width root eligible on `rust-core` and `rust-std`, overflow-admitting roots over a non-recursive inductive and a non-escaping closure, a well-founded root whose termination evidence is erased, and allocation-admitting list roots eligible on `rust-std` only, including a generic dependency instantiated at `Nat`; each root's closure, effects, and dispositions are published as its eligibility report, and verification extracts the roots through Lean's compiler front end into the canonical compiler input. | -| [production-coverage](examples/production-coverage/) | Language-1.2 semantic preservation coverage (SPEC.md §17.17): 33 production roots across four modules that together exercise every runtime row of the production registry (§17.13) — fixed-width arithmetic at every width, text, bytes, and decimal parsing and formatting, records, options, generic and nested inductive types, higher-order functions with captures, structural, mutual, and well-founded recursion, and every collection template and key order; verification extracts every root and checks its certificate A. | -| [models](examples/models/) | Language-1.2 models (SPEC.md §17.12) across nine modules: a stateful deterministic session with an invariant, a rule policy, a statistical triage and an integer feed-forward digit recognizer whose weights are content-addressed artifacts embedded with kernel-checked decodings, stateful ledgers in every contract shape whose evidence leaves runtime checks open, every composite form over stateless and stateful stages (stateful sequences with proved and checked junctions, stateful fan-out, product, and branch, and stages checked after they run), every claim kind discharged by statement-exact theorems and restated against the fixed model semantics, every runtime refusal decided by the kernel, and production roots that apply models through their required runtime checks, extracted through Lean. | -| [reasoning](examples/reasoning/) | Language-1.2 reasoning machines (SPEC.md §17.12) across five modules: a clinical forward expert system whose eight guarded rules derive a multi-step triage with its invariant and termination proved, a generic terminating countdown, a deduplicating breadth-first jug planner, a depth-first search and a generate-and-verify reasoner over a model's proposals, an answer proved correct under the logic's invariant with its check erased, forged traces and inapplicable steps refused at run time, the six-counter ledger of each run and every generated theorem kernel-checked, and production roots extracted through Lean and transcribed to calculus programs the compiler project checks against the reasoners themselves. | -| [fold-laws](examples/fold-laws/) | Language-1.2 program equalities over all inputs (SPEC.md §17.12, *Fold laws*) across three modules: a clamped requantization step monotone and bounded for every `Int`, truncating division by positive and negative literals, order and equality over `UInt8` and `Int8`, additive folds over lists, sets, and maps equal as sums (doubling, counting, weighting, append in either order, reverse, debits against credits, a map's keys and values), a single-pass statistics fold and a fused parity fold proved by the `law` form, and `decide` only on closed instances. | -| [helpdesk](examples/helpdesk/) | A text application written entirely from language-1.2 source and the source packages `std`, `std-models`, and `std-reasoning` (SPEC.md §17.22, `EX-09`): `dispatch : Bytes -> Bytes` trims the request with `Text`, scores it with an integer feed-forward model whose weights are content-addressed artifacts applied through its required precondition check, abstains with `decideOr` below a margin, commits through the generic `GateModel`, and plans the reply with the `Drain` reasoner; `classify` uses the model alone and `plan` the reasoner alone; the roots are exported with the packages committed under `tests/production-export/helpdesk/`. | -| [uor-atlas](examples/uor-atlas/) | The complete native Atlas declaration and proof graph, including the census/group chain, `S37`, `S38`, and the authoritative integer-uniqueness statement `S43`; no handwritten Atlas module is a generated dependency. | +## Why LexLean -## Building and running the gate +* **The paper cannot drift from the program.** Both are generated from one linked representation. Neither is copied, neither is hand-maintained, and a change to one is a change to the other. +* **Assumptions are audited, not assumed.** An attestation records the toolchain hashes, the process records, and the exact observed axiom set of every module. +* **The binary carries its guarantees.** Production compilation to Rust emits certificates that a consumer replays offline, without the source, without Lean, and without trusting the producer. -Prerequisites: Rust 1.97.1 (`rust-toolchain.toml` pins it), [just](https://github.com/casey/just), `cargo-deny`, and the pinned Lean toolchain `leanprover/lean4:v4.32.1` installed through `elan` (the dev container in [.devcontainer/](.devcontainer/) provides all of them). +## When to use LexLean -```text -just vv # the complete normative acceptance gate (SPEC.md §9.2) -just release # vv, then the §30 release criterion; refused until 1.0.0 -``` - -All 457 registered conformance IDs are implemented and pass; `just vv` runs clean from a checkout with the pinned toolchain installed. - -The differential against the independent generator `lean4-prod` (SPEC.md §17.19, `OR-01`..`OR-08`) acquires it at its pinned commit: from the checkout `LEXLEAN_ORACLE_DIR` names, or by fetching the commit with `git` into the Cargo target directory (`LEXLEAN_ORACLE_CACHE` overrides), and builds it with the pinned Lean and Rust toolchains. It is validation evidence only and no input to any identity. An oracle that cannot be acquired, is not the pinned files, or fails is unavailable: that fails the gate on Linux x86-64 and is printed as `NOT VALIDATED` elsewhere, and is never reported as agreement. - -`just vv` is the Linux x86-64 gate. On the other four supported hosts (§8.3) the crate builds and every test runs. A case whose assertions need something the host does not have runs its platform-independent assertions and prints which ones it skipped: the pinned toolchain, a `#!/bin/sh` program for the external-provider cases, a filesystem that distinguishes two names differing only in case, or one that accepts a name that is not valid UTF-8. Each is detected at run time rather than assumed from the target triple, and on Linux x86-64 the toolchain gate is mandatory, so nothing there passes vacuously. - -Releases live on release lines (SPEC.md §9.4): `release/vX.Y` is the branch of the release X.Y, cut from `main` when its work begins and the target of its pull requests; tags are made from it, it is merged forward into the next line after each landing, and `main` is the newest released line. A push to a release line runs the same gate as a push to `main`. +* **Safety-critical code that must be proved, not sampled.** Total programs with machine-checked termination, exact failure typing, and a certified Rust output. +* **Audited or regulated artifacts.** Every claim is a content-addressed record: what was checked, by which toolchain, under which assumptions. +* **Documents whose formal content must match their prose.** The canonical document is regenerated from the same representation that the kernel checks. +* **Verified models and reasoners.** Integer neural networks, rule-based reasoning machines, and text classifiers as closed semantic objects. The [MNIST model](https://github.com/UOR-Foundation/MNIST) is one: an int8 digit recognizer whose weights are content-addressed artifacts, whose forward pass is checked layer by layer, and whose contract for every input is a theorem. ## Capabilities -Every row is validated by `just vv`; the IDs link the claim to its register row, scenario, and conformance test. +Every capability below is a claim in [`model/ids.toml`](model/ids.toml), carried at honesty level `build`: constructed here and validated against its oracle by the test named `conformance_`. Every row is validated by `just vv`, and its IDs link the claim to its register row, scenario, and conformance test. | Capability | IDs | Level | | --- | --- | --- | @@ -199,35 +202,82 @@ Every row is validated by `just vv`; the IDs link the claim to its register row, Range rows abbreviate consecutive registered IDs; every individual ID in each range is registered in [`model/ids.toml`](model/ids.toml) at the stated level with its own scenario and test. +## Examples that verify under the pinned toolchain + +Every directory under [examples/](examples/) is discovered by the example gate (`EX-08`) and must format, lock, check, build, and verify with real Lean 4.32.1 (`cargo xtask verify-examples`). Its platform-independent build outputs and its normalized verification records are committed under `expected/` and compared byte for byte by the golden gate (§28.3) and the example gate (§29.5); that those bytes are also independent of where the build ran is the separate claim of `AR-13` and `EX-06`. + +| Example | What it exercises | +| --- | --- | +| [nat-add-zero](examples/nat-add-zero/) | The literal SPEC.md §29 document (`EX-01`..`EX-06`). | +| [peano-arithmetic](examples/peano-arithmetic/) | Five modules with explicit imports, a local path glossary of proof constants from `Init` (`Nat.add_comm`, `Nat.le_trans`, `Eq.symm`, universe-polymorphic `rfl`, ...), label words, document-denoted definitions of all three kinds (`count`, `double`, `even`, `positive`, `divides`), noun-of and binary-noun-of frames (`the successor of`, `the sum of ... and ...`), sections with inherited parameters and references to parameterized declarations, and every §16 proof form: `Assume`, `Apply`, `Close the goal with`/`by reflexivity`, witnesses, left/right, multi-rule `rewrite` at the goal, `constructor`, `cases` on naturals and on hypotheses (`And`, `Exists`), `induction`, and `calculate`; theorems under `\noaxioms`, `\allowaxioms{propext}`, and `\exactaxioms{Classical.choice;Quot.sound;propext}` whose observed axiom sets are audited exactly. | +| [propositional-logic](examples/propositional-logic/) | Reasoning over `Prop`-typed locals with a `proposition` type noun defined as the sort: commutativity and associativity of conjunction and disjunction, disjunction elimination, double negation, De Morgan, explosion, biconditionals, and classical double-negation elimination under an exact axiom policy, through cases on `And`/`Or`/`Iff` hypotheses, `constructor`, and `Apply`. | +| [list-induction](examples/list-induction/) | Universe-polymorphic `List` with an eliminator descriptor: type-valued section parameters, `List.nil`/`List.cons`, an infix `⧺` for `List.append`, structural induction over lists using earlier document lemmas as rewrite rules, and nested noun phrases (`the length of ... equals the sum of the length of ... and the length of ...`). | +| [semantic-1.1](examples/semantic-1.1/) | A source-Lean-free, multi-module language-1.1 project covering every closed type, declaration, term, instance, structural-recursion, match, Boolean/Nat validation, proof variant, portable integer width, byte/string form, primitive operation, and cross-module kernel reduction. | +| [language-1.2](examples/language-1.2/) | The language-1.2 contract (SPEC.md §17.12): a `lexlean/semantic-module/2` module whose definition and theorem statement use the 1.2-only typed `let` term, lowered to Lean `let` and verified with an empty observed axiom set. | +| [recursive-data](examples/recursive-data/) | Language-1.2 recursive data (SPEC.md §17.12) across two modules: a self-recursive parameterized `Tree`, a nested `Rose` through `List`, the mutual `Expr`/`Stmt` group, a parameterized result-like `Outcome`, products and pairs in a structure; structural recursion and induction with one hypothesis per recursive field, under exact axiom policies. | +| [higher-order](examples/higher-order/) | Language-1.2 first-class functions (SPEC.md §17.12): generic `mapList`, `foldList`, and `compose`; lambdas with explicit captures; definition references across modules; a visitor record of functions over an arithmetic AST agreeing with direct evaluation; a generic induction theorem applied at `Nat`; executable definitions passing only non-escaping closures. | +| [recursion](examples/recursion/) | Language-1.2 recursion (SPEC.md §17.12): mutual structural groups over a nested rose tree, the mutual `Expr`/`Stmt` syntax, and the naturals, each lowered with `termination_by structural`; three well-founded normalizations (`countdown`, `reduce`, a bounded `search`) whose per-call decrease obligations are proved by `linear_arithmetic` and bound as explicit evidence; closed values computed by kernel reduction under exact axiom policies. | +| [collections](examples/collections/) | Language-1.2 ordered collections (SPEC.md §17.12): a String-keyed compiler symbol table built by an executable fold, a call graph whose reachability and least-first topological order the kernel computes, a cyclic graph with no order, a reasoning-state fixed point (the ancestor closure of a parent relation) reached by bounded iteration, and reordered literals that are equal by construction. | +| [production](examples/production/) | Language-1.2 production eligibility (SPEC.md §17.13): six declared roots across two modules beside formal-only theorems and a proposition-valued definition; an effect-free fixed-width root eligible on `rust-core` and `rust-std`, overflow-admitting roots over a non-recursive inductive and a non-escaping closure, a well-founded root whose termination evidence is erased, and allocation-admitting list roots eligible on `rust-std` only, including a generic dependency instantiated at `Nat`; each root's closure, effects, and dispositions are published as its eligibility report, and verification extracts the roots through Lean's compiler front end into the canonical compiler input. | +| [production-coverage](examples/production-coverage/) | Language-1.2 semantic preservation coverage (SPEC.md §17.17): 33 production roots across four modules that together exercise every runtime row of the production registry (§17.13), covering fixed-width arithmetic at every width, text, bytes, and decimal parsing and formatting, records, options, generic and nested inductive types, higher-order functions with captures, structural, mutual, and well-founded recursion, and every collection template and key order; verification extracts every root and checks its certificate A. | +| [models](examples/models/) | Language-1.2 models (SPEC.md §17.12) across nine modules: a stateful deterministic session with an invariant, a rule policy, a statistical triage and an integer feed-forward digit recognizer whose weights are content-addressed artifacts embedded with kernel-checked decodings, stateful ledgers in every contract shape whose evidence leaves runtime checks open, every composite form over stateless and stateful stages (stateful sequences with proved and checked junctions, stateful fan-out, product, and branch, and stages checked after they run), every claim kind discharged by statement-exact theorems and restated against the fixed model semantics, every runtime refusal decided by the kernel, and production roots that apply models through their required runtime checks, extracted through Lean. | +| [reasoning](examples/reasoning/) | Language-1.2 reasoning machines (SPEC.md §17.12) across five modules: a clinical forward expert system whose eight guarded rules derive a multi-step triage with its invariant and termination proved, a generic terminating countdown, a deduplicating breadth-first jug planner, a depth-first search and a generate-and-verify reasoner over a model's proposals, an answer proved correct under the logic's invariant with its check erased, forged traces and inapplicable steps refused at run time, the six-counter ledger of each run and every generated theorem checked by the kernel, and production roots extracted through Lean and transcribed to calculus programs the compiler project checks against the reasoners themselves. | +| [fold-laws](examples/fold-laws/) | Language-1.2 program equalities over all inputs (SPEC.md §17.12, *Fold laws*) across three modules: a clamped requantization step monotone and bounded for every `Int`, truncating division by positive and negative literals, order and equality over `UInt8` and `Int8`, additive folds over lists, sets, and maps equal as sums (doubling, counting, weighting, append in either order, reverse, debits against credits, a map's keys and values), a single-pass statistics fold and a fused parity fold proved by the `law` form, and `decide` only on closed instances. | +| [helpdesk](examples/helpdesk/) | A text application written entirely from language-1.2 source and the source packages `std`, `std-models`, and `std-reasoning` (SPEC.md §17.22, `EX-09`): `dispatch : Bytes -> Bytes` trims the request with `Text`, scores it with an integer feed-forward model whose weights are content-addressed artifacts applied through its required precondition check, abstains with `decideOr` below a margin, commits through the generic `GateModel`, and plans the reply with the `Drain` reasoner; `classify` uses the model alone and `plan` the reasoner alone; the roots are exported with the packages committed under `tests/production-export/helpdesk/`. | +| [uor-atlas](examples/uor-atlas/) | The complete native Atlas declaration and proof graph, including the census/group chain, `S37`, `S38`, and the authoritative integer-uniqueness statement `S43`; no handwritten Atlas module is a generated dependency. | + +Three further projects are written in LexLean itself and pass the same gates as an example. [compiler/](compiler/) defines the production realization calculus (SPEC.md §17.14), its `Gnaf` module states GNAF requests over that calculus (§17.15), with the complete-system universe, machine contract, and objective order all fixed before any optimizer and a theorem checked by the kernel that the universe is complete, and its `Certification` module checks GNAF certificates (§17.18) under [compiler/certificates/](compiler/certificates/): a global optimum, an argmin, or a complete Pareto frontier is certified from evidence for every system of the universe rather than by enumerating it, with the soundness of the checker proved in [compiler/proofs/](compiler/proofs/); local normality, correctness, and representation-minimality are separate, weaker statuses, and an incomplete certificate names its first open obligation. The requests live under [compiler/gnaf/](compiler/gnaf/), [compiler/gnaf.manifest.json](compiler/gnaf.manifest.json) is the dependency manifest UOR-GNAF §20 requires, and the target fixtures' Rust packages (§17.16) live under [compiler/rust/](compiler/rust/). [stdlib/](stdlib/) is the standard library, and [bootstrap/](bootstrap/) holds the compiler's own components beside the Rust they replace, the stage-0 oracle. + +The larger [native Atlas source graph](examples/uor-atlas/src/Atlas.lex.tex) is rooted by `Atlas.lex.tex` and uses the generic closed-core form for lossless formal-library migration. Its module-local typed expression DAGs, declarations, definition bodies, proofs, inductive metadata, instances, and explicit axiom policies are linked semantic data. The same values generate readable canonical LaTeX and reconstruct kernel-checked Lean declarations. The one-time conversion and exact comparison are recorded in [MIGRATION.md](examples/uor-atlas/MIGRATION.md); the independently authored implementation is absent from the release tree. `VR-19` permanently requires one generated Lean module per native source module, public imports confined to `Init` and the generated graph, only the generic `Lean` backend-support import, and no second Atlas implementation. + +## Building and running the gate + +Prerequisites: Rust 1.97.1 (`rust-toolchain.toml` pins it), [just](https://github.com/casey/just), `cargo-deny`, and the pinned Lean toolchain `leanprover/lean4:v4.32.1` installed through `elan` (the dev container in [.devcontainer/](.devcontainer/) provides all of them). + +```text +just vv # the complete normative acceptance gate (SPEC.md §9.2) +just release # vv, then the §30 release criterion; refused until 1.0.0 +``` + +All 457 registered conformance IDs are implemented and pass; `just vv` runs clean from a checkout with the pinned toolchain installed. + +The differential against the independent generator `lean4-prod` (SPEC.md §17.19, `OR-01`..`OR-08`) acquires it at its pinned commit: from the checkout `LEXLEAN_ORACLE_DIR` names, or by fetching the commit with `git` into the Cargo target directory (`LEXLEAN_ORACLE_CACHE` overrides), and builds it with the pinned Lean and Rust toolchains. It is validation evidence only and no input to any identity. An oracle that cannot be acquired, is not the pinned files, or fails is unavailable: that fails the gate on Linux x86-64 and is printed as `NOT VALIDATED` elsewhere, and is never reported as agreement. + +`just vv` is the Linux x86-64 gate. On the other four supported hosts (§8.3) the crate builds and every test runs. A case whose assertions need something the host does not have runs its platform-independent assertions and prints which ones it skipped: the pinned toolchain, a `#!/bin/sh` program for the external-provider cases, a filesystem that distinguishes two names differing only in case, or one that accepts a name that is not valid UTF-8. Each is detected at run time rather than assumed from the target triple, and on Linux x86-64 the toolchain gate is mandatory, so nothing there passes vacuously. + +Releases live on release lines (SPEC.md §9.4): `release/vX.Y` is the branch of the release X.Y, cut from `main` when its work begins and the target of its pull requests; tags are made from it, it is merged forward into the next line after each landing, and `main` is the newest released line. A push to a release line runs the same gate as a push to `main`. + +Versions follow SPEC.md §30.1 and are recorded in [CHANGELOG.md](CHANGELOG.md). §2.3 fixes `0.1.0` as the initial implementation version and `1.0.0` as the first release satisfying the complete specification, so no tag before `1.0.0` claims the §30 release criterion: `cargo xtask release-check` reads that criterion and says exactly which parts of it do not hold. The release's evidence is the gate run of the tagged commit (SPEC.md §9.4, §30.3), so the publish job cannot refuse what the rehearsals accepted. + ## Evidence, not belief -- `check` and `build` never claim verification (`VR-18`); only `verify` runs Lean, and its attestation records toolchain hashes, process records, and observed axiom sets (`VR-01`..`VR-14`). -- Facts about external tools (Lean 4.32.1, Lake, leanchecker, `#print axioms` output shapes) are level `some-true` rows in [`model/ledger.toml`](model/ledger.toml): reproduced from cited authorities, not established here. -- The acceptance gate is `just vv` (SPEC.md §9.2); a release is refused until the complete §30 criterion holds (`RP-12`). +* `check` and `build` never claim verification (`VR-18`); only `verify` runs Lean, and its attestation records toolchain hashes, process records, and observed axiom sets (`VR-01`..`VR-14`). +* Facts about external tools (Lean 4.32.1, Lake, leanchecker, `#print axioms` output shapes) are level `some-true` rows in [`model/ledger.toml`](model/ledger.toml): reproduced from cited authorities, not established here. +* The acceptance gate is `just vv` (SPEC.md §9.2); a release is refused until the complete §30 criterion holds (`RP-12`). ## Documented deviations -- Generated Lean declares `public theorem` / `@[expose] public def` and `public import` where SPEC.md §18.1/§29.3 print bare `theorem` and `import`: under the Lean 4.32.1 module system a non-`public` declaration is module-private (the §18.9 axiom-audit module could not name it), and a non-`public` import may not contribute constants to a public declaration's signature, and a definition body is hidden from importing modules unless exposed (a theorem in another module could not unfold or eliminate a document definition). The committed oracles carry `public`. -- The §21.5 `modules/` artifact naming is realized as slash-separated directories (`modules/LexLeanExample/Main.lean`). -- Unique existence (§18.4 names `ExistsUnique`) lowers to its definitional expansion `Exists (fun (x : T) => And (P) ((y : T) → P[x:=y] → Eq y x))`: Lean 4.32.1's `Init` has no `ExistsUnique` constant. The linked IR keeps `ExistsUnique`; only the printed Lean bytes expand it, and a `Witness` step leaves the `And` goal for the remaining proof. -- The §18.8 probe module declares alpha-renamed universe variables with one `universe p0u ...` command before its `example` lines: Lean 4 has no `example.{u}` form. -- The pinned `leanchecker` has no version flag; its attestation `version_output` is the normalized answer to the fixed identity probe `lake env LexLeanIdentityProbe` (the preflighted executable by absolute path), checked against the pinned toolchain's exact response. -- §23.5's "two spaces per environment nesting level" is realized as two spaces per *section* depth: the §29.2 literal indents nothing inside `theorem` or `proof`, so declaration and proof environments do not add a level; only `\begin{section}` nesting does (`LX-14`, and every example's committed source is `fmt --check` clean). -- A numeral with a redundant leading zero (`007`) is rejected as noncanonical decimal source (`LLL1003`, with the canonical spelling as help) although §12's lexical class admits any digit run: canonical source has one spelling per value, and the formatter cannot choose between two. -- §18.4 says generated numerals carry an expected type, and the §29.3 literal prints `Nat.add llv0 0` bare. Generated Lean prints a numeral bare exactly where the applied signature binder is a monomorphic constant type and ascribes it (`(0 : Nat)`) everywhere else, so the literal and the rule agree. The ascription is what a document type definition is *defined as*, in whichever module of the project declares it (§17.7), never the definition's own name: Lean's `OfNat` instances live on the underlying type. -- §20.4's fallback for a Lean diagnostic that no generated mapping encloses ("the declaration component") is realized as the nearest preceding declaration-role mapping of the generated module: a location after the last declaration (the closing `end`) remaps to that last declaration, with the unmapped generated range kept as a note. -- Fixture directories are named `tests/fixtures//-/` and `tests/negative//` (`cl-04-check-no-artifacts`, `vr-11-exact-mismatch`) where §28.2 writes `tests/fixtures///`: one ID may own several fixtures, and the slug names which; the runner discovers fixtures by their `case.toml`, never by directory name, and every fixture runs from a temporary copy of its committed `project/`. -- A nested proof scope — a `constructor` branch, an `apply` premise, a `cases`/`induction` case — is set inside a `quote` environment. §19.5 fixes the phrases, not the layout, and a flat rendering makes two proofs that differ only in how their branches nest render to the same bytes; the indentation says where each scope closes, so the document presents the proof IR faithfully (§6 I8). -- Canonical LaTeX renders a quantified proposition as prose only in trailing position (the source formatter's §15.6 rule); a quantified operand that must be an island states its binder types (`\exists m \in \mathbb{N}, ...`), which the source math grammar has no spelling for. Document references no visible entry names render as `\texttt{Module::component}`, the escape form of qualified selectors, under their own coverage origin. -- Every identifier-shaped name canonical LaTeX emits --- a display spelling or math identifier (§12.2 admits `_` and `'`), a module segment (§15.1 admits `_`), an LRE operator name (§13.9 admits `_`), a glossary surface --- is emitted through the registered `\_` token wherever it carries `_`, which TeX would otherwise read as a subscript. The escape carries its own renderer-token coverage origin and the runs around it keep the name's, so §19.6 output coverage stays exact. -- §13.5 rule 5 admits a non-ASCII scalar in a canonical *source* form, but the canonical document emits glyphs only through the renderer-token registry (§19.1, §13.10), which the fixed §19.2 preamble can typeset. An entry whose LRE renders such a surface directly instead of naming a token is refused with `LLB6002` naming the entry, the form, and the scalar; every shipped core and standard entry with a Unicode surface already names one. -- §17.8 fixes generated local names as `llv` / `llh` in introduction order. A binder that the generated declaration never references keeps its index and carries a `_` prefix (`_llv1`, `_llh0`): pinned Lean's `unusedVariables` linter warns about an unreferenced binding, §20.2 makes any Lean warning a verification failure, and §18.1 fixes the file structure so no `set_option` may silence it — without the prefix an ordinary proposition with an unused quantified binder (`For every natural number \(n\) and natural number \(m\), \(n + 0 = n\)`) could never verify. The prefix marks the binding as deliberate; nothing else changes. +* Generated Lean declares `public theorem` / `@[expose] public def` and `public import` where SPEC.md §18.1/§29.3 print bare `theorem` and `import`: under the Lean 4.32.1 module system a non-`public` declaration is module-private (the §18.9 axiom-audit module could not name it), a non-`public` import may not contribute constants to a public declaration's signature, and a definition body is hidden from importing modules unless exposed (a theorem in another module could not unfold or eliminate a document definition). The committed oracles carry `public`. +* The §21.5 `modules/` artifact naming is realized as slash-separated directories (`modules/LexLeanExample/Main.lean`). +* Unique existence (§18.4 names `ExistsUnique`) lowers to its definitional expansion `Exists (fun (x : T) => And (P) ((y : T) → P[x:=y] → Eq y x))`: Lean 4.32.1's `Init` has no `ExistsUnique` constant. The linked IR keeps `ExistsUnique`; only the printed Lean bytes expand it, and a `Witness` step leaves the `And` goal for the remaining proof. +* The §18.8 probe module declares alpha-renamed universe variables with one `universe p0u ...` command before its `example` lines: Lean 4 has no `example.{u}` form. +* The pinned `leanchecker` has no version flag; its attestation `version_output` is the normalized answer to the fixed identity probe `lake env LexLeanIdentityProbe` (the preflighted executable by absolute path), checked against the pinned toolchain's exact response. +* §23.5's "two spaces per environment nesting level" is realized as two spaces per *section* depth: the §29.2 literal indents nothing inside `theorem` or `proof`, so declaration and proof environments do not add a level; only `\begin{section}` nesting does (`LX-14`, and every example's committed source is `fmt --check` clean). +* A numeral with a redundant leading zero (`007`) is rejected as noncanonical decimal source (`LLL1003`, with the canonical spelling as help) although §12's lexical class admits any digit run: canonical source has one spelling per value, and the formatter cannot choose between two. +* §18.4 says generated numerals carry an expected type, and the §29.3 literal prints `Nat.add llv0 0` bare. Generated Lean prints a numeral bare exactly where the applied signature binder is a monomorphic constant type and ascribes it (`(0 : Nat)`) everywhere else, so the literal and the rule agree. The ascription is what a document type definition is *defined as*, in whichever module of the project declares it (§17.7), never the definition's own name: Lean's `OfNat` instances live on the underlying type. +* §20.4's fallback for a Lean diagnostic that no generated mapping encloses ("the declaration component") is realized as the nearest preceding declaration-role mapping of the generated module: a location after the last declaration (the closing `end`) remaps to that last declaration, with the unmapped generated range kept as a note. +* Fixture directories are named `tests/fixtures//-/` and `tests/negative//` (`cl-04-check-no-artifacts`, `vr-11-exact-mismatch`) where §28.2 writes `tests/fixtures///`: one ID may own several fixtures, and the slug names which; the runner discovers fixtures by their `case.toml`, never by directory name, and every fixture runs from a temporary copy of its committed `project/`. +* A nested proof scope (a `constructor` branch, an `apply` premise, a `cases` or `induction` case) is set inside a `quote` environment. §19.5 fixes the phrases, not the layout, and a flat rendering makes two proofs that differ only in how their branches nest render to the same bytes; the indentation says where each scope closes, so the document presents the proof IR faithfully (§6 I8). +* Canonical LaTeX renders a quantified proposition as prose only in trailing position (the source formatter's §15.6 rule); a quantified operand that must be an island states its binder types (`\exists m \in \mathbb{N}, ...`), which the source math grammar has no spelling for. Document references no visible entry names render as `\texttt{Module::component}`, the escape form of qualified selectors, under their own coverage origin. +* Every identifier-shaped name canonical LaTeX emits (a display spelling or math identifier, a module segment, an LRE operator name, a glossary surface) is emitted through the registered `\_` token wherever it carries `_`, which TeX would otherwise read as a subscript. §12.2 admits `_` and `'`, §15.1 admits `_` in a module segment, and §13.9 admits `_` in an LRE operator name. The escape carries its own renderer-token coverage origin and the runs around it keep the name's, so §19.6 output coverage stays exact. +* §13.5 rule 5 admits a non-ASCII scalar in a canonical *source* form, but the canonical document emits glyphs only through the renderer-token registry (§19.1, §13.10), which the fixed §19.2 preamble can typeset. An entry whose LRE renders such a surface directly instead of naming a token is refused with `LLB6002` naming the entry, the form, and the scalar; every shipped core and standard entry with a Unicode surface already names one. +* §17.8 fixes generated local names as `llv` / `llh` in introduction order. A binder that the generated declaration never references keeps its index and carries a `_` prefix (`_llv1`, `_llh0`): pinned Lean's `unusedVariables` linter warns about an unreferenced binding, §20.2 makes any Lean warning a verification failure, and §18.1 fixes the file structure so no `set_option` may silence it. Without the prefix an ordinary proposition with an unused quantified binder (`For every natural number \(n\) and natural number \(m\), \(n + 0 = n\)`) could never verify. The prefix marks the binding as deliberate; nothing else changes. All are enforced by the same golden and conformance gates as everything else. ## Layout -Language data lives in [language/](language/), claim data in [model/](model/), schemas in [schemas/](schemas/), the compiler in [crates/lexlean/](crates/lexlean/), gates in [xtask/](xtask/) and [crates/conformance/](crates/conformance/), the examples in [examples/](examples/), and the negative fixtures in [tests/negative/](tests/negative/). The projects written in LexLean itself are [compiler/](compiler/) (the production calculus, GNAF, and certification), [stdlib/](stdlib/) (the standard library), and [bootstrap/](bootstrap/) (the compiler's own components, beside the Rust they replace, the stage-0 oracle); the pinned differential oracle is described in [oracle/](oracle/) as validation evidence only, and the schemas of the stable API and the tooling interface are under [api/](api/) and [tooling/](tooling/). CI is in [.github/](.github/). +Language data lives in [language/](language/), claim data in [model/](model/), schemas in [schemas/](schemas/), the compiler in [crates/lexlean/](crates/lexlean/), gates in [xtask/](xtask/) and [crates/conformance/](crates/conformance/), the examples in [examples/](examples/), and the negative fixtures in [tests/negative/](tests/negative/). The projects written in LexLean itself are [compiler/](compiler/) (the production calculus, GNAF, and certification), [stdlib/](stdlib/) (the standard library), and [bootstrap/](bootstrap/) (the compiler's own components, beside the Rust they replace, the stage-0 oracle). The pinned differential oracle is described in [oracle/](oracle/) as validation evidence only, the schemas of the stable API and the tooling interface are under [api/](api/) and [tooling/](tooling/), and the README's own logo is [assets/lexlean-logo.svg](assets/lexlean-logo.svg). CI is in [.github/](.github/). ## License diff --git a/SPEC.md b/SPEC.md index 4efccbfa47..a120758bd6 100644 --- a/SPEC.md +++ b/SPEC.md @@ -283,6 +283,8 @@ The completed repository MUST have this layout. Additional files are allowed onl │ ├── ci.yml │ ├── honesty.yml │ └── reproducibility.yml +├── assets/ +│ └── lexlean-logo.svg ├── AGENTS.md ├── CONFORMANCE.md ├── ERRORS.md diff --git a/assets/lexlean-logo.svg b/assets/lexlean-logo.svg new file mode 100644 index 0000000000..fb37c3fbd7 --- /dev/null +++ b/assets/lexlean-logo.svg @@ -0,0 +1,16 @@ + + LexLean + + + + + + + + + + LexLean + From 63880cf05db520b8f687136c4cc82a4e2e54105b Mon Sep 17 00:00:00 2001 From: humuhumu33 <68450279+humuhumu33@users.noreply.github.com> Date: Tue, 27 Oct 2026 12:49:55 +0000 Subject: [PATCH 02/10] docs: simplify the README and use an ASCII logo --- README.md | 237 +++++++++++++++--------------------------------------- 1 file changed, 67 insertions(+), 170 deletions(-) diff --git a/README.md b/README.md index e4dd959194..1adb68b2e6 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,24 @@
- - LexLean - - -
- -

One controlled-language document in. The canonical paper, a kernel-checked Lean 4 program, and a certified Rust package out.

- -

- Spec - · - Conformance - · - Diagnostics - · - Evidence - · - Changelog - · - MNIST model -

- -

- Latest release - Acceptance gate - Pinned Lean toolchain - Conformance register size - License -

- -

LexLean compiles .lex.tex modules written in a closed controlled language: every word, symbol, and control must be declared by a versioned lexicon package, every sentence parses under a fixed grammar, and one typed intermediate representation generates both the canonical LaTeX document and the prose-free Lean 4 program.

- -

lexlean verify compiles the generated Lean under the pinned leanprover/lean4:v4.32.1 toolchain, replays every module with leanchecker, audits axioms by parsing #print axioms exactly, and publishes a content-addressed attestation.

- -

Evidence, not belief. check and build never claim verification. Only verify runs Lean, and whatever it cannot check is reported as not validated, never passed in silence.

+
+ _               _
+| |             | |
+| |     _____  _| |     ___  __ _ _ __
+| |    / _ \ \/ / |    / _ \/ _` | '_ \
+| |___|  __/>  <| |___|  __/ (_| | | | |
+|______\___/_/\_\______\___|\__,_|_| |_|
+
+ +One controlled language document in. A canonical paper, a kernel checked Lean 4 program, and a certified Rust package out.
+LexLean compiles `.lex.tex` modules written in a closed controlled language. Every word, symbol, and control must be declared by a versioned lexicon package. Every sentence parses under a fixed grammar. One typed intermediate representation generates both the canonical LaTeX document and the prose free Lean 4 program. + +`lexlean verify` compiles the generated Lean under the pinned `leanprover/lean4:v4.32.1` toolchain. It replays every module with `leanchecker`, audits axioms by parsing `#print axioms` exactly, and publishes a content addressed attestation. + +**Evidence, not belief.** `check` and `build` never claim verification. Only `verify` runs Lean. Whatever it cannot check is reported as not validated, never passed in silence. + +The complete normative contract is [SPEC.md](SPEC.md). The generated register is [CONFORMANCE.md](CONFORMANCE.md). The closed diagnostic registry is [ERRORS.md](ERRORS.md). The falsifiability evidence is in [VERIFICATION.md](VERIFICATION.md). The changelog is [CHANGELOG.md](CHANGELOG.md). The MNIST model is at [UOR Foundation/MNIST](https://github.com/UOR-Foundation/MNIST). + ## Quickstart ### Run in the container @@ -47,7 +30,7 @@ docker pull ghcr.io/uor-foundation/lexlean:0.4.0 docker run --rm -v "$PWD:/work" ghcr.io/uor-foundation/lexlean:0.4.0 verify ``` -The image is around 4 GB, nearly all of it the pinned toolchain's compiled library: the part `verify` needs, and the part a smaller image would have to leave out. +The image is around 4 GB. Nearly all of it is the pinned toolchain's compiled library, the part `verify` needs. A smaller image would have to leave it out. ### Or install a binary @@ -64,8 +47,6 @@ A binary alone can `init`, `lock`, `fmt`, `check`, and `build`. `verify` additio cargo install --locked --path crates/lexlean ``` -The complete normative contract is [SPEC.md](SPEC.md) (`LEXLEAN-SPEC-1`). The generated register is [CONFORMANCE.md](CONFORMANCE.md), the closed diagnostic registry is [ERRORS.md](ERRORS.md), and the falsifiability evidence is in [VERIFICATION.md](VERIFICATION.md). - ### Write, build, verify ```text @@ -93,7 +74,7 @@ Close the goal by reflexivity. \end{lexlean} ``` -From that one source LexLean generates the prose-free Lean module +From that one source LexLean generates the prose free Lean module: ```lean module @@ -107,7 +88,7 @@ public theorem add_zero (llv0 : Nat) : Eq (Nat.add llv0 0) llv0 := by end LexLeanExample.Main ``` -and the canonical LaTeX document, regenerated from the linked representation rather than copied (the prose reads "The goal follows by reflexivity."), plus source maps, coverage, and a manifest, all byte-reproducible across directories. `verify` then compiles the module under the pinned toolchain, replays it with `leanchecker`, parses `#print axioms` exactly, and records the empty observed axiom set in a content-addressed attestation. +It also generates the canonical LaTeX document from the linked representation, plus source maps, coverage, and a manifest. All outputs are byte reproducible across directories. `verify` then compiles the module under the pinned toolchain, replays it with `leanchecker`, parses `#print axioms` exactly, and records the empty observed axiom set in a content addressed attestation. ## How LexLean works @@ -115,170 +96,86 @@ and the canonical LaTeX document, regenerated from the linked representation rat your document (.lex.tex, closed lexicon) | v -one typed semantic representation <- the single source of truth +one typed semantic representation (the single source of truth) + | + +====> canonical LaTeX (paper or PDF) | - +----+----------------+ - v v -canonical LaTeX prose-free Lean 4 -(paper or PDF) (kernel-checked, exact axiom audit) - | - v - production compilation - | - v - certified Rust package - + certificates A / B / E + attestation - (replays offline, without the source) + +====> prose free Lean 4 (kernel checked, exact axiom audit) + | + v + production compilation + | + v + certified Rust package + + certificates A / B / E + attestation + (replays offline, without the source) ``` -| Command | What it does | What it may claim | -| --- | --- | --- | -| `lexlean init` | Scaffolds a project | nothing | -| `lexlean lock` | Pins lexicons and dependencies in a canonical lock file | nothing | -| `lexlean check` | Lexical closure, grammar, typing, diagnostics | never verification | -| `lexlean build` | Generates Lean, LaTeX, source maps, manifests | never verification | -| `lexlean verify` | Compiles under the pinned toolchain, replays with `leanchecker`, audits axioms, attests | the only verified claim | -| `lexlean production build` | Exports certified Rust packages with their certificates | kernel-checked preservation | -| `lexlean migrate --to 1.2` | Upgrades a language-1.1 project, proved in a scratch copy first | writes nothing on refusal | +* `lexlean init` scaffolds a project. It claims nothing. +* `lexlean lock` pins lexicons and dependencies in a canonical lock file. It claims nothing. +* `lexlean check` checks lexical closure, grammar, typing, and diagnostics. It never claims verification. +* `lexlean build` generates Lean, LaTeX, source maps, and manifests. It never claims verification. +* `lexlean verify` compiles under the pinned toolchain, replays with `leanchecker`, audits axioms, and attests. It is the only verified claim. +* `lexlean production build` exports certified Rust packages with their certificates. It claims kernel checked preservation. +* `lexlean migrate --to 1.2` upgrades a language 1.1 project, proved in a scratch copy first. It writes nothing on refusal. -A language-1.2 project can also import the modules of a locked, content-addressed package of its workspace instead of copying them: `[[source_package]]` in `lexlean.toml` names a member directory listed by `lexlean-workspace.toml`, `lexlean.lock` pins the package by the digest of its manifest and source files, every command recomputes the pin, imports are closed to the project's own modules and the declared packages, and `verify` replays the package's modules under its module prefix with the package as their origin (SPEC.md §10.5, `PK-01`..`PK-05`; the workspace the cases use is [tests/packages/workspace](tests/packages/workspace/)). +A language 1.2 project can import the modules of a locked, content addressed package of its workspace instead of copying them. `[[source_package]]` in `lexlean.toml` names a member directory listed by `lexlean-workspace.toml`. `lexlean.lock` pins the package by the digest of its manifest and source files. Every command recomputes the pin. Imports are closed to the project's own modules and the declared packages. `verify` replays the package's modules under its module prefix with the package as their origin (SPEC.md §10.5, `PK-01`..`PK-05`). The workspace the cases use is [tests/packages/workspace](tests/packages/workspace/). -Language-1.1 semantic modules use the closed-core backend's fixed finite Lean budgets (`maxRecDepth = 100000`, `maxHeartbeats = 1000000000`) so complete nested byte-data declarations are not restricted by interactive defaults. Project child timeout and output limits and full kernel and axiom verification remain mandatory. These are generated backend settings, not caller-provided options. +Language 1.1 semantic modules use the closed core backend's fixed finite Lean budgets (`maxRecDepth = 100000`, `maxHeartbeats = 1000000000`) so complete nested byte data declarations are not restricted by interactive defaults. Project child timeout and output limits and full kernel and axiom verification remain mandatory. These are generated backend settings, not caller provided options. ## Why LexLean -* **The paper cannot drift from the program.** Both are generated from one linked representation. Neither is copied, neither is hand-maintained, and a change to one is a change to the other. -* **Assumptions are audited, not assumed.** An attestation records the toolchain hashes, the process records, and the exact observed axiom set of every module. -* **The binary carries its guarantees.** Production compilation to Rust emits certificates that a consumer replays offline, without the source, without Lean, and without trusting the producer. +The paper cannot drift from the program. Both are generated from one linked representation. Neither is copied, neither is hand maintained, and a change to one is a change to the other. Assumptions are audited, not assumed. An attestation records the toolchain hashes, the process records, and the exact observed axiom set of every module. The binary carries its guarantees. Production compilation to Rust emits certificates that a consumer replays offline, without the source, without Lean, and without trusting the producer. ## When to use LexLean -* **Safety-critical code that must be proved, not sampled.** Total programs with machine-checked termination, exact failure typing, and a certified Rust output. -* **Audited or regulated artifacts.** Every claim is a content-addressed record: what was checked, by which toolchain, under which assumptions. -* **Documents whose formal content must match their prose.** The canonical document is regenerated from the same representation that the kernel checks. -* **Verified models and reasoners.** Integer neural networks, rule-based reasoning machines, and text classifiers as closed semantic objects. The [MNIST model](https://github.com/UOR-Foundation/MNIST) is one: an int8 digit recognizer whose weights are content-addressed artifacts, whose forward pass is checked layer by layer, and whose contract for every input is a theorem. +Safety critical code that must be proved, not sampled. Total programs with machine checked termination, exact failure typing, and a certified Rust output. Audited or regulated artifacts. Every claim is a content addressed record: what was checked, by which toolchain, under which assumptions. Documents whose formal content must match their prose. The canonical document is regenerated from the same representation that the kernel checks. Verified models and reasoners. Integer neural networks, rule based reasoning machines, and text classifiers as closed semantic objects. The [MNIST model](https://github.com/UOR-Foundation/MNIST) is one: an int8 digit recognizer whose weights are content addressed artifacts, whose forward pass is checked layer by layer, and whose contract for every input is a theorem. ## Capabilities -Every capability below is a claim in [`model/ids.toml`](model/ids.toml), carried at honesty level `build`: constructed here and validated against its oracle by the test named `conformance_`. Every row is validated by `just vv`, and its IDs link the claim to its register row, scenario, and conformance test. - -| Capability | IDs | Level | -| --- | --- | --- | -| Exact repository identity, layout, generated documents, release gate, total classification of every closed enum by every consumer, and the devcontainer pinned to the toolchains | `RP-01`..`RP-18` | `build` | -| Closed project configuration, canonical lock file, and offline dependency policy | `CF-01`..`CF-18` | `build` | -| Total lexical closure: every accepted atom is covered by exactly one declared origin | `LX-01`..`LX-14` | `build` | -| Versioned lexicon packages with closed schemas, denotations, and renderer tokens | `GL-01`..`GL-18` | `build` | -| Fixed structural, mathematical, and proposition grammar with closed ambiguity handling | `GR-01`..`GR-16` | `build` | -| Typed closed IR with canonical serialization, native core modules (and the second schema of them that lossless migration of the proof library needs), portable language-1.1 application data and operations, versioned language-1.2 semantic modules, products, first-class functions, and widening conversions, ordered collections and graphs, semantic snapshots, alpha identities, recursion evidence, a split on a document term or a Boolean in a proof, and content identities | `SM-01`..`SM-36` | `build` | -| Document and generic semantic declarations with exact self-application, type checking, structural recursion, recursive and mutual language-1.2 data, generic and executable higher-order definitions, mutual and well-founded recursion with semantic evidence, explicit state threading, and acyclicity rules | `DF-01`..`DF-18` | `build` | -| The structured proof language with pinned Lean lowerings, including closed linear arithmetic, integer order, and the fold laws | `PF-01`..`PF-23` | `build` | -| Prose-free deterministic generated Lean with complete token traceability | `LN-01`..`LN-12` | `build` | -| Canonical LaTeX regeneration and the optional hash-checked PDF provider | `TX-01`..`TX-12` | `build` | -| Canonical diagnostics, source maps, coverage, manifests, and reproducible builds | `AR-01`..`AR-14` | `build` | -| Sixteen-stage verification with leanchecker replay and exact axiom audit | `VR-01`..`VR-23` | `build` | -| The exact CLI contract, the stable seven-method Rust `Engine` API, the host-driven end of the children the library started, the `production` subcommands, and the `migrate` command | `CL-01`..`CL-24` | `build` | -| Filesystem confinement, no shell, no hidden network, closed failure model | `SE-01`..`SE-12` | `build` | -| Language-1.2 production eligibility: closed targets, effects, and construct dispositions; runtime closures; target-dependent, fail-closed root analysis; deterministic eligibility reports; an exhaustiveness audit; measured stack bounds for every recursive root a harness runs | `PD-01`..`PD-08` | `build` | -| Named-root extraction through Lean's compiler front end: an adapter that is a closed tooling module over a registry derived from the pinned Lean and probed on every extraction, checked against a handwritten oracle; a closed, canonical, root-independent compiler input; fail-closed rejection; and an exact closure cross-check against production eligibility | `NE-01`..`NE-06` | `build` | -| The production realization calculus: a closed target syntax with canonical identity, a kernel-checked denotation, a realization library agreeing with LexLean's own collection primitives, complete realization coverage of the production registry, and a differentially tested Rust profile | `TC-01`..`TC-07` | `build` | -| The canonical Rust backend: a closed, checked Rust AST whose every construct corresponds to the calculus; hygienic identifiers, single ownership with last-use and component moves, exact failure typing, and no hidden allocation; contiguous lists with constant-work cells; a closed runtime library boundary of stated machine primitives; deterministic packages with checked exports, a lint gate and crate attributes read from one embedded language module, and provenance that states the realization's effects | `RB-01`..`RB-21` | `build` | -| GNAF requests over the calculus: an optimizer-independent complete-system universe, a machine contract that accounts every action, scalar and Pareto orders without weighting, fail-closed validation, and kernel-checked answers and authority vectors | `GN-01`..`GN-08` | `build` | -| GNAF certification: certificates that prove a global optimum, an argmin, or a complete Pareto frontier over the request's declared universe (a grammar of systems, never all calculus or Rust programs) from a premise for every system, a library proving the checker sound, closed transformation schemas, local normality kept distinct from optimality, a bridge from a representation metric to execution cost, and honest non-global statuses | `GC-01`..`GC-11` | `build` | -| Semantic preservation from the source to the calculus: a validated lowering of every production root, a kernel-checked certificate per root relating the lowered program to the source denotation with exact width predicates, a differential evaluator, a proof library that is LexLean source (native core modules migrated once from the Lean it replaces, its Lean generated by the compiler) pinned by exact axioms, certificate checking in verification, a declared Rust machine on which every rendering is evaluated, certificate B relating every rendering to its program, certificate E composing them end to end on the declared Rust machine (the printer, export wrappers, and `rustc` are outside it and are measured by the rustc differential), boundary validators, a rustc differential of the declared machine, and certificates A and B as kernel-term data built by the production compiler, which carries no Lean text template | `SP-01`..`SP-29` | `build` | -| Language-1.2 models: content-addressed typed artifacts, contracts with sound validators, exact deterministic, rule, statistical, neural (integer kernels), and composite realizations, generated evidence obligations restated in Lean, checked runtime boundaries, and their identity, production, and verification | `MD-01`..`MD-13` | `build` | -| The differential validation oracle: `lean4-prod` pinned by commit and content hash as validation evidence only, a corpus of every production root and one probe per runtime construct, a comparison of acceptance, contract, behavior, and resources that never compares bytes, versioned tables of known differences and of constructs outside the overlap, planted discrepancies detected, failures that are unavailable rather than validated, and its isolation from every identity | `OR-01`..`OR-08` | `build` | -| The production export contract: a stable, versioned `lexlean::api::production` façade and its CLI through which a consumer compiles production roots to certified Rust packages; closed requests refused before Lean on every root, target, pin, evidence, path, and package defect; results binding every output to the source, semantic, compiler-semantics, target, compiler-input, preservation, and certificate identities with unforgeable certification; deterministic, confined, offline bundles; source-free replay; versioned schemas; each output's effects and what `recursion` asks of the host | `PX-01`..`PX-13` | `build` | -| Language-1.2 reasoning machines: logics, guarded inference rules, verifiers, and forward, search, and generate-and-verify reasoners elaborated to ordinary declarations, with exact obligations, fixed-template theorems over the axiom-free reasoning runtime, a closed runtime boundary, resource ledgers, and their production and calculus realization, with GNAF requests over the clinical rule base's forward-chaining plans | `RS-01`..`RS-14` | `build` | -| Language-1.2 compiler-tooling modules: a closed, typed program over a registry of the external Lean interface (types with exact constructors and index requirements, calls with exact signatures), with flat index-exhaustive matching, licensed partial and mutual recursion, complete recursive traversal, command registration, invocation and evaluation as semantic data, both backends from one linked value, and no member that holds Lean text | `TL-01`..`TL-11` | `build` | -| The language-1.2 authoring notation: a readable `.lex.tex` text for a semantic module, in bijection with its canonical JSON, whose every position and variant is read from the schema, with readable forms for types and terms and a generic form for every other value, formatted canonically by `fmt` failing closed, the only form in which a language-1.2 source of the product is written (the data form is refused under language 1.2, and `lexlean::sdk` is the explicit conversion), the same for the compiler-tooling modules in the generic notation, with no compiler-semantics ID that depends on which form an embedded module is written in, with no product source owned by a generator but five named records, read and written by programs only through the authoring API (`lexlean::sdk`), and, for a native core module, a readable program over the shared table of kernel terms whose numbering is the order of its text | `AU-01`..`AU-13` | `build` | -| The runtime of generated Lean as native modules: the portable, collection, model, and reasoning runtimes of language 1.2 are LexLean source that every generated module imports, migrated losslessly and audited against their exact axioms, the released runtime text of languages 1.0 and 1.1 is frozen data equal to their released output, and no other Lean runtime text remains in the compiler but the decoder of core module 2 | `RT-01`..`RT-04` | `build` | -| The standard library: language-1.2 source beside the compiler whose members are certified production roots, each validated against its oracle by a seeded differential of its evaluator and rustc realizations; bytes and text over `Bytes`, an output buffer of a given capacity written in order; SHA-256 against FIPS 180-4, the NIST CAVP vectors, and the `sha2` crate; and the `std-models` and `std-reasoning` source packages, generic over types, whose laws are kernel-checked theorems and whose application is the `helpdesk` example | `SL-01`..`SL-05` | `build` | -| The bootstrap project: the compiler's own components as language-1.2 source compiled by LexLean's production pipeline to certified Rust packages, the exact axiom-output parser and its closed Lean-name check, the primitive scanner of §12.2, the preservation lexer and token audit, the target calculus's checker, the Rust crate validator, and the Rust printer, each held to the Rust it replaces (the stage-0 oracle) by the committed vectors and a seeded differential of its evaluator and rustc realizations, with planted defects detected and the production export committed | `BS-01`..`BS-09` | `build` | -| Source packages: a language-1.2 project imports the modules of a locked, content-addressed package of its workspace: `[[source_package]]` and `lexlean-workspace.toml`, the pins in `lexlean.lock` recomputed by every command, imports closed at link, no re-export of a package's production roots, and the package's modules replayed by the importer's `verify` with their origin in the records | `PK-01`..`PK-05` | `build` | -| The literal `nat-add-zero` example, the Lean-verified feature examples, and the complete negative fixture suite | `EX-01`..`EX-09` | `build` | -| Language-1.2 text components, first slice: tokenizers and their round-trip laws, with the laws carried as one native core module the generated modules import rather than authored Lean text | `LM-01`, `LM-02`, `LM-03`, `LM-13` | `build` | -| Language-1.2 text components, second slice: context windows with their bound, exactness, and suffix laws, and greedy and seeded text generators bounded by `max_tokens` whose scorer sees only contexts that fit, over the same native laws module | `LM-04`, `LM-05`, `LM-06` | `build` | -| Language-1.2 text components, third slice: text classifiers over token-count features with their width, total, and fit laws, composition of a window model under `scan` and adapters over `string` through the model constructs alone with no new declaration kind, and the audit that no prompt is code | `LM-07`, `LM-08`, `LM-09` | `build` | - -Range rows abbreviate consecutive registered IDs; every individual ID in each range is registered in [`model/ids.toml`](model/ids.toml) at the stated level with its own scenario and test. - -## Examples that verify under the pinned toolchain - -Every directory under [examples/](examples/) is discovered by the example gate (`EX-08`) and must format, lock, check, build, and verify with real Lean 4.32.1 (`cargo xtask verify-examples`). Its platform-independent build outputs and its normalized verification records are committed under `expected/` and compared byte for byte by the golden gate (§28.3) and the example gate (§29.5); that those bytes are also independent of where the build ran is the separate claim of `AR-13` and `EX-06`. - -| Example | What it exercises | -| --- | --- | -| [nat-add-zero](examples/nat-add-zero/) | The literal SPEC.md §29 document (`EX-01`..`EX-06`). | -| [peano-arithmetic](examples/peano-arithmetic/) | Five modules with explicit imports, a local path glossary of proof constants from `Init` (`Nat.add_comm`, `Nat.le_trans`, `Eq.symm`, universe-polymorphic `rfl`, ...), label words, document-denoted definitions of all three kinds (`count`, `double`, `even`, `positive`, `divides`), noun-of and binary-noun-of frames (`the successor of`, `the sum of ... and ...`), sections with inherited parameters and references to parameterized declarations, and every §16 proof form: `Assume`, `Apply`, `Close the goal with`/`by reflexivity`, witnesses, left/right, multi-rule `rewrite` at the goal, `constructor`, `cases` on naturals and on hypotheses (`And`, `Exists`), `induction`, and `calculate`; theorems under `\noaxioms`, `\allowaxioms{propext}`, and `\exactaxioms{Classical.choice;Quot.sound;propext}` whose observed axiom sets are audited exactly. | -| [propositional-logic](examples/propositional-logic/) | Reasoning over `Prop`-typed locals with a `proposition` type noun defined as the sort: commutativity and associativity of conjunction and disjunction, disjunction elimination, double negation, De Morgan, explosion, biconditionals, and classical double-negation elimination under an exact axiom policy, through cases on `And`/`Or`/`Iff` hypotheses, `constructor`, and `Apply`. | -| [list-induction](examples/list-induction/) | Universe-polymorphic `List` with an eliminator descriptor: type-valued section parameters, `List.nil`/`List.cons`, an infix `⧺` for `List.append`, structural induction over lists using earlier document lemmas as rewrite rules, and nested noun phrases (`the length of ... equals the sum of the length of ... and the length of ...`). | -| [semantic-1.1](examples/semantic-1.1/) | A source-Lean-free, multi-module language-1.1 project covering every closed type, declaration, term, instance, structural-recursion, match, Boolean/Nat validation, proof variant, portable integer width, byte/string form, primitive operation, and cross-module kernel reduction. | -| [language-1.2](examples/language-1.2/) | The language-1.2 contract (SPEC.md §17.12): a `lexlean/semantic-module/2` module whose definition and theorem statement use the 1.2-only typed `let` term, lowered to Lean `let` and verified with an empty observed axiom set. | -| [recursive-data](examples/recursive-data/) | Language-1.2 recursive data (SPEC.md §17.12) across two modules: a self-recursive parameterized `Tree`, a nested `Rose` through `List`, the mutual `Expr`/`Stmt` group, a parameterized result-like `Outcome`, products and pairs in a structure; structural recursion and induction with one hypothesis per recursive field, under exact axiom policies. | -| [higher-order](examples/higher-order/) | Language-1.2 first-class functions (SPEC.md §17.12): generic `mapList`, `foldList`, and `compose`; lambdas with explicit captures; definition references across modules; a visitor record of functions over an arithmetic AST agreeing with direct evaluation; a generic induction theorem applied at `Nat`; executable definitions passing only non-escaping closures. | -| [recursion](examples/recursion/) | Language-1.2 recursion (SPEC.md §17.12): mutual structural groups over a nested rose tree, the mutual `Expr`/`Stmt` syntax, and the naturals, each lowered with `termination_by structural`; three well-founded normalizations (`countdown`, `reduce`, a bounded `search`) whose per-call decrease obligations are proved by `linear_arithmetic` and bound as explicit evidence; closed values computed by kernel reduction under exact axiom policies. | -| [collections](examples/collections/) | Language-1.2 ordered collections (SPEC.md §17.12): a String-keyed compiler symbol table built by an executable fold, a call graph whose reachability and least-first topological order the kernel computes, a cyclic graph with no order, a reasoning-state fixed point (the ancestor closure of a parent relation) reached by bounded iteration, and reordered literals that are equal by construction. | -| [production](examples/production/) | Language-1.2 production eligibility (SPEC.md §17.13): six declared roots across two modules beside formal-only theorems and a proposition-valued definition; an effect-free fixed-width root eligible on `rust-core` and `rust-std`, overflow-admitting roots over a non-recursive inductive and a non-escaping closure, a well-founded root whose termination evidence is erased, and allocation-admitting list roots eligible on `rust-std` only, including a generic dependency instantiated at `Nat`; each root's closure, effects, and dispositions are published as its eligibility report, and verification extracts the roots through Lean's compiler front end into the canonical compiler input. | -| [production-coverage](examples/production-coverage/) | Language-1.2 semantic preservation coverage (SPEC.md §17.17): 33 production roots across four modules that together exercise every runtime row of the production registry (§17.13), covering fixed-width arithmetic at every width, text, bytes, and decimal parsing and formatting, records, options, generic and nested inductive types, higher-order functions with captures, structural, mutual, and well-founded recursion, and every collection template and key order; verification extracts every root and checks its certificate A. | -| [models](examples/models/) | Language-1.2 models (SPEC.md §17.12) across nine modules: a stateful deterministic session with an invariant, a rule policy, a statistical triage and an integer feed-forward digit recognizer whose weights are content-addressed artifacts embedded with kernel-checked decodings, stateful ledgers in every contract shape whose evidence leaves runtime checks open, every composite form over stateless and stateful stages (stateful sequences with proved and checked junctions, stateful fan-out, product, and branch, and stages checked after they run), every claim kind discharged by statement-exact theorems and restated against the fixed model semantics, every runtime refusal decided by the kernel, and production roots that apply models through their required runtime checks, extracted through Lean. | -| [reasoning](examples/reasoning/) | Language-1.2 reasoning machines (SPEC.md §17.12) across five modules: a clinical forward expert system whose eight guarded rules derive a multi-step triage with its invariant and termination proved, a generic terminating countdown, a deduplicating breadth-first jug planner, a depth-first search and a generate-and-verify reasoner over a model's proposals, an answer proved correct under the logic's invariant with its check erased, forged traces and inapplicable steps refused at run time, the six-counter ledger of each run and every generated theorem checked by the kernel, and production roots extracted through Lean and transcribed to calculus programs the compiler project checks against the reasoners themselves. | -| [fold-laws](examples/fold-laws/) | Language-1.2 program equalities over all inputs (SPEC.md §17.12, *Fold laws*) across three modules: a clamped requantization step monotone and bounded for every `Int`, truncating division by positive and negative literals, order and equality over `UInt8` and `Int8`, additive folds over lists, sets, and maps equal as sums (doubling, counting, weighting, append in either order, reverse, debits against credits, a map's keys and values), a single-pass statistics fold and a fused parity fold proved by the `law` form, and `decide` only on closed instances. | -| [helpdesk](examples/helpdesk/) | A text application written entirely from language-1.2 source and the source packages `std`, `std-models`, and `std-reasoning` (SPEC.md §17.22, `EX-09`): `dispatch : Bytes -> Bytes` trims the request with `Text`, scores it with an integer feed-forward model whose weights are content-addressed artifacts applied through its required precondition check, abstains with `decideOr` below a margin, commits through the generic `GateModel`, and plans the reply with the `Drain` reasoner; `classify` uses the model alone and `plan` the reasoner alone; the roots are exported with the packages committed under `tests/production-export/helpdesk/`. | -| [uor-atlas](examples/uor-atlas/) | The complete native Atlas declaration and proof graph, including the census/group chain, `S37`, `S38`, and the authoritative integer-uniqueness statement `S43`; no handwritten Atlas module is a generated dependency. | - -Three further projects are written in LexLean itself and pass the same gates as an example. [compiler/](compiler/) defines the production realization calculus (SPEC.md §17.14), its `Gnaf` module states GNAF requests over that calculus (§17.15), with the complete-system universe, machine contract, and objective order all fixed before any optimizer and a theorem checked by the kernel that the universe is complete, and its `Certification` module checks GNAF certificates (§17.18) under [compiler/certificates/](compiler/certificates/): a global optimum, an argmin, or a complete Pareto frontier is certified from evidence for every system of the universe rather than by enumerating it, with the soundness of the checker proved in [compiler/proofs/](compiler/proofs/); local normality, correctness, and representation-minimality are separate, weaker statuses, and an incomplete certificate names its first open obligation. The requests live under [compiler/gnaf/](compiler/gnaf/), [compiler/gnaf.manifest.json](compiler/gnaf.manifest.json) is the dependency manifest UOR-GNAF §20 requires, and the target fixtures' Rust packages (§17.16) live under [compiler/rust/](compiler/rust/). [stdlib/](stdlib/) is the standard library, and [bootstrap/](bootstrap/) holds the compiler's own components beside the Rust they replace, the stage-0 oracle. - -The larger [native Atlas source graph](examples/uor-atlas/src/Atlas.lex.tex) is rooted by `Atlas.lex.tex` and uses the generic closed-core form for lossless formal-library migration. Its module-local typed expression DAGs, declarations, definition bodies, proofs, inductive metadata, instances, and explicit axiom policies are linked semantic data. The same values generate readable canonical LaTeX and reconstruct kernel-checked Lean declarations. The one-time conversion and exact comparison are recorded in [MIGRATION.md](examples/uor-atlas/MIGRATION.md); the independently authored implementation is absent from the release tree. `VR-19` permanently requires one generated Lean module per native source module, public imports confined to `Init` and the generated graph, only the generic `Lean` backend-support import, and no second Atlas implementation. +Every capability is a claim in [`model/ids.toml`](model/ids.toml) at honesty level `build`. It is constructed here and validated against its oracle by the test named `conformance_`. Every row is validated by `just vv`, and its IDs link the claim to its register row, scenario, and conformance test. + +The 457 registered conformance IDs cover repository identity, configuration, lexical closure, lexicons, grammar, typed IR, declarations, proofs, Lean generation, LaTeX regeneration, diagnostics, verification, CLI, security, production eligibility, named root extraction, realization calculus, Rust backend, GNAF, certification, semantic preservation, models, differential oracle, production export, reasoning machines, compiler tooling, authoring notation, runtime, standard library, bootstrap, source packages, examples, and text components. See [CONFORMANCE.md](CONFORMANCE.md) for the full register and [model/ids.toml](model/ids.toml) for every individual ID with its scenario and test. + +## Examples that verify + +Every directory under [examples/](examples/) is discovered by the example gate (`EX-08`). Each must format, lock, check, build, and verify with real Lean 4.32.1 (`cargo xtask verify-examples`). Platform independent build outputs and normalized verification records are committed under `expected/` and compared byte for byte by the golden gate (§28.3) and the example gate (§29.5). That those bytes are also independent of where the build ran is the separate claim of `AR-13` and `EX-06`. + +The `nat-add-zero` example is the literal SPEC.md §29 document. Other examples cover Peano arithmetic, propositional logic, list induction, semantic 1.1, language 1.2, recursive data, higher order functions, recursion, collections, production, production coverage, models, reasoning, fold laws, helpdesk, and uor atlas. Three further projects are written in LexLean itself and pass the same gates: [compiler/](compiler/) defines the production realization calculus and GNAF certification; [stdlib/](stdlib/) is the standard library; [bootstrap/](bootstrap/) holds the compiler's own components beside the Rust they replace. ## Building and running the gate -Prerequisites: Rust 1.97.1 (`rust-toolchain.toml` pins it), [just](https://github.com/casey/just), `cargo-deny`, and the pinned Lean toolchain `leanprover/lean4:v4.32.1` installed through `elan` (the dev container in [.devcontainer/](.devcontainer/) provides all of them). +Prerequisites: Rust 1.97.1 (`rust-toolchain.toml` pins it), [just](https://github.com/casey/just), `cargo-deny`, and the pinned Lean toolchain `leanprover/lean4:v4.32.1` installed through `elan`. The dev container provides all of them. ```text just vv # the complete normative acceptance gate (SPEC.md §9.2) just release # vv, then the §30 release criterion; refused until 1.0.0 ``` -All 457 registered conformance IDs are implemented and pass; `just vv` runs clean from a checkout with the pinned toolchain installed. - -The differential against the independent generator `lean4-prod` (SPEC.md §17.19, `OR-01`..`OR-08`) acquires it at its pinned commit: from the checkout `LEXLEAN_ORACLE_DIR` names, or by fetching the commit with `git` into the Cargo target directory (`LEXLEAN_ORACLE_CACHE` overrides), and builds it with the pinned Lean and Rust toolchains. It is validation evidence only and no input to any identity. An oracle that cannot be acquired, is not the pinned files, or fails is unavailable: that fails the gate on Linux x86-64 and is printed as `NOT VALIDATED` elsewhere, and is never reported as agreement. - -`just vv` is the Linux x86-64 gate. On the other four supported hosts (§8.3) the crate builds and every test runs. A case whose assertions need something the host does not have runs its platform-independent assertions and prints which ones it skipped: the pinned toolchain, a `#!/bin/sh` program for the external-provider cases, a filesystem that distinguishes two names differing only in case, or one that accepts a name that is not valid UTF-8. Each is detected at run time rather than assumed from the target triple, and on Linux x86-64 the toolchain gate is mandatory, so nothing there passes vacuously. +All 457 registered conformance IDs are implemented and pass. `just vv` runs clean from a checkout with the pinned toolchain installed. -Releases live on release lines (SPEC.md §9.4): `release/vX.Y` is the branch of the release X.Y, cut from `main` when its work begins and the target of its pull requests; tags are made from it, it is merged forward into the next line after each landing, and `main` is the newest released line. A push to a release line runs the same gate as a push to `main`. +The differential against the independent generator `lean4-prod` (SPEC.md §17.19, `OR-01`..`OR-08`) is validation evidence only and no input to any identity. An unavailable oracle fails the gate on Linux x86 64 and prints `NOT VALIDATED` elsewhere. It is never reported as agreement. `just vv` is the Linux x86 64 gate. On the other four supported hosts (§8.3) the crate builds and every test runs. Platform dependent assertions are skipped and printed, detected at run time. On Linux x86 64 the toolchain gate is mandatory. -Versions follow SPEC.md §30.1 and are recorded in [CHANGELOG.md](CHANGELOG.md). §2.3 fixes `0.1.0` as the initial implementation version and `1.0.0` as the first release satisfying the complete specification, so no tag before `1.0.0` claims the §30 release criterion: `cargo xtask release-check` reads that criterion and says exactly which parts of it do not hold. The release's evidence is the gate run of the tagged commit (SPEC.md §9.4, §30.3), so the publish job cannot refuse what the rehearsals accepted. +Releases live on release lines (SPEC.md §9.4). `release/vX.Y` is cut from `main`, targets its pull requests, and is merged forward into the next line. `main` is the newest released line. A push to a release line runs the same gate as a push to `main`. Versions follow SPEC.md §30.1 and are recorded in [CHANGELOG.md](CHANGELOG.md). §2.3 fixes `0.1.0` as the initial version and `1.0.0` as the first release satisfying the complete specification. No tag before `1.0.0` claims the §30 criterion. `cargo xtask release-check` reads that criterion and says what does not hold. The release evidence is the gate run of the tagged commit. ## Evidence, not belief -* `check` and `build` never claim verification (`VR-18`); only `verify` runs Lean, and its attestation records toolchain hashes, process records, and observed axiom sets (`VR-01`..`VR-14`). -* Facts about external tools (Lean 4.32.1, Lake, leanchecker, `#print axioms` output shapes) are level `some-true` rows in [`model/ledger.toml`](model/ledger.toml): reproduced from cited authorities, not established here. -* The acceptance gate is `just vv` (SPEC.md §9.2); a release is refused until the complete §30 criterion holds (`RP-12`). +`check` and `build` never claim verification (`VR-18`). Only `verify` runs Lean. Its attestation records toolchain hashes, process records, and observed axiom sets (`VR-01`..`VR-14`). Facts about external tools (Lean 4.32.1, Lake, leanchecker, `#print axioms` output shapes) are level `some-true` rows in [`model/ledger.toml`](model/ledger.toml), reproduced from cited authorities and not established here. The acceptance gate is `just vv` (SPEC.md §9.2). A release is refused until the complete §30 criterion holds (`RP-12`). ## Documented deviations -* Generated Lean declares `public theorem` / `@[expose] public def` and `public import` where SPEC.md §18.1/§29.3 print bare `theorem` and `import`: under the Lean 4.32.1 module system a non-`public` declaration is module-private (the §18.9 axiom-audit module could not name it), a non-`public` import may not contribute constants to a public declaration's signature, and a definition body is hidden from importing modules unless exposed (a theorem in another module could not unfold or eliminate a document definition). The committed oracles carry `public`. -* The §21.5 `modules/` artifact naming is realized as slash-separated directories (`modules/LexLeanExample/Main.lean`). -* Unique existence (§18.4 names `ExistsUnique`) lowers to its definitional expansion `Exists (fun (x : T) => And (P) ((y : T) → P[x:=y] → Eq y x))`: Lean 4.32.1's `Init` has no `ExistsUnique` constant. The linked IR keeps `ExistsUnique`; only the printed Lean bytes expand it, and a `Witness` step leaves the `And` goal for the remaining proof. -* The §18.8 probe module declares alpha-renamed universe variables with one `universe p0u ...` command before its `example` lines: Lean 4 has no `example.{u}` form. -* The pinned `leanchecker` has no version flag; its attestation `version_output` is the normalized answer to the fixed identity probe `lake env LexLeanIdentityProbe` (the preflighted executable by absolute path), checked against the pinned toolchain's exact response. -* §23.5's "two spaces per environment nesting level" is realized as two spaces per *section* depth: the §29.2 literal indents nothing inside `theorem` or `proof`, so declaration and proof environments do not add a level; only `\begin{section}` nesting does (`LX-14`, and every example's committed source is `fmt --check` clean). -* A numeral with a redundant leading zero (`007`) is rejected as noncanonical decimal source (`LLL1003`, with the canonical spelling as help) although §12's lexical class admits any digit run: canonical source has one spelling per value, and the formatter cannot choose between two. -* §18.4 says generated numerals carry an expected type, and the §29.3 literal prints `Nat.add llv0 0` bare. Generated Lean prints a numeral bare exactly where the applied signature binder is a monomorphic constant type and ascribes it (`(0 : Nat)`) everywhere else, so the literal and the rule agree. The ascription is what a document type definition is *defined as*, in whichever module of the project declares it (§17.7), never the definition's own name: Lean's `OfNat` instances live on the underlying type. -* §20.4's fallback for a Lean diagnostic that no generated mapping encloses ("the declaration component") is realized as the nearest preceding declaration-role mapping of the generated module: a location after the last declaration (the closing `end`) remaps to that last declaration, with the unmapped generated range kept as a note. -* Fixture directories are named `tests/fixtures//-/` and `tests/negative//` (`cl-04-check-no-artifacts`, `vr-11-exact-mismatch`) where §28.2 writes `tests/fixtures///`: one ID may own several fixtures, and the slug names which; the runner discovers fixtures by their `case.toml`, never by directory name, and every fixture runs from a temporary copy of its committed `project/`. -* A nested proof scope (a `constructor` branch, an `apply` premise, a `cases` or `induction` case) is set inside a `quote` environment. §19.5 fixes the phrases, not the layout, and a flat rendering makes two proofs that differ only in how their branches nest render to the same bytes; the indentation says where each scope closes, so the document presents the proof IR faithfully (§6 I8). -* Canonical LaTeX renders a quantified proposition as prose only in trailing position (the source formatter's §15.6 rule); a quantified operand that must be an island states its binder types (`\exists m \in \mathbb{N}, ...`), which the source math grammar has no spelling for. Document references no visible entry names render as `\texttt{Module::component}`, the escape form of qualified selectors, under their own coverage origin. -* Every identifier-shaped name canonical LaTeX emits (a display spelling or math identifier, a module segment, an LRE operator name, a glossary surface) is emitted through the registered `\_` token wherever it carries `_`, which TeX would otherwise read as a subscript. §12.2 admits `_` and `'`, §15.1 admits `_` in a module segment, and §13.9 admits `_` in an LRE operator name. The escape carries its own renderer-token coverage origin and the runs around it keep the name's, so §19.6 output coverage stays exact. -* §13.5 rule 5 admits a non-ASCII scalar in a canonical *source* form, but the canonical document emits glyphs only through the renderer-token registry (§19.1, §13.10), which the fixed §19.2 preamble can typeset. An entry whose LRE renders such a surface directly instead of naming a token is refused with `LLB6002` naming the entry, the form, and the scalar; every shipped core and standard entry with a Unicode surface already names one. -* §17.8 fixes generated local names as `llv` / `llh` in introduction order. A binder that the generated declaration never references keeps its index and carries a `_` prefix (`_llv1`, `_llh0`): pinned Lean's `unusedVariables` linter warns about an unreferenced binding, §20.2 makes any Lean warning a verification failure, and §18.1 fixes the file structure so no `set_option` may silence it. Without the prefix an ordinary proposition with an unused quantified binder (`For every natural number \(n\) and natural number \(m\), \(n + 0 = n\)`) could never verify. The prefix marks the binding as deliberate; nothing else changes. - -All are enforced by the same golden and conformance gates as everything else. +Generated Lean declares `public` declarations and imports where SPEC.md §18.1 and §29.3 print bare forms. Under the Lean 4.32.1 module system a non public declaration is module private. A non public import may not contribute constants to a public declaration's signature. A definition body is hidden from importing modules unless exposed. The committed oracles carry `public`. + +Artifact naming uses slash separated directories (`modules/LexLeanExample/Main.lean`) instead of the §21.5 module path. Unique existence lowers to its definitional expansion because Lean's `Init` has no `ExistsUnique` constant. The linked IR keeps `ExistsUnique`; only the printed Lean bytes expand it. A `Witness` step leaves the `And` goal for the remaining proof. The pinned `leanchecker` has no version flag, so its attestation uses a fixed identity probe. + +Indentation uses two spaces per section depth. The §29.2 literal indents nothing inside `theorem` or `proof`, so only `\begin{section}` nesting adds a level. Redundant leading zeros are rejected as noncanonical decimal source (`LLL1003`). Generated numerals are ascribed except where the binder is a monomorphic constant type. Nested proof scopes use a `quote` environment. Identifier shaped names with `_` are emitted through the registered `\_` token. Non ASCII surfaces must name a renderer token. Unused binders get a `_` prefix to satisfy Lean's linter. Fixtures are discovered by their `case.toml`, not by directory name. + +All deviations are enforced by the same golden and conformance gates as everything else. ## Layout -Language data lives in [language/](language/), claim data in [model/](model/), schemas in [schemas/](schemas/), the compiler in [crates/lexlean/](crates/lexlean/), gates in [xtask/](xtask/) and [crates/conformance/](crates/conformance/), the examples in [examples/](examples/), and the negative fixtures in [tests/negative/](tests/negative/). The projects written in LexLean itself are [compiler/](compiler/) (the production calculus, GNAF, and certification), [stdlib/](stdlib/) (the standard library), and [bootstrap/](bootstrap/) (the compiler's own components, beside the Rust they replace, the stage-0 oracle). The pinned differential oracle is described in [oracle/](oracle/) as validation evidence only, the schemas of the stable API and the tooling interface are under [api/](api/) and [tooling/](tooling/), and the README's own logo is [assets/lexlean-logo.svg](assets/lexlean-logo.svg). CI is in [.github/](.github/). +Language data lives in [language/](language/). Claim data lives in [model/](model/). Schemas are in [schemas/](schemas/). The compiler is in [crates/lexlean/](crates/lexlean/). Gates are in [xtask/](xtask/) and [crates/conformance/](crates/conformance/). Examples are in [examples/](examples/). Negative fixtures are in [tests/negative/](tests/negative/). The projects written in LexLean itself are [compiler/](compiler/) (the production calculus, GNAF, and certification), [stdlib/](stdlib/) (the standard library), and [bootstrap/](bootstrap/) (the compiler's own components beside the Rust they replace). The pinned differential oracle is described in [oracle/](oracle/) as validation evidence only. The schemas of the stable API and the tooling interface are under [api/](api/) and [tooling/](tooling/). CI is in [.github/](.github/). ## License -Dual-licensed under [Apache-2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT), at your option. +Dual licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT), at your option. From 51484f648f0e0bcfebfe3993c38755fa08fc7d55 Mon Sep 17 00:00:00 2001 From: humuhumu33 <68450279+humuhumu33@users.noreply.github.com> Date: Tue, 27 Oct 2026 14:42:17 +0000 Subject: [PATCH 03/10] docs: use the enclosed LexLean logo image and tighten the README --- README.md | 118 ++++++++++------------------------------ assets/lexlean-logo.png | Bin 0 -> 31243 bytes 2 files changed, 30 insertions(+), 88 deletions(-) create mode 100644 assets/lexlean-logo.png diff --git a/README.md b/README.md index 1adb68b2e6..a95327bb0b 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,36 @@
-
- _               _
-| |             | |
-| |     _____  _| |     ___  __ _ _ __
-| |    / _ \ \/ / |    / _ \/ _` | '_ \
-| |___|  __/>  <| |___|  __/ (_| | | | |
-|______\___/_/\_\______\___|\__,_|_| |_|
-
- -One controlled language document in. A canonical paper, a kernel checked Lean 4 program, and a certified Rust package out. -
+ LexLean -LexLean compiles `.lex.tex` modules written in a closed controlled language. Every word, symbol, and control must be declared by a versioned lexicon package. Every sentence parses under a fixed grammar. One typed intermediate representation generates both the canonical LaTeX document and the prose free Lean 4 program. +

One controlled language in. A canonical paper, a kernel checked Lean 4 program, and a certified Rust package out.

+ -`lexlean verify` compiles the generated Lean under the pinned `leanprover/lean4:v4.32.1` toolchain. It replays every module with `leanchecker`, audits axioms by parsing `#print axioms` exactly, and publishes a content addressed attestation. +LexLean compiles `.lex.tex` modules written in a closed controlled language. Every word, symbol, and control comes from a versioned lexicon package. Every sentence follows a fixed grammar. One typed representation produces both the canonical LaTeX document and a Lean 4 program with no prose. -**Evidence, not belief.** `check` and `build` never claim verification. Only `verify` runs Lean. Whatever it cannot check is reported as not validated, never passed in silence. +`lexlean verify` compiles the generated Lean with `leanprover/lean4:v4.32.1`, replays every module with `leanchecker`, audits axioms by parsing `#print axioms` exactly, and publishes a content addressed attestation. `check` and `build` never claim verification. -The complete normative contract is [SPEC.md](SPEC.md). The generated register is [CONFORMANCE.md](CONFORMANCE.md). The closed diagnostic registry is [ERRORS.md](ERRORS.md). The falsifiability evidence is in [VERIFICATION.md](VERIFICATION.md). The changelog is [CHANGELOG.md](CHANGELOG.md). The MNIST model is at [UOR Foundation/MNIST](https://github.com/UOR-Foundation/MNIST). +[Spec](SPEC.md) · [Conformance](CONFORMANCE.md) · [Diagnostics](ERRORS.md) · [Evidence](VERIFICATION.md) · [Changelog](CHANGELOG.md) · [MNIST model](https://github.com/UOR-Foundation/MNIST) ## Quickstart -### Run in the container - -`lexlean verify` runs the pinned toolchain, so the published image carries the compiler and `leanprover/lean4:v4.32.1` together. This is the shortest path to a run that can actually verify: - ```text docker pull ghcr.io/uor-foundation/lexlean:0.4.0 docker run --rm -v "$PWD:/work" ghcr.io/uor-foundation/lexlean:0.4.0 verify ``` -The image is around 4 GB. Nearly all of it is the pinned toolchain's compiled library, the part `verify` needs. A smaller image would have to leave it out. - -### Or install a binary - -Each [release](https://github.com/UOR-Foundation/LexLean/releases) attaches one binary per supported host (SPEC.md §8.3), the packaged crate, a CycloneDX bill of materials, `checksums.txt` over every other asset, and the `just vv` evidence for the tagged commit. +The image is 4 GB because it carries the pinned toolchain. Each [release](https://github.com/UOR-Foundation/LexLean/releases) attaches one binary per supported host, the packaged crate, a CycloneDX bill of materials, checksums for every asset, and the gate evidence for the tagged commit. ```text tar -xzf lexlean-0.4.0-binaries.tar.gz sha256sum -c checksums.txt ``` -A binary alone can `init`, `lock`, `fmt`, `check`, and `build`. `verify` additionally needs the pinned toolchain installed through [elan](https://github.com/leanprover/elan). From source, with the prerequisites in [Building and running the gate](#building-and-running-the-gate): +A binary runs `init`, `lock`, `fmt`, `check`, and `build`. `verify` also needs the pinned toolchain through [elan](https://github.com/leanprover/elan). From source: ```text cargo install --locked --path crates/lexlean ``` -### Write, build, verify +Then: ```text lexlean init --name my-doc --module-prefix MyDoc @@ -57,7 +40,7 @@ lexlean build lexlean verify ``` -The document is plain controlled language. This is the complete SPEC.md §29 example, committed as [examples/nat-add-zero/src/Main.lex.tex](examples/nat-add-zero/src/Main.lex.tex): +This is the complete SPEC.md §29 example, committed as [examples/nat-add-zero/src/Main.lex.tex](examples/nat-add-zero/src/Main.lex.tex): ```latex \begin{lexlean}{Main} @@ -74,7 +57,7 @@ Close the goal by reflexivity. \end{lexlean} ``` -From that one source LexLean generates the prose free Lean module: +It generates a Lean module with no prose: ```lean module @@ -88,93 +71,52 @@ public theorem add_zero (llv0 : Nat) : Eq (Nat.add llv0 0) llv0 := by end LexLeanExample.Main ``` -It also generates the canonical LaTeX document from the linked representation, plus source maps, coverage, and a manifest. All outputs are byte reproducible across directories. `verify` then compiles the module under the pinned toolchain, replays it with `leanchecker`, parses `#print axioms` exactly, and records the empty observed axiom set in a content addressed attestation. +The same representation yields canonical LaTeX, source maps, coverage, and a manifest. Outputs are byte reproducible. `verify` checks the module, replays it with `leanchecker`, parses `#print axioms` exactly, and records the observed axiom set in a content addressed attestation. -## How LexLean works +## How it works ```text -your document (.lex.tex, closed lexicon) - | - v -one typed semantic representation (the single source of truth) - | - +====> canonical LaTeX (paper or PDF) - | - +====> prose free Lean 4 (kernel checked, exact axiom audit) - | - v - production compilation - | - v - certified Rust package - + certificates A / B / E + attestation - (replays offline, without the source) +document -> typed representation -> LaTeX + Lean 4 -> certified Rust ``` -* `lexlean init` scaffolds a project. It claims nothing. -* `lexlean lock` pins lexicons and dependencies in a canonical lock file. It claims nothing. -* `lexlean check` checks lexical closure, grammar, typing, and diagnostics. It never claims verification. -* `lexlean build` generates Lean, LaTeX, source maps, and manifests. It never claims verification. -* `lexlean verify` compiles under the pinned toolchain, replays with `leanchecker`, audits axioms, and attests. It is the only verified claim. -* `lexlean production build` exports certified Rust packages with their certificates. It claims kernel checked preservation. -* `lexlean migrate --to 1.2` upgrades a language 1.1 project, proved in a scratch copy first. It writes nothing on refusal. +`lexlean init` scaffolds a project and claims nothing. `lock` pins lexicons and dependencies. `check` checks closure, grammar, typing, and diagnostics, never verification. `build` generates Lean, LaTeX, source maps, and manifests, never verification. `verify` compiles under the pinned toolchain, replays with `leanchecker`, audits axioms, and attests; it is the only verified claim. `production build` exports certified Rust packages. `migrate --to 1.2` upgrades a language 1.1 project in a scratch copy first and writes nothing on refusal. -A language 1.2 project can import the modules of a locked, content addressed package of its workspace instead of copying them. `[[source_package]]` in `lexlean.toml` names a member directory listed by `lexlean-workspace.toml`. `lexlean.lock` pins the package by the digest of its manifest and source files. Every command recomputes the pin. Imports are closed to the project's own modules and the declared packages. `verify` replays the package's modules under its module prefix with the package as their origin (SPEC.md §10.5, `PK-01`..`PK-05`). The workspace the cases use is [tests/packages/workspace](tests/packages/workspace/). - -Language 1.1 semantic modules use the closed core backend's fixed finite Lean budgets (`maxRecDepth = 100000`, `maxHeartbeats = 1000000000`) so complete nested byte data declarations are not restricted by interactive defaults. Project child timeout and output limits and full kernel and axiom verification remain mandatory. These are generated backend settings, not caller provided options. +A language 1.2 project can import a locked, content addressed package of its workspace. `[[source_package]]` in `lexlean.toml` names a member directory listed by `lexlean-workspace.toml`; `lexlean.lock` pins it by the digest of its manifest and source files. Every command recomputes the pin, imports stay closed, and `verify` replays the package's modules with the package as their origin (SPEC.md §10.5, `PK-01`..`PK-05`). ## Why LexLean -The paper cannot drift from the program. Both are generated from one linked representation. Neither is copied, neither is hand maintained, and a change to one is a change to the other. Assumptions are audited, not assumed. An attestation records the toolchain hashes, the process records, and the exact observed axiom set of every module. The binary carries its guarantees. Production compilation to Rust emits certificates that a consumer replays offline, without the source, without Lean, and without trusting the producer. - -## When to use LexLean +One linked representation feeds every output, so the paper and the program cannot drift. Every claim is a content addressed record: what was checked, with which toolchain, under which assumptions. Production compilation emits certificates that a consumer replays offline, without the source or a trusted producer. -Safety critical code that must be proved, not sampled. Total programs with machine checked termination, exact failure typing, and a certified Rust output. Audited or regulated artifacts. Every claim is a content addressed record: what was checked, by which toolchain, under which assumptions. Documents whose formal content must match their prose. The canonical document is regenerated from the same representation that the kernel checks. Verified models and reasoners. Integer neural networks, rule based reasoning machines, and text classifiers as closed semantic objects. The [MNIST model](https://github.com/UOR-Foundation/MNIST) is one: an int8 digit recognizer whose weights are content addressed artifacts, whose forward pass is checked layer by layer, and whose contract for every input is a theorem. +Use it for safety critical code, audited or regulated artifacts, documents whose formal content must match their prose, and models or reasoners. The [MNIST model](https://github.com/UOR-Foundation/MNIST) is one: an int8 digit recognizer whose weights are content addressed artifacts and whose contract for every input is a theorem. ## Capabilities -Every capability is a claim in [`model/ids.toml`](model/ids.toml) at honesty level `build`. It is constructed here and validated against its oracle by the test named `conformance_`. Every row is validated by `just vv`, and its IDs link the claim to its register row, scenario, and conformance test. +Every capability is a claim in [`model/ids.toml`](model/ids.toml) at honesty level `build`. `just vv` validates every row by the test named `conformance_`. See [CONFORMANCE.md](CONFORMANCE.md) for the full register. -The 457 registered conformance IDs cover repository identity, configuration, lexical closure, lexicons, grammar, typed IR, declarations, proofs, Lean generation, LaTeX regeneration, diagnostics, verification, CLI, security, production eligibility, named root extraction, realization calculus, Rust backend, GNAF, certification, semantic preservation, models, differential oracle, production export, reasoning machines, compiler tooling, authoring notation, runtime, standard library, bootstrap, source packages, examples, and text components. See [CONFORMANCE.md](CONFORMANCE.md) for the full register and [model/ids.toml](model/ids.toml) for every individual ID with its scenario and test. +Every directory under [examples/](examples/) must format, lock, check, build, and verify with Lean 4.32.1. Other suites cover arithmetic, logic, induction, recursion, collections, production, models, reasoning, fold laws, helpdesk, and uor atlas. [compiler/](compiler/), [stdlib/](stdlib/), and [bootstrap/](bootstrap/) are written in LexLean itself. -## Examples that verify +## Gate -Every directory under [examples/](examples/) is discovered by the example gate (`EX-08`). Each must format, lock, check, build, and verify with real Lean 4.32.1 (`cargo xtask verify-examples`). Platform independent build outputs and normalized verification records are committed under `expected/` and compared byte for byte by the golden gate (§28.3) and the example gate (§29.5). That those bytes are also independent of where the build ran is the separate claim of `AR-13` and `EX-06`. - -The `nat-add-zero` example is the literal SPEC.md §29 document. Other examples cover Peano arithmetic, propositional logic, list induction, semantic 1.1, language 1.2, recursive data, higher order functions, recursion, collections, production, production coverage, models, reasoning, fold laws, helpdesk, and uor atlas. Three further projects are written in LexLean itself and pass the same gates: [compiler/](compiler/) defines the production realization calculus and GNAF certification; [stdlib/](stdlib/) is the standard library; [bootstrap/](bootstrap/) holds the compiler's own components beside the Rust they replace. - -## Building and running the gate - -Prerequisites: Rust 1.97.1 (`rust-toolchain.toml` pins it), [just](https://github.com/casey/just), `cargo-deny`, and the pinned Lean toolchain `leanprover/lean4:v4.32.1` installed through `elan`. The dev container provides all of them. +Prerequisites: Rust 1.97.1, [just](https://github.com/casey/just), `cargo-deny`, and Lean 4.32.1 through `elan`. The dev container provides all of them. ```text -just vv # the complete normative acceptance gate (SPEC.md §9.2) -just release # vv, then the §30 release criterion; refused until 1.0.0 +just vv +just release ``` -All 457 registered conformance IDs are implemented and pass. `just vv` runs clean from a checkout with the pinned toolchain installed. - -The differential against the independent generator `lean4-prod` (SPEC.md §17.19, `OR-01`..`OR-08`) is validation evidence only and no input to any identity. An unavailable oracle fails the gate on Linux x86 64 and prints `NOT VALIDATED` elsewhere. It is never reported as agreement. `just vv` is the Linux x86 64 gate. On the other four supported hosts (§8.3) the crate builds and every test runs. Platform dependent assertions are skipped and printed, detected at run time. On Linux x86 64 the toolchain gate is mandatory. - -Releases live on release lines (SPEC.md §9.4). `release/vX.Y` is cut from `main`, targets its pull requests, and is merged forward into the next line. `main` is the newest released line. A push to a release line runs the same gate as a push to `main`. Versions follow SPEC.md §30.1 and are recorded in [CHANGELOG.md](CHANGELOG.md). §2.3 fixes `0.1.0` as the initial version and `1.0.0` as the first release satisfying the complete specification. No tag before `1.0.0` claims the §30 criterion. `cargo xtask release-check` reads that criterion and says what does not hold. The release evidence is the gate run of the tagged commit. - -## Evidence, not belief - -`check` and `build` never claim verification (`VR-18`). Only `verify` runs Lean. Its attestation records toolchain hashes, process records, and observed axiom sets (`VR-01`..`VR-14`). Facts about external tools (Lean 4.32.1, Lake, leanchecker, `#print axioms` output shapes) are level `some-true` rows in [`model/ledger.toml`](model/ledger.toml), reproduced from cited authorities and not established here. The acceptance gate is `just vv` (SPEC.md §9.2). A release is refused until the complete §30 criterion holds (`RP-12`). - -## Documented deviations +All 457 registered conformance IDs are implemented and pass. `just vv` runs the complete normative acceptance gate (SPEC.md §9.2). `just release` runs `vv` and the §30 criterion; it is refused until 1.0.0. -Generated Lean declares `public` declarations and imports where SPEC.md §18.1 and §29.3 print bare forms. Under the Lean 4.32.1 module system a non public declaration is module private. A non public import may not contribute constants to a public declaration's signature. A definition body is hidden from importing modules unless exposed. The committed oracles carry `public`. +The [`lean4-prod`](https://github.com/UOR-Foundation/lean4-prod) differential is validation evidence only. A missing oracle fails on Linux x86 64 and prints `NOT VALIDATED` elsewhere. Releases live on `release/vX.Y`, and a tag before 1.0.0 does not claim the §30 criterion. -Artifact naming uses slash separated directories (`modules/LexLeanExample/Main.lean`) instead of the §21.5 module path. Unique existence lowers to its definitional expansion because Lean's `Init` has no `ExistsUnique` constant. The linked IR keeps `ExistsUnique`; only the printed Lean bytes expand it. A `Witness` step leaves the `And` goal for the remaining proof. The pinned `leanchecker` has no version flag, so its attestation uses a fixed identity probe. +## Evidence -Indentation uses two spaces per section depth. The §29.2 literal indents nothing inside `theorem` or `proof`, so only `\begin{section}` nesting adds a level. Redundant leading zeros are rejected as noncanonical decimal source (`LLL1003`). Generated numerals are ascribed except where the binder is a monomorphic constant type. Nested proof scopes use a `quote` environment. Identifier shaped names with `_` are emitted through the registered `\_` token. Non ASCII surfaces must name a renderer token. Unused binders get a `_` prefix to satisfy Lean's linter. Fixtures are discovered by their `case.toml`, not by directory name. +`check` and `build` never claim verification. Only `verify` runs Lean. Its attestation records toolchain hashes, process records, and observed axiom sets. External facts are `some-true` rows in [`model/ledger.toml`](model/ledger.toml). The gate is `just vv`; release waits for §30. -All deviations are enforced by the same golden and conformance gates as everything else. +Generated Lean declares `public` declarations and imports where Lean 4.32.1 requires them. Unique existence lowers to its definitional expansion. Leading zeros are rejected, numerals are ascribed except at monomorphic constant binders, nested proof scopes use `quote`, names with `_` escape as `\_`, non ASCII surfaces need a renderer token, and unused binders get a `_` prefix. Fixtures are found by `case.toml`. Every deviation is enforced by the same gates. ## Layout -Language data lives in [language/](language/). Claim data lives in [model/](model/). Schemas are in [schemas/](schemas/). The compiler is in [crates/lexlean/](crates/lexlean/). Gates are in [xtask/](xtask/) and [crates/conformance/](crates/conformance/). Examples are in [examples/](examples/). Negative fixtures are in [tests/negative/](tests/negative/). The projects written in LexLean itself are [compiler/](compiler/) (the production calculus, GNAF, and certification), [stdlib/](stdlib/) (the standard library), and [bootstrap/](bootstrap/) (the compiler's own components beside the Rust they replace). The pinned differential oracle is described in [oracle/](oracle/) as validation evidence only. The schemas of the stable API and the tooling interface are under [api/](api/) and [tooling/](tooling/). CI is in [.github/](.github/). +Language data is in [language/](language/), claims in [model/](model/), schemas in [schemas/](schemas/), the compiler in [crates/lexlean/](crates/lexlean/), and gates in [xtask/](xtask/) and [crates/conformance/](crates/conformance/). Examples are in [examples/](examples/) and negative fixtures in [tests/negative/](tests/negative/). CI is in [.github/](.github/). ## License diff --git a/assets/lexlean-logo.png b/assets/lexlean-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..1a50dc80fd2e60307de42e74cffb39286024bdb7 GIT binary patch literal 31243 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 literal 0 HcmV?d00001 From a4152103a9bb14327b7a26d6272e51c023e087e3 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 19:42:29 +0000 Subject: [PATCH 04/10] Land a cut on main only when the line contains main; dispatch the gate on an empty delivery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit tag.yml merged the line into main with `gh pr merge --auto`, which merges at once (main requires no checks) even when main holds commits the line lacks. It now merges only when origin/main is an ancestor of the tagged head, and otherwise leaves the pull request for a person. deliver-regenerated.sh dispatched ci.yml only after pushing a patch; a cut whose regeneration writes nothing was left with no gate run, since the workflow-token push of the version commit starts none. It now dispatches for a caller-named branch either way. SPEC.md §9.4 says both. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013Asa3MAztfvN671cYrybev --- .github/scripts/deliver-regenerated.sh | 5 +++++ .github/workflows/tag.yml | 22 ++++++++++++++++------ SPEC.md | 4 ++-- 3 files changed, 23 insertions(+), 8 deletions(-) diff --git a/.github/scripts/deliver-regenerated.sh b/.github/scripts/deliver-regenerated.sh index 9cc5c347c7..c2e2bad477 100755 --- a/.github/scripts/deliver-regenerated.sh +++ b/.github/scripts/deliver-regenerated.sh @@ -54,6 +54,11 @@ if [ -s "$dir/regenerated.patch" ]; then fi if git diff --cached --quiet; then say "The regenerated tree of \`$commit\` is the committed tree: nothing to deliver." + # A caller's branch was pushed with the workflow token, which started no + # run: the gate is dispatched for it all the same. + if [ -n "${BRANCH:-}" ]; then + gh workflow run ci.yml --repo "$repo" --ref "$branch" + fi else paths=$(git diff --cached --name-only | wc -l) { diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml index 1d4937c4a0..6a031142c4 100644 --- a/.github/workflows/tag.yml +++ b/.github/workflows/tag.yml @@ -3,7 +3,7 @@ # Once `ci.yml` has passed on that push, this tags it `vX.Y.Z`, dispatches # `release.yml` on the tag (a tag pushed with the workflow token starts no # run), and opens the pull request that carries the line to `main`, which -# receives a line at its tag, with auto-merge on. Any other push ends at the first step. +# receives a line at its tag, and merges it when the line contains `main`. Any other push ends at the first step. # # A gate that fails leaves the commit untagged; tag it by hand once a rerun # passes (`git tag -a vX.Y.Z -m "LexLean vX.Y.Z" && git push origin vX.Y.Z`), @@ -100,9 +100,19 @@ jobs: # A pull request opened with the workflow token starts no run, so the # gate is dispatched on the line: its plan finds the full run that # verified the tagged tree (the regenerated head of the cut, under - # equal-tree merges) and runs nothing again. The line contains - # `main`, so the merge lands that tree, and it merges itself once - # its checks pass. + # equal-tree merges) and runs nothing again. gh workflow run ci.yml --repo "$REPO" --ref "$GITHUB_REF_NAME" - gh pr merge --repo "$REPO" "$GITHUB_REF_NAME" --auto --merge \ - || echo "::warning::auto-merge not enabled on the pull request into main" + # Only a line that contains `main` lands the verified tree unchanged; + # then the merge needs no further gate and is made now. Otherwise + # `main` has commits the line lacks, and the pull request waits for a + # person to reconcile them. + git fetch --quiet origin main + if git merge-base --is-ancestor FETCH_HEAD HEAD 2>/dev/null \ + || { git fetch --quiet --unshallow origin 2>/dev/null; git fetch --quiet origin main \ + && git merge-base --is-ancestor FETCH_HEAD HEAD; }; then + gh pr merge --repo "$REPO" "$GITHUB_REF_NAME" --merge \ + || echo "::warning::the pull request into main did not merge" + else + echo "::warning::main has commits $GITHUB_REF_NAME lacks; the pull request into main waits for a person" + echo "\`main\` has commits \`$GITHUB_REF_NAME\` lacks: the pull request into main is left for a person." >> "$GITHUB_STEP_SUMMARY" + fi diff --git a/SPEC.md b/SPEC.md index a4a3468197..b2f9e4e3d0 100644 --- a/SPEC.md +++ b/SPEC.md @@ -693,7 +693,7 @@ Its image MUST install the pinned Rust and Lean toolchains at build, so that not **Release lines.** A release line is the branch `release/vX.Y` of the release X.Y: it is cut from `main` when work on X.Y begins, every pull request for the milestone X.Y targets it, each `vX.Y.Z` tag is made from it, and it is merged forward, by merge commit, into the next release line after each landing so that the next line carries every fix of the one before it. `main` is the newest released line: a release line is merged into `main` when its release is tagged, and nothing else lands on `main`. A release line is held to the same gate as `main`: a push to it is the whole gate under the rule above, and a pull request against it is a pull request of this repository. -**Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. Merging that pull request is the decision to release. `tag.yml` runs on every push to a release line and stops at once unless the push changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it waits for this push's run of `ci.yml`, and only when that run passed it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and enables auto-merge, since the line contains `main` and the merge lands that tree. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. +**Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. Merging that pull request is the decision to release. `tag.yml` runs on every push to a release line and stops at once unless the push changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it waits for this push's run of `ci.yml`, and only when that run passed it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and merges that pull request when the line contains `main`, so the merge lands that tree; when `main` has commits the line lacks, the pull request is left for a person. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. **The release's evidence.** `release.yml` runs no recipe of the gate. The CI evidence a release attaches (§30.3) is a run of `ci.yml` that was the whole gate and passed every job, on the tagged commit or, while the commit is a merge whose tree is the tree of its second parent, on that parent, at most four merges down (the walk the plan makes); `.github/release-gate.sh` finds it under the rule `plan` applies to a push, and refuses, naming the commits it looked at, when no such run exists. The evidence names the run, every job of it with its conclusion, and the transcript of every leg the run still retains. The gate run whole on one hosted runner exceeds the six-hour job limit (the `bdd` recipe alone takes over four hours there, and Atlas follows it), so a release gate that re-ran it would never conclude, and the run of the line has already verified the tree. @@ -713,7 +713,7 @@ The Intel host factory is separate from the normative BDD and Atlas partitions a `reproducibility.yml` MUST perform two builds in distinct absolute directories and compare every platform-independent artifact byte-for-byte after path normalization. -`regenerate.yml` is not part of the gate: it runs the write recipes of §9.2 on runners, so that a change which moves committed output is regenerated from a clean checkout rather than on a workstation. A push to a branch under `regenerate/`, or a `workflow_dispatch` on a ref, starts three jobs at once, each from its own clean checkout of that commit: `production-export-write`; `verify-write` over every example but UOR Atlas, or over every example when the branch is under `regenerate/atlas/` or the `atlas` input is set; and `golden-write fixtures-write calculus-write model-write`. They verify with the profile of the `examples` leg, which changes no byte of what is written (§22.11). Each returns what its recipes wrote as a binary patch, and the job `combine` applies the patches in turn to a clean checkout of the same commit, failing when two write one path. The job `finish` then applies that tree and writes what follows from it: the counts the bootstrap count cases assert, by `cargo xtask counts --write` over runs of the parts of `.github/bdd-parts.json` that hold a `crate::counts!` check under `LEXLEAN_COUNTS=fast`; the model documents, by `validate-model --write`; and the row of `tests/stack-bounds.json` of each recursive package of the bootstrap and stdlib exports that has none (`PD-08`), measured by a whole run under `LEXLEAN_MEASURE_STACK=all` of the case whose source names the package's root, which also checks the counts just written, while a row of a package no longer exported is dropped. It returns the result as one patch with the list of its paths, the counts the writer reported, and the commit it applies to. Its writers read the repository and write nothing to it (`contents: read`, no persisted credentials). The job `deliver` then commits the patch on the commit it was made from and pushes that commit, as a fast-forward, to the branch the commit heads: the head branch of the one open pull request of this repository whose head is the commit, or the branch a caller (`cut.yml`) names; a branch pushed again in the meantime rejects the push and is left alone. It dispatches `ci.yml` on that branch and deletes the `regenerate/` branch that started the run when that branch still names the commit. With no such pull request it pushes nothing and the patch stays the run's artifact. The delivered commit is reviewed in its pull request like any other written output (§28.3), and the gate then verifies the tree that carries it. +`regenerate.yml` is not part of the gate: it runs the write recipes of §9.2 on runners, so that a change which moves committed output is regenerated from a clean checkout rather than on a workstation. A push to a branch under `regenerate/`, or a `workflow_dispatch` on a ref, starts three jobs at once, each from its own clean checkout of that commit: `production-export-write`; `verify-write` over every example but UOR Atlas, or over every example when the branch is under `regenerate/atlas/` or the `atlas` input is set; and `golden-write fixtures-write calculus-write model-write`. They verify with the profile of the `examples` leg, which changes no byte of what is written (§22.11). Each returns what its recipes wrote as a binary patch, and the job `combine` applies the patches in turn to a clean checkout of the same commit, failing when two write one path. The job `finish` then applies that tree and writes what follows from it: the counts the bootstrap count cases assert, by `cargo xtask counts --write` over runs of the parts of `.github/bdd-parts.json` that hold a `crate::counts!` check under `LEXLEAN_COUNTS=fast`; the model documents, by `validate-model --write`; and the row of `tests/stack-bounds.json` of each recursive package of the bootstrap and stdlib exports that has none (`PD-08`), measured by a whole run under `LEXLEAN_MEASURE_STACK=all` of the case whose source names the package's root, which also checks the counts just written, while a row of a package no longer exported is dropped. It returns the result as one patch with the list of its paths, the counts the writer reported, and the commit it applies to. Its writers read the repository and write nothing to it (`contents: read`, no persisted credentials). The job `deliver` then commits the patch on the commit it was made from and pushes that commit, as a fast-forward, to the branch the commit heads: the head branch of the one open pull request of this repository whose head is the commit, or the branch a caller (`cut.yml`) names; a branch pushed again in the meantime rejects the push and is left alone. It dispatches `ci.yml` on that branch and deletes the `regenerate/` branch that started the run when that branch still names the commit. When the patch is empty and a caller named the branch, it dispatches `ci.yml` there all the same. With no such pull request it pushes nothing and the patch stays the run's artifact. The delivered commit is reviewed in its pull request like any other written output (§28.3), and the gate then verifies the tree that carries it. --- From eb6f1df2414a4804ec3392e0d19a66761814807c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 20:05:08 +0000 Subject: [PATCH 05/10] Land, tag, and release a cut once its gate passes, with no hand merge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cut.yml now carries a cut to its release: after regenerate.yml delivers and dispatches the gate (and returns the delivered head as `head`), the jobs `gate` and `gate-more` wait for that ci.yml run (two waits of 340 minutes, each within the six-hour job limit), and accept it only when release-gate.sh finds it the whole gate with every job passed. `land` merges the pull request with a merge commit at exactly that head (--match-head-commit) and only while the line has not moved since the cut, so the merge's tree is the verified head's. A merge made with the workflow token starts no run, so cut.yml calls tag.yml (now also a reusable workflow, inputs commit and line) on the merge. tag.yml accepts a commit's tree as verified when release-gate.sh finds the run release.yml will attach (the commit's, or its equal-tree second parent's), before waiting for a push run; a call has no push run and stops when there is no such evidence. Its push trigger still tags a person's merge. Its concurrency moves to the job, keyed by line. Anything that stops the landing leaves the pull request open, and a person's merge releases as before. SPEC.md §9.4, AGENTS.md and the changelog say so. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013Asa3MAztfvN671cYrybev --- .github/scripts/await-gate.sh | 63 +++++++++++ .github/scripts/deliver-regenerated.sh | 7 +- .github/workflows/cut.yml | 146 ++++++++++++++++++++++++- .github/workflows/regenerate.yml | 10 +- .github/workflows/tag.yml | 76 +++++++++---- AGENTS.md | 7 +- CHANGELOG.md | 8 +- SPEC.md | 2 +- 8 files changed, 284 insertions(+), 35 deletions(-) create mode 100755 .github/scripts/await-gate.sh diff --git a/.github/scripts/await-gate.sh b/.github/scripts/await-gate.sh new file mode 100755 index 0000000000..262bcb0d9d --- /dev/null +++ b/.github/scripts/await-gate.sh @@ -0,0 +1,63 @@ +#!/usr/bin/env bash +# The wait of `cut.yml` for the gate of a cut (SPEC.md §9.4): polls the runs +# of `ci.yml` on HEAD_SHA, the regenerated head `regenerate.yml` delivered and +# dispatched the gate on, until the newest pull request or dispatched run of +# it completes or WAIT_MINUTES pass. A run that completed `success` counts +# only when `.github/release-gate.sh` accepts it as the whole gate with every +# job passed, the evidence `release.yml` will read for the tag; so a cut lands +# on exactly what would release. +# +# Writes `state` to GITHUB_OUTPUT: `passed`, `failed` (the newest run failed, +# was cancelled, or passed without being the whole gate; exit 1), or +# `pending` (no verdict in time; exit 0, or exit 1 when FINAL is `true`, the +# last wait of the cut). A run re-run after a failure is the newest run again, +# so re-running the cut's failed jobs waits for it afresh. +# +# Inputs, from the environment: REPO, HEAD_SHA, WAIT_MINUTES, FINAL. `gh` +# reads the runs and jobs (`actions: read`); the checkout is HEAD_SHA. +set -euo pipefail + +repo=${REPO:?REPO names owner/name} +head=${HEAD_SHA:?HEAD_SHA names the commit the gate runs on} +wait=${WAIT_MINUTES:-340} +final=${FINAL:-false} +out=${GITHUB_OUTPUT:-/dev/null} +summary=${GITHUB_STEP_SUMMARY:-/dev/null} +say() { printf '%s\n' "$1" | tee -a "$summary"; } + +deadline=$((SECONDS + wait * 60)) +while :; do + state=$(gh api "repos/$repo/actions/workflows/ci.yml/runs?head_sha=$head&per_page=30" \ + --jq "[.workflow_runs[] | select(.head_repository.full_name == \"$repo\") | select(.event == \"pull_request\" or .event == \"workflow_dispatch\")][0] // empty | \"\(.status) \(.conclusion) \(.html_url)\"" \ + 2>/dev/null || true) + case "$state" in + "completed success "*) + if SHA=$head OUT="${RUNNER_TEMP:-/tmp}/gate-evidence.txt" .github/release-gate.sh; then + say "The gate passed on \`$head\`: ${state##* }" + echo "state=passed" >> "$out" + exit 0 + fi + say "The newest run of \`ci.yml\` on \`$head\` passed without being the whole gate: ${state##* }" + echo "state=failed" >> "$out" + exit 1 + ;; + completed*) + echo "::error::the gate of $head did not pass: $state" + say "The gate of \`$head\` did not pass (${state##* }). Re-run its failed jobs, then re-run this run's failed jobs to land the cut; or fix the cut branch and merge its pull request by hand." + echo "state=failed" >> "$out" + exit 1 + ;; + esac + if [ "$SECONDS" -ge "$deadline" ]; then + break + fi + sleep 60 +done + +echo "state=pending" >> "$out" +if [ "$final" = true ]; then + echo "::error::the gate of $head did not finish in time: ${state:-no run yet}" + say "The gate of \`$head\` gave no verdict in time (${state:-no run yet}). Re-run this run's failed jobs to wait again, or merge the pull request by hand once it passes." + exit 1 +fi +say "The gate of \`$head\` gave no verdict in $wait minutes (${state:-no run yet}); the next job waits on." diff --git a/.github/scripts/deliver-regenerated.sh b/.github/scripts/deliver-regenerated.sh index c2e2bad477..e327aa40f6 100755 --- a/.github/scripts/deliver-regenerated.sh +++ b/.github/scripts/deliver-regenerated.sh @@ -15,7 +15,9 @@ # # Inputs, from the environment: REPO, COMMIT, BRANCH (may be empty), RUN_URL, # REGENERATED (the downloaded `regenerated-` artifact), GITHUB_REF, -# GITHUB_STEP_SUMMARY. The checkout is COMMIT with the workflow token. +# GITHUB_STEP_SUMMARY. The checkout is COMMIT with the workflow token. Output, +# to GITHUB_OUTPUT: `head`, the commit the gate was dispatched on, when it was +# (`cut.yml` waits for that run and lands the cut on it); nothing otherwise. set -euo pipefail repo=${REPO:?REPO names owner/name} @@ -23,6 +25,7 @@ commit=${COMMIT:?COMMIT names the regenerated commit} branch=${BRANCH:-} dir=${REGENERATED:?REGENERATED names the artifact directory} summary=${GITHUB_STEP_SUMMARY:-/dev/null} +output=${GITHUB_OUTPUT:-/dev/null} say() { printf '%s\n' "$1" | tee -a "$summary"; } (cd "$dir" && sha256sum --check --quiet SHA256SUMS) @@ -58,6 +61,7 @@ if git diff --cached --quiet; then # run: the gate is dispatched for it all the same. if [ -n "${BRANCH:-}" ]; then gh workflow run ci.yml --repo "$repo" --ref "$branch" + echo "head=$commit" >> "$output" fi else paths=$(git diff --cached --name-only | wc -l) @@ -76,6 +80,7 @@ else # A plain push is a fast-forward or nothing. git push origin "HEAD:refs/heads/$branch" gh workflow run ci.yml --repo "$repo" --ref "$branch" + echo "head=$(git rev-parse HEAD)" >> "$output" say "Delivered $paths regenerated paths to \`$branch\` as \`$(git rev-parse HEAD)\` and dispatched \`ci.yml\` there." fi diff --git a/.github/workflows/cut.yml b/.github/workflows/cut.yml index dffbca81ae..5ce64b7b21 100644 --- a/.github/workflows/cut.yml +++ b/.github/workflows/cut.yml @@ -1,5 +1,5 @@ # A release cut in one push (SPEC.md §9.4): the version commit, its -# regeneration, and the pull request that lands it on its line. +# regeneration, its gate, and its landing, tag, and release, with no hand step. # # git push origin release/vX.Y:refs/heads/cut/vX.Y.Z # @@ -8,10 +8,20 @@ # `## X.Y.Z`, commits that on the pushed commit, and opens the pull request # from `cut/vX.Y.Z` into `release/vX.Y`. `regenerate.yml` then writes what the # version moves (every build oracle names the compiler's version), delivers -# that to the branch, and dispatches the gate there. Merging the pull request -# is the decision to release: `tag.yml` tags the merge once its gate passes -# and `release.yml` publishes it. The pushed commit must be on the line, and -# the version must follow the line's and have no tag. +# that to the branch, and dispatches the gate there. `gate` and `gate-more` +# wait for that run (the gate takes hours, and a job may run six), `land` +# merges the pull request at the head the gate passed on, and `tag.yml`, +# called here because a merge made with the workflow token starts no run, +# tags the merge, dispatches `release.yml`, and carries the line to `main`. +# The pushed commit must be on the line, and the version must follow the +# line's and have no tag. +# +# What stops the landing leaves the pull request open, and a person's merge +# of it releases as before (`tag.yml` on the push): a gate that failed (re-run +# its failed jobs, then this run's failed jobs, and the cut lands), a gate +# with no verdict after two waits (re-run this run's failed jobs to wait +# again), no pull request, a line that moved since the cut, or a head pushed +# since the gate ran. name: cut on: @@ -83,7 +93,7 @@ jobs: -m "cargo xtask bump-version $VERSION: the workspace version, SPEC.md §2.3, RP-01, Cargo.lock, and the changelog's unreleased entries." git push origin "HEAD:refs/heads/$GITHUB_REF_NAME" echo "commit=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT" - body="Cuts LexLean $VERSION on \`$LINE\` (\`cut.yml\`). \`regenerate.yml\` writes what the version moves and dispatches the gate here. Merging releases: \`tag.yml\` tags the merge as \`v$VERSION\` once its gate passes, and \`release.yml\` publishes it. Edit the \`## $VERSION\` changelog section before merging if it needs a summary." + body="Cuts LexLean $VERSION on \`$LINE\` (\`cut.yml\`). \`regenerate.yml\` writes what the version moves and dispatches the gate here. Once that gate passes, \`cut.yml\` merges this pull request at the head it verified, tags the merge as \`v$VERSION\`, and \`release.yml\` publishes it; nobody needs to merge it. A push to this branch before then stops the automatic landing, and merging by hand releases as before." if url=$(gh pr create --repo "$GITHUB_REPOSITORY" --base "$LINE" --head "$GITHUB_REF_NAME" \ --title "Release $VERSION" --body "$body" 2>&1); then echo "Opened $url" >> "$GITHUB_STEP_SUMMARY" @@ -106,3 +116,127 @@ jobs: with: ref: ${{ needs.version.outputs.commit }} branch: ${{ needs.version.outputs.branch }} + + # The gate of the delivered head: the run `regenerate.yml` dispatched, + # planned as the pull request's, which must be the whole gate and pass every + # job. Two waits, because the gate runs for hours and a job for at most six. + gate: + name: wait for the gate + needs: regenerate + if: needs.regenerate.outputs.head != '' + runs-on: ubuntu-24.04 + timeout-minutes: 360 + permissions: + contents: read + actions: read + outputs: + state: ${{ steps.wait.outputs.state }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.regenerate.outputs.head }} + persist-credentials: false + - name: Wait for the gate of the delivered head + id: wait + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + HEAD_SHA: ${{ needs.regenerate.outputs.head }} + WAIT_MINUTES: "340" + run: .github/scripts/await-gate.sh + + gate-more: + name: wait for the gate (continued) + needs: [regenerate, gate] + if: needs.gate.outputs.state == 'pending' + runs-on: ubuntu-24.04 + timeout-minutes: 360 + permissions: + contents: read + actions: read + outputs: + state: ${{ steps.wait.outputs.state }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.regenerate.outputs.head }} + persist-credentials: false + - name: Wait for the gate of the delivered head + id: wait + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + HEAD_SHA: ${{ needs.regenerate.outputs.head }} + WAIT_MINUTES: "340" + FINAL: "true" + run: .github/scripts/await-gate.sh + + # The merge of the pull request at the head the gate passed on, as a merge + # commit: the line has not moved since the cut, so the merge's tree is the + # head's, which is the evidence `ci.yml`'s plan and `release-gate.sh` accept + # for it (the merge pushed with the workflow token starts no run of its own). + land: + name: land the cut + needs: [version, regenerate, gate, gate-more] + if: >- + !cancelled() && needs.regenerate.result == 'success' + && (needs.gate.outputs.state == 'passed' || needs.gate-more.outputs.state == 'passed') + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: write + pull-requests: write + outputs: + merge: ${{ steps.merge.outputs.merge }} + line: ${{ steps.merge.outputs.line }} + steps: + - name: Merge the pull request at the verified head + id: merge + shell: bash + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + BRANCH: ${{ needs.version.outputs.branch }} + HEAD_SHA: ${{ needs.regenerate.outputs.head }} + run: | + set -euo pipefail + pr=$(gh pr list --repo "$REPO" --head "$BRANCH" --state open --json number,baseRefName,headRefOid \ + --jq '.[] | "\(.number) \(.baseRefName) \(.headRefOid)"') + if [ -z "$pr" ] || [ "$(printf '%s\n' "$pr" | wc -l)" -ne 1 ]; then + echo "::error::no single open pull request from $BRANCH; open it and merge it by hand" + exit 1 + fi + read -r number line head <<< "$pr" + if [ "$head" != "$HEAD_SHA" ]; then + echo "::error::$BRANCH is at $head, not $HEAD_SHA where the gate passed; merge it by hand once its gate passes" + exit 1 + fi + base=$(gh api "repos/$REPO/branches/$line" --jq .commit.sha) + if [ "$(gh api "repos/$REPO/compare/$base...$HEAD_SHA" --jq .behind_by)" != 0 ]; then + echo "::error::$line moved to $base since the cut, so the merge would land a tree the gate did not verify; merge it by hand" + exit 1 + fi + gh pr merge --repo "$REPO" "$number" --merge --match-head-commit "$HEAD_SHA" + merge=$(gh pr view --repo "$REPO" "$number" --json mergeCommit --jq .mergeCommit.oid) + if [ -z "$merge" ] || [ "$merge" = null ]; then + echo "::error::pull request #$number reports no merge commit" + exit 1 + fi + echo "merge=$merge" >> "$GITHUB_OUTPUT" + echo "line=$line" >> "$GITHUB_OUTPUT" + echo "Merged #$number into \`$line\` as \`$merge\` at the verified head \`$HEAD_SHA\`." >> "$GITHUB_STEP_SUMMARY" + + tag: + name: tag + needs: land + uses: ./.github/workflows/tag.yml + # A reusable workflow is validated against what its caller grants: `tag` + # pushes the tag, dispatches, and opens and merges the pull request into + # `main`. + permissions: + contents: write + actions: write + pull-requests: write + with: + commit: ${{ needs.land.outputs.merge }} + line: ${{ needs.land.outputs.line }} diff --git a/.github/workflows/regenerate.yml b/.github/workflows/regenerate.yml index 2b1fb67b43..a381de13b0 100755 --- a/.github/workflows/regenerate.yml +++ b/.github/workflows/regenerate.yml @@ -16,7 +16,8 @@ # # A push to `regenerate/**` starts it from any commit, because GitHub # dispatches only a workflow its default branch carries. `cut.yml` calls it on -# the version commit of a release cut, naming the branch to deliver to. +# the version commit of a release cut, naming the branch to deliver to, and +# lands the cut once the gate passes on the head this returns (`head`). name: regenerate on: @@ -41,6 +42,10 @@ on: atlas: type: boolean default: false + outputs: + head: + description: The commit of `branch` the gate was dispatched on (the delivered head), or empty when nothing was delivered or dispatched + value: ${{ jobs.deliver.outputs.head }} permissions: contents: read @@ -350,6 +355,8 @@ jobs: contents: write actions: write pull-requests: read + outputs: + head: ${{ steps.deliver.outputs.head }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: @@ -359,6 +366,7 @@ jobs: name: regenerated-${{ inputs.ref || github.sha }} path: ${{ runner.temp }}/regenerated - name: Commit the regenerated tree to the pull request and run the gate there + id: deliver shell: bash env: GH_TOKEN: ${{ github.token }} diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml index 6a031142c4..9e6844cc9c 100644 --- a/.github/workflows/tag.yml +++ b/.github/workflows/tag.yml @@ -1,9 +1,18 @@ -# The tag of a cut (SPEC.md §9.4): a push to a release line whose first -# parent carried another workspace version is the merge of a cut (`cut.yml`). -# Once `ci.yml` has passed on that push, this tags it `vX.Y.Z`, dispatches -# `release.yml` on the tag (a tag pushed with the workflow token starts no -# run), and opens the pull request that carries the line to `main`, which -# receives a line at its tag, and merges it when the line contains `main`. Any other push ends at the first step. +# The tag of a cut (SPEC.md §9.4): a commit on a release line whose first +# parent carried another workspace version is the merge of a cut. `cut.yml` +# calls this on the merge it made once the gate passed on the cut's head (a +# merge pushed with the workflow token starts no run); a push to a line, a +# person's merge of a cut, starts it too. Once the commit's tree is verified, +# this tags it `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with +# the workflow token starts no run), and opens the pull request that carries +# the line to `main`, which receives a line at its tag, and merges it when the +# line contains `main`. Any other commit ends at the first step. +# +# The tree is verified when `.github/release-gate.sh` finds the run of +# `ci.yml` that `release.yml` will attach: one on the commit, or, while it is +# a merge whose tree is its second parent's, on that parent (the cut's head). +# A push without such a run waits for its own push run; a call has none to +# wait for and stops. # # A gate that fails leaves the commit untagged; tag it by hand once a rerun # passes (`git tag -a vX.Y.Z -m "LexLean vX.Y.Z" && git push origin vX.Y.Z`), @@ -13,21 +22,36 @@ name: tag on: push: branches: ["release/**"] + workflow_call: + inputs: + commit: + description: The merge of a cut on its line, which `cut.yml` made + type: string + required: true + line: + description: The release line the commit is on, `release/vX.Y` + type: string + required: true permissions: contents: read -concurrency: - group: tag-${{ github.ref }} - cancel-in-progress: false - jobs: tag: name: tag a cut if: github.repository == 'UOR-Foundation/LexLean' runs-on: ubuntu-24.04 + # One per line, whether pushed or called (a called workflow's `github.ref` + # is its caller's). + concurrency: + group: tag-refs/heads/${{ inputs.line || github.ref_name }} + cancel-in-progress: false # The gate of a push that does not merge a verified tree runs for hours. timeout-minutes: 360 + env: + COMMIT: ${{ inputs.commit || github.sha }} + LINE: ${{ inputs.line || github.ref_name }} + CALLED: ${{ inputs.commit != '' }} permissions: contents: write actions: write @@ -35,6 +59,7 @@ jobs: steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ inputs.commit || github.sha }} fetch-depth: 2 - name: Is this push a cut id: cut @@ -57,7 +82,7 @@ jobs: exit 1 fi echo "version=$version" >> "$GITHUB_OUTPUT" - - name: Wait for the gate of this push + - name: Wait for the gate of this commit's tree if: steps.cut.outputs.version != '' shell: bash env: @@ -65,16 +90,23 @@ jobs: REPO: ${{ github.repository }} run: | set -euo pipefail + if SHA=$COMMIT OUT="$RUNNER_TEMP/gate-evidence.txt" .github/release-gate.sh; then + exit 0 + fi + if [ "$CALLED" = true ]; then + echo "::error::no run of ci.yml verified the tree of $COMMIT, and a merge made with the workflow token starts none" + exit 1 + fi for _ in $(seq 1 340); do - state=$(gh api "repos/$REPO/actions/workflows/ci.yml/runs?head_sha=$GITHUB_SHA&event=push&per_page=1" \ + state=$(gh api "repos/$REPO/actions/workflows/ci.yml/runs?head_sha=$COMMIT&event=push&per_page=1" \ --jq '.workflow_runs[0] | "\(.status) \(.conclusion) \(.html_url)"' 2>/dev/null || true) case "$state" in "completed success "*) echo "gate passed: ${state##* }"; exit 0 ;; - completed*) echo "::error::the gate of $GITHUB_SHA did not pass: $state"; exit 1 ;; + completed*) echo "::error::the gate of $COMMIT did not pass: $state"; exit 1 ;; esac sleep 60 done - echo "::error::the gate of $GITHUB_SHA did not finish in time" + echo "::error::the gate of $COMMIT did not finish in time" exit 1 - name: Tag, release, and carry the line to main if: steps.cut.outputs.version != '' @@ -90,18 +122,18 @@ jobs: tag -a "v$VERSION" -m "LexLean v$VERSION" git push origin "refs/tags/v$VERSION" gh workflow run release.yml --repo "$REPO" --ref "v$VERSION" - echo "Tagged v$VERSION at $GITHUB_SHA and dispatched release.yml" >> "$GITHUB_STEP_SUMMARY" - if [ -z "$(gh pr list --repo "$REPO" --base main --head "$GITHUB_REF_NAME" --state open --json number --jq '.[].number')" ]; then - gh pr create --repo "$REPO" --base main --head "$GITHUB_REF_NAME" \ + echo "Tagged v$VERSION at $COMMIT and dispatched release.yml" >> "$GITHUB_STEP_SUMMARY" + if [ -z "$(gh pr list --repo "$REPO" --base main --head "$LINE" --state open --json number --jq '.[].number')" ]; then + gh pr create --repo "$REPO" --base main --head "$LINE" \ --title "Land v$VERSION on main" \ - --body "\`main\` receives \`$GITHUB_REF_NAME\` at its tag \`v$VERSION\` (SPEC.md §9.4; opened by \`tag.yml\`)." \ + --body "\`main\` receives \`$LINE\` at its tag \`v$VERSION\` (SPEC.md §9.4; opened by \`tag.yml\`)." \ || echo "::warning::no pull request into main opened" fi # A pull request opened with the workflow token starts no run, so the # gate is dispatched on the line: its plan finds the full run that # verified the tagged tree (the regenerated head of the cut, under # equal-tree merges) and runs nothing again. - gh workflow run ci.yml --repo "$REPO" --ref "$GITHUB_REF_NAME" + gh workflow run ci.yml --repo "$REPO" --ref "$LINE" # Only a line that contains `main` lands the verified tree unchanged; # then the merge needs no further gate and is made now. Otherwise # `main` has commits the line lacks, and the pull request waits for a @@ -110,9 +142,9 @@ jobs: if git merge-base --is-ancestor FETCH_HEAD HEAD 2>/dev/null \ || { git fetch --quiet --unshallow origin 2>/dev/null; git fetch --quiet origin main \ && git merge-base --is-ancestor FETCH_HEAD HEAD; }; then - gh pr merge --repo "$REPO" "$GITHUB_REF_NAME" --merge \ + gh pr merge --repo "$REPO" "$LINE" --merge \ || echo "::warning::the pull request into main did not merge" else - echo "::warning::main has commits $GITHUB_REF_NAME lacks; the pull request into main waits for a person" - echo "\`main\` has commits \`$GITHUB_REF_NAME\` lacks: the pull request into main is left for a person." >> "$GITHUB_STEP_SUMMARY" + echo "::warning::main has commits $LINE lacks; the pull request into main waits for a person" + echo "\`main\` has commits \`$LINE\` lacks: the pull request into main is left for a person." >> "$GITHUB_STEP_SUMMARY" fi diff --git a/AGENTS.md b/AGENTS.md index 39de274e8c..132110311c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -118,8 +118,11 @@ The mechanical steps are workflows, not hand work. A tree that moves committed output is regenerated by pushing its head to `regenerate/`; when that head is an open pull request's, `regenerate.yml` commits the result to the pull request and restarts the gate there. A release `X.Y.Z` is cut by -`git push origin release/vX.Y:refs/heads/cut/vX.Y.Z`; merging the pull request -`cut.yml` opens tags and publishes it (`tag.yml`, `release.yml`). +`git push origin release/vX.Y:refs/heads/cut/vX.Y.Z`; that push is the whole +decision: `cut.yml` regenerates the cut, waits for its gate, merges its pull +request at the verified head, tags and publishes it (`tag.yml`, +`release.yml`). Merge the pull request by hand only when `cut.yml` stopped +short and says why. A pull request that is final is marked ready with auto-merge on (`gh pr merge --auto --merge`), so it lands when its gate passes and its branch is deleted on merge. diff --git a/CHANGELOG.md b/CHANGELOG.md index bcbd097509..f70d4b602e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,8 +28,12 @@ workspace carried at those versions without a tag. A release is cut by pushing the line's head to `cut/vX.Y.Z`: `cut.yml` runs the new `cargo xtask bump-version X.Y.Z` (every site of the workspace version, the changelog's `## Unreleased` heading, and `Cargo.lock`), opens the - pull request, and regenerates it; `tag.yml` tags the merge once its gate - passes, dispatches `release.yml`, and opens the pull request into `main`. + pull request, regenerates it, waits for the gate on the regenerated head, + merges the pull request at that head, and calls `tag.yml`, which tags the + merge, dispatches `release.yml`, and opens the pull request into `main`; no + person merges a cut. `tag.yml` still tags a person's merge of a cut, and + accepts the run that verified a merged head's tree without waiting for the + merge's own. - Decision regions (SPEC.md §17.12, `PF-24`, UOR-Foundation/PrismPM#605; no new diagnostic code; changes the language-1.2 identity). The runtime gains a sixth native module, `LexLeanRuntime.Regions`: a checker of local box diff --git a/SPEC.md b/SPEC.md index b2f9e4e3d0..71a3a439eb 100644 --- a/SPEC.md +++ b/SPEC.md @@ -693,7 +693,7 @@ Its image MUST install the pinned Rust and Lean toolchains at build, so that not **Release lines.** A release line is the branch `release/vX.Y` of the release X.Y: it is cut from `main` when work on X.Y begins, every pull request for the milestone X.Y targets it, each `vX.Y.Z` tag is made from it, and it is merged forward, by merge commit, into the next release line after each landing so that the next line carries every fix of the one before it. `main` is the newest released line: a release line is merged into `main` when its release is tagged, and nothing else lands on `main`. A release line is held to the same gate as `main`: a push to it is the whole gate under the rule above, and a pull request against it is a pull request of this repository. -**Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. Merging that pull request is the decision to release. `tag.yml` runs on every push to a release line and stops at once unless the push changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it waits for this push's run of `ci.yml`, and only when that run passed it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and merges that pull request when the line contains `main`, so the merge lands that tree; when `main` has commits the line lacks, the pull request is left for a person. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. +**Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. The cut is the decision to release, and nothing after it waits for a person. `regenerate.yml` returns the head it delivered and dispatched `ci.yml` on; `cut.yml` waits for that run (in two jobs of at most six hours each, because the gate runs for hours) and lands the cut only when `.github/release-gate.sh` accepts it as the whole gate with every job passed, the evidence `release.yml` will attach. It then merges the pull request with a merge commit at exactly that head, and only while the line has not moved since the cut, so the merge's tree is the head's; a merge made with the workflow token starts no run, so `cut.yml` calls `tag.yml` on that merge itself. `tag.yml` also runs on every push to a release line, which is how a person's merge of a cut releases. It stops at once unless the commit changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it accepts the commit's tree as verified when `release-gate.sh` finds that run (on the commit, or, while it is a merge whose tree is its second parent's, on that parent), and otherwise waits for the push's own run of `ci.yml` (a call has none and stops); only when the tree is verified it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and merges that pull request when the line contains `main`, so the merge lands that tree; when `main` has commits the line lacks, the pull request is left for a person. What stops the landing leaves the cut's pull request open, and merging it by hand releases as above: a gate that failed (re-running its failed jobs and then the cut run's failed jobs lands the cut), a gate with no verdict after both waits, no pull request, a line that moved since the cut, or a head pushed since the gate ran. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. **The release's evidence.** `release.yml` runs no recipe of the gate. The CI evidence a release attaches (§30.3) is a run of `ci.yml` that was the whole gate and passed every job, on the tagged commit or, while the commit is a merge whose tree is the tree of its second parent, on that parent, at most four merges down (the walk the plan makes); `.github/release-gate.sh` finds it under the rule `plan` applies to a push, and refuses, naming the commits it looked at, when no such run exists. The evidence names the run, every job of it with its conclusion, and the transcript of every leg the run still retains. The gate run whole on one hosted runner exceeds the six-hour job limit (the `bdd` recipe alone takes over four hours there, and Atlas follows it), so a release gate that re-ran it would never conclude, and the run of the line has already verified the tree. From feac64ad7de028606c6d2839bcdfb626830c2c4c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 20:11:24 +0000 Subject: [PATCH 06/10] Leave an empty ## Unreleased after a cut, so the next cut finds one bump-version renamed the only ## Unreleased heading to ## X.Y.Z and required exactly one, so the cut after it refused until someone restored the heading. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013Asa3MAztfvN671cYrybev --- SPEC.md | 2 +- xtask/src/bump.rs | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/SPEC.md b/SPEC.md index a6f73f8ffa..561a9d9f8f 100644 --- a/SPEC.md +++ b/SPEC.md @@ -695,7 +695,7 @@ Its image MUST install the pinned Rust and Lean toolchains at build, so that not **Release lines.** A release line is the branch `release/vX.Y` of the release X.Y: it is cut from `main` when work on X.Y begins, every pull request for the milestone X.Y targets it, each `vX.Y.Z` tag is made from it, and it is merged forward, by merge commit, into the next release line after each landing so that the next line carries every fix of the one before it. `main` is the newest released line: a release line is merged into `main` when its release is tagged, and nothing else lands on `main`. A release line is held to the same gate as `main`: a push to it is the whole gate under the rule above, and a pull request against it is a pull request of this repository. -**Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. The cut is the decision to release, and nothing after it waits for a person. `regenerate.yml` returns the head it delivered and dispatched `ci.yml` on; `cut.yml` waits for that run (in two jobs of at most six hours each, because the gate runs for hours) and lands the cut only when `.github/release-gate.sh` accepts it as the whole gate with every job passed, the evidence `release.yml` will attach. It then merges the pull request with a merge commit at exactly that head, and only while the line has not moved since the cut, so the merge's tree is the head's; a merge made with the workflow token starts no run, so `cut.yml` calls `tag.yml` on that merge itself. `tag.yml` also runs on every push to a release line, which is how a person's merge of a cut releases. It stops at once unless the commit changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it accepts the commit's tree as verified when `release-gate.sh` finds that run (on the commit, or, while it is a merge whose tree is its second parent's, on that parent), and otherwise waits for the push's own run of `ci.yml` (a call has none and stops); only when the tree is verified it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and merges that pull request when the line contains `main`, so the merge lands that tree; when `main` has commits the line lacks, the pull request is left for a person. What stops the landing leaves the cut's pull request open, and merging it by hand releases as above: a gate that failed (re-running its failed jobs and then the cut run's failed jobs lands the cut), a gate with no verdict after both waits, no pull request, a line that moved since the cut, or a head pushed since the gate ran. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. +**Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z` under a new empty `## Unreleased`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. The cut is the decision to release, and nothing after it waits for a person. `regenerate.yml` returns the head it delivered and dispatched `ci.yml` on; `cut.yml` waits for that run (in two jobs of at most six hours each, because the gate runs for hours) and lands the cut only when `.github/release-gate.sh` accepts it as the whole gate with every job passed, the evidence `release.yml` will attach. It then merges the pull request with a merge commit at exactly that head, and only while the line has not moved since the cut, so the merge's tree is the head's; a merge made with the workflow token starts no run, so `cut.yml` calls `tag.yml` on that merge itself. `tag.yml` also runs on every push to a release line, which is how a person's merge of a cut releases. It stops at once unless the commit changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it accepts the commit's tree as verified when `release-gate.sh` finds that run (on the commit, or, while it is a merge whose tree is its second parent's, on that parent), and otherwise waits for the push's own run of `ci.yml` (a call has none and stops); only when the tree is verified it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and merges that pull request when the line contains `main`, so the merge lands that tree; when `main` has commits the line lacks, the pull request is left for a person. What stops the landing leaves the cut's pull request open, and merging it by hand releases as above: a gate that failed (re-running its failed jobs and then the cut run's failed jobs lands the cut), a gate with no verdict after both waits, no pull request, a line that moved since the cut, or a head pushed since the gate ran. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. **The release's evidence.** `release.yml` runs no recipe of the gate. The CI evidence a release attaches (§30.3) is a run of `ci.yml` that was the whole gate and passed every job, on the tagged commit or, while the commit is a merge whose tree is the tree of its second parent, on that parent, at most four merges down (the walk the plan makes); `.github/release-gate.sh` finds it under the rule `plan` applies to a push, and refuses, naming the commits it looked at, when no such run exists. The evidence names the run, every job of it with its conclusion, and the transcript of every leg the run still retains. The gate run whole on one hosted runner exceeds the six-hour job limit (the `bdd` recipe alone takes over four hours there, and Atlas follows it), so a release gate that re-ran it would never conclude, and the run of the line has already verified the tree. diff --git a/xtask/src/bump.rs b/xtask/src/bump.rs index be3ee8a24c..3099ddebe8 100644 --- a/xtask/src/bump.rs +++ b/xtask/src/bump.rs @@ -79,12 +79,12 @@ fn sites(old: &str, new: &str) -> Vec { format!("\"a {new} tree must refuse release"), 1, ), - // The unreleased entries become the release's (Keep a Changelog); the - // next landing opens a new `## Unreleased`. + // The unreleased entries become the release's (Keep a Changelog), under + // a fresh, empty `## Unreleased` that the next cut finds. site( "CHANGELOG.md", "\n## Unreleased\n".to_owned(), - format!("\n## {new}\n"), + format!("\n## Unreleased\n\n## {new}\n"), 1, ), ] From 8287848058b1d0b5dcf6ddbc919d8c1d9b6b3be5 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 20:16:28 +0000 Subject: [PATCH 07/10] Bind both automatic merges to what was verified cut.yml's land job merged through the API with --match-head-commit, which binds the head but not the base: a line that advanced between the check and the merge gave a tree the gate never saw. It now makes the merge on the checked line head and pushes it with a lease on that head. tag.yml's merge of the line into main is bound to the tagged commit with --match-head-commit. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013Asa3MAztfvN671cYrybev --- .github/workflows/cut.yml | 31 ++++++++++++++++++++++--------- .github/workflows/tag.yml | 6 ++++-- SPEC.md | 2 +- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/.github/workflows/cut.yml b/.github/workflows/cut.yml index 5ce64b7b21..3b3c1ed55c 100644 --- a/.github/workflows/cut.yml +++ b/.github/workflows/cut.yml @@ -172,9 +172,11 @@ jobs: run: .github/scripts/await-gate.sh # The merge of the pull request at the head the gate passed on, as a merge - # commit: the line has not moved since the cut, so the merge's tree is the - # head's, which is the evidence `ci.yml`'s plan and `release-gate.sh` accept - # for it (the merge pushed with the workflow token starts no run of its own). + # commit made here on the line's head B and pushed with a lease on B: B is + # an ancestor of the head, so the merge's tree is the head's, the evidence + # `ci.yml`'s plan and `release-gate.sh` accept for it (the push, made with + # the workflow token, starts no run of its own), and a line that moved after + # the check refuses the push instead of taking a tree nobody verified. land: name: land the cut needs: [version, regenerate, gate, gate-more] @@ -190,6 +192,9 @@ jobs: merge: ${{ steps.merge.outputs.merge }} line: ${{ steps.merge.outputs.line }} steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 - name: Merge the pull request at the verified head id: merge shell: bash @@ -198,6 +203,7 @@ jobs: REPO: ${{ github.repository }} BRANCH: ${{ needs.version.outputs.branch }} HEAD_SHA: ${{ needs.regenerate.outputs.head }} + REPO_OWNER: ${{ github.repository_owner }} run: | set -euo pipefail pr=$(gh pr list --repo "$REPO" --head "$BRANCH" --state open --json number,baseRefName,headRefOid \ @@ -211,17 +217,24 @@ jobs: echo "::error::$BRANCH is at $head, not $HEAD_SHA where the gate passed; merge it by hand once its gate passes" exit 1 fi - base=$(gh api "repos/$REPO/branches/$line" --jq .commit.sha) - if [ "$(gh api "repos/$REPO/compare/$base...$HEAD_SHA" --jq .behind_by)" != 0 ]; then + git fetch --quiet origin "+refs/heads/$line:refs/remotes/origin/$line" + base=$(git rev-parse "refs/remotes/origin/$line") + if ! git merge-base --is-ancestor "$base" "$HEAD_SHA"; then echo "::error::$line moved to $base since the cut, so the merge would land a tree the gate did not verify; merge it by hand" exit 1 fi - gh pr merge --repo "$REPO" "$number" --merge --match-head-commit "$HEAD_SHA" - merge=$(gh pr view --repo "$REPO" "$number" --json mergeCommit --jq .mergeCommit.oid) - if [ -z "$merge" ] || [ "$merge" = null ]; then - echo "::error::pull request #$number reports no merge commit" + git checkout --quiet --detach "$base" + git -c user.name='github-actions[bot]' \ + -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \ + merge --quiet --no-ff --no-edit \ + -m "Merge pull request #$number from $REPO_OWNER/$BRANCH" -m "Release ${BRANCH#cut/v}, landed by cut.yml at the head its gate verified." "$HEAD_SHA" + if [ "$(git rev-parse 'HEAD^{tree}')" != "$(git rev-parse "$HEAD_SHA^{tree}")" ]; then + echo "::error::the merge's tree is not the tree the gate verified" exit 1 fi + # The lease makes the push land only on the B checked above. + git push --force-with-lease="refs/heads/$line:$base" origin "HEAD:refs/heads/$line" + merge=$(git rev-parse HEAD) echo "merge=$merge" >> "$GITHUB_OUTPUT" echo "line=$line" >> "$GITHUB_OUTPUT" echo "Merged #$number into \`$line\` as \`$merge\` at the verified head \`$HEAD_SHA\`." >> "$GITHUB_STEP_SUMMARY" diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml index 9e6844cc9c..81cb9dd0b8 100644 --- a/.github/workflows/tag.yml +++ b/.github/workflows/tag.yml @@ -142,8 +142,10 @@ jobs: if git merge-base --is-ancestor FETCH_HEAD HEAD 2>/dev/null \ || { git fetch --quiet --unshallow origin 2>/dev/null; git fetch --quiet origin main \ && git merge-base --is-ancestor FETCH_HEAD HEAD; }; then - gh pr merge --repo "$REPO" "$LINE" --merge \ - || echo "::warning::the pull request into main did not merge" + # Bound to the tagged commit: a line that moved past it is not + # what this run verified, and the merge is refused. + gh pr merge --repo "$REPO" "$LINE" --merge --match-head-commit "$COMMIT" \ + || echo "::warning::the pull request into main did not merge at $COMMIT; it waits for a person" else echo "::warning::main has commits $LINE lacks; the pull request into main waits for a person" echo "\`main\` has commits \`$LINE\` lacks: the pull request into main is left for a person." >> "$GITHUB_STEP_SUMMARY" diff --git a/SPEC.md b/SPEC.md index 561a9d9f8f..ded8449e08 100644 --- a/SPEC.md +++ b/SPEC.md @@ -695,7 +695,7 @@ Its image MUST install the pinned Rust and Lean toolchains at build, so that not **Release lines.** A release line is the branch `release/vX.Y` of the release X.Y: it is cut from `main` when work on X.Y begins, every pull request for the milestone X.Y targets it, each `vX.Y.Z` tag is made from it, and it is merged forward, by merge commit, into the next release line after each landing so that the next line carries every fix of the one before it. `main` is the newest released line: a release line is merged into `main` when its release is tagged, and nothing else lands on `main`. A release line is held to the same gate as `main`: a push to it is the whole gate under the rule above, and a pull request against it is a pull request of this repository. -**Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z` under a new empty `## Unreleased`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. The cut is the decision to release, and nothing after it waits for a person. `regenerate.yml` returns the head it delivered and dispatched `ci.yml` on; `cut.yml` waits for that run (in two jobs of at most six hours each, because the gate runs for hours) and lands the cut only when `.github/release-gate.sh` accepts it as the whole gate with every job passed, the evidence `release.yml` will attach. It then merges the pull request with a merge commit at exactly that head, and only while the line has not moved since the cut, so the merge's tree is the head's; a merge made with the workflow token starts no run, so `cut.yml` calls `tag.yml` on that merge itself. `tag.yml` also runs on every push to a release line, which is how a person's merge of a cut releases. It stops at once unless the commit changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it accepts the commit's tree as verified when `release-gate.sh` finds that run (on the commit, or, while it is a merge whose tree is its second parent's, on that parent), and otherwise waits for the push's own run of `ci.yml` (a call has none and stops); only when the tree is verified it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and merges that pull request when the line contains `main`, so the merge lands that tree; when `main` has commits the line lacks, the pull request is left for a person. What stops the landing leaves the cut's pull request open, and merging it by hand releases as above: a gate that failed (re-running its failed jobs and then the cut run's failed jobs lands the cut), a gate with no verdict after both waits, no pull request, a line that moved since the cut, or a head pushed since the gate ran. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. +**Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z` under a new empty `## Unreleased`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. The cut is the decision to release, and nothing after it waits for a person. `regenerate.yml` returns the head it delivered and dispatched `ci.yml` on; `cut.yml` waits for that run (in two jobs of at most six hours each, because the gate runs for hours) and lands the cut only when `.github/release-gate.sh` accepts it as the whole gate with every job passed, the evidence `release.yml` will attach. It then merges the pull request with a merge commit of exactly that head onto the line's head, which must be an ancestor of it, and pushes the merge with a lease on that line head, so a line that moves meanwhile refuses the push and the merge's tree is always the head's; a merge made with the workflow token starts no run, so `cut.yml` calls `tag.yml` on that merge itself. `tag.yml` also runs on every push to a release line, which is how a person's merge of a cut releases. It stops at once unless the commit changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it accepts the commit's tree as verified when `release-gate.sh` finds that run (on the commit, or, while it is a merge whose tree is its second parent's, on that parent), and otherwise waits for the push's own run of `ci.yml` (a call has none and stops); only when the tree is verified it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and merges that pull request, only while the line's head is still the tagged commit, when the line contains `main`, so the merge lands that tree; when `main` has commits the line lacks, the pull request is left for a person. What stops the landing leaves the cut's pull request open, and merging it by hand releases as above: a gate that failed (re-running its failed jobs and then the cut run's failed jobs lands the cut), a gate with no verdict after both waits, no pull request, a line that moved since the cut, or a head pushed since the gate ran. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. **The release's evidence.** `release.yml` runs no recipe of the gate. The CI evidence a release attaches (§30.3) is a run of `ci.yml` that was the whole gate and passed every job, on the tagged commit or, while the commit is a merge whose tree is the tree of its second parent, on that parent, at most four merges down (the walk the plan makes); `.github/release-gate.sh` finds it under the rule `plan` applies to a push, and refuses, naming the commits it looked at, when no such run exists. The evidence names the run, every job of it with its conclusion, and the transcript of every leg the run still retains. The gate run whole on one hosted runner exceeds the six-hour job limit (the `bdd` recipe alone takes over four hours there, and Atlas follows it), so a release gate that re-ran it would never conclude, and the run of the line has already verified the tree. From cbaaa5cd1d9e7a84a4bea25de283f4bc862fd05d Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 20:19:56 +0000 Subject: [PATCH 08/10] Serialize and verify the merge of a line into main main takes changes only through a pull request, so the lease that binds the cut's landing cannot be used; GitHub's merge binds the head, not the base. The main-forward step is now its own job in one concurrency group across all lines, and the merge it makes is checked to have the examined main as first parent and the tagged commit's tree. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013Asa3MAztfvN671cYrybev --- .github/workflows/tag.yml | 71 ++++++++++++++++++++++++++++++++------- SPEC.md | 2 +- 2 files changed, 59 insertions(+), 14 deletions(-) diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml index 81cb9dd0b8..cfd954e943 100644 --- a/.github/workflows/tag.yml +++ b/.github/workflows/tag.yml @@ -55,7 +55,8 @@ jobs: permissions: contents: write actions: write - pull-requests: write + outputs: + version: ${{ steps.cut.outputs.version }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: @@ -123,6 +124,41 @@ jobs: git push origin "refs/tags/v$VERSION" gh workflow run release.yml --repo "$REPO" --ref "v$VERSION" echo "Tagged v$VERSION at $COMMIT and dispatched release.yml" >> "$GITHUB_STEP_SUMMARY" + + # The line carried to `main` at its tag. `main` takes changes only through a + # pull request, and GitHub's merge binds the head (the tagged commit) but + # not the base, so the step that checks `main` and merges runs one at a time + # across every line, and the merge it made is checked after: its first + # parent must be the `main` checked and its tree the tagged commit's. + main: + name: carry the line to main + needs: tag + if: needs.tag.outputs.version != '' + runs-on: ubuntu-24.04 + timeout-minutes: 15 + concurrency: + group: tag-main + cancel-in-progress: false + env: + COMMIT: ${{ inputs.commit || github.sha }} + LINE: ${{ inputs.line || github.ref_name }} + VERSION: ${{ needs.tag.outputs.version }} + permissions: + contents: read + actions: write + pull-requests: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ inputs.commit || github.sha }} + fetch-depth: 0 + - name: Merge the line into main at its tag + shell: bash + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + run: | + set -euo pipefail if [ -z "$(gh pr list --repo "$REPO" --base main --head "$LINE" --state open --json number --jq '.[].number')" ]; then gh pr create --repo "$REPO" --base main --head "$LINE" \ --title "Land v$VERSION on main" \ @@ -135,18 +171,27 @@ jobs: # equal-tree merges) and runs nothing again. gh workflow run ci.yml --repo "$REPO" --ref "$LINE" # Only a line that contains `main` lands the verified tree unchanged; - # then the merge needs no further gate and is made now. Otherwise - # `main` has commits the line lacks, and the pull request waits for a - # person to reconcile them. - git fetch --quiet origin main - if git merge-base --is-ancestor FETCH_HEAD HEAD 2>/dev/null \ - || { git fetch --quiet --unshallow origin 2>/dev/null; git fetch --quiet origin main \ - && git merge-base --is-ancestor FETCH_HEAD HEAD; }; then - # Bound to the tagged commit: a line that moved past it is not - # what this run verified, and the merge is refused. - gh pr merge --repo "$REPO" "$LINE" --merge --match-head-commit "$COMMIT" \ - || echo "::warning::the pull request into main did not merge at $COMMIT; it waits for a person" - else + # otherwise `main` has commits the line lacks, and the pull request + # waits for a person to reconcile them. + git fetch --quiet origin "+refs/heads/main:refs/remotes/origin/main" + base=$(git rev-parse refs/remotes/origin/main) + if ! git merge-base --is-ancestor "$base" "$COMMIT"; then echo "::warning::main has commits $LINE lacks; the pull request into main waits for a person" echo "\`main\` has commits \`$LINE\` lacks: the pull request into main is left for a person." >> "$GITHUB_STEP_SUMMARY" + exit 0 + fi + # Bound to the tagged commit: a line that moved past it is not what + # this run verified, and the merge is refused. + if ! gh pr merge --repo "$REPO" "$LINE" --merge --match-head-commit "$COMMIT"; then + echo "::warning::the pull request into main did not merge at $COMMIT; it waits for a person" + exit 0 + fi + merge=$(gh pr list --repo "$REPO" --base main --head "$LINE" --state merged --limit 1 \ + --json mergeCommit --jq '.[0].mergeCommit.oid') + git fetch --quiet origin "$merge" + if [ "$(git rev-parse "$merge^1")" != "$base" ] \ + || [ "$(git rev-parse "$merge^{tree}")" != "$(git rev-parse "$COMMIT^{tree}")" ]; then + echo "::error::main moved during the merge: $merge is not v$VERSION's tree on the main that was checked ($base); revert it by a pull request" + exit 1 fi + echo "Merged \`$LINE\` into \`main\` as \`$merge\`, the tree of \`v$VERSION\`." >> "$GITHUB_STEP_SUMMARY" diff --git a/SPEC.md b/SPEC.md index ded8449e08..13348ebf2b 100644 --- a/SPEC.md +++ b/SPEC.md @@ -695,7 +695,7 @@ Its image MUST install the pinned Rust and Lean toolchains at build, so that not **Release lines.** A release line is the branch `release/vX.Y` of the release X.Y: it is cut from `main` when work on X.Y begins, every pull request for the milestone X.Y targets it, each `vX.Y.Z` tag is made from it, and it is merged forward, by merge commit, into the next release line after each landing so that the next line carries every fix of the one before it. `main` is the newest released line: a release line is merged into `main` when its release is tagged, and nothing else lands on `main`. A release line is held to the same gate as `main`: a push to it is the whole gate under the rule above, and a pull request against it is a pull request of this repository. -**Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z` under a new empty `## Unreleased`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. The cut is the decision to release, and nothing after it waits for a person. `regenerate.yml` returns the head it delivered and dispatched `ci.yml` on; `cut.yml` waits for that run (in two jobs of at most six hours each, because the gate runs for hours) and lands the cut only when `.github/release-gate.sh` accepts it as the whole gate with every job passed, the evidence `release.yml` will attach. It then merges the pull request with a merge commit of exactly that head onto the line's head, which must be an ancestor of it, and pushes the merge with a lease on that line head, so a line that moves meanwhile refuses the push and the merge's tree is always the head's; a merge made with the workflow token starts no run, so `cut.yml` calls `tag.yml` on that merge itself. `tag.yml` also runs on every push to a release line, which is how a person's merge of a cut releases. It stops at once unless the commit changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it accepts the commit's tree as verified when `release-gate.sh` finds that run (on the commit, or, while it is a merge whose tree is its second parent's, on that parent), and otherwise waits for the push's own run of `ci.yml` (a call has none and stops); only when the tree is verified it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and merges that pull request, only while the line's head is still the tagged commit, when the line contains `main`, so the merge lands that tree; when `main` has commits the line lacks, the pull request is left for a person. What stops the landing leaves the cut's pull request open, and merging it by hand releases as above: a gate that failed (re-running its failed jobs and then the cut run's failed jobs lands the cut), a gate with no verdict after both waits, no pull request, a line that moved since the cut, or a head pushed since the gate ran. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. +**Cutting a release.** A release `X.Y.Z` is cut by one push of the line's head to the branch `cut/vX.Y.Z`. `cut.yml` refuses a name that is not a version, a commit not on `release/vX.Y`, and a version already tagged; it runs `cargo xtask bump-version X.Y.Z`, which moves every site of the workspace version together (the `[workspace.package]` version and the workspace's path dependencies in `Cargo.toml`, the §2.3 block above, the identity literals of `RP-01` and `RP-12`, the changelog's `## Unreleased` heading, which becomes `## X.Y.Z` under a new empty `## Unreleased`, and the workspace rows of `Cargo.lock`), refuses to write anything when a site does not read as it expects or the version does not follow the workspace's, and puts every file back when the lock cannot be updated, commits that on the pushed commit, opens the pull request into the line, and calls `regenerate.yml` on the commit, which writes what the version moves and delivers it to the branch. The cut is the decision to release, and nothing after it waits for a person. `regenerate.yml` returns the head it delivered and dispatched `ci.yml` on; `cut.yml` waits for that run (in two jobs of at most six hours each, because the gate runs for hours) and lands the cut only when `.github/release-gate.sh` accepts it as the whole gate with every job passed, the evidence `release.yml` will attach. It then merges the pull request with a merge commit of exactly that head onto the line's head, which must be an ancestor of it, and pushes the merge with a lease on that line head, so a line that moves meanwhile refuses the push and the merge's tree is always the head's; a merge made with the workflow token starts no run, so `cut.yml` calls `tag.yml` on that merge itself. `tag.yml` also runs on every push to a release line, which is how a person's merge of a cut releases. It stops at once unless the commit changed the workspace version from its first parent's to one with no tag and a `## X.Y.Z` changelog entry; then it accepts the commit's tree as verified when `release-gate.sh` finds that run (on the commit, or, while it is a merge whose tree is its second parent's, on that parent), and otherwise waits for the push's own run of `ci.yml` (a call has none and stops); only when the tree is verified it tags the commit `vX.Y.Z`, dispatches `release.yml` on the tag (a tag pushed with the workflow token starts no run), opens the pull request that merges the line into `main`, dispatches `ci.yml` on the line (a pull request opened with the workflow token starts no run), whose plan finds the run that verified the tagged tree and runs nothing again, and merges that pull request, only while the line's head is still the tagged commit, when the line contains `main` (one such merge at a time across every line, since `main` takes changes only through a pull request and GitHub's merge cannot be bound to the base; the merge is then checked to have the `main` it examined as its first parent and the tagged tree as its tree, and fails loudly otherwise), so the merge lands that tree; when `main` has commits the line lacks, the pull request is left for a person. What stops the landing leaves the cut's pull request open, and merging it by hand releases as above: a gate that failed (re-running its failed jobs and then the cut run's failed jobs lands the cut), a gate with no verdict after both waits, no pull request, a line that moved since the cut, or a head pushed since the gate ran. A tag pushed by hand starts `release.yml` itself; nothing here changes what a release publishes or what evidence it requires. **The release's evidence.** `release.yml` runs no recipe of the gate. The CI evidence a release attaches (§30.3) is a run of `ci.yml` that was the whole gate and passed every job, on the tagged commit or, while the commit is a merge whose tree is the tree of its second parent, on that parent, at most four merges down (the walk the plan makes); `.github/release-gate.sh` finds it under the rule `plan` applies to a push, and refuses, naming the commits it looked at, when no such run exists. The evidence names the run, every job of it with its conclusion, and the transcript of every leg the run still retains. The gate run whole on one hosted runner exceeds the six-hour job limit (the `bdd` recipe alone takes over four hours there, and Atlas follows it), so a release gate that re-ran it would never conclude, and the run of the line has already verified the tree. From d0d58d2d67e46c33eeca22198b6b8e9fb9f15723 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 20:58:49 +0000 Subject: [PATCH 09/10] Give the main-forward job contents: write, which merging needs Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013Asa3MAztfvN671cYrybev --- .github/workflows/tag.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml index cfd954e943..a48d856935 100644 --- a/.github/workflows/tag.yml +++ b/.github/workflows/tag.yml @@ -143,8 +143,10 @@ jobs: COMMIT: ${{ inputs.commit || github.sha }} LINE: ${{ inputs.line || github.ref_name }} VERSION: ${{ needs.tag.outputs.version }} + # Merging a pull request writes the base branch: contents, not only + # pull-requests. permissions: - contents: read + contents: write actions: write pull-requests: write steps: From 7f699211285ddd5048270b00f3ff21a73afcfef9 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 08:39:59 +0000 Subject: [PATCH 10/10] Name this repository case-insensitively in the Intel run identity The repository was renamed UOR-Foundation/lexlean, so GITHUB_REPOSITORY no longer equals the literal UOR-Foundation/LexLean and every Intel construction job refused its own run as a foreign repository. GitHub names repositories case-insensitively; the check now does too, and a test pins both spellings. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013Asa3MAztfvN671cYrybev --- .github/scripts/intel_host_tests.py | 4 +++- .github/scripts/test_intel_host_tests.py | 9 +++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/.github/scripts/intel_host_tests.py b/.github/scripts/intel_host_tests.py index b95030bb4a..92816bfeb8 100644 --- a/.github/scripts/intel_host_tests.py +++ b/.github/scripts/intel_host_tests.py @@ -322,7 +322,9 @@ def source_identity(root): def run_identity(): result = {name: os.environ.get(name, "") for name in ("GITHUB_REPOSITORY", "GITHUB_RUN_ID", "GITHUB_RUN_ATTEMPT")} require(all(result.values()), "GitHub repository, run ID and attempt are required") - require(result["GITHUB_REPOSITORY"] == "UOR-Foundation/LexLean", "foreign repository") + # GitHub names a repository case-insensitively, and reports it as it is + # spelled now (`lexlean` since the rename), so the spelling is not identity. + require(result["GITHUB_REPOSITORY"].casefold() == "uor-foundation/lexlean", "foreign repository") require(all(result[n].isdigit() for n in ("GITHUB_RUN_ID", "GITHUB_RUN_ATTEMPT")), "invalid run ID/attempt") return result diff --git a/.github/scripts/test_intel_host_tests.py b/.github/scripts/test_intel_host_tests.py index 89c45ec720..c2118f6e24 100644 --- a/.github/scripts/test_intel_host_tests.py +++ b/.github/scripts/test_intel_host_tests.py @@ -153,6 +153,15 @@ def test_committed_lane_plan_is_complete_and_preserves_existing_parts(self): self.assertGreater(len(lanes["lanes"]), 0) self.assertEqual(set(lanes["producer"]), set(bdd["targets"])) + def test_run_identity_names_this_repository_in_any_case(self): + for name in ("UOR-Foundation/LexLean", "UOR-Foundation/lexlean"): + with patch.dict(os.environ, {"GITHUB_REPOSITORY": name, "GITHUB_RUN_ID": "1", "GITHUB_RUN_ATTEMPT": "1"}): + self.assertEqual(factory.run_identity()["GITHUB_REPOSITORY"], name) + for name in ("someone/lexlean", "UOR-Foundation/lexlean-fork"): + with patch.dict(os.environ, {"GITHUB_REPOSITORY": name, "GITHUB_RUN_ID": "1", "GITHUB_RUN_ATTEMPT": "1"}): + with self.assertRaises(BaseException): + factory.run_identity() + def test_plan_missing_duplicate_foreign_and_added_part_are_refused(self): fixture = Fixture(self.directory) for change in (lambda p: p["lanes"]["lower"].clear(), lambda p: p["lanes"]["print"].append("a"), lambda p: p["lanes"]["moves"].append("unknown")):