Просмотр исходного кода

docs: Stage B folds into Stage C — two-phase is one job

Explored Stage B (two-phase declarations); found it is not separable:
bodies are lowered during ProcDecl, so deferring them requires the
statement/expression AST (Stage C).  Revised the plan to a single
long branch converting statements/expressions to AST with a lowering
walk, keeping the old path behind a flag until green.
Eric Streit 1 неделя назад
Родитель
Сommit
7cec94afe0
1 измененных файлов с 40 добавлено и 29 удалено
  1. 40 29
      docs/session-handoff-2026-10-01.md

+ 40 - 29
docs/session-handoff-2026-10-01.md

@@ -4,35 +4,46 @@ State: `master` at tag **`v3-wrap-modules`** (`bdcefbb`).  Suite
 **177/177**, fixpoint **OK** (2,899,706 bytes).  Working tree clean
 except the user's `compiler/toto.mod`.
 
-## >>> NEXT SESSION: architectural work (decided) <<<
-
-The single biggest blocker identified this session is the
-**single-pass, no-AST frontend** (declaration-before-use, emit-during-
-parse).  It is the root cause of: text-patched forward variables,
-forward procedures needing a DEFINITION, set values in `CONST`, and
-the statement-context suffix difficulty.
-
-**Decided plan for tomorrow: options 1 and 2.**
-
-1. **Thin AST / two-phase parse for declarations** — parse a unit's
-   declarations fully into the symbol table *before* lowering any
-   body, so forward references (variables, procedures, typed
-   constants, `CONST` constructors) resolve naturally.  This would
-   delete the `FwdPatchAll` / placeholder / text-rewriting machinery.
-2. **Interim discipline (cheaper, preserves no-AST)** — keep no-AST,
-   but finish the symbol table for a module before emitting any
-   procedure body (extend the existing module-level `FlushPend`
-   discipline to procedure bodies).
-
-Suggested order: do **2** first as the structural stepping stone, then
-**1** if the goal is to compile gm2's corpus as-is.  Ask/confirm the
-long-term target before committing to 1: *"compile gm2 corpus as-is"*
-(→ both) vs *"clean classic Modula-2 that self-hosts"* (→ neither is a
-blocker; forward references stay out of scope).
-
-Work on a branch off `v3-session-2026-10-01`; run `fixpoint.sh` **and**
-`run_tests.sh` after every increment; revert the increment if either
-fails; commit only when both are green.
+## >>> NEXT SESSION: architectural work — FINDING (2026-10-02) <<<
+
+**Stage A is DONE** (tag `v3-ast-stageA`, commit `c91695c`): the AST
+node module `compiler/src/AST.def/.mod` exists and is tested
+(`tests/t_ast.mod`), and a real bug was fixed along the way (array-of-
+record element stride in `QbeGen.ElemSize`).  Suite 178/178, fixpoint
+OK.  See `docs/summary_ast-stageA.md`.
+
+**KEY FINDING — Stage B is not separable from Stage C.**
+
+While starting Stage B (two-phase declarations) it became clear that
+option 2 is *not* an independent stepping stone:
+
+- Bodies are lowered **during** `ProcDecl`, interleaved with parsing.
+- To finish the symbol table before lowering a body you must not lower
+  the body while parsing it.
+- If you don't lower it then, you must have stored it — and a body is
+  statements + expressions, i.e. **Stage C's AST**.
+- A "declarations-only" AST does not help: the *bodies* are what needs
+  deferring.
+
+There is no intermediate.  Either bodies are lowered inline (today) or
+they are built into a tree (Stage C).  **Options 1 and 2 are the same
+job.**
+
+### Revised plan
+
+Do the two-phase refactor as **one long, single-purpose branch**:
+
+1. Convert `Block` / `StatSeq` / `Stat` and the expression hierarchy to
+   build `AST` nodes instead of lowering.
+2. Move the current `QbeGen` calls for bodies into a **tree walk**
+   (`Lower(n)`), run *after* the unit's declarations are complete in
+   SymTab.
+3. Then declarations (`ConstBlock`/`TypeBlock`/`VarBlock`/`ProcDecl`)
+   likewise; delete `FwdPatchAll` / `FixLoadClass` / `FixStoreClass`
+   and the `Design` forward-variable placeholder path.
+
+Expect the **fixpoint to be red between increments**; keep the old path
+behind a flag until the new walk passes `run_tests.sh`, then flip.
 
 ## What landed today