docs(ffi-linkage): checkpoint — Phase 9.1+9.2 IDENTIFIER purge COMPLETE; comment/doc/issues text purge remains

current/CHECKPOINT-EXTERN-EXPORT.md

@@ -5,7 +5,28 @@ Companion to `current/PLAN-EXTERN-EXPORT.md` — one merged plan: **Part A** add
 every commit, one step at a time per the cadence rule.
 
 ## Last completed step
-**Phase 9.1 (partial) — internal linkage-identifier purge** (commits `b838f63` 9.1a,
+**Phase 9.1 + 9.2 — internal IDENTIFIER purge COMPLETE** (commits 9.1a `b838f63`,
+9.1b `b78e7dd`, 9.1c `cd14794`, 9.1d `7ffdc7d`, 9.2a `3354446`, 9.2b `5c8af6e`,
+9.2b-fix `a15a868`, 9.2c `d27be42`, 9.2d `8cca3b9`). **Every `foreign` IDENTIFIER in
+`src/` is renamed** — the only `foreign` left in `src/` is COMMENTS + the kept token
+(`hash_foreign` + its `#foreignx` lexer-boundary test) + the rejection-message string.
+Suite green (646/444) at every commit.
+- **9.1d** eliminated the `foreign_expr` AST node: migrated `c_import.zig` auto-synth
+  to the extern shape, deleted the node + `ForeignExpr` + all readers.
+- **9.2a/b/c/d** ran the runtime-class family rename (Decision 5 → `Runtime*`):
+  types `ForeignClassDecl`→`RuntimeClassDecl` etc.; fns `parseForeignClassDecl`→
+  `parseRuntimeClassDecl`, `lowerForeignMethodCall`→`lowerRuntimeMethodCall`, …; state
+  `foreign_class_map`→`runtime_class_map`, `foreign_class_decl` variant→
+  `runtime_class_decl`; the extern-ref validators → `Extern` (linkage, `checkExternRefs`);
+  the reference flag → **`is_extern`** (per user: reuse existing terminology, not a new
+  `is_reference`); and `foreign_path`→`runtime_path` COUPLED across the hook boundary
+  (build.sx accessor `jni_main_runtime_path_at` + the registered hook string +
+  bundle.sx + specs.md), with 37 `.ir` snapshots regenerated for the renamed
+  `@BuildOptions.jni_main_runtime_path_at` declare stub (symbol-name change only).
+- **9.1a/b/c** (linkage): 5 collision-free renames (callExtern, …); "foreign symbol"
+  diagnostic + panic → "extern symbol" (1172 regen); deleted dead VarDecl legacy fields.
+
+### Prior: Phase 9.1 (partial) — internal linkage-identifier purge (commits `b838f63` 9.1a,
 `b78e7dd` 9.1b, `cd14794` 9.1c). **PHASE 9 STARTED.** Decision 6 = PURGE EVERYTHING,
 scoped (user, 2026-06-15): purge `foreign` from **all `.sx` files + all documentation +
 all our Zig (`src/`)**, analyzing each grep hit — **legitimate keeps stay**
