chore(reflaxe): align entrypoint null safety

Author: fullofcaffeine

.beads/issues.jsonl

@@ -430,6 +430,7 @@
 {"_type":"issue","id":"haxe.elixir-5tm","title":"Fix unused function warnings in TodoLive","description":"UNUSED FUNCTIONS: Three private functions in TodoLive.ex are unused: render_todo_item/2 (line 590), render_tags/1 (line 668), is_optimistically_toggled/2 (line 275). Either: (1) These are dead code - remove from Haxe source, (2) DCE should eliminate them, or (3) They should be called somewhere. Investigate in src_haxe/server/live/TodoLive.hx and fix appropriately.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-03T00:01:15Z","updated_at":"2025-12-08T17:24:29Z","closed_at":"2025-12-08T11:24:29Z","dependency_count":0,"dependent_count":1,"comment_count":0}
 {"_type":"issue","id":"haxe.elixir-e0m","title":"Fix app-level unused variables in TodoLive","description":"APP-LEVEL WARNINGS: TodoLive.ex has many unused variables that should be fixed in the Haxe source (src_haxe/server/live/TodoLive.hx): raw_params_completed, raw_params_description, raw_params_due_date, raw_params_priority, raw_params_tags, raw_params_title, raw_params_user_id (in create_todo), broadcast_result, s_optimistic, broadcast, todo_updated, todo_updates (in toggle_todo_status), refreshed_todos, currently_selected (in handle_event). Either use these variables or remove/prefix them in Haxe source.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-03T00:01:08Z","updated_at":"2025-12-08T17:24:29Z","closed_at":"2025-12-08T11:24:29Z","dependency_count":0,"dependent_count":1,"comment_count":0}
 {"_type":"issue","id":"haxe.elixir-upq","title":"Fix unused variable warnings - add underscore prefix in compiler","description":"COMPILER ENHANCEMENT: The compiler generates ~50+ unused variable warnings in Elixir. Variables like 'value', 'this1', 'e', 'o', 'c', 't', 'args', 'cl', 'constr', 'index' are declared but never used. Elixir convention requires prefixing unused variables with underscore (_value, _this1, etc). Fix in code generator to detect unused variables and add underscore prefix automatically. This is a systematic fix, not per-variable.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-03T00:00:59Z","updated_at":"2025-12-08T17:24:35Z","closed_at":"2025-12-08T11:24:35Z","dependency_count":0,"dependent_count":1,"comment_count":0}
