docs: %raw concrete examples + codegen environment spec (#54, #89) - #94
Merged
hyperpolymath merged 1 commit intoMay 11, 2026
Merged
Conversation
#54 — Human Programming Guide gains a "What \`%raw\` becomes in practice" subsection under the existing Anti-pattern 2 decision tree, with three case studies from the idaptik Wave 3 pilot (Main.res → migration/main/): - \`%raw("console.log(...)")\` → typed \`Console.log\` via \`@affinescript/dom\` - DOM injection via \`%raw("document.getElementById...innerHTML=...")\` → typed binding; missing \`setTextContent\` helper was added to the binding package rather than inlined (decision-tree step 2) - \`%raw("try {...} catch (e) { e.message + ... }")\` → structured \`Result[E, T]\` with E as a sum naming each failure mode All three translated without \`Unsafe.embed\` — the 80/20 outcome of step 1 (use the typed binding) holds in practice. #89 — New docs/specs/codegen-environment.adoc covers how top-level declarations are threaded through the codegen environment: - TopFn: append to ctx.funcs, register positive index in func_indices - TopConst: append to ctx.globals (WASM global, I32, immutable), register NEGATIVE index -(global_idx + 1) in the SAME func_indices table - ExprVar lookup dispatches on the sign — non-negative emits Call, negative decodes global_idx = -i - 1 and emits GlobalGet - Forward-reference limitation: source order matters; consts must precede fns that reference them - Cross-module: WASM/WasmGC use Codegen.gen_imports; other 22 codegens use Module_loader.flatten_imports. Imported TopConsts are NOT cross-module threaded (known gap; only TopFn flows across module boundaries today) - Per-target table for non-WASM TopConst handling (js/rust/ocaml documented; other backends should raise CodegenError UnsupportedFeature if unimplemented per loud-fail policy) References #73 as the known impl bug (Codegen.UnboundVariable for top-level const bindings — typecheck OK, compile fails) without claiming the bug is fixed. Closes#54, closes#89. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyperpolymath added a commit
that referenced
this pull request
May 11, 2026
…adoc PR #94 contributes docs/specs/codegen-environment.adoc as the canonical .adoc spec for the codegen module environment. This commit removes the duplicate inline §8.1/§8.2 in SPEC.md and replaces the section body with a 2–3 sentence pointer to the canonical file, keeping the §8 heading as an anchor so existing cross-references still resolve. §2.9 (const_decl EBNF) and §2.10 (extern_*_decl EBNF) are retained — they are grammar productions and belong in SPEC.md. Refs #89 — companion to PR #94 (canonical doc) and PR #92 (extern impl). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
hyperpolymath
deleted the
docs/raw-decision-tree-examples-and-codegen-env-spec
branch
May 11, 2026 02:40
hyperpolymath added a commit
that referenced
this pull request
May 11, 2026
…ude/CLAUDE.md Estate-wide governance rules for the Hypatia review bot and the gitbot-fleet auto-merge bot. Kept in a standalone section so the bots can read it cold without parsing the rest of CLAUDE.md. Four rules: - DOC-FORMAT: docs/ uses .adoc; .md only for community-health filenames. - DOC-DEDUP: block two open PRs from closing the same issue. - STACK-SIGNAL: docs PRs that document an unmerged feature must declare "Depends on: #NNN" and not auto-merge until the dep merges. - ISSUE-CLOSURE: bots never close issues directly; only via PR merge keywords or explicit human agreement. These rules are derived from the recurring failure modes seen in the PR #91 / #92 / #93 / #94 batch (duplicate codegen-env doc PRs both closing #89; affex-spec.md instead of .adoc; missing "Depends on: #92" on the docs PR for extern grammar). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
3 tasks
hyperpolymath
commented
May 11, 2026
OwnerAuthor
Acknowledged as the canonical .adoc home for #89Posting for the audit trail — no code changes requested here.
|
3 tasks
hyperpolymath added a commit
that referenced
this pull request
May 12, 2026
…realisation (#106) * docs: thin SPEC.adoc §8 to forward-reference codegen-environment.adoc PR #94 landed the full codegen environment reference as docs/specs/codegen-environment.adoc. §8 in SPEC.adoc is now redundant; replace its body with a one-paragraph forward-reference to avoid maintaining two copies. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: promote SPEC §8 to real spec; expand codegen-environment to full realisation Reverses direction from the prior commit on this branch (which thinned §8 to a one-paragraph forward-reference). SPEC.adoc §8 — "Top-Level Binding Environment" - Renamed from "Codegen Module Environment" (which was wrong layer — it described implementation, not language). - Now a proper, target-agnostic specification: - 8.1 Top-Level Kinds — table of all eight constructors of `top_level`, what each binds, whether it has a runtime artefact. - 8.2 Declaration Order and Visibility — source-order processing, no forward references, recommended ordering. - 8.3 Identifier Resolution — local → variant tag → top-level lookup order with positional rules. - 8.4 Cross-Module Bindings — fn/extern fn flow, const restriction documented as known gap. - 8.5 Conformance Criteria — six MUST clauses (C1–C6) that any code generator has to satisfy. - Voice matches §1–§7 (judgement-form clauses, target-agnostic). codegen-environment.adoc — full WebAssembly realisation reference - Reframed as "WebAssembly Realisation of SPEC §8". - Added `ctx` record reproduction with field-by-field semantics. - Promoted `func_indices` encoding to its own §3 with a decode table. - §4 walks every `gen_decl` arm (TopFn, FnExtern legacy, TopExternFn, TopConst, TopType, TopExternType, TopEffect/Trait/Impl) in implementation order, naming concrete steps and side-effects. - §5 documents `gen_imports` end-to-end (load, find, intern, import, register) plus glob expansion. - §6 documents the actual ExprVar/ExprApp resolution paths. - §7 cross-walks the SPEC §8.5 criteria C1–C6 against codegen.ml sites. - §8 per-target matrix covers js/rust/ocaml/codegen_gc/codegen_node plus the loud-fail policy for the remaining backends. - §9 worked example traces a const-then-fn program through codegen. - §10 records #73 as CLOSED, since the negative-sentinel ExprVar arm at lib/codegen.ml:442–445 resolves it. Net effect: SPEC.adoc gains a real §8 instead of a placeholder pointer; codegen-environment.adoc becomes a usable implementation manual for contributors landing new back-ends. --------- Co-authored-by: Claude <noreply@anthropic.com>
2 tasks
hyperpolymath added a commit
that referenced
this pull request
May 14, 2026
PR #94 landed the full codegen environment reference as docs/specs/codegen-environment.adoc. §8 in SPEC.adoc is now redundant; replace its body with a one-paragraph forward-reference to avoid maintaining two copies. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
hyperpolymath added a commit
that referenced
this pull request
May 14, 2026
…#110) * docs: thin SPEC.adoc §8 to forward-reference codegen-environment.adoc PR #94 landed the full codegen environment reference as docs/specs/codegen-environment.adoc. §8 in SPEC.adoc is now redundant; replace its body with a one-paragraph forward-reference to avoid maintaining two copies. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: thin SPEC.adoc §8 to forward-reference codegen-environment.adoc PR #94 landed the full codegen environment reference as docs/specs/codegen-environment.adoc. §8 in SPEC.adoc is now redundant; replace its body with a one-paragraph forward-reference to avoid maintaining two copies. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
%rawbecomes in practice" subsection under the existing Anti-pattern 2 decision tree, with three case studies from the idaptik Wave 3 pilot (Main.res→migration/main/): typedConsole.log, typed DOM binding (with the "add missing helper to binding package" decision-tree step 2 demonstrated), and structuredResult[E, T]. All three translated withoutUnsafe.embed.docs/specs/codegen-environment.adocclarifies how top-levelfnandconstdeclarations are threaded through the codegen environment. Key concept: the WASM target stores both fn names and const names in the samefunc_indicestable, using a sign sentinel — positive =funcsindex, negative =-(global_idx + 1)decoded back to aglobalsindex. Also covers the forward-reference limitation (source order matters), cross-module threading (gen_imports for WASM/WasmGC; flatten_imports for the other 22 codegens), and flags that importedTopConsts are not cross-module-threaded today.References #73 (the known implementation bug) without claiming it's fixed.
Closes
Test plan
docs/guides/frontier-programming-practices/Human_Programming_Guide.adocand confirm the new table renders cleanlydocs/specs/codegen-environment.adocand confirm anchors + toc work