Skip to content

refactor: one file per guarantee under laws/ and proofs/ - #86

Merged
ngngardner merged 2 commits into
mainfrom
refactor/split-laws
Nov 1, 2026
Merged

ngngardner merged 2 commits into
mainfrom
refactor/split-laws

Conversation

@ngngardner

Copy link
Copy Markdown
Contributor

Summary

  • One file per guarantee. Each guarantee is laws/<Name>.bend (its prose, then its quantified laws), proved by proofs/<Name>.bend. LAWS.bend and PROOF.bend only import them. That's 22 law files, 6 shared definition files and 16 lemma files, replacing the 3.4k-line LAWS.bend, the 6.4k-line PROOF.bend and the fifteen proof/wp*.bend lemma modules.
  • proof/ folded in. Its lemmas are placed by the files that use them, like any other proof helper. 14 identical copies of a lemma across modules are kept once; where two modules gave different lemmas the same name (42 names), the later one takes its module's topic as a prefix (ras.add_zero, huf.fl).
  • No requirement IDs.
    • SPEC.md's definitions (well formed, sample) and the section scopes now head LAWS.bend.
    • png_walk_anc, which two rows cited, is its own guarantee: laws/PngAncillaryChunksIgnored.bend.
    • The table itself is kept as docs/SPEC.md, since the RFCs cite its IDs.
  • Trust boundary.
    • Dropped: the checker's soundness and the gate runner, which hold for every Bend project.
    • Other encoders' DEFLATE streams are now trusted in a comment on src/inflate.bend's header, other encoders' JPEGs on src/jpeg.bend's header, the T.871 conversion on Jpeg.rgb, and the JPEG round trip's within-8 bound on encode_jpeg in main.bend.
  • Helpers: 8 proof helpers that no proof reached are gone.
  • bolt.bend drops def trace().

Depends on

Emerging-Patterns/bolt#257. The pinned bolt reads law files by name only and still runs trace. This PR stays a draft until that release lands and the pin is bumped here.

Test plan

  • bend PROOF.bend → ALL PROOFS CHECK (about 50 s, same as main)
  • Lint with bolt from #257: 0 errors, 3 warnings (the L001 coverage warnings on main.bend, which main also shows). Main has 1 error under that bolt, the C011 for def trace().
  • Bump the bolt pin after the release, then nix flake check

🤖 Generated with Claude Code

ngngardner and others added 2 commits October 31, 2026 23:32
SPEC.md, a 3.4k-line LAWS.bend, a 6.4k-line PROOF.bend and fifteen lemma
modules under proof/ (28k lines, importing LAWS.bend back) had to be read
side by side, matched up by ID tags. Each guarantee is now laws/<Name>.bend,
its prose on top and its quantified laws under it, proved by
proofs/<Name>.bend. LAWS.bend and PROOF.bend only import them.

The proof/ modules are folded in: their lemmas are placed like any other
proof helper, by the files that use them. Definitions the laws share are
under laws/defs/, lemmas several proofs use under proofs/lemmas/, each named
for what it holds. Copies of one lemma in several modules are kept once;
where two modules gave different lemmas one name, the later gets its
module's topic as a prefix (ras.add_zero, huf.fl). 8 proof helpers no proof
reached are gone.

Requirement IDs are gone: a file's name is its guarantee's. SPEC.md's
definitions (well formed, sample) and section scopes head LAWS.bend, and
the table itself is kept as docs/SPEC.md, which the RFCs' IDs point into.

Of the trust boundary, the checker's soundness and the gate runner hold for
every Bend project and are dropped. Reading other encoders' DEFLATE streams
is trusted on src/inflate.bend, reading other encoders' JPEGs on
src/jpeg.bend's header, the T.871 colour conversion on Jpeg.rgb, and the
JPEG round trip's error bound on encode_jpeg in main.bend.

This needs a bolt that reads law and proof files by what LAWS.bend and
PROOF.bend import, and no longer runs `trace`; bolt.bend drops `trace`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
bolt v1.22.0 reads law and proof files by what LAWS.bend and PROOF.bend
import, which this layout needs. Rules changed since the old pin, so some
noqa comments no longer silence anything (S005); they are removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ngngardner
ngngardner marked this pull request as ready for review November 1, 2026 03:39
@ngngardner
ngngardner enabled auto-merge (squash) November 1, 2026 03:39
@ngngardner
ngngardner merged commit cd9ea41 into main Nov 1, 2026
4 checks passed
@ngngardner
ngngardner deleted the refactor/split-laws branch November 1, 2026 03:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant