sx/current/CHECKPOINT-EXTERN-EXPORT.md

# sx `extern`/`export` + `#foreign` retirement — Checkpoint (FFI-linkage stream)

Companion to `current/PLAN-EXTERN-EXPORT.md` — one merged plan: **Part A** adds
`extern`/`export`, **Part B** migrates `#foreign` and purges `foreign`. Update after
every commit, one step at a time per the cadence rule.

## Last completed step
**Phase 1.2d** (green) — **PHASE 1 COMPLETE.** `extern` data globals now parse + lower:
added a `kw_extern` branch in the var-decl-with-type-annotation path (`parser.zig:~451`,
beside `#foreign`) parsing `[LIB] ["csym"]` into `is_extern`/`extern_lib`/`extern_name`
(+ updated the trailing diagnostic to list `extern`); `registerTopLevelGlobal` now uses
`extern_name orelse foreign_name orelse name` for the C symbol and sets `is_extern =
is_foreign or is_extern`; `globalInitValue` returns null (no init) for extern too.
Example **1225 green** — `__stdinp : *void extern;` lowers to `@__stdinp = external
global ptr` and `@__stdinp` reads non-null. Full suite green (636 corpus / 443 unit, 0
fail). Kickoff exit criteria met: suite green; extern libc fn + global bindings run;
`#foreign` unregressed (all its examples pass → snapshots unchanged).

