docs(ffi-linkage): checkpoint — Phase 7.1 done + keep-list policy; next Phase 7.2 (13xx objc)

current/CHECKPOINT-EXTERN-EXPORT.md

@@ -5,7 +5,24 @@ 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 6.5 — migrate `gpu/` `#foreign`→`extern`; `library/` now `#foreign`-free**
+**Phase 7.1 — migrate incidental 12xx ffi examples `#foreign`→`extern`** (`refactor`
+commit `731fb8d`). **PHASE 7 STARTED.** Migrated 12 plain-C examples that use
+`#foreign` incidentally (FFI plumbing, output unchanged):
+1200/1206/1209-1215/1220/1221/1222. Blanket keyword swap (all fn/global markers, no
+class forms in 12xx). Empty snapshot diff; corpus validates directly (all marker'd).
+Suite green (647/444). **KEEP-LIST POLICY ESTABLISHED (applies to all 7.x):** an
+example is KEPT on `#foreign` (deferred to Phase 8 cutover) iff migrating it would
+change a snapshot OR its identity is the `#foreign` keyword. Concretely kept:
+- **Diagnostics asserting on `#foreign` source/message** — migrating flips the echoed
+  source line or message → non-empty diff: `1172` (foreign-symbol-conflict), `1174`
+  (foreign-postfix-conflict), `1620` (cimport-foreign-ref-unvalidated).
+- **The equivalence test** `1228` (needs both `#foreign` + `extern` twins by design).
+- **Identity-`#foreign` feature tests** (filename `ffi-foreign-*`, defer rename/dedup
+  to Phase 8): `1205`/`1207`/`1216`/`1218`/`1219`.
+- **Comment-only provenance prose** (`1223`/`1229`/`1230`/`1231`) — `#foreign` only in
+  explanatory comments; left intact per Decision-6-recommended (keep provenance).
+
+### Prior: Phase 6.5 — migrate `gpu/` `#foreign`→`extern`; `library/` now `#foreign`-free
 (`refactor` commit `32a7628`). **PHASE 6 COMPLETE.** Final batch: gpu/gles3.sx
 (eglGetProcAddress + 1 comment) + gpu/metal.sx (MTLCreateSystemDefaultDevice), bare
 fn markers → `extern`. Verified byte-identical `sx ir` on importers 1610 (gles3) +
@@ -209,24 +226,23 @@ AOT), 1227 (export fn rename, AOT), 1348 (objc extern class), 1349 (objc export
 (jni extern class), 1174/1175 (interplay diagnostics).
 
 ## Next step
-**PART B — Phase 7 (migrate `examples/` + `issues/` `#foreign`→`extern`/`export`).**
-**PHASE 6 COMPLETE — `library/` is `#foreign`-free.**
+**PART B — Phase 7.2 (migrate `examples/13xx-ffi-objc-*` `#foreign`→`extern`/`export`).**
+Phase 7.1 (12xx incidental) COMPLETE. Apply the KEEP-LIST POLICY above to every batch.
 
-- **Phase 7** (`refactor` batches, snapshot diff must be EMPTY per batch): migrate the
-  corpus + issue repros. Batches (PLAN-EXTERN-EXPORT Phase 7): 7.1 `examples/12xx-ffi-*`
-  (plain C), 7.2 `examples/13xx-ffi-objc-*`, 7.3 `examples/14xx-ffi-jni-*`, 7.4
-  `issues/*` repros + stragglers. ⚠ Same shape rules as Phase 6: fn/global markers →
-  `extern …` (blanket keyword swap is safe for fn-only files); runtime classes →
-  postfix (`#objc_class/#jni_class("X") extern {` import, `… export {` defined). Check
-  each file's shapes first. Most examples ARE marker'd → the corpus validates the empty
-  snapshot diff directly; a non-empty diff ⇒ STOP and coalesce, don't regen.
-  - **Decision needed for 7.4:** the `issues/*.md` writeups contain `#foreign` in prose
-    repros — Decision 6 (historical carve-out, STILL OPEN) governs whether those get
-    migrated or kept as provenance. Migrate `issues/*.sx` repros (live tree); defer the
-    `.md` prose pending Decision 6. Also: some examples are diagnostic tests that
-    deliberately reference `#foreign` (e.g. 1174 foreign-postfix-conflict, 1620 lib-ref)
-    — those must KEEP `#foreign` until the Phase 8 cutover (they test the keyword's
-    behavior). Identify and exclude them from the 7.x bulk rename.
+- **Phase 7.2** (`refactor`, snapshot diff must be EMPTY): migrate `examples/13xx-ffi-objc-*`.
+  ⚠ 13xx has Obj-C **runtime classes** — use the postfix shape (`#objc_class("X") extern {`
+  import == old `#foreign #objc_class`; `… export {` defined == bare `#objc_class`). Check
+  each file's shapes first (`grep -c '#foreign #'`). Apply the keep-list: exclude any 13xx
+  whose snapshot asserts on `#foreign` text or whose identity is the keyword (scan
+  `examples/expected/13*.std{err,out}` for "foreign" first, like 7.1 did). Most 13xx ARE
+  marker'd (50 found in Phase 6.4) → corpus validates the empty diff directly.
+- **Remaining Phase 7 batches:** 7.3 `examples/14xx-ffi-jni-*` (JNI runtime classes,
+  same postfix rules), 7.4 `issues/*.sx` repros + stragglers (16xx platform examples,
+  the scattered 04/06/07/10 ones). For 7.4 `issues/*.md` prose: defer per Decision 6
+  (recommended = keep as provenance).
+- **Decision 6 (STILL OPEN)** governs the `issues/*.md` + comment-prose carve-out — the
+  recommended default (keep provenance, gate only the live tree) is being applied; flag
+  to the user before Phase 9 if not yet ratified.
 - **6.2 verification note (carry forward):** the `platform/` runtime modules
   (uikit/android/android_jni) are NOT compiled by any marker'd host corpus test — verify
   future platform-adjacent migrations via direct `sx ir` on importers (1610/1606 compile
@@ -353,6 +369,12 @@ Part A ratified (bare / postfix / `⇒ callconv(.c)` / lib-separate). Part B:
   deleted at cutover). Affects only diagnostic wording — IR/behavior identical either way.
 
 ## Log
+- (7.1 12xx) **PHASE 7 STARTED.** Migrated 12 incidental plain-C examples
+  (1200/1206/1209-1215/1220/1221/1222) `#foreign`→`extern`; output byte-identical,
+  empty snapshot diff, corpus-validated. Established the keep-list policy (see Last
+  completed step): kept 1172/1174/1620/1228 + ffi-foreign-* (1205/1207/1216/1218/1219)
+  + comment-only 1223/1229/1230/1231 for Phase 8. Suite green (647/444). `refactor`
+  `731fb8d`.
 - (6.5 gpu) **PHASE 6 COMPLETE.** Migrated `gpu/gles3.sx` + `gpu/metal.sx` (3 sites);
   `library/` now `#foreign`-free (`grep -rln '#foreign' library/` → 0). Verified
   byte-identical `sx ir` on importers 1610/1606. Suite green (647/444). `refactor`