From 7570e03ac0187f92641ed03e653c70fccfac32f4 Mon Sep 17 00:00:00 2001 From: Evan Date: Sun, 16 Aug 2026 16:20:48 -0700 Subject: [PATCH 1/2] docs: expand unit 6b to includes, computed constants, and inline functions A two-corpus census (tibetswap b82e921, chia-gaming cdab9c9) found source-level import of shared definitions in every production puzzle file, tibetswap defining 124 of 136 functions inline, chia-gaming using computed compile-time constants 36 times, and let effectively absent at two uses, both in test files. The census also corrected the deferral's premise: chia-gaming's source imports are universal (about 200 import and include statements across 19 puzzle files), and its compiled-sibling hash plumbing lives in its build layer, not the language. Unit 6b is therefore resequenced ahead of unit 7 so the benchmark puzzles share their tree-hash helpers instead of pasting them four times, and unit 7's style constraint is widened to admit the new surfaces. assign stays held on unit 7 evidence with a pre-registered trigger, and the compiled-sibling import stays deferred. Decision by Evan, 2026-08-16, skeleton change under ground rule 6. --- docs/execution-plan.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/execution-plan.md b/docs/execution-plan.md index 85903e4..a3fb80e 100644 --- a/docs/execution-plan.md +++ b/docs/execution-plan.md @@ -80,9 +80,9 @@ descriptions, and commit messages* - [x] **Unit 4: language core.** Landed 2026-08-15 (PR 50) as the compiler, `bitlisp-compile`, and the REPL language surface, the language stated in `docs/lang/language.md`. Decisions by Evan, 2026-08-15: the module form is named `program`; `if` and `list` ship as compiler special forms; the symbol table keys on compiled-body tree hashes (refining this bullet's earlier "bytecode positions" wording); the REPL accepts source forms at the prompt under the raw-first rule, raw VM text never changing meaning. Constants inline with no optimizer, the function tree orders by declaration, one namespace covers declarations, bindings, condition constants, and reserved words. Compiled representatives pinned in `vectors/vm/compiled-programs.json`. - [x] **Unit 5: currying and program identity.** Added 2026-08-15 (decision by Evan, skeleton change under ground rule 6) and landed 2026-08-16 (PR 51): `curry` and `uncurry` as library, one-shot (`bitlisp-curry`, `bitlisp-uncurry`), and REPL surfaces, plus the tree-hash flag, the surfaces stated in `docs/lang/curry.md`. Decisions by Evan, 2026-08-15 and 2026-08-16: the standalone commands ship beside the REPL commands, the flag covers all three converters including `bitlisp-compile`, the identity story gets its own doc, and the surfaces are named `treehash` and `-T` rather than the `opc -H` spelling. The curried shape matches Chialisp tooling byte for byte, and uncurry is deliberately stricter than Chia's deployed uncurry, a divergence stated in the doc and pinned by a test. Discrete from unit 4 (no call-semantics contact) and from macros (operates on programs, not source). The unit 7 puzzles consume all three. The Phase 4 commitment-hash deferral stands. - [x] **Unit 6: macros.** Landed 2026-08-16 (PR 52) as `defmacro` with `qq` and `unquote`, classic Chialisp semantics stated in `docs/lang/macros.md`. Decisions by Evan, 2026-08-16: macros only, includes split to their own unit below (skeleton change under ground rule 6). `if` and `list` stay compiler forms, so macros cannot shadow built-ins. Expansion is depth-capped and cost-budgeted, a recorded deviation from Chialisp's unbounded expansion. No `function` or `com` reflection form, the laziness expressiveness gap recorded in the language doc. No refactor rode along, the shared emission-primitives cleanup stays a candidate for a standalone PR. Expansion runs as a source pre-pass before reachability, macro bodies compile at declaration against earlier macros only, and read-back diverges from clvm_tools by one hop only (decision by Evan, 2026-08-16, steelmanned both ways, then narrowed twice as four review rounds showed every wider evidence scheme unsound on post-reader bytes): names the caller writes in a call's own arguments error when unresolved, REPL def spellings are barred resolution-side, and capture plus stale template spellings stay as Chialisp has them, documented sharp edges. The three new reserved words are a deliberate source and symbol-file compatibility break for earlier programs that used them as names, pinned by a loader test. Compiled representatives pinned in `vectors/vm/macro-programs.json`. Kept after the 2026-08-16 public-record review (decision by Evan): the fixed special forms and capped expansion avoid the macro-built-language failure mode on that record, and re-evaluation stays open at unit 7. Reversed by unit 6c the same day. -- [ ] **Unit 6b: includes.** Split from unit 6 (decision by Evan, 2026-08-16): an include mechanism needs its own recorded decision against the self-containment rule, a program compiling identically pasted into the REPL. Deferred behind unit 7 evidence (decision by Evan, 2026-08-16): the usage surveys behind unit 6c showed real include demand but reframed the design target, since chia-gaming abandoned textual include for importing a compiled sibling program plus its tree hash as a compile-time constant, the mechanism that keeps a multi-puzzle system's interlocking hashes consistent. `bitlisp-compile -T` covers that need manually in v0, and the puzzles decide whether duplication or hash plumbing justifies the mechanism. +- [ ] **Unit 6b: includes and the compile-time forms.** Split from unit 6 (decision by Evan, 2026-08-16): an include mechanism needs its own recorded decision against the self-containment rule, a program compiling identically pasted into the REPL. Scope expanded and resequenced ahead of unit 7 (decision by Evan, 2026-08-16, on a two-corpus census of tibetswap and chia-gaming): source-level include of shared constants and functions, computed compile-time constants, and inline functions. Every production puzzle file in both corpora imports shared definitions, and tibetswap defines nine of every ten functions inline. The census corrected the earlier deferral's premise: chia-gaming never abandoned source-level import, its compiled-sibling hash plumbing lives in its build layer outside the language, and that import stays deferred with `bitlisp-compile -T` covering the need manually in v0. `let` stays out, two uses across both corpora, both in tests. `assign` stays held on unit 7 evidence with a pre-registered trigger: benchmark-puzzle helpers that exist only to name intermediate values. - [x] **Unit 6c: the macro reversal.** Landed 2026-08-16 as the removal of `defmacro`, `qq`, and `unquote` and the addition of `assert`, `and`, and `or` as fixed compiler forms with classic utility_macros semantics, reversing unit 6 (decision by Evan, 2026-08-16, both sides steelmanned under ground rule 3). The evidence: three usage surveys (Chia's canonical 91-puzzle corpus, the corpora vendored in references/, and chia-gaming) found no novel macro in any deployed puzzle, short-circuit assert, and, and or the entire production vocabulary, and chia-gaming's production referee choosing built-in destructuring over the structural macro sitting unbuilt beside it. The reserved-word set change breaks compatibility in both directions, pinned by the loader test. Compiled representatives joined `vectors/vm/compiled-programs.json`, and `macro-programs.json` left with the feature. -- [ ] **Unit 7: the four benchmark puzzles, written in the language, as the acceptance artifact:** payment pool, async offer, vault, singleton wrapper. This phase makes them exist and run, Phase 4 measures them. One PR per puzzle where size warrants. Style constraint (decision by Evan, 2026-08-16, simplified by unit 6c): the puzzles are plain functions and the fixed forms, there being no macro system, and the authoring experience feeds the typed v1 gate's ledger note on whether unit 6c's cut ever binds. +- [ ] **Unit 7: the four benchmark puzzles, written in the language, as the acceptance artifact:** payment pool, async offer, vault, singleton wrapper. This phase makes them exist and run, Phase 4 measures them. One PR per puzzle where size warrants. Style constraint (decision by Evan, 2026-08-16, simplified by unit 6c, widened by unit 6b's resequencing): the puzzles are plain functions, the fixed forms, and the unit 6b surfaces, there being no macro system, and the authoring experience feeds the typed v1 gate's ledger note on whether unit 6c's cut ever binds. **Standing constraints:** From ed6be574dd4e8ccca26a574e705190e363b7e4b2 Mon Sep 17 00:00:00 2001 From: Evan Date: Sun, 16 Aug 2026 16:20:48 -0700 Subject: [PATCH 2/2] tools: fetch the surveyed puzzle corpora in fetch-references chia-gaming and tibetswap back the unit 6b census, and the script now clones them so the survey is reproducible from a fresh checkout. --- tools/fetch-references.sh | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tools/fetch-references.sh b/tools/fetch-references.sh index 7002c22..150e378 100755 --- a/tools/fetch-references.sh +++ b/tools/fetch-references.sh @@ -24,5 +24,9 @@ clone https://github.com/ajtowns/bllsh.git bllsh clone https://github.com/Chia-Network/clvm_tools.git clvm_tools clone https://github.com/Chia-Network/clvm_tools_rs.git clvm_tools_rs +# Deployed-puzzle corpora, surveyed for language-design decisions. +clone https://github.com/Chia-Network/chia-gaming.git chia-gaming +clone https://github.com/yakuhito/tibet.git tibet + echo echo "Done. These checkouts are git-ignored and are not a build input."