Documentation: Clarify codegen environment rules for top-level const and function bindings #89

Activity

1. hyperpolymath

   added

   bugSomething is broken or behaves incorrectlySomething is broken or behaves incorrectly

   on May 10, 2026
2. hyperpolymath

   added 4 commits that reference this issue on May 11, 2026

   docs: tighten SPEC.md codegen-environment section, drop unmerged exte…

   ...

   fbbc569

   docs(spec): thin SPEC.md §8 to forward-reference codegen-environment.…

   ...

   28af966

   docs: clarify codegen environment rules for top-level const and fn bi…

   ...

   3089d71

   docs: tighten SPEC.md codegen-environment section, drop unmerged exte…

   ...

   b29a1dd
3. hyperpolymath

   closed this as completedin #91on May 11, 2026
4. hyperpolymath

   added a commit that references this issue on May 11, 2026

   docs: clarify codegen environment rules for top-level const and fn bi…

   ...

   This issue will close once commit c392e49 is merged into the 'main' branch.

   c392e49
5. hyperpolymath commented on May 11, 2026

   

   hyperpolymath

   on May 11, 2026

   OwnerAuthor

   More actions

   Resolved by PR #91 (merged as c392e49).

   The SPEC.md changes:

   • Section 2.1 (Program Structure): top_level production now lists const_decl, extern_fn_decl, and extern_type_decl alongside fn_decl so the grammar matches what the parser actually accepts after PR feat: typed-wasm xmod + Node backend + extern + VS Code (#35, #42) #90 landed extern support.
   • Section 2.9 (Constant Declarations): new EBNF and prose noting that const initializers must reduce to Wasm constant expressions, with a forward-reference to section 8 for the codegen environment encoding.
   • Section 2.10 (Extern Declarations): new EBNF for extern fn / extern type, with the runtime contract (extern fn → (import "env" "<name>" ...), extern type → no Wasm artifact).
   • Section 8 (Codegen Module Environment): new section documenting the func_indices : (string * int) list table. Positive k ≥ 0 is a Wasm function index (defined functions or extern-imported functions); negative k < 0 encodes -(global_idx + 1) for top-level constants. Includes per-case gen_decl behaviour for TopFn (defined), TopFn with FnExtern body, and TopConst. Explicitly notes the call-site ExprApp lookup currently emits call k unconditionally — decoding the negative sentinel back to global.get is the implementation half tracked under Codegen.UnboundVariable for top-level const bindings (typecheck OK, compile fails) #73.

   The companion lib/codegen.ml doc-comment on the func_indices field was updated to mention both TopFn paths (defined and extern) and that insertion is in source declaration order.

   Note: PR #94 introduces a more detailed docs/specs/codegen-environment.adoc that goes deeper on cross-module threading and non-WASM target behaviour. That landing will subsume the SPEC.md §8 content here; this issue is resolved at the level it asked for (clarify that both consts and fns must be present in the codegen environment, document the population rules).
6. hyperpolymath

   added 2 commits that reference this issue on May 11, 2026

   Merge pull request #94 from hyperpolymath/docs/raw-decision-tree-exam…

   ...

   854f880

   docs(governance): add Hypatia and gitbot-fleet standing rules to .cla…

   ...

   b04d575