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 +
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. + -```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.
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. The canonical paper, a kernel-checked Lean 4 program, and a certified Rust package out.
- -- 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.
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.
- _ _ -| | | | -| | _____ _| | ___ __ _ _ __ -| | / _ \ \/ / | / _ \/ _` | '_ \ -| |___| __/> <| |___| __/ (_| | | | | -|______\___/_/\_\______\___|\__,_|_| |_| -- -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.
+ 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_YJ~;bxlo@{NndC zx{C}>ZhrOB28_mA-=`TFo%H=Uqz!11Ki+ijCDJRtE*Ge6XYts(D;&qLx%^nhV7dRh zc^s^slqK8AsJ0UpRO~D*Y;eI^-On(ncuI40W7UsaYUfdH7%T!AFcidDhoZBto0qrV zoR@irBxm78)hsmZ3GL)bgpD-Uz_ync;&&fzG#hZ$r`N#97Q2Td_A==`7~SRkJWf?U zc*Nzt)w`flF20lcMc&%l$Wd5YPw$+yGMBW0+Bqj9BQ?WUhy;qdLR#uVu}W%_CfGY< zd3BG?QwK}t0PAs@Z?UQYv&~%ZkTcb%-Ev2?y*ceg(sSA)y0ZEnWoOObv^(%F`L!7s)`{leT>f_Zo>$*ufR_anKHT;mZ*=O(Vm~n|OcS`y- zyC+lBjU)8@kjsX=u6uWqH>x8@k~fTp1Kk#rVbqeYo21?_4+OR0rt1glcy8AM7-H?W zB()*x>F{(sR}6KXzqi#&ouGuiA5u4-*LC`(itF}ENv#^-4@Xt%PtQMIDz6^*!No>ePz{LaRB|rfz(D zEt1r!j5 |MSCtQlr0tIPyn(ZZM2ql9tQPin^ew4c zHr(dhEY$OpD;i}V2q*9M2mcSol@-7&OT;`HW=o>2nuqjC$JqM~0;1=>hp~8!FqBXT z_P+^4Zi(73XO*!y48(3u&;8N|26!kk5E&)9+}$5pRtn21<)%gcEVEJ8v)1IT9d#H@ zES|~gf9Npo-bEWR7+bkA*U#p**j{GK%!}Zlt-HPcS5nVWkvD*J?uWM!Dz1NXJser? zV$0lAAxK*%ygt@kBIsam7-MJ1TN}APnkX~^PN99iA&f<057ED|ZJWAU_i24xGRDS( zHz2-0p458jSV`;2e12>#fYW^k&RZLN@%!z?nv*un?hEiNYVt9JVbHwT`#@wF`Iw~Z z_*XsZA$Lw%q%Qer;>MU%3B`~jCvBY^`RF}oq4ib7MsH0Cg`t}eZJp-DChv_UmJ&|H ziY#v}E#r^di{3Ie%;G57Eb8Dfam}D+@u)!L_24ndn2jgA0g4jgq}J6YC7eMXS7?#N z^)|}%+gfuylgUDloOx?o+ijKU`Ne3F-zUKxjyGwM3-#bHYmU6NAA-jdh5jz~Gb{c* zJs0>Q?z^|pg1;X1$(wIP|M>6hspk$+ZOYGV-x3dSyV$I0JYT;Y)-%26%C;607i=6n z31H%4hW-N=8#Il(>z9;gmb4Hsn%|qP4#uf6w4Z8&f_W+HP6uC6@t MrLt4FulKUDFR#H_j}hNw1A^;OU|b%(foyTl^$S zn_WBQz-!>&Ij2=lnLe27NS)rF>&T{oa9fnmc)pDc(^_1sOFHM=2fhs#)^X?VSOl)u zZAZkfd5msUEwzgm@8mN#D3ayYE~!eW1+hiMmv$_vit7ahUy&G18r|qw3Y9?Y{7r6H z^dIGbeX0IP(U5g@GL-wSP8NMb_El?dn^XEm$beBTQ*T{OgW)dqpSe>cMOlT_Jj@z~ z!{LgV&l)a_YS~USnunRpeh|#QzA|R#dygo0u!VR!!sNvVDgk `a8gBp!`6NYa-rJ**EK*$9J)8imEXmC|!$Eq!TzH}WN2Zwmx4?qPQ- zbABcp>W#joFw_}+3yT=xPS;!NRCnJhuyJ(@i;q(avdVB?6x6KP&>h`a`%LTcxHC}F z)uA&GQ8aaX2v$$7QLz9*s@Bi6d&Tq|+0I`TH7fqRvxzC4I-Z(o@9wvl9_z7XHXg4W zbX`+)KEo!aqSt9W!+x+NJ(dnx-q|EpNl%+$Kj)nuONC7AY$|aquyxl7x}zbn-Db1% zboC2NcXy^iQ-ZtpY G9UPQ;++Vg6K3QMp6`G z4T2U0-7eRf3T9fH3EwL*eXVM#v& 0~49?%EzDfiTTv9LVn?Z&-X0-F13#H@a)j zKo}uv6iYD_nbTBsCwH!h{T(uzs%ux8t4q{Wk_#bjRFSQqB~h!%k->=Mrs_g1y(E)# zHLX6ujBs4`G32Ztw;H@!J8n5R@nv-5S0kO<*w|~ua;Fi+h>@4kg5twt3PF`lp(8)7 zXBwk@gvQ1cf_dwei=NUTzv~K!CQ?T;y5HeCUG{L9!gnyQj(JpQBb-N){&_?A$?y?R z-NKuH!ZX(@AExjA%$?`aopqV++U_r19USeM?y``aaheuzd1tb&>+9V!+htT1ZoI); z6mC4O>pQO&a7J`cCxF3{A$Pa-4f8hz`t!zR{w($P=+7Ges#Rt#j1_WzE-bA;&tUww z) 02l;AyLml+Ym+mol#gwc1@w3nGe6q<9 zcN(WiR~UTQX_IlyDMFonzI5rYzUJlnfKUg0>z|fVsWXL=!r}3GE`FmaGkZU5u82Mi zrf9hPdxR>v$99q{d1K?9n1n_^g}6vEHDhF6w@k|1?(ioUn0gRf>RiR&4ma@|cJXXK z`5sImn8k(chRENIpi<^&k-Mtvy5-c{Fo6Q >E6?v14_4L od z=kQ>!G-;_@+WPt4xSMq&-zI04IJ?JcZgTNdkE -Qp%EuY|bACUJ7{%u81; z@mQ3$p`Np`cr6>p7;N({2+tzHU!yCFVZ2*<;sK-*5tR$eo1}>wl6yM{q4~f~&Zb@C zy?$62G6pt!XK{4r_o&b`H~8z0{NAtZaOA7(u{( --jLpV zhuHWbxU3wr)420v=yF|fWf=KllGS+9#<0VZ^3EU8O-9!u>LHXRf_kXIBO8X;-gWhx zca=cJGQLChNqmn$`fggS)(LvN3r5mO{PY;9-waI@5=KETRdGq#b(Lc?J5D7aJLWB{ z?$ai)8h27hlQxj1o3J2Q9qqUAJJ!y7%WjJ$*O!>ZU8MKEJPt=*e>`@_T4S#kv9a a*UfA-Q4etV>9m$KiogI_jTmc-Tz z(S<{=cch%q&s`9MNe6kyW66gDxad|Rx)fFcT9H$+6`|<%5xk4A<6!0jp1=j_+$lZf z&@h7mvC!dkI#}{I^dmn8&FcRhwxW=I2Uk6oaZ8<38@Kia&;hH#&iDm_dZC^OGdT{h zjWYrL6DLogQ8GFTi-YoNiyXcSW_C;)Q1EjL2H%B>Zy{v(>W9@c*&OiLztJ3apsCFL z=LXKgU~K0#fLZl_asFI-q&)@*S|QD^042}D(B2Sijcvaont%C^8v)^GP>K7@-;dcI zz3WB%Fo>&gXh2z|UEUkbVo-hTh259I>Q9S z91FcTvS}U|q7Mt3I~=dY6lY~C;qu%!s^m>g!Vcf>hhUAwj)8by8(^ZME}P>Tw#fuo z^BjM3zj#;(CT$AB+8<%7mG;Cv2dy>mVl-a5Vm12ZXxt_hz?$hS!1B|Rq)SB4?^PX^ z>d~ttbOTuIyeAd5I*MHz{1!#d3jkxNEjaQvI?;_w_o3qM7$A@TF|Fd^8L+AXQG=FY z@&?awJ^lQ4f6c?b6u72<0r_)Wl@b7V$_9Fh;BMOjjrtcV_xgb!7??R)=O!e2N7yD- zby N_XUVcOc{$HR*1Y L%_mG*i9R0+l@e78wAg2e*Dr8Z4+~dG7_smFd%_cskHvfJkqP#*z9I@1nc8@9 zTEw*{=gsEMC5ul_BJ|h%q(kQ2=3V;oK44xq_Hrf^;jj8U{`BBY`$)=-Su4Yf5_^9s zX!V~Pbd${g_@JL|8FaEyaA-$#u6Vk1I;*nBIIvl8$hAbzGC54+w@I)YjqcN2;jC=b zaH@F0n93cuV$hlg%Em-R5Ww1U7Vs|Xswn!^zC50*sGa3`#P*=B1^<=4Q=d6n*u3nz z^{sxeML3VV7PLfce*4lSG8@3nyE|=YsQ=`HcVVxYBlr0$dEXQ1Eb=F9o5k9HvJbLd zeT @><=*KL)*I@M*q zVp_0rvoqQXaXv+pieqr6616*T!nnP0Qhed-g1YUQM=f>6i@Eg|E$8g8Z!~2>Mf=2Y zee~J2-0@-w5?bpqQH=4}JKkmJQFDy^=1N*pP@iqHo2K@|f<58U<-nI=C+VNbZkSCb zNBn*mF+eV{^L}?-;z0vXk@mB%2#NZ~aZV7^EDFz`DHPe7pgJwK@;%qYVPnBp;)21a zAO?qi{->+{idS@Zul84hLnF2FekUnDY(h n;+S73!M$Vk^c#0^U0eI_z?kg2TLglTqCDx$SdX zF~O&F&MTi3GtZaOxbw&`*zJ5h$;f9vvj$1ug1Q~pB{auzbJW)-{+|v1i;jPcz&Xgh z=TnEJFC&_U2H)P{T}7<(+;CZoh9Nd2AC5;}M=jP%>@mCQIZr;UF7Vf~t_zDW*rIY6 zbn1(?YO+MyVc$9DAt|4hn9DDY=ms(!Vu!y 4aIjo7qIm*`zu!_?o*tx1CYG^w}u=Dg`l% z=fiMq`_x!_ebeNyq~ootb+qy1f?-9~Zq(omBps(UE1f4B1yOWjKSpiJW(&K0=qxGi zPhWpSVU$NPrb=g3Zko?j>b?}(;Qh5$Mq+C*q|Ie$dl2xt*L^#-Mx(VTvZ5<#{nvFx zZ~H3+9lnA+_mfCEt~Iz`dlkO77+g8zG@k#nX3J_ySa62M{gKgK8i>2gfbrF&F#0A2 zLCaLTE^U~rE|t;Bb+eB53)hJxT3y8}n?$C44R1F_Ig9%k*W`V0tL%Bkc)QUG1{#oi zTiumD=QRLYdz;N3B!aC)!zmw#t`|27^j%_IC>z=>{6NctX{Yvr27M>5+;+ZP6=VpR zS`y&rgn@MA+cpXBmLmpxiLkYR Ji>nu#&(3p1*G3*z7X+rH-cW<>IY; zc0G^HhVx$@Hyhah9{r5Em%iZYeOCTO&ce__jT<$KOweW}YP)I(wO2$;l_jy>f1S7Z z&rF|H{8l__hvVb=Fu4b-4wb-fv-IKNcVOxA4dil7iQu5)tRyK %~<33q$lT$6=HL&)?W~{UTLLBS+l&A)MSeS%-TcJ1{*pIbbk2q zIL7*?H*K8D`hY|EYM1VGcBRo1!$#}r%p#+WwVmZ=#Gij{ 5PVHTW@z{8)l-G&|(UdL(9iLAtW%)w5T8@O+F4-a2!C|_1Q zGiFl~?D{v!C~Xn7H`M3hA-{1BX^7hDCKKG*8IACu8YCI=`Tcu$eTa%u*RHd(hQBti z!QJMAH_c_5Krn0-#Xr6J%(7>AuFQ(u(2mEx*R%+@qD4QJpxIu3TQSZS@Av5jJsfvG zNj6m1nr$q!mgtG=4Xq=*tMezUJhsg@3R{VMebUDJ7r0Be=R{EpzC*rEKJf~ `g)x9DKhva>0@t}v8_H*Qb__}l0B;J zUXTfhFMS{R_PUR&-`6AfrTL0Q@h6FJ?Xgf`30C&D=gA_wQQ^?cz(jzj6ww3l6ARo@ zjT)CBSFobNbjp9N-*(6=5fv|>{@BVv1yGAiFG9}1n^wNeZ9;0kmq&zeOE)VqtN~VO{65NCTg#End1)~?Vo&I!;qFwj zaqc-W|14PLPV_S>23kw;l@Dz>EL)=H)%Bd!?|7p4Z!unX%v6QFB?dxzmZbfM*n0nX z663Dc6YX=<(uVxb78CtfyZV7OAs7DpJt e77d7ilxsy zdgp=K9;$JZ71E=7?d
SPbbp|Kc}b z`PO=WMftYYPcUvf@2++y1&2)oHKCcKHE JitW{KMGUV5FLB3D0AinJ#(UjtosLqM2c9i@K524;7fPEl6Xr#k8d=Obv_$& zRd;hW+v9xHx&El_r0m4ZDG7&KzgA}Py~SiH?(x`leU#I+D4N@J(%lpB1A%ij{97(b zQ5!NuHD#+iYkSM_Z4#m-RRqZ%Qeqo_+<-gn1%iIFoNkZoTo%e=AwHx3L1-hbfsjKz zL*tH@@vsmkL&(4LM<3;tq#unP8k>LtpS!d7>iWG%)pr+tP>%*tVJY$DsZ&;xpPo{t z+zZ=|iWbfyHy>P%6MhQ3+>GJgQu0+#Ez6S8ny5M&-5DuH9h Llid{nKhCY17p;65sc< C|rZ4a2Ovn1ZZZZjjKu<`{G?sr|cJk~TGew}yM+-mQSFm!*?^KmH$rSN>trh&&$ zOkLalw<2%x{mFRLRHZn-V)fl;Ycs!rE=7CnIgn{55=?gl(pcrUvP0V$IGakJqXj?6 zJ7Dyd-{x;&XIyLEGlrd(oP;LZ@#yRo!IsV)GPgTCt8duCC%&QV|LS?T49l#}d!R(` zX8VMresn2m`qj~TcqowwR_ 4t8>4^St70N?Inkk6Z2i?jCzzk5bbHQ* z&eVx1WsN_BcUxwnV$gX5cxM2Bzg L4jzKo*)p^*<;f@n@Pj|e?U722; zdeju7UGZnV5;YLNx8lndp=Sn!P}_M@@k;qZwNV0v4-p8xs?(HBy7X*kpDZ@OP$GBL zZAx|~TKg(cyC~W&*BO&Lz=L gh^nI4X1d|-wNsaBV9c&Fj4$Xf&~!Ul_OM>r>qza|s^tjR2Nut!q+gyp z^V*|d#nLFpPdRc_eBDC^S`_rvP0^O6P7A~mpUK@ptZw8RZ_fEF$m68ODO3cf)ZV{f zpo~;D7|)9rdU5xB|NhHL35^6mF#5Z6K}f$~a{A^%j$QWv)6Cw+NU*n;TCpjoWtqiK zAY$Kq#q ?}!*$9s4^83k#JQ$2%fO|8-IhY}^t;wNA7 zi_YZO3T654B#}`)cl-P1q*S5NsplKR$rAFDAV>KXfeJ}kxOz*>Iq*u}lXKS)Am~v| z>A&DiJ4j-^J*)btF{)s#ciMYWWkZYV1tVae?HtTQnB|oy@a^jsMFXd0=&fh|ImsaY zwC8)v^uo=V7H>ays~0 p)P(wx+YsPgspPgWtNS{&k6-nx^@^@^;Y^?{TAeAkQ~hm&YYglM*1-oB3_k z6tfu&8R;LPR!)$?`G>l4Z#BD`3v%vzAP7SMFK2Yop@yv6M=Z%o)s?JVHTB*O09+h% z*lmbOA1nvf)On@nYLe5$hm(6NsS+CYM6aW-Jv8pQ{;RP1W%|<1((^!VA7zdE@Pjb- zG>^;Hq#<=+UCSpBpv{8Zv1IYvbhXJMbS4V&bHE4BMLv#m z-W-j%2_o}dMK0<`uNgg-Kz1{P0x!G`R}Lyh3v4C^Hi?bAQUyNY7YMP*ZIh>t^RI*S zuRX^?YbV=dH+?L9!h~~Yv7WJPEQ-5Hczor0^Uc||JFqAr>uR9ZAd2>Yk|uJG4YzZC zF>Y%cAn!Jr>X5T4Uz}f%?-BmRm3Z8=0 nh~9t}>po z^5#=m)g9go_SkXjx&Hi_#%6FEx#DM&1*w{!Uz^EDC13LWj&&HcANC%9Ifq(FrM B`Vn*4WJ+9*Sm8ULc+MzqYPDEUIdYGsB=f)C(da88zw<26`i}nu7KnGrORINH7S- zCn_ciS|Sf0Su hV z-hcRJ*mKTad+oLM+H38-e(Pbv!{E=Nr!UBd%dq9)L7w0n2;0!=T{_PrEmGQ{kMSs$ zaaZ0#Aa&`3p%kSeaL8AGI;0O6$;hG~ +Ic@URm?HVprof3BhD7IYvvt!9bRUf zy?OMT_dC|iKKbVUoA$4ACs$8aiAbS4`TZ-lQ0G8KmSY(T9j%C&?mT%s#CW@xLq*k= z hpRUo#%aK;hCcM97Bx=^9Hwjr4zWsIk=|-^DDXe7XxQ$K|_@*;A_*tK2j# z0q#JPZ|?iJbe&=-Qt7820DRD8%Bq5-i=DDhC_H-2zhoy6vOSM _2!#+K|}JP!OE zyeXbvbEgM3dG8G-%8p8C>k{oSax$BZY93}e^0b;ZY(B`?E9IFsYMD~zBcLT<{^16X zv}mbHBOfEh6@1syv|o26CPnB1==c$$yEl+&P>?dgqQA*}+&>n ~v5RQL z6X~06o7mUt^XTxku^oiXz}UIUIJf_~yIyTP7N9(#OJKo0?G}MHHG##R>0YA3i^@I8 z2`njj7qdB3xIzKD3|@!C?u^xgp3s8uG#_zpz)F@V(YoRE%YOW(Er{lj;btp{E}Q#) znmi(VyL*WW66Q=nTU%i{OQa~DR=rvv)Y~0xhB4le`)!@DHl+rL)s>bp0(Kl@7NYwl zVaM>)v-4Ls3j8xW1{nw#2%!9kWG^@ns<01nTMaP0olZp5><=}fPCpg1KM ;%E*$d zG86^Z13Db<< zQ9T_3 tMo_Ms9T9Wmb;mk!m)mP>y9dW-3^=(!!E(Zu>jL=Qq*H zUc9>s@T+_`#MROqX2bYg!lK?7G+Wk3t}R4oQYo&i18G#t_yJY>20M{%NJyhad*6%F zRt9O5DNS~7D=9^3bVe{&q?W;#eED!B(w3ZOlbD<>@N 7e!?QlIgqGiv zEXkQuQR=OEB(TRQvbv-n*y)uso2^;)L0%;sGzu#hon3W*JBi@ON4VGMvVoGY)u@d- z*pxi@l7 c{ &_ z?c=8Ki0Xo|?`Fx=slA%QLsRpNfe@C~u)S@fILCfq8%941!_oe!>fwjg>4{ut%T$ct zS~45uWwo+NVdvp|qNMxSgIqrC8{ngzhpTNM&l;WmH^t$(qJM9zuolWYPMH+qA>`2V1@11S{W76K<0km! z?Qd8NwH}5!+&wuWUw9(fu$l2qqLj{G1}5>UKmgJGhD-SlG91fR`Z41t7;oxv1nlY8 z|BT2Q;9wb$Oreyn?LDx7 f-gq%^01eixB|!>&gn7R4jw%E=Auw1I*9S5q=IXIX&f%9wfrLIl#6{QqW>Rt! z6^$lZ9dp5#tfeV@yqtd8EA9YWqS`hd5~Z--%Rtt`*%fW0r95@s0ddU{!vVi 5U0b 09|t6xedyG{w*Q*RKT zAU!(iW|5q90&i{CfKh026l~g$k>6LFdEJlmqeg`aw_BhrL1h_PvdOOM_4;sCh{cfD zK#xx7>y5}`Pxz{+=yp%sxzT2cC nEr2Hz25l RD5`e5Ct<+_AgA8cjF_AF7cOL(mh zrmUO%_KHjkp!-xEf02Gq@`+`Rug0B7sy9|uwO@n2k=GGQik^uSOTQBpk!l|_v&a1$ zl#O|gQY`0B7N7-X+f8qlittXq_Y`O)3}~*Z&A8ZOuqKD^=z%%VnQn+cz8!7dHkjYd z_A2R2PI|Q21Eowt+BH#@C6ukbeSnOdAw4!t8y5ID$4C(zDI6A{;cQ}pY8n;mO$^V4 zu9s!3SWeuxNq5}hwUy4f32kkS<+Rs67n~X_$P6?bo6_s^+~11YV%xx;m3hYIWT<<$ z=c~t$eHT-y=(zHMQeP35#>#qVOoQOXm;;RaNZ9Okw6fNnsv~V+v;A!oySRx4& zo-|69O3i}PbL}2|darPM$Hm1XlWGd4Zr!sz1nyOW;igU`rBaChjHcD?mMuMXqX8q} zUQq;PYD1kmQ!)t;+(z}2oIS7%g*yfbZRR>-7V`tkF`%tgM_T!S8V98EwZkmB yDO>|6Jvu>2k1n02^$5 zcZ^~FzzBX551WnGIG;^d`s2o$zj+$*3-IMX3aAXy29lo(DF=MgU#w2n^UeEZymR>Q zW7^hA?wHD3oLPpppFfEZP#A#iBG>ME47LDy&8V`7@_^X{90?8a?tgYFJ4y_S;=4-@o_-zZc zD%2jmMy)=EvVR*DbCaEjZMf!*_csV2f`T`G`6;t5YQnwopCsd_I^o2;m-(kJw)y?x z86 2m8Z2j17x-kKf0k!f6 z(_y5Cv#^3#`GaQNDZn}NY9FK@_CcN{LbVqFSs<({-Ssqp1A-l=#V?HvVMgFHP1hf} z`3V0i9{!bB?1L?rz@%u#LJQ;vt=I=6Q!U&j6#HPy7q{c28FI0Yx0*0><_Kempw1}v z0cUmIrlTI&)2dgfV$D7{{n6H(koW&WixpH_ EG zY{p3@;-Iiag)fCD+N`VFwS>@k{&=E>$nWF@nvzNLR-8P6GDj?+&iZ4VLB!d9gM9Is z`nWSIQ8u)5p${5Z{UO_P5I %*={%Z_Kvr;Tb+I3id(Phzy?U5`WoxZ^;C{-^|$8)tXzX}mFJX6#EgX) z{Dw6Jv(@QQOgYBl2*-1c2ja)bGnQizqWbx3AT1j!`(fMEU~%>q)(QCQ)b@#a-gh2` zrP}6AruCZt`lZ-1E_`kuj|(#HAnH!_KH}g*72W9)%6%vjeWh@hy#xE#uMa*qgiD1` z@58 BYJsD0RF1p@5aP8}7omyZGLcUB*6uC(C&K$&38C!hYrn%I_r6C6{IzF zVTk!P;l(6XvP)i3`Ppy6Qb!zR@dyQLOHe&Dbhy_ncd>s1&dl1@ b#Q$y=0 zPUc!Vu{`NRv~{lA1yB@&^+JT@D~o%L&fem;SDn&Cgm6mhPsuN()k9{&L{sq?=SaNu z$^~8VP E 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")):