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.1 (green) — wired extern fn lowering in decl.zig; example 1223 now green, full suite green (634 corpus / 443 unit, 0 fail). A bare extern fn lowers exactly like a lib-less #foreign import: declare i32 @abs(i32) #0 — external linkage, C ABI, NO __sx_ctx param; calls emit call i32 @abs(i32 -7) and resolve against the default-linked libc. Six edits, all routing extern declare-only (mirroring the foreign_expr guards): (1) funcWantsImplicitCtx suppresses ctx for .extern_; (2) declareFunction adds is_extern_decl and (3) includes it in the C-ABI promotion; (4) lazyLowerFunction routes .extern_→declare-only; (5) lowerFunction declare-only guard; (6) lowerFunctionBodyInto never promotes/lowers an extern stub. Hand-authored 1.0b snapshot matched byte-exact — no regen needed. No .ir snapshot added (the trivial declare i32 @abs(i32) doesn't warrant a 1000-line full-prelude dump; behavioral .stdout already catches ctx/linkage regressions).

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 FUNCTIONS WORK (import; bare form, no rename) — parse + lower complete, behavior-equivalent to a lib-less #foreign fn. Still TODO in Phase 1: the extern LIB "csym" lib/rename axis (fields exist, unconsumed) and the extern-global form. export not started (Phase 2). Part B foreign footprint to purge: 643 lines / ~57 identifiers in src/ + 28 doc lines. End-state invariant: zero foreign (Phase 9.4 gate). Done: 0.0 tokens, 0.1 AST/parser plumbing, 1.0a fn-path parsing + lib/name fields, 1.0b xfail example, 1.1 fn lowering (green).

Next step

Phase 1.2 (green) — two parts, each its own xfail→green or behavior-lock:

1. extern LIB "csym" rename for fns — extend parseOptionalExternExport() (or parseFnDecl) to parse the optional LIB ident + "csym" string after the keyword into FnDecl.extern_lib/extern_name; consume them in declareFunction (mirror the #foreign c_name block at decl.zig:~2119: declare under the C name, map sx→C in foreign_name_map/dedupe). New example renaming a libc symbol (e.g. c_abs :: (n: i32) -> i32 extern "abs";).
2. extern-global g : T extern [LIB] ["csym"]; — parse path at parser.zig:425 (the var-decl with type annotation): accept postfix extern → set VarDecl.is_extern/extern_lib/extern_name; lower like the #foreign global (decl.zig:~1115-1137, .is_extern = vd.is_foreign). New example mirroring examples/1205-ffi-foreign-global with extern.

Stop at end of Phase 1 (do NOT start Phase 2 export or Part B migration). Then the A→B gate: a unit test that #foreign and extern lower to identical IR.

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).

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.