From 0f784991b41c4e4926e971e39736506b17976671 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 13 May 2026 00:09:16 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20thin=20SPEC.adoc=20=C2=A78=20to=20f?= =?UTF-8?q?orward-reference=20codegen-environment.adoc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/specs/SPEC.adoc | 144 +------------------------------------------ 1 file changed, 3 insertions(+), 141 deletions(-) diff --git a/docs/specs/SPEC.adoc b/docs/specs/SPEC.adoc index 403f0ff..167c361 100644 --- a/docs/specs/SPEC.adoc +++ b/docs/specs/SPEC.adoc @@ -652,147 +652,9 @@ Compiles to (ownership removed): == 8. Top-Level Binding Environment -This section specifies how top-level declarations populate the binding -environment that subsequent declarations and their bodies resolve against. -It complements §3 (which gives the typing judgements) by fixing the -*operational* rules every conforming code generator must obey, independent -of any concrete target. - -The WebAssembly realisation of these rules is documented at -link:codegen-environment.adoc[`docs/specs/codegen-environment.adoc`]. - -=== 8.1 Top-Level Kinds - -A program is an ordered sequence of top-level declarations. Each kind -contributes to the binding environment as follows: - -[cols="1,2,2", options="header"] -|=== -| Declaration | Binds | Runtime artefact - -| `fn f(…) { … }` (§2.4) -| `f` as a function value -| Yes — function in the target module - -| `extern fn f(…) -> T;` (§2.10) -| `f` as a function value -| Yes — host-supplied import - -| `const c: T = e;` (§2.9) -| `c` as an immutable value of type `T` -| Yes — same-type immutable cell - -| `type T = …;` (§2.2) -| `T` as a type -| No — compile-time only - -| `extern type T;` (§2.10) -| `T` as an opaque type -| No — compile-time only - -| `effect E { … }` (§2.7) -| `E` and its operations -| No — handled by effect lowering (§7) - -| `trait Tr { … }` (§2.8) -| `Tr` as a trait -| No — compile-time only - -| `impl Tr for T { … }` (§2.8) -| Trait dictionary for `(Tr, T)` -| No — compile-time only -|=== - -=== 8.2 Declaration Order and Visibility - -Top-level declarations are processed in source order. The binding -environment in scope when a declaration is processed contains exactly -the names of declarations that *precede* it in source order, together -with the names introduced by the module's `use` clauses (§8.4). - -A reference to a name not yet bound at its use site is a static error: - -[source,affinescript] ----- -fn use_pi() -> Float { pi } // ERROR: `pi` not yet declared -const pi: Float = 3.141592; ----- - -Reordering resolves it: - -[source,affinescript] ----- -const pi: Float = 3.141592; -fn use_pi() -> Float { pi } // OK: `pi` is in scope here ----- - -The recommended source ordering — types, effects, constants, traits, -impls, functions — is sufficient (though not necessary) to avoid every -forward-reference error. - -=== 8.3 Identifier Resolution - -A bare identifier `x` in expression position resolves by the following -lookup order, in the context where the expression appears: - -. Local bindings introduced by enclosing `let`, lambda parameters, or - function parameters. -. Variant constructors of any in-scope `enum` type, resolved to their - tag (§2.2). -. Top-level bindings: `fn`, `extern fn`, and `const` names registered - under §8.1. - -A call expression `f(args)` resolves `f` against the same environment. -A name bound to a `const` may appear in expression position only; a -name bound to a `fn` or `extern fn` may appear in either expression or -call position. The well-formedness of these positions is established by -the type system (§3); a backend may rely on the typechecker having -rejected ill-positioned references. - -=== 8.4 Cross-Module Bindings - -Imports (`use M::{…}`, `use M::*`) extend the binding environment of -the importer with the public top-level names of the imported module, -under the alias chosen by the import form (§2.1). The order in which -import-introduced names enter the environment is *before* every -local top-level declaration of the importer. - -Items that flow across module boundaries: - -* `fn` and `extern fn` — imported as references to the original definition. -* `const` — its initialiser is compiled inline into the importer's - module, so each importer materialises its own copy of the value. - The denotation seen at use sites is the same as the source `const` - in the defining module. - -=== 8.5 Conformance Criteria - -A conforming code generator MUST: - -C1:: Process top-level declarations in source order. - -C2:: Register a top-level name in its environment *before* generating -the body of any later declaration that may reference it. - -C3:: For each runtime-bearing declaration (`fn`, `extern fn`, `const`) -emit an artefact whose denotation matches §2 and §3 — functions are -first-class values, constants are immutable cells of their declared -type. - -C4:: For each compile-time declaration (`type`, `extern type`, `effect`, -`trait`, `impl`) record sufficient information in the environment for -subsequent declarations to typecheck and lower correctly, without -necessarily emitting any target artefact. - -C5:: Report a static error (rather than emit a malformed module) when -an identifier escapes its lexical scope or names a binding not yet in -the environment under C1–C2. - -C6:: If a binding kind is unsupported by the target, raise -`UnsupportedFeature` at the declaration site, never silently drop it. - -Implementations MAY use any internal representation for the binding -environment; C1–C6 fix what is observable, not how it is stored. +See link:codegen-environment.adoc[`docs/specs/codegen-environment.adoc`] for the +full codegen module environment reference, including the `func_indices` +dual-use encoding, population order, and extern binding rules. == Appendix: Grammar Reference From 14ffaa81dd46887e41f9d1793c3b60de4635a26a Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 14 May 2026 02:07:42 +0200 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20thin=20SPEC.adoc=20=C2=A78=20to=20f?= =?UTF-8?q?orward-reference=20codegen-environment.adoc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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