design: rewrite the step/macro spec against the real grammar #29

New issue

Closed

opened 2026-07-02 14:03:39 +00:00 by toph · 0 comments

toph commented

2026-07-02 14:03:39 +00:00

Owner

The approved step/macro design spec doesn't hold together; the slice stays on hold until it's revised. Findings from review:

$name has three incompatible meanings: display label (evaluated immediately, scope discarded), stored macro (deferred), retained namespace (needed by post-hoc export { --pq } $thirds — supported by nothing). As planned, that export either fails "undefined step" or re-runs the body, physically double-folding the paper.
Parameterized steps claim a closed scope, but corners .a–.d live in the root scope — the design's own flagship example (@map .p onto --(.a .c)) is undefined under its own rule. Two plan tests contradict each other; ideas.md says "dynamic scoping" — a third story.
A parameter list silently switches the evaluation model (run now + full visibility vs. run later + none) — a refactoring trap baked into the surface.
Spec examples don't parse: @axiom3 .e1 .e2 (no such verb), moving --e (moving takes points only), .(.p1 .p2) (wrong sigil), bare export { --pq } (not in the grammar).
step fuses scoping with diagram grouping; inline vs export-all differ only in display, proving the axes are independent.
No qualified access: repeating a step ("petal fold each corner" — the core origami composition pattern) collides on every exported name, and FOLD provenance emits indistinguishable entries from different scopes.

Decisions already made for the rewrite:

One evaluation model: step bodies see a fixed prelude scope (corners, paper edges); a parameter list changes arity only; invocation is always explicit via apply.
Evaluated steps become retained namespace values; export reads from them and never re-runs; apply is the only re-execution form. Qualified access ($b1 = apply …; $b1.tip) falls out and gives FOLD collision-free names.
Scope and diagram grouping become orthogonal: one construct for names, an annotation for panels.
Identifiers use _, not - — kebab-case forecloses numeric/arithmetic syntax (repeat n, ratios in ideas.md) and makes whitespace load-bearing next to the -- sigil.
Uniform no-silent-rebinding per #24.

Every example in the revised spec must be run through the parser before approval.

The approved step/macro design spec doesn't hold together; the slice stays on hold until it's revised. Findings from review: - `$name` has three incompatible meanings: display label (evaluated immediately, scope discarded), stored macro (deferred), retained namespace (needed by post-hoc `export { --pq } $thirds` — supported by nothing). As planned, that export either fails "undefined step" or *re-runs the body*, physically double-folding the paper. - Parameterized steps claim a closed scope, but corners `.a`–`.d` live in the root scope — the design's own flagship example (`@map .p onto --(.a .c)`) is undefined under its own rule. Two plan tests contradict each other; ideas.md says "dynamic scoping" — a third story. - A parameter list silently switches the evaluation model (run now + full visibility vs. run later + none) — a refactoring trap baked into the surface. - Spec examples don't parse: `@axiom3 .e1 .e2` (no such verb), `moving --e` (`moving` takes points only), `.(.p1 .p2)` (wrong sigil), bare `export { --pq }` (not in the grammar). - `step` fuses scoping with diagram grouping; `inline` vs export-all differ *only* in display, proving the axes are independent. - No qualified access: repeating a step ("petal fold each corner" — the core origami composition pattern) collides on every exported name, and FOLD provenance emits indistinguishable entries from different scopes. Decisions already made for the rewrite: - One evaluation model: step bodies see a fixed prelude scope (corners, paper edges); a parameter list changes arity only; invocation is always explicit via `apply`. - Evaluated steps become retained namespace values; `export` reads from them and never re-runs; `apply` is the only re-execution form. Qualified access (`$b1 = apply …; $b1.tip`) falls out and gives FOLD collision-free names. - Scope and diagram grouping become orthogonal: one construct for names, an annotation for panels. - Identifiers use `_`, not `-` — kebab-case forecloses numeric/arithmetic syntax (`repeat n`, ratios in ideas.md) and makes whitespace load-bearing next to the `--` sigil. - Uniform no-silent-rebinding per #24. Every example in the revised spec must be run through the parser before approval.

toph referenced this issue from a commit

2026-07-02 22:08:15 +00:00

docs(spec): rewrite step/macro design per #29 — def/apply/export/step split

toph referenced this issue from a pull request that will close it,

2026-07-03 00:29:15 +00:00

feat: def/apply/export/step — reusable folding sequences, instances, panels #35

toph closed this issue

2026-07-03 00:39:23 +00:00