docs(adr): ESC-04 — ADR-017 ReScript block-module disposition (Refs #262 #229) (#271)

AffineScript is strictly one-module-per-file (ADR-011 file=module;
grammar parser.mly:130-134 — `module A { }` parse-errors). #229 ports
carry ReScript block modules; single-per-file is mechanical (canonical
map), multi-block-per-file had no clean target (ESC-04 #262).

ADR-017 (accepted): one module per file — split, do not nest. Each
`module X { body }` -> its own X.affine with a `module X;` header; N
block-modules -> N files. Grammar NOT extended (ADR-011/ADR-012). No
compiler change — settles the porting doctrine + #229 canonical-map
structural rule. The split-file Resolve.UndefinedModule is cross-module
graph coherence (INT-02), tracked in RESCRIPT-ELIMINATION Tier-4, NOT
conflated here.

ADR-017 is sequential between ADR-016 (effect-threaded async-boundary,
#234/#270) and ADR-018 (no-raw-escape, #245/#272); inserted in order in
SETTLED-DECISIONS + META.a2ml + RESCRIPT-ELIMINATION ESC-04 row.
Reconstructed cleanly on current main (the original branch's ADR-016
->017 renumber history is collapsed to one in-order commit; supersedes
the prior #271 head). Docs-only; gate unaffected. Refs #262 #229.

Co-authored-by: hyperpolymath <hyperpolymath@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/META.a2ml

@@ -1096,6 +1096,57 @@ references = [
   "docs/specs/SETTLED-DECISIONS.adoc (ADR-016 section)",
 ]
 
+[[adr]]
+id = "ADR-017"
+status = "accepted"
+date = "2026-05-19"
+title = "ReScript block-module disposition: one module per file (split, do not nest)"
+context = """
+ReScript `module Name { … }` block modules have no AffineScript block
+form: the grammar (parser.mly:130-134) is a single optional `module
+Path;` header, before imports — `module A { }` parse-errors. ADR-011
+settled "real modules": the file IS the module. The estate #229 ports
+carry block modules; a SINGLE one per file is mechanical (hoist header,
+drop braces, dedent — in the #229 canonical map, verified to parse), but
+MULTIPLE block-modules in one file (e.g. standards/lol/.../OpenCyc.affine:
+module Config{} module Concepts{} module Types{}…; 14 estate
+occurrences) had no clean target. Escalated language-side as ESC-04
+(#262) — the bidirectional-evidence discipline of ADR-014 / #228.
+(ADR-016 is effect-threaded async-boundary, #234/#270; ADR-018 is the
+no-raw-escape doctrine, #245 — this is ADR-017, sequential.)
+"""
+decision = """
+One module per file — split, do not nest. Each ReScript `module X {
+body }` becomes its own `X.affine` whose first declaration is `module
+X;`, body dedented, `use` after the header. A file with N block-modules
+is split into N files. The grammar is NOT extended with a block/nested
+module form: that contradicts ADR-011 (file = module) and is a major
+conflict-risky grammar change for cosmetic gain — the contortion ADR-012
+forbids. No compiler change (the file-header form already parses); this
+ADR settles the porting doctrine + the #229 canonical-map structural
+rule. Adjacent and explicitly OUT of scope: a split file still hits
+Resolve.UndefinedModule until the repo module-path<->file-layout matches
+the loader — cross-module graph coherence (INT-02 loader-bridge),
+tracked in RESCRIPT-ELIMINATION.adoc Tier-4, never conflated here.
+"""
+consequences = """
+- The #229 block-module residue (idaptik-dlc-vm, standards/lol, parts of
+  burble) has a defined target: split-per-file. Full validation still
+  needs the per-repo module graph (INT-02), tracked separately.
+- No language/compiler change; no estate consumer churn from this ADR.
+- This decision is settled; do not reopen without amending this ADR.
+  ESC-04 #262; #229 canonical map in docs/RESCRIPT-ELIMINATION.adoc.
+"""
+references = [
+  "https://github.com/hyperpolymath/affinescript/issues/262",
+  "https://github.com/hyperpolymath/affinescript/issues/229",
+  "lib/parser.mly (module_decl; one `module Path;` header per file)",
+  "docs/specs/SETTLED-DECISIONS.adoc (ADR-017 section)",
+  "docs/RESCRIPT-ELIMINATION.adoc (#229 canonical map; Tier-4 INT-02)",
+  "META.a2ml [[adr]] ADR-011 (real modules: file = module)",
+  "META.a2ml [[adr]] ADR-012 (grammar changes are correctness assertions)",
+]
+
 [[adr]]
 id = "ADR-018"
 status = "accepted"

docs/RESCRIPT-ELIMINATION.adoc

@@ -273,9 +273,13 @@ ReScript `import P [as A]`→`use P [as A];`, single block-module
   `module P;` header (hoisted before imports — `parser.mly:130-134`
   requires the header first), braces dropped, body dedented one level.
   Oracle-verified to parse.
-* *Tier-3 ESC-04 (#262):* *multi*-block-module per file (e.g.
-  `standards/lol/.../OpenCyc.affine`) has *no clean target* —
-  AffineScript is one-module-per-file. Escalated, not guessed.
+* *ESC-04 (#262) — SETTLED by ADR-017:* AffineScript is strictly
+  one-module-per-file. Doctrine: *split, do not nest* — each ReScript
+  `module X { body }` (incl. each of N in a multi-block file like
+  `standards/lol/.../OpenCyc.affine`) becomes its own `X.affine` with a
+  `module X;` header. No grammar change (ADR-011 file=module; a
+  block-module form is the ADR-012-forbidden contortion). Full
+  validation still needs the per-repo module graph (INT-02, Tier-4).
 
 === Reclassified OUT of #229 — permanently (scanner over-scope)
 

docs/specs/SETTLED-DECISIONS.adoc

@@ -343,6 +343,40 @@ This decision is settled; do not reopen without amending the ADR. Full
 ADR in `.machine_readable/6a2/META.a2ml` (ADR-016); ledger #234 /
 CORE-02 in `docs/TECH-DEBT.adoc`.
 
+== ReScript Block-Module Disposition: One Module Per File (ADR-017)
+
+ReScript `module Name { … }` block modules have no AffineScript block
+form: the grammar (`parser.mly:130-134`) is a single optional
+`module Path;` *header*, before imports — `module A { }` parse-errors.
+ADR-011 already settled "real modules": *the file is the module*. The
+estate ReScript→AffineScript ports (#229) carry block modules — a single
+one per file is mechanical (hoist the header, drop the braces, dedent;
+already in the #229 canonical map and verified to parse), but *multiple*
+block-modules in one file (e.g. `standards/lol/.../OpenCyc.affine`:
+`module Config { } module Concepts { } module Types { } …`, 14 estate
+occurrences) had no clean target. Escalated language-side as ESC-04
+(#262), the same bidirectional-evidence discipline as ADR-014 / #228.
+
+Decision: *one module per file — split, do not nest.* Each ReScript
+`module X { body }` becomes its own `X.affine` whose first declaration is
+`module X;`, body dedented, `use` imports after the header. A file with N
+block-modules is split into N files. The grammar is **not** extended with
+a block/nested-module form: that would contradict ADR-011 (file = module)
+and is a major, conflict-risky grammar change for cosmetic gain — exactly
+the contortion ADR-012 forbids. No language/compiler change is needed
+(the file-header form already parses); this ADR settles the *porting
+doctrine* + the #229 canonical-map structural rule.
+
+Adjacent, explicitly NOT in scope here: a split file still hits
+`Resolve.UndefinedModule` until the repo's module-path↔file-layout
+matches the loader — that is cross-module graph coherence (INT-02
+loader-bridge territory), tracked in `RESCRIPT-ELIMINATION.adoc` Tier-4
+and the INT-02 ledger, never conflated with this disposition.
+
+This decision is settled; do not reopen without amending the ADR. Full
+ADR in `.machine_readable/6a2/META.a2ml` (ADR-017); #229 canonical map in
+`docs/RESCRIPT-ELIMINATION.adoc`; escalation issue #262.
+
 == No Raw/FFI Escape: Typed `extern` Is the Only Host Bridge (ADR-018)
 
 ReScript `%%raw("<host source>")` / `%raw` injects arbitrary untyped host