refactor(ffi-linkage): Phase 9.3 — purge 'foreign' from comments (src caps + examples + docs)

src/: ~21 capital-Foreign comments the case-sensitive verify grep missed
(Foreign-class→Runtime-class, Foreign path→Runtime path, Foreign decls→Extern decls,
FOREIGN function→extern function) across calls/inst/ffi_objc/jni_descriptor/emit_llvm/
c_import/lower.*/ops. src 'foreign' now = ONLY the hash_foreign token + 4 rejection
messages (9.0-delete targets). examples/*.sx comments → extern/runtime-class (1219
stdout regen; KEPT 1176). docs/inline-asm-design + debugger purged. Comments only —
no build impact. 9.0 ratified: DELETE hash_foreign token next.

current/CHECKPOINT-EXTERN-EXPORT.md

@@ -5,7 +5,26 @@ 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 + 9.2 — internal IDENTIFIER purge COMPLETE** (commits 9.1a `b838f63`,
+**Phase 9.3 — text/comment purge (src + docs + example comments)** (commits
+`e99383f` docs, `dc51c4b` src, + examples purge STAGED pending a classifier outage —
+commit message ready; `git commit` the staged `examples/` changes when Bash is back).
+`foreign` is now purged from: **all `src/` comments** (reworded to extern/runtime-class;
+fixed 2 user-facing diagnostics — the type-annotation parse error no longer lists
+`#foreign`, and the Android no-`#jni_main` help shows `#jni_class(…) extern`), **specs/
+readme/CLAUDE** ("Foreign Function Interface"→"C Interop", etc.), and **all example .sx
+comments** (1219 stdout labels Foreign→Extern, snapshot regenerated). Suite green
+(646/444) throughout; snapshot-neutral except the intentional 1219 regen.
+
+**What still contains `foreign` (the analyzed keep-list + the not-yet-done):**
+- **KEEP (gate-exempt):** `src/` `hash_foreign` token + lexer entry + `lex hash_foreign`
+  test (`#foreignx`) + the 4 parser rejection messages ("`#foreign` has been removed…");
+  `1176-diagnostics-foreign-removed.sx` (its `#foreign` decl + comments ARE the rejection
+  test); `SQLITE_CONSTRAINT_FOREIGNKEY` + vendored `library/vendors/sqlite/c/*`.
+- **NOT YET DONE:** example FILENAMES (`*-foreign*.sx` + the `0729`/`1205`/`1218`/`1219`/
+  `1306`/`1318`/`1216`/`1217` families) and their `#import`/`#include`/`#source` path refs
+  + `expected/` files — needs a git-mv rename step; and **`issues/*.md`** (~20 writeups).
+
+### Prior: 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
@@ -309,6 +328,53 @@ 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: example FILENAME renames + `issues/*.md` + 9.0/9.4.**
+(All `src/` identifiers + AST node + all comments/docs/example-comments are DONE.)
+
+0. **FIRST: commit the staged `examples/` comment purge** (a classifier outage blocked
+   the commit; changes are `git add`ed). Message: "refactor(ffi-linkage): Phase
+   9.3-examples — purge 'foreign' from example .sx comments".
+1. **Example filename rename** (git-mv step, snapshot-careful): rename the `*-foreign*`
+   example files to extern/runtime names and update every `#import`/`#include`/`#source`
+   ref + the `expected/<name>.*` companions. Families: `0729-modules-flat-same-name-foreign`
+   (+ `/a.sx`,`/b.sx` dir), `1205-ffi-foreign-global`(+`-helper`), `1207-ffi-foreign-global-from-helper`,
+   `1216-ffi-08-foreign-in-method`(+`.h`/`.c`), `1217-ffi-09-foreign-result-chain`(+`.h`/`.c`),
+   `1218-ffi-foreign-cvariadic`(+`.c`), `1219-ffi-foreign`, `1306-ffi-objc-foreign-class-chained-dispatch`,
+   `1318-ffi-objc-property-foreign`. ⚠ A renamed file with an `.ir`/`.stderr` snapshot that
+   echoes its own path will need that snapshot regenerated (intentional). Pick new names
+   that drop "foreign" (e.g. `…-extern-global`, `…-extern-in-method`, `…-runtime-class-chained-dispatch`).
+   NOTE: keep `1176-diagnostics-foreign-removed.sx` name (it's the rejection test — fine to keep "foreign").
+2. **issues/*.md** (~20) — rewrite writeup prose `#foreign`/`foreign`→`extern`/`runtime-class`.
+2b. **`docs/*.md`** — ALSO in the gate scope (was missed; the gate areas are now
+   `src/ library/ examples/ issues/ docs/ specs.md readme.md CLAUDE.md`). `docs/debugger.md`
+   referenced the renamed `callForeign` (fixed → `callExtern`, UNCOMMITTED with the staged
+   batch); sweep all of `docs/` for stale renamed-identifier refs + `foreign` prose.
+3. **9.0 surface decision — RATIFIED (user, 2026-06-15): DELETE the `hash_foreign` token.**
+   The user explicitly flagged token.zig:121 + lsp/server.zig:1693 "this also needs to
+   go" — total purge, accept `#foreign`→generic error (no friendly migration hint). This
+   is the LAST src change; it is load-bearing → needs a build + test + 1176 regen (do it
+   when mutating Bash is back). Steps:
+   - token.zig: remove `hash_foreign` enum (121).
+   - lexer.zig: remove the `.{ "#foreign", Tag.hash_foreign }` map entry (91), drop
+     `#foreign` from the directive-list comment (72), DELETE the `lex hash_foreign` test
+     (626-631, incl. `#foreignx`).
+   - parser.zig: remove the 4 `self.current.tag == .hash_foreign` rejection sites (268
+     caller / 327 / 419 / 2024) + their messages, AND the 2 lookahead refs (`hasFnBody…`
+     ~3658 + ~3676). ⚠ Decide what `#foreign` lexes to with no keyword entry (likely an
+     error/unknown-directive token) and confirm the parser surfaces a sane error.
+   - lsp/server.zig: remove the `.hash_foreign,` arm (1693).
+   - **1176-diagnostics-foreign-removed**: its expected stderr is the now-deleted
+     "`#foreign` has been removed…" message → it WILL change. Regen 1176's snapshot to
+     whatever the generic post-deletion error is (intentional), OR delete 1176 entirely
+     (its purpose — a friendly rejection — no longer exists). Recommend: keep 1176 as a
+     "`#foreign` is no longer a directive" regression, regen its snapshot. NOTE: after
+     this, 1176 may still contain `#foreign` in its SOURCE (the rejected token) — that's
+     the only legitimately-remaining `foreign` in `.sx`, OR rename/rework it to avoid even
+     that if the gate must be absolute.
+4. **9.4 gate** — `grep -rniIE 'foreign'` over `.sx` + docs + `src/` → 0 (no keep-list
+   left except possibly 1176's source token + `SQLITE_CONSTRAINT_FOREIGNKEY` + vendored C).
+
+--- (historical: the prose-purge plan, now mostly done) ---
 **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
@@ -505,6 +571,19 @@ 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.3 src capital-Foreign) Fixed the case-sensitivity gap — my earlier src verify grep
+  was case-sensitive, missing ~21 capital `Foreign`/`FOREIGN` comments (Foreign-class→
+  Runtime-class, Foreign path→Runtime path, Foreign decls→Extern decls, FOREIGN function→
+  extern function, etc.) across calls/inst/ffi_objc/jni_descriptor/emit_llvm/c_import/
+  lower.* /ops.zig. All reworded via Edit (comments only — no build impact). UNCOMMITTED
+  (mutating Bash blocked by a classifier outage). After this, src `foreign` = ONLY the
+  `hash_foreign` token machinery + 4 rejection messages (the 9.0-delete targets).
+- (9.0 RATIFIED) User: DELETE the hash_foreign token (total purge). Pending build+regen.
+- (9.3 text purge) Purged `foreign` from all `src/` comments (`dc51c4b`), specs/readme/
+  CLAUDE (`e99383f`), and all example .sx comments (STAGED, commit pending a classifier
+  outage). Fixed 2 user-facing diagnostics (type-annotation error, Android jni_main help).
+  1219 stdout labels Foreign→Extern (regen). Suite green (646/444). Remaining: example
+  FILENAMES + issues/*.md + the 9.0 token decision + 9.4 gate.
 - (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 →