@@ -288,7 +309,34 @@ AOT), 1227 (export fn rename, AOT), 1348 (objc extern class), 1349 (objc export
 (jni extern class), 1174/1175 (interplay diagnostics).
 
 ## Next step
-**PART B — finish Phase 9 (the scoped `foreign` purge).** Phases 5–8 + 9.1a/b/c COMPLETE.
+**PART B — finish Phase 9: the COMMENT / DOC / issues text purge** (all `src/`
+identifiers + the AST node are already done; remaining is prose). Lower-risk than the
+renames (text only, mostly snapshot-neutral) but needs per-instance reading — NOT a
+blind sed. Footprint: `src/` ~205 (all comments now), `examples/*.sx` ~100 comments,
+`issues/*.md` ~20 files, docs (specs/readme/CLAUDE).
+
+Order:
+1. **src/ comments** (~200) — reword `foreign`→`extern`/`runtime-class` to match the
+   renamed identifiers. KEEP: the rejection-message string, the `hash_foreign` token +
+   its `#foreignx`/`lex hash_foreign` test, and any comment that legitimately explains
+   the cutover (it must name `#foreign` to say it's removed). The ast.zig FnDecl comment
+   still says "mirroring `#foreign LIB "csym"` (foreign_lib/foreign_name)" — reword.
+2. **examples/*.sx comments** — the deferred provenance comments (full list in the prior
+   Next-step revision / git). ⚠ Many CONTRAST `#foreign` vs `extern` — reword to stay
+   coherent. ⚠ `1219-ffi-foreign.sx` prints `"foreign-rename: {}"`/`"=== 15. Foreign ==="`
+   to STDOUT — changing those regens its snapshot (intentional). `1176`/`1216` legitimately
+   discuss `#foreign` removal — keep minimal `#foreign` mentions where the test IS about it.
+3. **issues/*.md** (~20) — rewrite writeup prose to `extern`/`export`/`runtime-class`.
+4. **docs** — specs.md (rename "Foreign Function Interface" heading → "C Interop"; the
+   `#import c` "foreign declarations" prose; the comptime "foreign function calls" line;
+   §3344 "foreign code can't observe the error channel"), readme.md (211-212 the `#import
+   c` exemption prose), CLAUDE.md (host_ffi `#foreign("c")` ref → `extern`; "foreign calls").
+5. **9.0 surface decision** (recommend KEEP `hash_foreign` token + rejection for a good
+   deprecation — then it + the message + 1176 + `#foreignx` are permanent gate-exempt keeps).
+6. **9.4 gate** — `grep -rniIE 'foreign'` over `.sx` + docs + `src/` minus the keep-list → 0.
+   KEEP-LIST (gate-exempt): `SQLITE_CONSTRAINT_FOREIGNKEY` + SQLite API names, vendored
+   `library/vendors/sqlite/c/*`, the `hash_foreign` token + `#foreignx` test + rejection
+   message string, `1176-diagnostics-foreign-removed.sx` (rejection test must contain it).
 **Gate (scoped per user 2026-06-15):** `grep -rniIE 'foreign'` → 0 across `.sx` files,
 all docs, and our `src/` Zig — EXCLUDING the legitimate keeps listed in Last completed
 step (SQLite API names, vendored C, the rejection test/message + `hash_foreign` token).
@@ -457,6 +505,14 @@ Part A ratified (bare / postfix / `⇒ callconv(.c)` / lib-separate). Part B:
   deleted at cutover). Affects only diagnostic wording — IR/behavior identical either way.
 
 ## Log
+- (9.2a-d) **RUNTIME-CLASS IDENTIFIER PURGE COMPLETE** (Decision 5 → `Runtime*`).
+  9.2a types (`3354446`), 9.2b fns+state+`is_extern` flag (`5c8af6e`, fixed `a15a868`
+  per user: reuse `is_extern` not new `is_reference`), 9.2c extern-ref validators →
+  `Extern` (`d27be42`), 9.2d `foreign_path`→`runtime_path` coupled across the build-hook
+  boundary + 37 `.ir` regens (`8cca3b9`). `src/` now has ZERO `foreign` identifiers
+  (only comments + the kept token/message remain). Suite green throughout.
+- (9.1d) Eliminated the `foreign_expr` AST node — migrated `c_import.zig` auto-synth to
+  the extern shape, deleted the node + all readers. `refactor` `7ffdc7d`.
 - (9.1c) Deleted dead `VarDecl.is_foreign`/`foreign_lib`/`foreign_name` (global `#foreign`
   rejects → write-dead); 3 decl.zig readers simplified to `vd.extern_name`/`vd.is_extern`.
   Snapshot-neutral; suite green (646/444). `refactor` `cd14794`.