+{"_type":"issue","id":"haxe.elixir.codex-et5","title":"Align extraParams null-safety macro with Reflaxe conventions","description":"Add the Reflaxe skeleton-style package-scoped nullSafety macro to Reflaxe.Elixir entrypoint HXML files. This should apply to compiler package code only, before bootstrap/init, without changing target/user semantics.","acceptance_criteria":"extraParams.hxml and repo-local haxe_libraries/reflaxe.elixir.hxml run nullSafety(\"reflaxe.elixir\") before CompilerBootstrap/CompilerInit; docs/changelog mention the convention; package smoke and representative repo-local builds pass; no user/app semantics are changed.","status":"closed","priority":3,"issue_type":"task","owner":"boss@fullofcaffeine.com","created_at":"2026-07-09T14:08:02Z","created_by":"Marcelo Serpa","updated_at":"2026-07-09T14:40:40Z","started_at":"2026-07-09T14:08:11Z","closed_at":"2026-07-09T14:40:40Z","close_reason":"Aligned entrypoint HXML with package-scoped nullSafety before bootstrap/init, documented the convention, made HaxeThrow.value nullable to satisfy the compiler-package null-safety contract, and verified package smoke, quick snapshots, examples compile/output/WAE/runtime, mix-fast, and todo-app sentinel+Playwright.","labels":["cleanup","packaging","reflaxe"],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"haxe.elixir.codex-4vd","title":"Move remaining Haxe std replacements into _std","description":"Move the remaining upstream-colliding Haxe stdlib replacement modules that still live under plain std/haxe/** into std/elixir/_std/**. Keep target-owned local additions under plain std/**. This aligns the source tree with the Reflaxe _std ownership convention without changing compiler semantics.","acceptance_criteria":"Upstream reference modules no longer live as plain std/haxe/** files unless there is a documented exception; target-owned local additions remain under std/**; guard:stdlib-layout and guard:stdlib-parity pass; affected snapshots/examples are updated only for intentional source-map/path drift; package smoke still proves Reflaxe build emits packaged .cross.hx files.","status":"closed","priority":3,"issue_type":"task","owner":"boss@fullofcaffeine.com","created_at":"2026-07-09T12:50:24Z","created_by":"Marcelo Serpa","updated_at":"2026-07-09T13:25:20Z","started_at":"2026-07-09T12:51:52Z","closed_at":"2026-07-09T13:25:20Z","close_reason":"Moved the remaining upstream-colliding plain std/haxe/** modules into std/elixir/_std/** while leaving target-owned support surfaces under std/haxe/**. Added a guard allowlist for remaining plain std/haxe/** support modules, updated docs/changelog, and refreshed generated test source maps for intentional _std path drift. Validation: npm run guard:stdlib-layout; npm run guard:stdlib-parity; npm run guard:docs-links; git diff --check; npm run test:quick; scripts/test-chunks.sh --parallel 8 --chunk-deadline 900 --timeout 120 --categories phoenix,liveview,ecto,otp,exunit,bootstrap; npm run test:haxelib-package; npm run test:examples; npm run test:examples-output; npm run test:examples-elixir; npm run test:examples-runtime; npm run test:haxe-exunit-stdlib; npm run guard:upstream-unitstd; npm run guard:hx-format; npm run test:mix-fast; todo-app async QA sentinel with Playwright e2e/smoke/*.spec.ts (5/5 passed). Path scan found only existing guard/docs examples.","labels":["cleanup","reflaxe","stdlib"],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"haxe.elixir.codex-oky","title":"Update stdlib parity roadmap for early source overrides","description":"After the Reflaxe _std layout cleanup, update stale stdlib parity roadmap/template references that describe early overrides as src/haxe/**/*.cross.hx. The current convention is std/elixir/_std for normal std replacements, target-owned std/** APIs, and selected src/haxe/** early overrides with only haxe.Exception using .cross.hx.","notes":"Updated stdlib parity roadmap/templates so future tasks use std/elixir/_std for normal std overrides, target-owned std/** APIs/support modules, and selected src/haxe/** early overrides. Clarified parity-report comments for plain early src/haxe/ds/*.hx modules. Validation: npm run guard:docs-links, npm run guard:stdlib-parity, npm run guard:stdlib-layout, git diff --check. Path scan reported only existing guard/docs examples.","status":"closed","priority":3,"issue_type":"task","owner":"boss@fullofcaffeine.com","created_at":"2026-07-09T11:14:55Z","created_by":"Marcelo Serpa","updated_at":"2026-07-09T11:16:34Z","started_at":"2026-07-09T11:15:08Z","closed_at":"2026-07-09T11:16:34Z","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"haxe.elixir.codex-uvr","title":"Clarify remaining early haxe.Exception cross override","description":"Audit the lone authored src/haxe/Exception.cross.hx after the Reflaxe _std layout cleanup. Determine whether it can follow the plain .hx early override convention or must remain .cross.hx for macro/tooling safety, then document the result and validate no regressions.","notes":"Resolved as docs-only cleanup. Kept src/haxe/Exception.cross.hx in place because upstream haxe.Exception is extern and only Elixir output needs the concrete Reflaxe.Exception base; documented the selected plain src/haxe/ds/*.hx early override set separately. Validation: npm run guard:docs-links, npm run guard:stdlib-layout, npm run test:quick. Path scan reported only existing guard/docs examples.","status":"closed","priority":3,"issue_type":"task","owner":"boss@fullofcaffeine.com","created_at":"2026-07-09T10:26:06Z","created_by":"Marcelo Serpa","updated_at":"2026-07-09T10:35:18Z","started_at":"2026-07-09T10:26:25Z","closed_at":"2026-07-09T10:35:18Z","dependency_count":0,"dependent_count":0,"comment_count":0}

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 * **reflaxe:** align stdlib override sources with the Reflaxe `_std` layout; source-tree and GitHub/Lix builds now load `std/elixir/_std` before target-owned `std` APIs so PhoenixHx/examples keep using the Elixir stdlib overrides in dev mode.
 * **reflaxe:** move remaining upstream-colliding `std/haxe/**` replacement modules into `std/elixir/_std`, leaving plain `std/haxe/**` for target-owned support surfaces.
+* **reflaxe:** align package entrypoint HXML files with Reflaxe-generated targets by applying package-scoped `nullSafety("reflaxe.elixir")` before bootstrap/init macros.
 * **reflaxe:** audit vendored framework patches against upstream Reflaxe and document which local fixes remain required before they can be removed or upstreamed.
 * **reflaxe:** remove debug-only vendored framework drift while preserving required local Reflaxe patches.
 * **docs:** clarify the remaining early `src/haxe/**` overrides, including why `src/haxe/Exception.cross.hx` intentionally remains the lone source-tree `.cross.hx` file.

docs/03-compiler-development/CROSS_FILES_STAGING_MECHANISM.md

@@ -168,11 +168,14 @@ there would point at the user's project, not at the installed library. Instead,
 does cwd-independent setup:
 
 ```hxml
+--macro nullSafety("reflaxe.elixir")
 --macro reflaxe.elixir.CompilerBootstrap.Start()
 --macro reflaxe.elixir.CompilerInit.Start()
 -D loop_unroll_max_cost=0
 ```
 
+The null-safety macro is scoped to the compiler package (`reflaxe.elixir`), matching Reflaxe-generated
+target entrypoints without applying null-safety metadata to user application packages.
 For repo-local scoped-lib builds, `haxe_libraries/reflaxe.elixir.hxml` plays the same role, but it can
 use `${SCOPE_DIR}` because Lix expands that to this repository's library root.
 

docs/05-architecture/HXML_ARCHITECTURE.md

@@ -198,6 +198,7 @@ still target Phoenix-native namespaces and paths. See the
 ```hxml
 # App builds normally get compiler init from reflaxe.elixir/extraParams.hxml.
 # Spell these macros directly only in repo-internal harnesses or advanced custom builds.
+--macro nullSafety("reflaxe.elixir")
 --macro reflaxe.elixir.CompilerBootstrap.Start()
 --macro reflaxe.elixir.CompilerInit.Start()
 

docs/05-architecture/TARGET_CONDITIONAL_STDLIB_GATING.md

@@ -82,6 +82,8 @@ must shadow the official Haxe stdlib in Elixir builds.
   `-cp ${SCOPE_DIR}/std/elixir/_std/` so source-tree builds see authored std overrides directly;
   `CompilerBootstrap.Start()` still prepends the target paths for Elixir builds so ordering matches
   consumer installs.
+- Added package-scoped `--macro nullSafety("reflaxe.elixir")` before bootstrap/init so the entrypoint
+  HXML files match Reflaxe-generated target conventions without changing user application packages.
 - Added `--macro reflaxe.elixir.CompilerBootstrap.Start()` so repo-local scoped-lib builds get the same package-root classpath insertion behavior as consumer installs.
 - For the handful of modules that must be available before macros run, we place a documented
   bootstrap-safe implementation under `src/haxe/**`. Use this only for concrete early-resolution
@@ -92,11 +94,13 @@ must shadow the official Haxe stdlib in Elixir builds.
 Gating activates (i.e., `std/elixir/_std/` and `std/` are added to the active Haxe classpath) in these scenarios:
 
 - Haxe 5 + Elixir custom target:
+  - `--macro nullSafety("reflaxe.elixir")` may be present through the package entrypoint
   - `--macro reflaxe.elixir.CompilerInit.Start()` is present
   - Platform is `CustomTarget("elixir")`
   - Result: classpath injection runs; Elixir-only overrides are available
 
 - Haxe 4 + Reflaxe.Elixir builds (tests/examples):
+  - `--macro nullSafety("reflaxe.elixir")` may be present through the package entrypoint
   - `--macro reflaxe.elixir.CompilerBootstrap.Start()` is present
   - Elixir build signals:
     - Preferred: `-D elixir_output=...` (stable signal used throughout the harness)

extraParams.hxml

@@ -13,6 +13,7 @@
 # this file run too late to guarantee ownership of every upstream-colliding std
 # module. Reflaxe package builds flatten std/elixir/_std into packaged
 # .cross.hx files, so installed consumers only need `-lib reflaxe.elixir`.
+--macro nullSafety("reflaxe.elixir")
 --macro reflaxe.elixir.CompilerBootstrap.Start()
 --macro reflaxe.elixir.CompilerInit.Start()
 

haxe_libraries/reflaxe.elixir.hxml

@@ -35,6 +35,11 @@
 
 # Define the library version
 -D reflaxe.elixir=0.14.20
+
+# Match Reflaxe-generated target entrypoints: type the compiler package with
+# Haxe null-safety metadata before bootstrap/init macros run.
+--macro nullSafety("reflaxe.elixir")
+
 # Bootstrap early (target-conditional stdlib gating + vendored reflaxe injection)
 --macro reflaxe.elixir.CompilerBootstrap.Start()
 

std/reflaxe/elixir/runtime/HaxeThrow.hx

@@ -46,7 +46,7 @@ import elixir.types.Term;
  */
 @:native("Reflaxe.Elixir.HaxeThrow")
 class HaxeThrow extends haxe.Exception {
-	public var value:Term;
+	public var value:Null<Term>;
 
 	public function new(message:String, ?previous:haxe.Exception, ?native:Any) {
 		super(message, previous, native);