## Current state
Syntax: bare `extern`/`export`, postfix after `callconv(.c)`, `extern ⇒ callconv(.c)`.
**Decision 4 revised** (user 2026-06-14): `extern` carries an optional `LIB`+`"csym"`
axis (`extern_lib`/`extern_name`) like `#foreign`; the `#library` decl + build-flag
linking stays separate. **`extern` IS FULLY WORKING** (PHASE 1 DONE): functions —
bare (`f :: (…) -> R extern;`) AND renamed (`extern [LIB] "csym"`); data globals —
bare (`g : T extern;`) AND renamed. All behavior-equivalent to the matching `#foreign`
form (external linkage, C ABI, no sx ctx). `extern_lib` is parsed + stored but is a
*reference* only — actual linking stays the `#library`/build-flag axis (same as
`#foreign`'s lib ref). `export` NOT started (Phase 2). Aggregates NOT started (Phase 3).
Part B `foreign` footprint to purge: 643 lines / ~57 identifiers in `src/` + 28 doc
lines. End-state invariant: **zero `foreign`** (Phase 9.4 gate). Examples: 1223 (bare
fn), 1224 (fn rename), 1225 (bare global).

## Next step
**SESSION STOP** — kickoff scope was Phases 0–1 only; Phase 1 is complete. Do NOT
start Phase 2 here. Next session picks up **Phase 2 — `export`** (define + expose):
fills the four export-gap conditions in `decl.zig` (all on the *define* path, not
`declareExtern`): (i) force `.external` linkage when `extern_export == .export_`
(`:2382`/`:2514`); (ii) promote to C ABI (`:2110`/the `lowerFunction` cc at `:2522`);
(iii) symbol-name override via `export "csym"` (already parsed into `extern_name` —
just consume on the define path); (iv) ctx already suppressed for `.export_`? NO —
`funcWantsImplicitCtx` currently suppresses only `.extern_`; broaden to `!= .none`
(or add `.export_`). Start with an xfail multi-file test: an `export fn` called from a
companion `.c` caller. Then Phase 3 (aggregates), Phase 4 (interplay/diagnostics/docs
+ the A→B gate: unit test that `#foreign` and `extern` lower to identical IR).

**Deferred (do in Phase 4):** (a) docs — `specs.md`/`readme.md` document
`extern`/`export` (the plan defers docs to Phase 4; `#foreign` stays documented until
the Part B cutover); (b) visibility-gate equivalence — bare `extern` (no `extern_lib`)
is currently unconditionally visible via the `c_import_bare` gate
(`decl.zig:~2241`, `fd.body.data != .foreign_expr → return true`), whereas a lib-less
`#foreign` is policed by `visibleOverEdges`. Single-file examples don't exercise this;
verify/align it at the A→B gate (a bare-extern lib-less fn should be policed like its
`#foreign` twin). Adding it now would be untested — needs a cross-module example.

## Open decisions
Part A ratified (bare / postfix / `⇒ callconv(.c)` / lib-separate). Part B (confirm
before Phase 9): runtime-class rename target — `Runtime*Class*` (recommended);
historical carve-out — keep `issues/*.md` provenance, gate the live tree only.

## Log
- (init) Plan written; FFI-linkage stream opened.
- (merge) Folded FOREIGN-MIGRATION in as Part B; deleted the split plan + checkpoint.
- (0.0) Added `kw_extern`/`kw_export` tokens + keyword-map entries + LSP keyword
  classification + `lex linkage keywords` test. Suite green; no identifier collisions
  in the corpus. `lock` commit.
- (0.1) Added `ast.ExternExportModifier` + `FnDecl.extern_export` +
  `VarDecl.is_extern`/`extern_name` + `parseOptionalExternExport()` (unconsumed) + 2
  parser unit tests. Suite green (443/633). `lock` commit.
- (1.0a) Wired fn-path extern parsing (`parseFnDecl` + both lookahead predicates) +
  added `FnDecl.extern_lib`/`extern_name` + `VarDecl.extern_lib` per user feedback
  (decision 4 revised: extern carries an optional lib axis). Unconsumed by lowering.
  Suite green (443/633). `lock` commit.
- (1.0b) Added `examples/1223-ffi-extern-fn.sx` + hand-authored success snapshots.
  RED (634 ran, 1 failed — sema `body produces no value`). `xfail` commit; 1.1 greens it.
- (1.1) Wired extern fn lowering (6 edits in `decl.zig`, all declare-only routing
  mirroring `foreign_expr`): `funcWantsImplicitCtx` + `declareFunction` cc +
  `lazyLowerFunction`/`lowerFunction`/`lowerFunctionBodyInto` guards. 1223 green;
  `declare i32 @abs(i32)` (C ABI, no ctx). Suite green (634/443). `green` commit.
- (1.2a) Added `examples/1224-ffi-extern-fn-rename.sx` (`c_abs :: … extern "abs";`) +
  hand-authored success snapshot (`c_abs(-42) = 42`). RED (635 ran, 1 failed — parse
  error: `"abs"` after `extern` not yet accepted). `xfail`; 1.2b greens it. (Also
  recovered a formatter-clobbered `parser.zig` — see Known issues.)
- (1.2b) `parseFnDecl` parses the optional `[LIB] ["csym"]` tail into
  `extern_lib`/`extern_name`; `declareFunction` unifies the rename (foreign c_name OR
  extern_name → declare under C name, map sx→C) and extends the dedupe guard to
  extern. 1224 green (`c_abs`→`abs`); 1223 unregressed. Suite green (635/443).
  `green` commit. extern_lib parsed+stored (lib linking stays the `#library` axis).
- (1.2c) Added `examples/1225-ffi-extern-global.sx` (`__stdinp : *void extern;`,
  mirrors `#foreign` global 1205) + success snapshot. RED (636 ran, 1 failed — parse
  error: var-decl `extern` not accepted). `xfail`; 1.2d greens it.
- (1.2d) Parser `kw_extern` branch in the var-decl path (`[LIB] ["csym"]` →
  `is_extern`/`extern_lib`/`extern_name`) + `registerTopLevelGlobal`/`globalInitValue`
  consume `is_extern`. 1225 green (`@__stdinp = external global ptr`). Suite green
  (636/443). `green` commit. **PHASE 1 COMPLETE** — `extern` fns + globals fully work.

## Known issues
- **Workflow hazard (1.2):** an editor format-on-save (or `zig fmt`) clobbered the
  working-tree `src/parser.zig` between commits — it reformatted one-liners AND
  silently dropped my `hasFnBodyAfterArrow` extern edit, reverting 1223 to a parse
  error. Recovered with `git checkout src/parser.zig` (HEAD had the correct,
  committed version). **After any Edit-tool change to a file the IDE may have open,
  rebuild + run the affected example before trusting the edit.**