Makefile

.PHONY: all clean test compiler examples ci ci-sweep

# Pin the default goal to `all` regardless of rule order. Without this, the
# first FILE-target rule defined becomes the default goal — and the generated
# version-header rule ($(VERSION_HEADER)) is defined above `all:`, so a bare
# `make` would build only the header. Explicit default goal makes rule order
# irrelevant.
.DEFAULT_GOAL := all

# Detect OS and shell environment.
# WINDOWS_NATIVE is set only for pure Windows (mingw32-make + cmd.exe).
# IS_WINDOWS is set for any Windows variant (native, MSYS2, MinGW, Cygwin).
WINDOWS_NATIVE :=
IS_WINDOWS :=
# WINDOWS=1 — cross-build FOR Windows from a non-Windows host (see the
# "Windows cross-build" block below). Declared here, ahead of host
# detection, because every downstream conditional keys off IS_WINDOWS /
# EXE_EXT: the cross build wants the Windows CODE PATHS with a Linux
# host's shell utilities, so it sets those two and leaves WINDOWS_NATIVE
# (which switches to cmd.exe-isms like `if not exist`) unset.
ifeq ($(WINDOWS),1)
    IS_WINDOWS := 1
    EXE_EXT := .exe
    DETECTED_OS := MINGW64_NT-cross
endif
ifeq ($(OS),Windows_NT)
    IS_WINDOWS := 1
    _UNAME_S := $(shell uname -s 2>&1)
    ifneq ($(findstring MINGW,$(_UNAME_S)),)
        DETECTED_OS := $(_UNAME_S)
        EXE_EXT := .exe
    else ifneq ($(findstring MSYS,$(_UNAME_S)),)
        DETECTED_OS := $(_UNAME_S)
        EXE_EXT := .exe
    else ifneq ($(findstring CYGWIN,$(_UNAME_S)),)
        DETECTED_OS := $(_UNAME_S)
        EXE_EXT := .exe
    else
        DETECTED_OS := Windows
        EXE_EXT := .exe
        WINDOWS_NATIVE := 1
    endif
else ifneq ($(WINDOWS),1)
    DETECTED_OS := $(shell uname -s)
    ifneq ($(findstring MINGW,$(DETECTED_OS)),)
        EXE_EXT := .exe
        IS_WINDOWS := 1
    else ifneq ($(findstring MSYS,$(DETECTED_OS)),)
        EXE_EXT := .exe
        IS_WINDOWS := 1
    else ifneq ($(findstring CYGWIN,$(DETECTED_OS)),)
        EXE_EXT := .exe
        IS_WINDOWS := 1
    else
        EXE_EXT :=
    endif
endif

ifdef WINDOWS_NATIVE
    PATH_SEP := \\
    MKDIR := if not exist
    RM := del /Q
    RM_DIR := rd /S /Q
else
    PATH_SEP := /
    MKDIR := mkdir -p
    RM := rm -f
    RM_DIR := rm -rf
endif

# Parallel job count (override with: make test-ae NPROC=8)
ifdef WINDOWS_NATIVE
NPROC ?= $(shell echo %NUMBER_OF_PROCESSORS% 2>nul || echo 4)
else
NPROC ?= $(shell sysctl -n hw.ncpu 2>/dev/null || nproc 2>/dev/null || echo 4)
endif

# Version: the VERSION FILE IN THIS TREE is authoritative; the highest git tag
# is only a fallback for an untagged dev checkout.
#
# This ordering used to be reversed ("prefer highest git tag"), which mislabels
# a tagged release build. `git tag -l` reports the tags VISIBLE IN THIS CLONE,
# and release.yml's build jobs check out shallow, so the visible set can be
# stale or partial — `tail -1` then lands on an OLDER tag and overrides the
# correct VERSION file. Measured: v0.516.0 shipped an `ae --version` saying
# 0.417.0, while `git show v0.516.0:VERSION` said 0.516.0 all along. The tree
# was right and the tag scan was wrong.
#
# For a tagged build the two should be identical, so preferring the tree costs
# nothing and is immune to clone depth. For a tarball there is no git at all.
# Only an untagged dev checkout — where VERSION is still the 0.0.0 placeholder
# — consults tags, so `make` on a plain main still reports a real-ish number.
#
# One arm now, not two: `cat` covers Windows too (the WINDOWS_NATIVE split
# existed because `git tag` shell-outs are awkward under cmd.exe; a file read
# is not). WINDOWS_NATIVE keeps `type` since cmd.exe has no `cat`.
ifdef WINDOWS_NATIVE
VERSION := $(shell type VERSION 2>nul || echo 0.0.0)
else
VERSION := $(shell cat VERSION 2>/dev/null | tr -d '[:space:]')
ifeq ($(VERSION),)
VERSION := 0.0.0
endif
ifeq ($(VERSION),0.0.0)
VERSION := $(shell git tag -l 'v*.*.*' 2>/dev/null | sed 's/^v//' | sort -t. -k1,1n -k2,2n -k3,3n | tail -1)
ifeq ($(VERSION),)
VERSION := 0.0.0
endif
endif
endif

# Numeric version components, split from $(VERSION) (MAJOR.MINOR.PATCH). A
# trailing pre-release suffix on PATCH (e.g. "0-dev") is stripped to digits.
# These feed the generated runtime/aether_version.h so the macro, the two
# VERSION sidecars, and `aetherc --version` all derive from one source.
VERSION_MAJOR := $(shell echo "$(VERSION)" | cut -d. -f1 | tr -dc 0-9)
VERSION_MINOR := $(shell echo "$(VERSION)" | cut -d. -f2 | tr -dc 0-9)
VERSION_PATCH := $(shell echo "$(VERSION)" | cut -d. -f3 | tr -dc 0-9)
# MAJOR*1_000_000 + MINOR*1_000 + PATCH — the monotonic form for #if gating.
VERSION_NUM := $(shell echo $$(( $(VERSION_MAJOR)*1000000 + $(VERSION_MINOR)*1000 + $(VERSION_PATCH) )))

# Generated, dependency-free version header. Baked into the exact header bytes
# consumers compile against (installed to include/aether/runtime/ by the normal
# `find runtime -name '*.h'` walk), so it cannot desync from the compiler.
# GENERATED — do not commit / edit by hand (gitignored).
#
# This is a real FILE target (depends on VERSION + Makefile), NOT a phony one:
# a phony target used as a build prerequisite makes GNU make treat the depending
# target as perpetually out-of-date in ways that can short-circuit its recipe.
# Build targets take it as an ORDER-ONLY prerequisite (`| $(VERSION_HEADER)`),
# so it's built if missing but never forces a rebuild. It's regenerated only
# when VERSION or the Makefile changes, and written atomically (tmp + mv) and
# only on content change, so the tree is never spuriously dirtied.
VERSION_HEADER := runtime/aether_version.h
$(VERSION_HEADER): VERSION Makefile
	@tmp="$(VERSION_HEADER).tmp.$$$$"; \
	{ \
	  echo "/* Aether SDK version — GENERATED by the Makefile from \$$(VERSION)."; \
	  echo " * Do not edit by hand. Dependency-free (#defines only) so anything,"; \
	  echo " * including the --emit=csrc prologue, can include it cheaply. This is"; \
	  echo " * the static, drift-proof complement to AetherLibMeta.aether_version"; \
	  echo " * (per-artifact runtime metadata). */"; \
	  echo "#ifndef AETHER_VERSION_H"; \
	  echo "#define AETHER_VERSION_H"; \
	  echo ""; \
	  echo "#define AETHER_VERSION       \"$(VERSION)\""; \
	  echo "#define AETHER_VERSION_MAJOR $(VERSION_MAJOR)"; \
	  echo "#define AETHER_VERSION_MINOR $(VERSION_MINOR)"; \
	  echo "#define AETHER_VERSION_PATCH $(VERSION_PATCH)"; \
	  echo "/* MAJOR*1000000 + MINOR*1000 + PATCH — monotonic, for #if gating:"; \
	  echo " *   #if AETHER_VERSION_NUM < 390000"; \
	  echo " *   #  error \"requires Aether >= 0.390\""; \
	  echo " *   #endif */"; \
	  echo "#define AETHER_VERSION_NUM   $(VERSION_NUM)"; \
	  echo ""; \
	  echo "#endif /* AETHER_VERSION_H */"; \
	} > "$$tmp"; \
	if [ -f "$(VERSION_HEADER)" ] && cmp -s "$$tmp" "$(VERSION_HEADER)"; then \
	  rm -f "$$tmp"; \
	else \
	  mv "$$tmp" "$(VERSION_HEADER)"; \
	  echo "Generated $(VERSION_HEADER) (v$(VERSION))"; \
	fi

# Convenience phony alias for explicit regeneration (e.g. `make gen-version-header`).
.PHONY: gen-version-header
gen-version-header: $(VERSION_HEADER)

# #1366: the bare C symbols the stdlib exposes. Codegen renames a user function
# that would collide with one, so this must track std/ automatically: a
# hand-kept list is what let string_replace_all reach a release.
# GENERATED, do not commit or edit by hand (gitignored).
STDLIB_SYMS_HEADER := compiler/codegen/aether_stdlib_symbols.h
STDLIB_MODULE_AE := $(wildcard std/*/module.ae) $(wildcard std/*/*/module.ae)
$(STDLIB_SYMS_HEADER): $(STDLIB_MODULE_AE) Makefile
	@tmp="$(STDLIB_SYMS_HEADER).tmp.$$$$"; \
	{ \
	  echo "/* GENERATED by the Makefile from the std module.ae files. Do not edit. */"; \
	  echo "#ifndef AETHER_STDLIB_SYMBOLS_H"; \
	  echo "#define AETHER_STDLIB_SYMBOLS_H"; \
	  echo "/* Sorted for bsearch. */"; \
	  echo "static const char* const AETHER_STDLIB_SYMBOLS[] = {"; \
	  grep -rhoE '^extern[[:space:]]+[A-Za-z_][A-Za-z0-9_]*' $(STDLIB_MODULE_AE) 2>/dev/null \
	    | awk '{print $$2}' | LC_ALL=C sort -u | sed 's/.*/    "&",/'; \
	  echo "};"; \
	  echo "#define AETHER_STDLIB_SYMBOL_COUNT \\"; \
	  echo "    (sizeof(AETHER_STDLIB_SYMBOLS) / sizeof(AETHER_STDLIB_SYMBOLS[0]))"; \
	  echo "#endif"; \
	} > "$$tmp"; \
	if [ -f "$(STDLIB_SYMS_HEADER)" ] && cmp -s "$$tmp" "$(STDLIB_SYMS_HEADER)"; then \
	  rm -f "$$tmp"; \
	else \
	  mv "$$tmp" "$(STDLIB_SYMS_HEADER)"; \
	  echo "Generated $(STDLIB_SYMS_HEADER)"; \
	fi

.PHONY: gen-stdlib-symbols
gen-stdlib-symbols: $(STDLIB_SYMS_HEADER)

# #1746: the fingerprint of the front end, the code that turns module text
# into an AST (lexer, parser, AST, `when defined` answers, and the artifact
# codec itself). A compiled module artifact (.aea) records it and is only
# decoded by a compiler with the same one, so an edit to any of these files
# retires every artifact built before it. Over-invalidation (a comment edit)
# costs one re-parse; under-invalidation would load a stale AST, so the set
# errs wide. GENERATED, do not commit or edit by hand (gitignored).
FRONTEND_ID_HEADER := compiler/aether_frontend_id.h
FRONTEND_ID_SRC := compiler/ast.h compiler/ast.c compiler/parser/lexer.c \
    compiler/parser/lexer.h compiler/parser/parser.c compiler/parser/parser.h \
    compiler/parser/tokens.h compiler/aether_defines.c compiler/aether_aea.c \
    compiler/aether_aea.h
$(FRONTEND_ID_HEADER): $(FRONTEND_ID_SRC) Makefile
	@tmp="$(FRONTEND_ID_HEADER).tmp.$$$$"; \
	id=$$(cat $(FRONTEND_ID_SRC) | cksum | awk '{print $$1 "-" $$2}'); \
	{ \
	  echo "/* GENERATED by the Makefile from the front-end sources. Do not edit. */"; \
	  echo "#ifndef AETHER_FRONTEND_ID_H"; \
	  echo "#define AETHER_FRONTEND_ID_H"; \
	  echo "#define AETHER_FRONTEND_ID \"$$id\""; \
	  echo "#endif"; \
	} > "$$tmp"; \
	if [ -f "$(FRONTEND_ID_HEADER)" ] && cmp -s "$$tmp" "$(FRONTEND_ID_HEADER)"; then \
	  rm -f "$$tmp"; \
	else \
	  mv "$$tmp" "$(FRONTEND_ID_HEADER)"; \
	  echo "Generated $(FRONTEND_ID_HEADER)"; \
	fi

.PHONY: gen-frontend-id
gen-frontend-id: $(FRONTEND_ID_HEADER)

# #1746: compiled module artifacts for the std tree, into $(BUILD_DIR)/modules/ (the
# layout `make install` puts under $(PREFIX)/lib/aether/modules/). Only an
# installed toolchain reads artifacts; this target is for inspecting them.
.PHONY: modules
modules: compiler
	@rm -rf $(BUILD_DIR)/modules
	@sh scripts/build_module_artifacts.sh $(BUILD_DIR)/aetherc$(EXE_EXT) . $(BUILD_DIR)/modules

# Compiler configuration with ccache support.
# FreeBSD base has no gcc at all (clang is installed as `cc`).
ifdef WINDOWS_NATIVE
CC := gcc
else
BASE_CC := $(shell if command -v gcc >/dev/null 2>&1; then echo gcc; \
                   elif command -v cc >/dev/null 2>&1; then echo cc; \
                   else echo clang; fi)
CC := $(shell command -v ccache >/dev/null 2>&1 && echo "ccache $(BASE_CC)" || echo "$(BASE_CC)")
endif
EXTRA_CFLAGS ?=
PLATFORM ?= native

# Platform-specific overrides
ifeq ($(PLATFORM),wasm)
    CC := emcc
    EXTRA_CFLAGS += -DAETHER_NO_THREADING -DAETHER_NO_FILESYSTEM -DAETHER_NO_NETWORKING
    SCHEDULER_SRC := runtime/scheduler/aether_scheduler_coop.c
else ifeq ($(PLATFORM),embedded)
    EXTRA_CFLAGS += -DAETHER_NO_THREADING -DAETHER_NO_FILESYSTEM -DAETHER_NO_NETWORKING -DAETHER_NO_GETENV
    SCHEDULER_SRC := runtime/scheduler/aether_scheduler_coop.c
else
    # Auto-detect: if EXTRA_CFLAGS disables threading, use cooperative scheduler
    ifneq ($(findstring AETHER_NO_THREADING,$(EXTRA_CFLAGS)),)
        SCHEDULER_SRC := runtime/scheduler/aether_scheduler_coop.c
    else
        SCHEDULER_SRC := runtime/scheduler/multicore_scheduler.c
    endif
endif

# ---------------------------------------------------------------------------
# FreeBSD cross-build (FREEBSD=1) — build the ae/aetherc toolchain FOR FreeBSD
# from a Linux (or any) host, via `zig cc`. GitHub Actions has no native
# FreeBSD runner, so the release FreeBSD zip is produced this way. This mirrors
# the link recipe tools/ae_cross.c uses for `ae build --target=x86_64-freebsd`,
# but applied to the compiler's own C sources through the Makefile's CC/LDFLAGS.
#
# Required inputs:
#   ZIG            path to a zig 0.16.0+ binary           e.g. .../zig
#   AETHER_SYSROOT FreeBSD base sysroot (headers + libc)  e.g. .../bases/x86_64-freebsd15
# Provision Zig with this repo's scripts/get-zig.sh and the FreeBSD base with
# aether-crossbuild's fetch-freebsd-base.sh.
#
# Notes:
#   - Zig 0.16 supplies the FreeBSD CRT/libc. The base sysroot supplies system
#     headers and FreeBSD-only libraries such as Casper and libthr.
#   - casper libs are ALWAYS needed: std/casper/aether_casper.c is
#     unconditionally in the build and references cap_*; the base ships them.
#   - Optional Tier-2 libs (OpenSSL/zlib/nghttp2/brotli/zstd) are forced
#     OFF for the cross build: pkg-config on the host would find the host's
#     Linux libs and poison the FreeBSD binary. A cross build ships those std
#     features as their "unavailable" stubs (same as any build without them);
#     a future crossbuild-sysroot-staged variant can re-enable them. PCRE2 and
#     libfyaml are the vendored copies, so std.regex and std.yaml work.
FREEBSD_CPU ?= x86_64
FREEBSD_ABI ?= 15.0
ifeq ($(FREEBSD),1)
  ifeq ($(ZIG),)
    $(error FREEBSD=1 needs ZIG=<path to zig> (>= 0.16.0))
  endif
  ifeq ($(AETHER_SYSROOT),)
    $(error FREEBSD=1 needs AETHER_SYSROOT=<FreeBSD base sysroot>)
  endif
  # Zig 0.16 supplies the FreeBSD CRT/libc. State the ABI version explicitly so
  # its startup objects match the FreeBSD 15 base used for the remaining system
  # libraries. Target-root -L paths are resolved beneath --sysroot; passing the
  # already-prefixed host paths makes Zig prefix the sysroot a second time.
  CC := $(ZIG) cc -target $(FREEBSD_CPU)-freebsd.$(FREEBSD_ABI) --sysroot=$(AETHER_SYSROOT) -I$(AETHER_SYSROOT)/usr/include
  # zig's archiver, as WINDOWS=1 uses: macOS's ar writes no symbol index for
  # ELF objects, and FreeBSD's linker then found nothing in a libaether.a
  # cross-built from a Mac (GNU ar on the Linux release runner did).
  AR := $(ZIG) ar
  RANLIB := $(ZIG) ranlib
  # Host pkg-config is wrong for the target — force the optional libs off.
  OPENSSL := 0
  ZLIB := 0
  NGHTTP2 := 0
  BROTLI := 0
  ZSTD := 0
  # std.yaml's libfyaml is vendored too, so the cross build has it with no
  # host library involved (it shipped the stubs before).
  YAML := vendored
  # PCRE2 has a vendored in-tree fallback (no host library involved), as the
  # Windows and Android cross builds use. PCRE2 := 0 here shipped the FreeBSD
  # release with std.regex as its refusing stub: every regex.compile failed
  # with "built without libpcre2-8".
  PCRE2 := vendored
  # Link the FreeBSD-only libraries from the base sysroot. Zig supplies the
  # CRT and libc for this target; adding the base's startup objects as well
  # would duplicate `_start`. Overrides the native LDFLAGS assembly below.
  FREEBSD_LDFLAGS := -L/usr/lib -L/lib -lthr -lm \
    -lcasper -lcap_pwd -lcap_sysctl -lcap_grp -lcap_dns
endif

# ---------------------------------------------------------------------------
# Windows cross-build (WINDOWS=1) — build the ae/aetherc toolchain FOR Windows
# from a Linux (or any) host, via `zig cc -target x86_64-windows-gnu` (#1592).
# Companion to FREEBSD=1 above, and deliberately simpler: zig BUNDLES the
# mingw-w64 headers and CRT sources and builds them on demand, so unlike the
# FreeBSD leg there is NO sysroot to fetch and no -nostdlib CRT bookkeeping.
#
# Required input:
#   ZIG   path to a zig 0.16.0+ binary     e.g. .../zig
# Provision with this repo's scripts/get-zig.sh (same as FreeBSD CI).
#
# Purpose is a FAST Windows signal on a Linux runner (#1593): the MSYS2 legs
# take ~20 minutes, so Windows-specific compile breakage is discovered long
# after the author moved on. This lane compiles the same code
# paths in a few minutes. It is an EARLIER signal, never a replacement — the
# MSYS2 jobs stay the fidelity tip.
#
# Capability-lean by design: the optional Tier-2 libs are forced OFF, exactly
# as the FreeBSD cross does and for the same reason — host pkg-config would
# find the host's Linux libs and poison the Windows binary. Cross-compiling
# OpenSSL/nghttp2 for windows-gnu is the genuinely expensive part and is out
# of scope; std ships those features as their "unavailable" stubs. Vendored
# PCRE2 and libfyaml need no host library, so std.regex and std.yaml stay
# available.
WINDOWS_CPU ?= x86_64
ifeq ($(WINDOWS),1)
  ifeq ($(ZIG),)
    $(error WINDOWS=1 needs ZIG=<path to zig> (>= 0.16.0))
  endif
  CC := $(ZIG) cc -target $(WINDOWS_CPU)-windows-gnu
  AR := $(ZIG) ar
  RANLIB := $(ZIG) ranlib
  # Host pkg-config is wrong for the target — force the optional libs off.
  OPENSSL := 0
  ZLIB := 0
  NGHTTP2 := 0
  # std.yaml's libfyaml is vendored: no host library involved.
  YAML := vendored
  # Same reason as the three above: the HOST's pkg-config would happily report
  # a libbrotlienc/libzstd that the cross toolchain has no headers for, and
  # the source then #includes a header zig cannot find. Both stub cleanly.
  BROTLI := 0
  ZSTD := 0
  # PCRE2 has a vendored in-tree fallback (no host library involved), so
  # std.regex survives the cross build.
  PCRE2 := vendored
  # NB __USE_MINGW_ANSI_STDIO=1 still applies (it keys off IS_WINDOWS
  # below): zig ships mingw-w64's libmingwex, so the __mingw_* printf
  # family resolves exactly as it does under MSYS2. Verified by a clean
  # cross-build + link of compiler/ae/stdlib.
endif

# ---------------------------------------------------------------------------
# Android cross-build (ANDROID=1) — build the ae/aetherc toolchain FOR Android
# (bionic libc) from a Linux or macOS host, with the Android NDK's clang. Zig
# can name the target but ships no bionic, so the NDK is the toolchain here;
# GitHub's ubuntu runners carry one ($ANDROID_NDK_LATEST_HOME).
#
# Required input:
#   ANDROID_NDK   an Android NDK (r26+)       e.g. .../android-ndk-r27c
# Optional:
#   ANDROID_CPU   aarch64 (default)
#   ANDROID_API   minimum API level, 29 (Android 10) by default
#
# Capability-lean like the other cross builds, for the same reason: the host's
# pkg-config would report the host's libraries. The optional Tier-2 libs are
# off (std ships those features as their "unavailable" stubs); PCRE2 and
# libfyaml are the vendored copies, so std.regex and std.yaml survive. The result is built, not tested: no
# Android runner runs the suite.
ANDROID_CPU ?= aarch64
ANDROID_API ?= 29
ifeq ($(ANDROID),1)
  ifeq ($(ANDROID_NDK),)
    $(error ANDROID=1 needs ANDROID_NDK=<path to an Android NDK>)
  endif
  ifeq ($(shell uname -s),Darwin)
    ANDROID_NDK_HOST := darwin-x86_64
  else
    ANDROID_NDK_HOST := linux-x86_64
  endif
  ANDROID_NDK_BIN := $(ANDROID_NDK)/toolchains/llvm/prebuilt/$(ANDROID_NDK_HOST)/bin
  CC := $(ANDROID_NDK_BIN)/$(ANDROID_CPU)-linux-android$(ANDROID_API)-clang
  AR := $(ANDROID_NDK_BIN)/llvm-ar
  RANLIB := $(ANDROID_NDK_BIN)/llvm-ranlib
  OPENSSL := 0
  ZLIB := 0
  NGHTTP2 := 0
  BROTLI := 0
  ZSTD := 0
  PCRE2 := vendored
  YAML := vendored
endif

# Objects and archives of different targets do not mix (a native link against
# PE objects dies deep in the link with confusing errors), so each target
# builds into its own tree, named by BUILD_TARGET_ID.
ifeq ($(WINDOWS),1)
  BUILD_TARGET_ID := windows-$(WINDOWS_CPU)
else ifeq ($(ANDROID),1)
  BUILD_TARGET_ID := android-$(ANDROID_CPU)
else ifeq ($(FREEBSD),1)
  BUILD_TARGET_ID := freebsd-$(FREEBSD_CPU)
else
  BUILD_TARGET_ID := native-$(DETECTED_OS)
endif
# #2321: the native build stays flat in build/, where every test, `ae` and the
# release packaging look for it; a cross build is quarantined under
# build/.alien/<target>/, so a warm native build and a warm cross build coexist
# and switching between them rebuilds nothing. Every path below goes through
# $(BUILD_DIR), which is why this sits ahead of all of them.
ifneq ($(filter native-%,$(BUILD_TARGET_ID)),)
  BUILD_DIR := build
else
  BUILD_DIR := build/.alien/$(BUILD_TARGET_ID)
endif
# Each tree records the target it holds. With one tree per target the guard
# below can only fire on a tree built before the split (a flat build/ that a
# cross build filled), which `make clean` resolves.
BUILD_TARGET_STAMP := $(BUILD_DIR)/.build-target
_STAMPED := $(strip $(shell cat $(BUILD_TARGET_STAMP) 2>/dev/null))
# The check runs at PARSE time, so it must not fire for the very goals that
# resolve it: `make clean` (and clean-ish goals) would otherwise be
# unreachable — the guard would block the only way out of the state it is
# complaining about. $(MAKECMDGOALS) is empty for a bare `make` (== all).
_CLEAN_ONLY := $(if $(strip $(filter-out clean distclean help,$(or $(MAKECMDGOALS),all))),,1)
ifneq ($(_STAMPED),)
ifneq ($(_STAMPED),$(BUILD_TARGET_ID))
ifneq ($(_CLEAN_ONLY),1)
$(error $(BUILD_DIR)/ holds $(_STAMPED) artifacts but this is a $(BUILD_TARGET_ID) build. \
It was filled before cross builds moved to build/.alien/<target>/ \
(#2321); run `make clean` once)
endif
endif
endif

# MinGW / MSYS2 (native Windows): bind the printf family to the
# C99-conformant __mingw_* implementations instead of legacy MSVCRT.
# MSVCRT mishandles the C99 conversions we emit (%lld / %llu / %zu / %g)
# and makes vsnprintf(NULL, 0, ...) return -1 instead of the would-be
# length — the latter breaks the two-pass sizing in the generated
# string-interpolation helper, yielding empty interpolated strings
# (#681). The generated `.c` also self-defines this before <stdio.h>;
# setting it here additionally covers the compiler, runtime, and stdlib
# translation units (which use snprintf/vsnprintf in os/json/etc.).
ifdef IS_WINDOWS
EXTRA_CFLAGS += -D__USE_MINGW_ANSI_STDIO=1
endif

# Windows application manifest (#2077): declares the UTF-8 process code page
# so the C runtime and the narrow Win32 calls read Aether's UTF-8 strings as
# UTF-8. Compiled with windres into one resource object that is linked into
# ae.exe, aetherc.exe and, by `ae build`/`ae run`, into every executable they
# produce (it is looked up beside libaether.a). Native MSYS2 builds only:
# the zig cross build has no windres, and its output carries no manifest.
MANIFEST_OBJ :=
ifdef IS_WINDOWS
  ifneq ($(WINDOWS),1)
    WINDRES ?= windres
    MANIFEST_OBJ := $(BUILD_DIR)/aether_manifest.o
  endif
endif

# Windows: the C entry point of an --emit=obj object
# (runtime/windows/aether_lib_main.c). Elsewhere the object carries a weak
# main(); a COFF weak definition does not reliably keep libmingw32's WinMain
# entry out of the link, so on Windows the entry is this one-member archive,
# which `ae cflags --libs` names ahead of -laether: linked only when the
# program has no main() of its own. Kept out of libaether.a because the shared
# runtime DLL is linked from that whole archive and must define no main.
LIB_MAIN_ARCHIVE :=
ifdef IS_WINDOWS
  LIB_MAIN_ARCHIVE := $(BUILD_DIR)/libaether_main.a
endif

# Optional OpenSSL detection (enables HTTPS client). Probes pkg-config;
# falls back silently if OpenSSL isn't installed — the HTTP client still
# works for `http://` URLs and returns a clean error for `https://`.
# Override with OPENSSL=0 to force-disable.
OPENSSL ?= auto
ifeq ($(OPENSSL),auto)
  OPENSSL_CFLAGS := $(shell pkg-config --cflags openssl 2>/dev/null)
  OPENSSL_LDFLAGS := $(shell pkg-config --libs openssl 2>/dev/null)
else ifeq ($(OPENSSL),1)
  OPENSSL_CFLAGS := $(shell pkg-config --cflags openssl 2>/dev/null)
  OPENSSL_LDFLAGS := $(shell pkg-config --libs openssl 2>/dev/null)
else
  OPENSSL_CFLAGS :=
  OPENSSL_LDFLAGS :=
endif
ifneq ($(OPENSSL_LDFLAGS),)
  OPENSSL_CFLAGS += -DAETHER_HAS_OPENSSL
endif

# zlib auto-detection: same pattern as OpenSSL. zlib is ambient on every
# POSIX box we care about; when absent (bare embedded, etc.) the stdlib
# wrappers report "zlib unavailable" cleanly.
# zlib auto-detection. pkg-config first, then an actual compile-and-link
# probe (#1690).
#
# The probe alone is not enough on macOS: the SDK ships libz and zlib.h
# but NO zlib.pc, so `pkg-config --libs zlib` fails while `-lz` links
# and runs. Detection therefore reported "no zlib", every gzip response
# came back uncompressed, and tests/integration/http_middleware_d2
# failed on that leg with no hint that a dependency was missing — the
# gzip middleware was behaving correctly for a build without a backend.
#
# The fallback compiles and links a one-liner against -lz rather than
# looking for a file, so it answers the question that actually matters:
# will this link. Kept second so a box where pkg-config DOES know about
# zlib (a non-default prefix, a cross sysroot) still gets its flags.
ZLIB ?= auto
ifeq ($(ZLIB),0)
  ZLIB_CFLAGS :=
  ZLIB_LDFLAGS :=
else
  ZLIB_CFLAGS := $(shell pkg-config --cflags zlib 2>/dev/null)
  ZLIB_LDFLAGS := $(shell pkg-config --libs zlib 2>/dev/null)
  ifeq ($(ZLIB_LDFLAGS),)
    ZLIB_LDFLAGS := $(shell sh tests/scripts/probe_zlib.sh "$(CC)" 2>/dev/null)
  endif
endif
ifneq ($(ZLIB_LDFLAGS),)
  ZLIB_CFLAGS += -DAETHER_HAS_ZLIB
endif

# nghttp2 auto-detection: enables HTTP/2 server-side handling
# (frame parsing, HPACK encode/decode, stream state machine, flow
# control) by wrapping libnghttp2. Same pkg-config probe shape as
# OpenSSL/zlib; when absent, http_server_set_h2 returns
# "HTTP/2 unavailable: built without libnghttp2" and HTTP/1.1
# remains the only protocol the server speaks. Issue #260 Tier 2.
NGHTTP2 ?= auto
ifeq ($(NGHTTP2),auto)
  NGHTTP2_CFLAGS := $(shell pkg-config --cflags libnghttp2 2>/dev/null)
  NGHTTP2_LDFLAGS := $(shell pkg-config --libs libnghttp2 2>/dev/null)
else ifeq ($(NGHTTP2),1)
  NGHTTP2_CFLAGS := $(shell pkg-config --cflags libnghttp2 2>/dev/null)
  NGHTTP2_LDFLAGS := $(shell pkg-config --libs libnghttp2 2>/dev/null)
else
  NGHTTP2_CFLAGS :=
  NGHTTP2_LDFLAGS :=
endif
ifneq ($(NGHTTP2_LDFLAGS),)
  NGHTTP2_CFLAGS += -DAETHER_HAS_NGHTTP2
  # #1896: nghttp2.h declares its API __declspec(dllimport) unless
  # NGHTTP2_STATICLIB is defined (nghttp2.h:58-65). Without it every call
  # compiles to an __imp_nghttp2_* reference, which the static libnghttp2.a
  # the link actually uses cannot satisfy -- hence dozens of
  # "undefined reference to `__imp_nghttp2_session_*'" on MinGW/MSYS2. The
  # Windows link line is -static (WIN_LINK_LIBS), so the headers have to be
  # told the same thing the linker was told.
  ifneq ($(findstring MINGW,$(DETECTED_OS))$(findstring MSYS,$(DETECTED_OS))$(findstring CYGWIN,$(DETECTED_OS)),)
    NGHTTP2_CFLAGS += -DNGHTTP2_STATICLIB
  endif
endif

# Brotli detection: enables std.brotli (RFC 7932). `br` is what current
# browsers actually prefer over gzip in Accept-Encoding, so this is the
# higher-value codec for HTTP specifically. Same pkg-config probe shape as
# zlib/nghttp2; when absent, brotli.stream_new reports "brotli unavailable"
# and a server negotiating content-encoding falls back to gzip. Issue #1891.
BROTLI ?= auto
ifeq ($(BROTLI),0)
  BROTLI_CFLAGS :=
  BROTLI_LDFLAGS :=
else
  BROTLI_CFLAGS := $(shell pkg-config --cflags libbrotlienc libbrotlidec 2>/dev/null)
  # --static so libbrotlicommon comes with it. It is a Requires.private of
  # libbrotlienc and libbrotlidec, so a plain --libs omits it -- fine when the
  # loader resolves a shared object, fatal on a static link: MinGW's ld then
  # reports a wall of undefined BrotliGetDictionary / BrotliDefaultAllocFunc /
  # _kBrotli* references from inside libbrotlienc.a itself. Found on a real
  # MSYS2 box; a Linux shared link hides it entirely. Asking for both
  # libraries names -lbrotlicommon twice, and the link line must name each
  # library once (optional_library_linking checks), so keep the LAST of each:
  # a static link resolves left to right, and -lbrotlicommon has to follow
  # libbrotlidec as well as libbrotlienc.
  BROTLI_LDFLAGS := $(shell pkg-config --static --libs libbrotlienc libbrotlidec 2>/dev/null \
    | awk '{ o = ""; for (i = NF; i > 0; i--) if (!seen[$$i]++) o = $$i " " o; print o }')
endif
ifneq ($(BROTLI_LDFLAGS),)
  BROTLI_CFLAGS += -DAETHER_HAS_BROTLI
endif

# zstd detection: enables std.zstd (RFC 8878). A different FORMAT from
# DEFLATE, not a faster zlib -- its case is strongest away from the browser
# (archives, logs, snapshots, internal RPC), since Content-Encoding: zstd
# support is thinner than br/gzip. Same pkg-config probe shape as the others;
# when absent, zstd.stream_new reports "zstd unavailable". Issue #1891.
ZSTD ?= auto
ifeq ($(ZSTD),0)
  ZSTD_CFLAGS :=
  ZSTD_LDFLAGS :=
else
  ZSTD_CFLAGS := $(shell pkg-config --cflags libzstd 2>/dev/null)
  ZSTD_LDFLAGS := $(shell pkg-config --libs libzstd 2>/dev/null)
endif
ifneq ($(ZSTD_LDFLAGS),)
  ZSTD_CFLAGS += -DAETHER_HAS_ZSTD
endif

# PCRE2 detection: enables std.regex (full Perl-compatible regex —
# captures, $-substitutions, Unicode, look-around, etc.). A system
# libpcre2-8 found by pkg-config is preferred (distro security updates
# keep covering it); without one the build compiles the vendored copy in
# std/regex/pcre2/ instead (#1389), so std.regex works everywhere rather
# than silently degrading to its "built without libpcre2-8" stub — the
# failure mode that cost aether-ui 8 rounds of misdiagnosis. PCRE2=0
# opts out entirely (stub mode, for minimal builds); PCRE2=vendored
# forces the vendored engine even when a system library exists.
PCRE2 ?= auto
ifeq ($(PCRE2),auto)
  PCRE2_CFLAGS := $(shell pkg-config --cflags libpcre2-8 2>/dev/null)
  PCRE2_LDFLAGS := $(shell pkg-config --libs libpcre2-8 2>/dev/null)
else ifeq ($(PCRE2),1)
  PCRE2_CFLAGS := $(shell pkg-config --cflags libpcre2-8 2>/dev/null)
  PCRE2_LDFLAGS := $(shell pkg-config --libs libpcre2-8 2>/dev/null)
else
  # PCRE2=0 — regex deliberately disabled. std.regex now REFUSES to compile its
  # no-op stubs unless asked by name, so that a build which merely forgot the
  # defines fails loudly instead of stubbing every regex call at runtime. This
  # is the one build that genuinely wants them, so it opts in explicitly.
  PCRE2_CFLAGS := -DAETHER_REGEX_ALLOW_STUB
  PCRE2_LDFLAGS :=
endif
ifneq ($(PCRE2_LDFLAGS),)
  PCRE2_CFLAGS += -DAETHER_HAS_PCRE2
  # On Windows/MinGW we link the STATIC libpcre2-8.a; without PCRE2_STATIC the
  # pcre2.h prototypes default to __declspec(dllimport), so the linker looks for
  # __imp_pcre2_* import stubs that the static lib doesn't provide. Define it so
  # the header declares plain symbols matching the static archive.
  ifneq ($(IS_WINDOWS),)
    PCRE2_CFLAGS += -DPCRE2_STATIC
  endif
else ifneq ($(PCRE2),0)
  # No system libpcre2-8 (or PCRE2=vendored): build the vendored engine.
  # AETHER_VENDOR_PCRE2 turns std/regex/aether_pcre2_vendored.c from an
  # empty TU into the full unity build, and switches aether_regex.c to
  # the in-tree pcre2.h. PCRE2_LDFLAGS stays empty on purpose — the
  # engine is inside libaether.a, so no -l flag may be emitted anywhere
  # (AETHER_PCRE2_LIBS's emptiness is load-bearing, as with every other
  # capability macro).
  PCRE2_CFLAGS := -DAETHER_HAS_PCRE2 -DAETHER_VENDOR_PCRE2
endif

# YAML: std.yaml's libfyaml.
#   YAML=vendored (default)  the in-tree copy in std/yaml/libfyaml/, compiled
#                        into libaether.a by std/yaml/aether_libfyaml_vendored.c,
#                        as std.regex does with PCRE2. No system library and
#                        no -lfyaml anywhere: before this, a release built
#                        against a system libfyaml put -lfyaml in `ae cflags
#                        --libs`, so every program on a machine without the
#                        library failed to link, hello-world included.
#   YAML=1               a system libfyaml, REQUIRED: the build stops here
#                        without it. Programs importing std.yaml link -lfyaml.
#   YAML=auto            a system libfyaml if pkg-config finds one, else the
#                        vendored copy (PCRE2=auto's rule).
#   YAML=0               the stubs, deliberately: every entry point reports
#                        "std.yaml unavailable" at run time.
YAML ?= vendored
# YAML_MODE is YAML with auto resolved: a variable given on the command line
# cannot be reassigned inside the Makefile, so YAML itself is never changed.
YAML_MODE := $(YAML)
ifeq ($(YAML),auto)
  YAML_CFLAGS := $(shell pkg-config --cflags libfyaml 2>/dev/null)
  YAML_LDFLAGS := $(shell pkg-config --libs libfyaml 2>/dev/null)
  ifeq ($(YAML_LDFLAGS),)
    YAML_MODE := vendored
  endif
else ifeq ($(YAML),1)
  YAML_CFLAGS := $(shell pkg-config --cflags libfyaml 2>/dev/null)
  YAML_LDFLAGS := $(shell pkg-config --libs libfyaml 2>/dev/null)
  ifeq ($(YAML_LDFLAGS),)
    $(error YAML=1 but pkg-config finds no libfyaml: install it (apt libfyaml-dev, brew libfyaml, pkg libfyaml, MSYS2 mingw-w64-x86_64-libfyaml) or build with YAML=vendored (the default) / YAML=0)
  endif
else ifeq ($(YAML),vendored)
else ifeq ($(YAML),0)
else
  $(error YAML=$(YAML): use vendored (the default), 1, auto or 0)
endif
ifeq ($(YAML_MODE),vendored)
  # AETHER_VENDOR_YAML turns std/yaml/aether_libfyaml_vendored.c from an
  # empty TU into the whole library, and makes aether_yaml.c use its renamed
  # (aether_fy_*) symbols. The library includes its public headers as
  # <libfyaml.h>, so its include/ goes on the path, as YAML_VENDOR_INC: it
  # sits in AETHER_REQUIRED_CFLAGS ahead of every pkg-config -I, since one of
  # those can be the directory a system libfyaml's headers (another version)
  # are in. FreeBSD's -I/usr/local/include from nghttp2 and friends did
  # exactly that with pkg's libfyaml 0.9 installed. The
  # -idirafter directory stands in for <mach/mach_vm.h> where a toolchain
  # has none (zig's macOS headers), after every system directory.
  # YAML_LDFLAGS stays empty on purpose: the library is inside libaether.a,
  # so no -l flag may be emitted anywhere (AETHER_YAML_LIBS's emptiness is
  # what keeps -lfyaml out of `ae cflags --libs` and every link).
  YAML_CFLAGS := -DAETHER_HAS_YAML -DAETHER_VENDOR_YAML -idirafter std/yaml/libfyaml_compat
  YAML_VENDOR_INC := -Istd/yaml/libfyaml/include
  YAML_LDFLAGS :=
else ifneq ($(YAML_LDFLAGS),)
  # A system libfyaml (YAML=1, or auto that found one): compile the real
  # bindings + link it.
  YAML_CFLAGS += -DAETHER_HAS_YAML
  # #1896: on MinGW/MSYS2 the link line carries -static (WIN_LINK_LIBS below),
  # which avoids libwinpthread/libgcc DLL dependencies in release binaries.
  # -static is NOT positional for library resolution -- it governs the whole
  # link -- so ld demands libfyaml.a. MSYS2's mingw-w64-x86_64-libfyaml ships
  # ONLY libfyaml.dll.a, so the link fails with "cannot find -lfyaml" even
  # though the library is installed and pkg-config reports it correctly.
  # fyaml is the only one of our dependencies with no static archive there
  # (openssl, zlib, nghttp2, pcre2, brotli and zstd all have both), so scope
  # the exception to it rather than dropping -static and giving every Windows
  # binary a DLL tail. (The vendored default avoids this altogether.)
  ifneq ($(findstring MINGW,$(DETECTED_OS))$(findstring MSYS,$(DETECTED_OS))$(findstring CYGWIN,$(DETECTED_OS)),)
    YAML_LDFLAGS := -Wl,-Bdynamic $(YAML_LDFLAGS) -Wl,-Bstatic
  endif
else
  # YAML=0: define NOTHING and link NOTHING, so aether_yaml.c compiles its
  # unavailable-stub path and aether_libfyaml_vendored.c an empty TU.
  YAML_CFLAGS :=
  YAML_LDFLAGS :=
endif

# #959: homebrew's pkg-config .pc files emit versioned
# `-L/opt/homebrew/Cellar/<pkg>/<version>/lib` paths. Those `-L` dirs get
# baked into the shipped `ae` binary (via -DAETHER_*_LIBS below) and break
# every user `ae build` with `ld: library 'ssl' not found` the moment the
# formula is upgraded to a new version. Rewrite each Cellar path to the
# version-agnostic `/opt/homebrew/opt/<pkg>` symlink homebrew always keeps
# pointed at the current version. A no-op on layouts without `/Cellar/`
# (Linux, MacPorts, custom prefixes), so it applies unconditionally. The
# CFLAGS keep the as-probed paths — they are only used to build Aether
# itself (where the probed version is present), never baked into user builds.
cellar_to_opt = $(shell printf '%s' '$(1)' | sed 's|/Cellar/\([^/]*\)/[^/]*|/opt/\1|g')
OPENSSL_LDFLAGS := $(call cellar_to_opt,$(OPENSSL_LDFLAGS))
ZLIB_LDFLAGS    := $(call cellar_to_opt,$(ZLIB_LDFLAGS))
NGHTTP2_LDFLAGS := $(call cellar_to_opt,$(NGHTTP2_LDFLAGS))
PCRE2_LDFLAGS   := $(call cellar_to_opt,$(PCRE2_LDFLAGS))
BROTLI_LDFLAGS  := $(call cellar_to_opt,$(BROTLI_LDFLAGS))
ZSTD_LDFLAGS    := $(call cellar_to_opt,$(ZSTD_LDFLAGS))
YAML_LDFLAGS    := $(call cellar_to_opt,$(YAML_LDFLAGS))

# -fPIC on every runtime/stdlib object so the precompiled `build/libaether.a`
# can be linked into a shared object by `ae build --emit=lib`. Without it,
# any `--emit=lib` build that pulls in a TLS-using runtime object (e.g.
# std.http's `aether_http.o`, whose initial-exec TLS emits an
# R_X86_64_TPOFF32 relocation illegal in a `.so`) fails to link
# (vcr_embed_abi_wish.md Part A). Negligible codegen cost on x86-64/arm64
# (most distros already default to PIE); one archive serves both the exe
# link and the shared-object link.
# Two kinds of flag, kept apart on purpose.
#
# AETHER_REQUIRED_CFLAGS is structural: the include paths, dependency
# generation, and the defines that select which code is compiled in. The build
# is not merely slower without them, it is a different build.
#
# CFLAGS is the tunable half: optimisation, debug info, warnings, sanitizers.
# Callers replace it wholesale and are right to, e.g.
#
#     make test-build CFLAGS="-O0 -g"                       (valgrind leg)
#     make compiler   CFLAGS="-fsanitize=address ... -O1 -g" (ASan leg)
#
# They were previously one variable, so those commands did far more than they
# said: every -I disappeared, and with them -DAETHER_HAS_SANDBOX, which gates
# real code in runtime/aether_sandbox.c. The sanitizer and valgrind legs were
# therefore testing a configuration that never ships. It stayed invisible
# because the remaining includes all resolved same-directory or relatively,
# until a header outside those trees (include/libaether.h, #1420) finally made
# it fail out loud.
#
# Recipes use `$(AETHER_REQUIRED_CFLAGS) $(CFLAGS)` so tuning one cannot
# silently delete the other.
AETHER_REQUIRED_CFLAGS = -fPIC -Iinclude -Icompiler -Iruntime -Iruntime/actors -Iruntime/scheduler -Iruntime/utils -Iruntime/memory -Iruntime/config -Istd -Istd/string -Istd/io -Istd/math -Istd/net -Istd/collections -Istd/json -Istd/yaml $(YAML_VENDOR_INC) -MMD -MP -DAETHER_VERSION=\"$(VERSION)\" -DAETHER_HAS_SANDBOX $(OPENSSL_CFLAGS) $(ZLIB_CFLAGS) $(NGHTTP2_CFLAGS) $(PCRE2_CFLAGS) $(YAML_CFLAGS) $(BROTLI_CFLAGS) $(ZSTD_CFLAGS)

CFLAGS = -O2 -Wall -Wextra -Wstrict-prototypes -Wno-unused-parameter -Wno-unused-function $(EXTRA_CFLAGS)
# Casper link libraries (FreeBSD only) — std.casper delegates DNS /
# passwd / sysctl past Capsicum capability mode. libcasper + the
# per-service libs ship in the FreeBSD base system. We resolve them by
# globbing the actual shared-object filenames rather than relying on
# `-lcasper` (the `.so` linker symlinks are absent on some installs,
# e.g. GhostBSD) or hardcoding a soname version (libcap_sysctl is at
# .so.2 while its siblings are at .so.1). Empty if the libs aren't
# present — std.casper then links its non-FreeBSD stub path.
CASPER_LDFLAGS :=
ifeq ($(shell uname -s),FreeBSD)
  CASPER_LDFLAGS := $(firstword $(wildcard /lib/libcasper.so.* /usr/lib/libcasper.so.*)) \
                    $(firstword $(wildcard /lib/libcap_net.so.* /usr/lib/libcap_net.so.*)) \
                    $(firstword $(wildcard /lib/libcap_pwd.so.* /usr/lib/libcap_pwd.so.*)) \
                    $(firstword $(wildcard /lib/libcap_sysctl.so.* /usr/lib/libcap_sysctl.so.*))
endif

# std.audio's vendored miniaudio backend (std/audio/miniaudio.h). miniaudio
# dlopens the actual OS audio backends (ALSA/PulseAudio/sndio) at runtime, so
# only the loader/threads/math libs are needed at link time; macOS needs the
# audio frameworks. Windows folds its audio into the existing WIN_LINK_LIBs.
AUDIO_LDFLAGS :=
# Keyed on the HOST uname, so a cross build must opt out explicitly or it
# picks up the host's POSIX libs (zig-lld: "unable to find dynamic system
# library 'pthread'"). Windows folds audio into WIN_LINK_LIBS either way.
ifeq ($(WINDOWS),1)
  AUDIO_LDFLAGS :=
else ifeq ($(ANDROID),1)
  # bionic has threads in libc (no separate libpthread to link).
  AUDIO_LDFLAGS := -ldl -lm
else ifeq ($(FREEBSD),1)
  # A FreeBSD cross build takes FreeBSD's, whatever the host: from macOS the
  # host's CoreAudio frameworks went into the cross-built ae's link line, and
  # every `ae build` on FreeBSD failed on -framework.
  AUDIO_LDFLAGS := -lpthread -lm
else ifeq ($(shell uname -s),Linux)
  AUDIO_LDFLAGS := -lpthread -ldl -lm
else ifeq ($(shell uname -s),FreeBSD)
  AUDIO_LDFLAGS := -lpthread -lm
else ifeq ($(shell uname -s),Darwin)
  AUDIO_LDFLAGS := -framework CoreFoundation -framework CoreAudio -framework AudioToolbox
endif

# The link-side half of the AETHER_REQUIRED_CFLAGS split above, and it has to
# stay in lockstep with it: feature detection decides BOTH the -I/-D for a
# dependency and the -l that resolves the symbols that then get emitted. Split
# only the compile side and an `LDFLAGS="..."` override compiles OpenSSL in and
# links it out, so the build fails on undefined SSL symbols. Neither half is
# tunable on its own.
ifeq ($(FREEBSD),1)
# Cross build: the explicit base-libc link tail replaces the native assembly
# (which would pull the host's -lm / -pthread / globbed host casper libs).
AETHER_REQUIRED_LDFLAGS = $(FREEBSD_LDFLAGS)
else
AETHER_REQUIRED_LDFLAGS = -lm $(OPENSSL_LDFLAGS) $(ZLIB_LDFLAGS) $(NGHTTP2_LDFLAGS) $(PCRE2_LDFLAGS) $(YAML_LDFLAGS) $(CASPER_LDFLAGS) $(AUDIO_LDFLAGS) $(BROTLI_LDFLAGS) $(ZSTD_LDFLAGS)
endif

# The toolchain's own binaries (aetherc, ae, aether-lsp, apkg) link without
# libfyaml. None of them parses YAML: aetherc leaves std.yaml's object out of
# its link (below), and the others take std from libaether.a, which pulls it
# in only for a caller. Linked with it, a release built against libfyaml
# could not even start on a machine without the library. A program that
# imports std.yaml links it, through AETHER_YAML_LIBS, and only that program.
#
# Cut YAML_LDFLAGS out as the one run of words it was put in as, not word by
# word: filter-out drops every copy of each word, and pkg-config's libfyaml
# line on FreeBSD is `-L/usr/local/lib -lpthread -lm -lfyaml -lyaml`, so it
# took the -L/usr/local/lib that nghttp2, pcre2, brotli and zstd need too, and
# aetherc no longer linked there.
AETHER_TOOL_LDFLAGS = $(if $(strip $(YAML_LDFLAGS)),$(subst $(YAML_LDFLAGS),,$(AETHER_REQUIRED_LDFLAGS)),$(AETHER_REQUIRED_LDFLAGS))
AETHERC_STD_OBJS = $(filter-out $(OBJ_DIR)/std/yaml/aether_yaml.o $(OBJ_DIR)/std/yaml/aether_libfyaml_vendored.o,$(STD_OBJS))

# Tunable link flags: sanitizers and anything else a caller passes. Empty by
# default, so `make ... LDFLAGS="-fsanitize=address"` adds to the required set
# rather than replacing it.
LDFLAGS =

# Hardening flags (issue #396). Opt-in via `HARDEN=1`. The CI matrix
# pins a Linux/gcc + HARDEN=1 entry so a hardened-build regression
# trips a red check before merge; the default release CFLAGS stay
# unchanged because (a) some hardening flags add measurable runtime
# overhead and (b) macOS Clang has a documented gap with
# `_FORTIFY_SOURCE` on a few historical setups. Each flag below is
# justified inline:
#
#   -fstack-protector-all  : stack canaries on every function — not
#                             just those gcc heuristics flag (-strong)
#                             — catches the smashing class of bugs
#                             that escape the default heuristic.
#   -D_FORTIFY_SOURCE=2    : runtime checks on read/write/memcpy/
#                             strncpy/printf-family wrappers. Requires
#                             at least -O1; we already use -O2, so
#                             nothing extra needed. Linux/gcc will
#                             warn at compile time when it can prove
#                             a buffer overflow; turn those into
#                             real bug fixes, not blanket suppressions.
#   -Wformat -Wformat-security :
#                             flag printf-family format strings that
#                             come from non-literal sources (the
#                             classic %s-format-injection pattern).
#                             Default in modern Linux distros; we
#                             standardise on it explicitly.
ifeq ($(HARDEN),1)
CFLAGS += -fstack-protector-all -D_FORTIFY_SOURCE=2 -Wformat -Wformat-security
endif
ifneq ($(FREEBSD),1)
ifneq ($(WINDOWS),1)
ifneq ($(PLATFORM),wasm)
ifneq ($(PLATFORM),embedded)
ifeq ($(findstring AETHER_NO_THREADING,$(EXTRA_CFLAGS)),)
AETHER_REQUIRED_LDFLAGS += -pthread
endif
endif
endif
endif
endif

# Zero warnings achieved - ready for -Werror
OBJ_DIR = $(BUILD_DIR)/obj

# Windows-specific: -static avoids libwinpthread/libgcc DLL dependencies.
# MinGW OpenSSL 3 static libs pull in Windows Crypto API + GDI/Advapi
# symbols (CertFreeCertificateContext, CertOpenSystemStoreW, etc.) that
# aren't auto-linked — we add the import libs explicitly so std.net TLS
# and std.cryptography work in Windows release binaries.
WIN_LINK_LIBS = -static -lws2_32 -lcrypt32 -lgdi32 -luser32 -ladvapi32 -lbcrypt -ldbghelp
# The compiler's stack is its own on every platform: aetherc and aether-lsp
# run on a thread whose stack the compiler sizes (compiler/
# aether_compile_stack.h, #3539), not on the main thread's, which on Windows
# was 2 MB and overflowed at about 600 chained operators (#2907).
ifdef WINDOWS_NATIVE
    AETHER_REQUIRED_LDFLAGS += $(WIN_LINK_LIBS)
else ifneq ($(findstring MINGW,$(DETECTED_OS)),)
    AETHER_REQUIRED_LDFLAGS += $(WIN_LINK_LIBS)
else ifneq ($(findstring MSYS,$(DETECTED_OS)),)
    AETHER_REQUIRED_LDFLAGS += $(WIN_LINK_LIBS)
else ifneq ($(findstring CYGWIN,$(DETECTED_OS)),)
    AETHER_REQUIRED_LDFLAGS += $(WIN_LINK_LIBS)
endif

COMPILER_SRC = compiler/aetherc.c compiler/parser/lexer.c compiler/parser/parser.c compiler/ast.c compiler/analysis/typechecker.c compiler/analysis/contract_eval.c compiler/analysis/derive.c compiler/analysis/actor_reply.c compiler/analysis/missing_return.c compiler/analysis/actor_protocol.c compiler/analysis/free_check.c compiler/analysis/slice_escape.c compiler/analysis/slice_own.c compiler/analysis/hoist.c compiler/analysis/slice_coerce.c compiler/analysis/sandbox_trust.c compiler/analysis/quote.c compiler/aether_defines.c compiler/codegen/codegen.c compiler/codegen/codegen_expr.c compiler/codegen/codegen_stmt.c compiler/codegen/codegen_actor.c compiler/codegen/codegen_func.c compiler/codegen/codegen_schema.c compiler/codegen/codegen_own.c compiler/aether_error.c compiler/aether_module.c compiler/aether_aea.c compiler/analysis/type_inference.c compiler/codegen/optimizer.c compiler/aether_diagnostics.c compiler/aether_strmap.c compiler/aether_compile_stack.c runtime/actors/aether_message_registry.c lsp/aether_lsp.c
COMPILER_LIB_SRC = compiler/parser/lexer.c compiler/parser/parser.c compiler/ast.c compiler/analysis/typechecker.c compiler/analysis/contract_eval.c compiler/analysis/derive.c compiler/analysis/actor_reply.c compiler/analysis/missing_return.c compiler/analysis/actor_protocol.c compiler/analysis/free_check.c compiler/analysis/slice_escape.c compiler/analysis/slice_own.c compiler/analysis/hoist.c compiler/analysis/slice_coerce.c compiler/analysis/sandbox_trust.c compiler/analysis/quote.c compiler/aether_defines.c compiler/codegen/codegen.c compiler/codegen/codegen_expr.c compiler/codegen/codegen_stmt.c compiler/codegen/codegen_actor.c compiler/codegen/codegen_func.c compiler/codegen/codegen_schema.c compiler/codegen/codegen_own.c compiler/aether_error.c compiler/aether_module.c compiler/aether_aea.c compiler/analysis/type_inference.c compiler/codegen/optimizer.c compiler/aether_diagnostics.c compiler/aether_strmap.c compiler/aether_compile_stack.c runtime/actors/aether_message_registry.c lsp/aether_lsp.c
RUNTIME_SRC = $(SCHEDULER_SRC) runtime/scheduler/scheduler_optimizations.c runtime/scheduler/aether_io_poller_epoll.c runtime/scheduler/aether_io_poller_kqueue.c runtime/scheduler/aether_io_poller_poll.c runtime/config/aether_optimization_config.c runtime/memory/aether_arena.c runtime/memory/aether_pool.c runtime/memory/aether_memory_stats.c runtime/utils/aether_trace.c runtime/utils/aether_spawn.c runtime/utils/aether_bounds_check.c runtime/utils/aether_test.c runtime/memory/aether_arena_optimized.c runtime/aether_runtime_types.c runtime/aether_locale_num.c runtime/utils/aether_cpu_detect.c runtime/utils/aether_simd_vectorized.c runtime/aether_runtime.c runtime/aether_numa.c runtime/aether_sandbox.c runtime/sandbox/spawn_sandboxed_linux.c runtime/sandbox/aether_sandbox_kernel_linux.c runtime/sandbox/spawn_sandboxed_bsd.c runtime/sandbox/spawn_sandboxed_stub.c runtime/sandbox/capsicum_autosandbox.c runtime/sandbox/aether_audit.c runtime/aether_shared_map.c runtime/aether_observe.c runtime/aether_schema.c runtime/aether_process_mem.c runtime/aether_host.c runtime/aether_exec.c runtime/aether_resource_caps.c runtime/libaether_caps.c runtime/actors/aether_send_buffer.c runtime/actors/aether_send_message.c runtime/actors/aether_actor_thread.c runtime/actors/aether_panic.c runtime/actors/aether_unwind.c runtime/actors/aether_supervision.c runtime/aether_callbacks.c
STD_SRC = std/string/aether_string.c std/math/aether_math.c std/net/aether_http.c std/net/aether_tls_trust.c std/net/aether_http_server.c std/net/aether_http_pool.c std/net/aether_http_park.c std/net/aether_http_evloop.c std/net/aether_net.c std/udp/aether_udp.c std/collections/aether_collections.c std/intmap/aether_intmap.c std/json/aether_json.c std/yaml/aether_yaml.c std/yaml/aether_libfyaml_vendored.c std/xml/aether_xml.c std/fs/aether_fs.c std/log/aether_log.c std/io/aether_io.c std/os/aether_os.c std/ipc/aether_ipc.c std/mem/aether_mem.c std/cryptography/aether_cryptography.c std/cryptography/aes/aether_aes.c std/zlib/aether_zlib.c std/brotli/aether_brotli.c std/zstd/aether_zstd.c std/lzf/lzf_c.c std/lzf/lzf_d.c std/lzf/aether_lzf.c std/dl/aether_dl.c std/http/middleware/aether_middleware.c std/http/server/h2/aether_h2.c std/http/proxy/aether_proxy_pool.c std/http/proxy/aether_proxy_lb.c std/http/proxy/aether_proxy_breaker.c std/http/proxy/aether_proxy_health.c std/http/proxy/aether_proxy_cache.c std/http/proxy/aether_proxy_opts.c std/http/proxy/aether_proxy_metrics.c std/http/proxy/aether_proxy_middleware.c std/http/script_gateway/aether_script_gateway.c std/bytes/aether_bytes.c std/bytes/cursor/aether_bytes_cursor.c std/strbuilder/aether_strbuilder.c std/config/aether_config.c std/actors/aether_actor_registry.c std/regex/aether_regex.c std/regex/aether_pcre2_vendored.c std/posix/regex/aether_posix_regex.c std/posix/regex/aether_posix_regcomp.c std/posix/regex/aether_posix_regexec.c std/posix/regex/aether_posix_regerror.c std/posix/regex/aether_posix_regfree.c std/capsicum/aether_capsicum.c std/casper/aether_casper.c std/snapshot/aether_snapshot.c std/sync/aether_sync.c std/audio/aether_audio.c std/worker/aether_worker.c std/alloc/aether_alloc.c std/tracking/aether_tracking.c std/tar/aether_tar.c std/quote/aether_quote.c std/unicode/aether_unicode.c std/unicode/utf8proc/utf8proc.c
# Stdlib sources that reference scheduler internals (scheduler_io_register,
# g_sync_step_actor, current_core_id). Excluded from the compiler binary
# because aetherc does not link the runtime scheduler, but included in
# libaether.a and user programs where the runtime is present.
STD_REACTOR_SRC = std/net/aether_actor_bridge.c
COLLECTIONS_SRC = std/collections/aether_set.c std/collections/aether_pqueue.c std/collections/aether_intarr.c std/collections/aether_floatarr.c std/collections/aether_longarr.c std/collections/aether_strarr.c std/collections/aether_bits.c std/collections/aether_stringlist.c std/collections/aether_stringseq.c

# I/O poller backends (needed by both compiler and runtime targets)
IO_POLLER_SRC = runtime/scheduler/aether_io_poller_epoll.c runtime/scheduler/aether_io_poller_kqueue.c runtime/scheduler/aether_io_poller_poll.c

# Object files
COMPILER_OBJS = $(COMPILER_SRC:%.c=$(OBJ_DIR)/%.o)

# Tools driver, per-object build (#1221). ae.c was one 8.5k-line TU compiled
# in a single gcc invocation, so any edit recompiled the whole driver. Each
# ae_*.c now compiles to its own object with -MMD -MP dependency tracking, so
# an edit recompiles only the touched object (and, via the .d files, whatever
# includes a changed ae_internal.h) and relinks. The _LIBS macros are baked in
# so build_gcc_cmd can construct user-program link lines.
TOOLS_CFLAGS = -O2 -Itools -MMD -MP \
    -DAETHER_VERSION=\"$(VERSION)\" \
    -DAETHER_OPENSSL_LIBS='"$(OPENSSL_LDFLAGS)"' \
    -DAETHER_ZLIB_LIBS='"$(ZLIB_LDFLAGS)"' \
    -DAETHER_NGHTTP2_LIBS='"$(NGHTTP2_LDFLAGS)"' \
    -DAETHER_PCRE2_LIBS='"$(PCRE2_LDFLAGS)"' \
    -DAETHER_YAML_LIBS='"$(YAML_LDFLAGS)"' \
    -DAETHER_CASPER_LIBS='"$(CASPER_LDFLAGS)"' \
    -DAETHER_AUDIO_LIBS='"$(AUDIO_LDFLAGS)"' \
    -DAETHER_BROTLI_LIBS='"$(BROTLI_LDFLAGS)"' \
    -DAETHER_ZSTD_LIBS='"$(ZSTD_LDFLAGS)"' \
    $(if $(AETHER_ENABLE_LLM),-DAETHER_ENABLE_LLM=1)
TOOLS_SRC = tools/ae.c tools/ae_help.c tools/ae_fmt.c tools/ae_bindgen.c \
            tools/ae_cross.c tools/ae_repl.c tools/ae_version.c \
            tools/ae_cache.c tools/ae_checksec.c tools/ae_sha256.c tools/apkg/toml_parser.c $(if $(AETHER_ENABLE_LLM),tools/llm_shim.c)
TOOLS_OBJS = $(TOOLS_SRC:%.c=$(OBJ_DIR)/%.o)
COMPILER_LIB_OBJS = $(COMPILER_LIB_SRC:%.c=$(OBJ_DIR)/%.o)
RUNTIME_OBJS = $(RUNTIME_SRC:%.c=$(OBJ_DIR)/%.o)
IO_POLLER_OBJS = $(IO_POLLER_SRC:%.c=$(OBJ_DIR)/%.o)
STD_OBJS = $(STD_SRC:%.c=$(OBJ_DIR)/%.o)
STD_REACTOR_OBJS = $(STD_REACTOR_SRC:%.c=$(OBJ_DIR)/%.o)
COLLECTIONS_OBJS = $(COLLECTIONS_SRC:%.c=$(OBJ_DIR)/%.o)
TEST_OBJS = $(TEST_SRC:%.c=$(OBJ_DIR)/%.o)

# The version is injected as -DAETHER_VERSION on the command line, NOT via an
# #include, so -MMD cannot see it: bump VERSION and every object still looks up
# to date, leaving a binary that reports the PREVIOUS version. Measured: a tree
# whose generated header said 0.516.0 produced an `ae --version` of 0.515.0,
# because build/obj/tools/ae_version.o was hours older than the header and
# nothing told make to rebuild it.
#
# $(VERSION_HEADER) is regenerated whenever VERSION changes (rule above), so
# making the version-bearing objects depend on it is the cheap, honest link
# between "the version changed" and "recompile the things that bake it in".
$(OBJ_DIR)/tools/ae_version.o: $(VERSION_HEADER)
$(OBJ_DIR)/tools/ae.o: $(VERSION_HEADER)
$(OBJ_DIR)/compiler/aetherc.o: $(VERSION_HEADER)
# aether_abi.h includes it (#2957): the runtime ABI id the runtime reports
# and the one the code generator writes into each library.
$(OBJ_DIR)/runtime/aether_exec.o: $(VERSION_HEADER)
$(OBJ_DIR)/compiler/codegen/codegen.o: $(VERSION_HEADER)

# Test files using TEST() macro system (exclude standalone tests)
TEST_SRC = tests/runtime/test_harness.c \
           tests/runtime/test_main.c \
           tests/runtime/test_64bit.c \
           tests/runtime/test_runtime_collections.c \
           tests/runtime/test_runtime_strings.c \
           tests/runtime/test_runtime_panic.c \
           tests/runtime/test_runtime_strbuilder.c \
           tests/runtime/test_runtime_math.c \
           tests/runtime/test_runtime_json.c \
           tests/runtime/test_runtime_http.c \
           tests/runtime/test_runtime_net.c \
           tests/runtime/test_runtime_udp.c \
           tests/runtime/test_io_poller.c \
           tests/runtime/test_runtime_observe.c \
           tests/runtime/test_runtime_process_mem.c \
           tests/runtime/test_spawn_env.c \
           tests/runtime/test_ipc_write.c \
           tests/runtime/test_runtime_schema.c \
           tests/runtime/test_runtime_intmap.c \
           tests/runtime/test_runtime_shared_map.c \
           tests/runtime/test_tools_sha256.c tools/ae_sha256.c \
           tests/runtime/test_scheduler.c \
           tests/runtime/test_scheduler_stress.c \
           tests/runtime/test_zerocopy.c \
           tests/runtime/test_lockfree_mailbox.c \
           tests/runtime/test_send_buffer.c \
           tests/runtime/test_scheduler_optimizations.c \
           tests/runtime/test_spsc_queue.c \
           tests/runtime/test_worksteal_race.c \
           tests/runtime/test_ask_relief.c \
           tests/runtime/test_ask_message.c \
           tests/runtime/test_wait_inside_actor.c \
           tests/runtime/test_step_context.c \
           tests/runtime/test_exec_accounts.c \
           tests/runtime/test_abi_layout.c \
           tests/runtime/test_sender_move_order.c \
           tests/runtime/test_actor_thread_sends.c \
           tests/runtime/test_overflow_reentry.c \
           tests/runtime/test_actor_death.c \
           tests/runtime/test_actor_rebirth.c \
           tests/runtime/test_mailbox_bound.c \
           tests/runtime/test_win_mutex_no_debug_info.c \
           tests/runtime/test_http_server.c \
           tests/runtime/test_http_resolver.c \
           tests/runtime/test_net_localhost.c \
           tests/runtime/test_resource_caps.c \
           tests/runtime/test_libaether_caps.c \
           tests/memory/test_memory_arena.c \
           tests/memory/test_memory_pool.c \
           tests/memory/test_memory_leaks.c \
           tests/memory/test_memory_stress.c \
           tests/compiler/test_lexer.c \
           tests/compiler/test_typechecker.c \
           tests/compiler/test_lexer_comprehensive.c \
           tests/compiler/test_parser.c \
           tests/compiler/test_aea.c \
           tests/compiler/test_compile_stack.c \
           tests/compiler/test_parser_comprehensive.c \
           tests/compiler/test_type_inference_comprehensive.c \
           tests/compiler/test_pattern_matching_comprehensive.c \
           tests/compiler/test_structs.c \
           tests/compiler/test_switch_statements.c \
           tests/compiler/test_codegen.c \
           tests/compiler/test_module_orchestrator.c \
           tests/compiler/test_security.c \
           tests/compiler/test_slices.c

# Dependency files, so a header change recompiles every object that includes
# it, the tests' included. `-include` expands its list where it stands, so it
# comes after TEST_SRC: above it, $(TEST_OBJS) was empty and a test object
# built against an older header (an ActorBase without a new field) was linked
# against a runtime built with the new one.
DEPS = $(COMPILER_OBJS:.o=.d) $(COMPILER_LIB_OBJS:.o=.d) $(RUNTIME_OBJS:.o=.d) $(STD_OBJS:.o=.d) $(STD_REACTOR_OBJS:.o=.d) $(COLLECTIONS_OBJS:.o=.d) $(TEST_OBJS:.o=.d) $(TOOLS_OBJS:.o=.d)
-include $(DEPS)

# Standalone test programs with their own main() - build separately
# These are not part of the main test suite but can be built manually
STANDALONE_TESTS = tests/runtime/test_runtime_manual.c \
                   tests/compiler/test_arrays.c

# Every C source with its own main() that no other target compiles: the
# runtime examples, the micro-benchmarks, the demos. Nothing links them, so
# they rot invisibly — three of them had stale include paths and one was
# written against a renamed logging API. `check-standalone` compiles each so
# that cannot happen again.
STANDALONE_SRC = $(wildcard runtime/examples/*.c) \
                 $(wildcard tests/runtime/bench_*.c) \
                 $(STANDALONE_TESTS) \
                 tools/profiler/profiler_demo.c \
                 std/log/demo_log.c \
                 tests/differential/driver.c
ifneq ($(IS_WINDOWS),)
  # POSIX-only standalone sources: the differential driver dlopen()s
  # candidate compilers (<dlfcn.h>), and the work-stealing bench uses
  # raw pthreads that clash with aether_thread.h's pthread_t -> HANDLE
  # mapping on MinGW. Everything else in the gate compiles on Windows.
  STANDALONE_SRC := $(filter-out tests/differential/driver.c runtime/examples/workstealing_bench.c,$(STANDALONE_SRC))
endif

all: compiler ae stdlib

# The target this tree holds (BUILD_TARGET_ID), read by the guard near the top.
# Written once per tree by the goals that fill it.
$(BUILD_TARGET_STAMP):
	@mkdir -p $(BUILD_DIR) 2>/dev/null || true
	@echo "$(BUILD_TARGET_ID)" > "$@"

# Create object directories
$(OBJ_DIR)/compiler $(OBJ_DIR)/compiler/parser $(OBJ_DIR)/compiler/codegen $(OBJ_DIR)/compiler/analysis $(OBJ_DIR)/runtime $(OBJ_DIR)/runtime/actors $(OBJ_DIR)/runtime/sandbox $(OBJ_DIR)/runtime/scheduler $(OBJ_DIR)/runtime/memory $(OBJ_DIR)/runtime/config $(OBJ_DIR)/runtime/simd $(OBJ_DIR)/runtime/utils $(OBJ_DIR)/std $(OBJ_DIR)/std/string $(OBJ_DIR)/std/io $(OBJ_DIR)/std/math $(OBJ_DIR)/std/net $(OBJ_DIR)/std/udp $(OBJ_DIR)/std/fs $(OBJ_DIR)/std/log $(OBJ_DIR)/std/collections $(OBJ_DIR)/std/intmap $(OBJ_DIR)/std/json $(OBJ_DIR)/std/yaml $(OBJ_DIR)/std/xml $(OBJ_DIR)/std/os $(OBJ_DIR)/std/ipc $(OBJ_DIR)/std/mem $(OBJ_DIR)/std/cryptography $(OBJ_DIR)/std/cryptography/aes $(OBJ_DIR)/std/zlib $(OBJ_DIR)/std/brotli $(OBJ_DIR)/std/zstd $(OBJ_DIR)/std/lzf $(OBJ_DIR)/std/dl $(OBJ_DIR)/std/bytes $(OBJ_DIR)/std/bytes/cursor $(OBJ_DIR)/std/strbuilder $(OBJ_DIR)/std/config $(OBJ_DIR)/std/actors $(OBJ_DIR)/std/capsicum $(OBJ_DIR)/std/casper $(OBJ_DIR)/std/snapshot $(OBJ_DIR)/std/sync $(OBJ_DIR)/std/audio $(OBJ_DIR)/std/worker $(OBJ_DIR)/std/alloc $(OBJ_DIR)/std/tracking $(OBJ_DIR)/std/tar $(OBJ_DIR)/std/quote $(OBJ_DIR)/std/unicode $(OBJ_DIR)/std/unicode/utf8proc $(OBJ_DIR)/std/http $(OBJ_DIR)/std/http/middleware $(OBJ_DIR)/std/http/proxy $(OBJ_DIR)/std/http/script_gateway $(OBJ_DIR)/std/http/server $(OBJ_DIR)/std/http/server/h2 $(OBJ_DIR)/std/regex $(OBJ_DIR)/std/posix $(OBJ_DIR)/std/posix/regex $(OBJ_DIR)/lsp $(OBJ_DIR)/tests $(OBJ_DIR)/tests/compiler $(OBJ_DIR)/tests/memory $(OBJ_DIR)/tests/runtime $(OBJ_DIR)/tools $(OBJ_DIR)/tools/apkg:
ifdef WINDOWS_NATIVE
	@if not exist "$(subst /,\,$@)" mkdir "$(subst /,\,$@)"
else
	@mkdir -p $@
endif

# Pattern rule for object files
# Rebuild when the flags change, not just when a source does (#1646).
#
# Object files carry no record of what built them, so `make HARDEN=1` after a
# plain build recompiled NOTHING and relinked the same unhardened objects into
# a binary the caller believes is hardened: zero canaries, zero fortified
# calls, and a successful build. A security posture nobody can see is worse
# than none, and it is how the hardened CI leg came to be reported as testing
# nothing.
#
# The stamp holds a digest of everything that changes code generation, and
# every object depends on it. The digest is computed inside the recipe rather
# than in a variable because CKSUM_CMD is defined further down this file: an
# immediate `:=` here would expand it to nothing and the stamp would never
# change, which is the same silence in a new place.
#
# FORCE, not .PHONY: the recipe must RUN every build to compare, but the file
# must only be TOUCHED when the digest actually moves. A phony stamp is always
# newer than its dependents and would rebuild the world on every make.
BUILD_FLAGS_STAMP := $(OBJ_DIR)/.build-flags

.PHONY: build-flags-force
build-flags-force:

$(BUILD_FLAGS_STAMP): build-flags-force
	@mkdir -p $(dir $@) 2>/dev/null || true
	@digest=$$(printf '%s|%s|%s|%s|%s|%s' "$(CC)" "$(CFLAGS)" "$(EXTRA_CFLAGS)" \
	    "$(AETHER_REQUIRED_CFLAGS)" "HARDEN=$(HARDEN)" "$(PLATFORM)" \
	    | $(CKSUM_CMD) 2>/dev/null | cut -d' ' -f1); \
	  if [ ! -f "$@" ] || [ "$$(cat "$@" 2>/dev/null)" != "$$digest" ]; then \
	    printf '%s' "$$digest" > "$@"; \
	  fi

$(OBJ_DIR)/%.o: %.c $(BUILD_FLAGS_STAMP) | $(STDLIB_SYMS_HEADER) $(FRONTEND_ID_HEADER) $(OBJ_DIR)/compiler $(OBJ_DIR)/compiler/parser $(OBJ_DIR)/compiler/codegen $(OBJ_DIR)/compiler/analysis $(OBJ_DIR)/runtime $(OBJ_DIR)/runtime/actors $(OBJ_DIR)/runtime/sandbox $(OBJ_DIR)/runtime/scheduler $(OBJ_DIR)/runtime/memory $(OBJ_DIR)/runtime/config $(OBJ_DIR)/runtime/simd $(OBJ_DIR)/runtime/utils $(OBJ_DIR)/std $(OBJ_DIR)/std/string $(OBJ_DIR)/std/io $(OBJ_DIR)/std/math $(OBJ_DIR)/std/net $(OBJ_DIR)/std/udp $(OBJ_DIR)/std/fs $(OBJ_DIR)/std/log $(OBJ_DIR)/std/collections $(OBJ_DIR)/std/intmap $(OBJ_DIR)/std/json $(OBJ_DIR)/std/yaml $(OBJ_DIR)/std/xml $(OBJ_DIR)/std/os $(OBJ_DIR)/std/ipc $(OBJ_DIR)/std/mem $(OBJ_DIR)/std/cryptography $(OBJ_DIR)/std/cryptography/aes $(OBJ_DIR)/std/zlib $(OBJ_DIR)/std/brotli $(OBJ_DIR)/std/zstd $(OBJ_DIR)/std/lzf $(OBJ_DIR)/std/dl $(OBJ_DIR)/std/bytes $(OBJ_DIR)/std/bytes/cursor $(OBJ_DIR)/std/strbuilder $(OBJ_DIR)/std/config $(OBJ_DIR)/std/actors $(OBJ_DIR)/std/capsicum $(OBJ_DIR)/std/casper $(OBJ_DIR)/std/snapshot $(OBJ_DIR)/std/sync $(OBJ_DIR)/std/audio $(OBJ_DIR)/std/worker $(OBJ_DIR)/std/alloc $(OBJ_DIR)/std/tracking $(OBJ_DIR)/std/tar $(OBJ_DIR)/std/quote $(OBJ_DIR)/std/unicode $(OBJ_DIR)/std/unicode/utf8proc $(OBJ_DIR)/std/http $(OBJ_DIR)/std/http/middleware $(OBJ_DIR)/std/http/proxy $(OBJ_DIR)/std/http/script_gateway $(OBJ_DIR)/std/http/server $(OBJ_DIR)/std/http/server/h2 $(OBJ_DIR)/std/regex $(OBJ_DIR)/std/posix $(OBJ_DIR)/std/posix/regex $(OBJ_DIR)/lsp $(OBJ_DIR)/tests $(OBJ_DIR)/tests/compiler $(OBJ_DIR)/tests/memory $(OBJ_DIR)/tests/runtime
	@echo "Compiling $<..."
	@$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) -c $< -o $@

# Upstream liblzf (vendored verbatim under std/lzf/) has a few style
# choices the modern -Werror set flags:
#   - lzf_d.c's decoder uses C-style fallthrough in its dispatch loop
#     (gcc -Wimplicit-fallthrough).
#   - lzfP.h defines LZF_USE_OFFSETS via `#define X defined(_M_X64)` and
#     then `#if X`, an expansion-to-defined that's non-portable under
#     C99 but works on every compiler the upstream targets
#     (gcc/clang -Wexpansion-to-defined).
# We silence both on the lzf objects rather than patching the vendored
# source, so future re-vendoring stays a copy-paste.
LZF_CFLAGS_RELAX = -Wno-implicit-fallthrough -Wno-expansion-to-defined
$(OBJ_DIR)/std/lzf/lzf_c.o: CFLAGS += $(LZF_CFLAGS_RELAX)
$(OBJ_DIR)/std/lzf/lzf_d.o: CFLAGS += $(LZF_CFLAGS_RELAX)
$(OBJ_DIR)/std/lzf/aether_lzf.o: CFLAGS += $(LZF_CFLAGS_RELAX)

# Vendored miniaudio (single-header, ~96k lines) is compiled inside
# aether_audio.c via MINIAUDIO_IMPLEMENTATION. Relax the warnings we don't
# own — same treatment as vendored liblzf above.
# GCC-only: MinGW-w64 GCC mis-analyses miniaudio's atomic intrinsics
# (ma_atomic_*_32 on opaque node-graph/resource-manager structs) as "writing
# into a region of size 0" — a known GCC false positive on miniaudio's own
# realtime code, not our storage. Guarded on the compiler being GCC because
# clang has no -Wstringop-overflow group and, under -Werror, promotes the
# unknown-warning-option to a hard error (macOS clang build).
AUDIO_GCC_ONLY_RELAX := $(shell $(CC) --version 2>/dev/null | grep -qi clang || echo -Wno-stringop-overflow)
AUDIO_CFLAGS_RELAX = -Wno-unused-function -Wno-unused-variable \
                     -Wno-implicit-fallthrough -Wno-sign-compare \
                     -Wno-unused-parameter -Wno-type-limits \
                     $(AUDIO_GCC_ONLY_RELAX)
$(OBJ_DIR)/std/audio/aether_audio.o: CFLAGS += $(AUDIO_CFLAGS_RELAX)

# ---- miniaudio object cache (CI) ---------------------------------------
# Compiling MINIAUDIO_IMPLEMENTATION (the ~96k-line vendored header) costs ~1
# minute per build, paid on every matrix leg because `make ci` starts with
# `clean` (rm -rf build). miniaudio.h changes ~never, so we cache the compiled
# object OUTSIDE build/ (so clean can't wipe it) and restore it after clean.
#
# Safety: a cached object is used ONLY when it would be byte-identical to a
# fresh compile. AUDIO_CACHE_STAMP is a content hash of the source, the header,
# and the compiler identity + audio flags; the restore refuses a stamp mismatch
# and falls back to a normal compile. In CI the actions/cache KEY already pins
# hash(miniaudio.h)+OS+compiler, so a restored object is guaranteed to match;
# the stamp guards local/edge use. A miss always rebuilds — never stale.
AUDIO_CACHE_DIR    := .ci-cache
AUDIO_CACHE_OBJ    := $(AUDIO_CACHE_DIR)/aether_audio.o
AUDIO_CACHE_STAMP  := $(AUDIO_CACHE_DIR)/aether_audio.stamp
AUDIO_OBJ          := $(OBJ_DIR)/std/audio/aether_audio.o
# Portable content hasher (sha256sum on Linux, shasum on macOS, cksum fallback).
CKSUM_CMD := $(shell command -v sha256sum >/dev/null 2>&1 && echo sha256sum || (command -v shasum >/dev/null 2>&1 && echo 'shasum -a 256' || echo cksum))
# Content key: source + vendored header + compiler identity + every build knob
# that can change the emitted object — compiler version, the audio relax flags,
# and the build-variant flags (HARDEN, EXTRA_CFLAGS: coop/wasm/embedded set
# -DAETHER_NO_THREADING etc). If any of these differ the stamp differs, so a
# hardened / coop / cross object never gets restored over a plain one.
AUDIO_CACHE_KEY := $(shell cat std/audio/aether_audio.c std/audio/miniaudio.h std/audio/stb_vorbis.c std/audio/aether_audio.h 2>/dev/null | $(CKSUM_CMD) 2>/dev/null | cut -d' ' -f1)-$(shell $(CC) --version 2>/dev/null | head -1 | tr -dc 'a-zA-Z0-9.')-h$(HARDEN)-$(shell printf '%s %s' "$(AUDIO_GCC_ONLY_RELAX)" "$(EXTRA_CFLAGS)" | $(CKSUM_CMD) 2>/dev/null | cut -d' ' -f1)

# Restore the cached object into build/ if the stamp matches, then touch it
# newer than its source so make treats it as up-to-date and skips the compile.
# No-op (silent) when there is no valid cache — the normal rule then builds it.
.PHONY: audio-cache-restore
audio-cache-restore:
	@if [ -f "$(AUDIO_CACHE_OBJ)" ] && [ -f "$(AUDIO_CACHE_STAMP)" ] && \
	    [ "$$(cat $(AUDIO_CACHE_STAMP))" = "$(AUDIO_CACHE_KEY)" ]; then \
	  mkdir -p "$(dir $(AUDIO_OBJ))"; \
	  cp "$(AUDIO_CACHE_OBJ)" "$(AUDIO_OBJ)"; \
	  touch "$(AUDIO_OBJ)"; \
	  echo "audio-cache: restored miniaudio object (stamp hit) — skipping ~96k-line compile"; \
	else \
	  echo "audio-cache: no valid cached object — will compile miniaudio from source"; \
	fi

# Save the freshly-built object + its stamp to the cache dir (idempotent).
# actions/cache then persists $(AUDIO_CACHE_DIR) between runs.
.PHONY: audio-cache-save
audio-cache-save: $(AUDIO_OBJ)
	@mkdir -p "$(AUDIO_CACHE_DIR)"
	@cp "$(AUDIO_OBJ)" "$(AUDIO_CACHE_OBJ)"
	@printf '%s' "$(AUDIO_CACHE_KEY)" > "$(AUDIO_CACHE_STAMP)"
	@echo "audio-cache: saved miniaudio object to $(AUDIO_CACHE_OBJ)"

# ---- contrib/i18n collation check (CI) ---------------------------------
# contrib/i18n (Phase 5 of #863) compiles the vendored utf8proc.c and the
# ~74k-line GENERATED DUCET table (ducet/ducet_data.c). Both are committed
# (vendored), so CI never fetches at build time — no supply-chain surface
# beyond the pinned, reviewed files. We considered mirroring the miniaudio
# object cache here, but measured the combined compile at <1s (utf8proc ~0.4s,
# ducet_data ~0.25s) — nothing like miniaudio's ~1min — so an actions/cache
# round-trip would cost more than it saves. Just compile it each run.
#
# Standalone from `make ci` (contrib is not in the test-ae glob); invoked by
# its own CI job (see .github/workflows/ci.yml: ci-contrib-i18n).
I18N_DIR := contrib/i18n

.PHONY: contrib-i18n-check
contrib-i18n-check: compiler ae stdlib
	@echo "contrib-i18n: building collate test"
	@./$(BUILD_DIR)/ae$(EXE_EXT) build $(I18N_DIR)/collate/test_collate.ae \
	  --extra $(I18N_DIR)/aether_i18n.c \
	  --extra std/unicode/utf8proc/utf8proc.c \
	  --extra $(I18N_DIR)/ducet/ducet_data.c \
	  -o $(BUILD_DIR)/test_collate$(EXE_EXT)
	@echo "contrib-i18n: running collate test"
	@./$(BUILD_DIR)/test_collate$(EXE_EXT)

# contrib-check: build + RUN every contrib test_*.ae (not just type-check).
# This is the runtime-coverage gate the nightly was missing — type-checking
# alone let the tinyweb WebSocket server path rot (compiled fine, runtime-
# broken). The table of tests + their --extra C files lives in
# .github/scripts/contrib_check.sh. contrib-check-valgrind runs each under
# valgrind as a leak gate (for the dedicated nightly build box).
#
# contrib-check-lsan is the second leak gate, for the entries valgrind cannot
# measure: contrib/vulkan renders through lavapipe, whose LLVM JIT makes
# valgrind report ~13k errors, none of them this repo's. LeakSanitizer suppresses
# by module instead, so the driver is excluded by object and every allocation
# the module makes is still gated. Linux only (no LSan on macOS).
.PHONY: contrib-check contrib-check-valgrind contrib-check-lsan
contrib-check: compiler ae stdlib
	@EXE_EXT='$(EXE_EXT)' bash .github/scripts/contrib_check.sh

contrib-check-valgrind: compiler ae stdlib
	@EXE_EXT='$(EXE_EXT)' VALGRIND=1 bash .github/scripts/contrib_check.sh

contrib-check-lsan: compiler ae stdlib
	@EXE_EXT='$(EXE_EXT)' LSAN=1 bash .github/scripts/contrib_check.sh

# Compiler target (incremental build with object files)
compiler: $(BUILD_DIR)/aetherc$(EXE_EXT) $(BUILD_TARGET_STAMP)

# A FILE target, so an already-current tree relinks nothing. As a phony
# `compiler` it relinked build/aetherc on every `make`, and anything that runs
# make in this tree (`make install` from two of the integration tests) rewrote
# the binary other tests were executing at that moment: macOS kills a process
# whose text file changed under it, which is a SIGKILL in a test that never
# went near the build system.
# The runtime pieces aetherc links, for this rule, compiler-fast and the
# release compiler alike: compiler-fast kept a list of its own, which lost
# aether_spawn.c and aether_sandbox.c and could not link (#3351), and so
# did the release compiler's, which lost aether_unwind.c once the caps code
# read the execution frames, so `make install` could not link. std.dl keeps
# what every Aether library binds to (aether_runtime_abi), and aether_exec.c
# keeps the host API with it (#3439): the compiler links the std objects
# whole, so it links those three files too.
AETHERC_RUNTIME_SRC = runtime/utils/aether_spawn.c runtime/aether_sandbox.c runtime/sandbox/aether_audit.c runtime/actors/aether_panic.c runtime/actors/aether_unwind.c runtime/aether_resource_caps.c runtime/aether_locale_num.c runtime/aether_callbacks.c runtime/aether_exec.c runtime/aether_host.c runtime/libaether_caps.c
AETHERC_RUNTIME_OBJS = $(patsubst %.c,$(OBJ_DIR)/%.o,$(AETHERC_RUNTIME_SRC))

$(BUILD_DIR)/aetherc$(EXE_EXT): $(COMPILER_OBJS) $(STD_OBJS) $(COLLECTIONS_OBJS) $(AETHERC_RUNTIME_OBJS) $(IO_POLLER_OBJS) $(MANIFEST_OBJ) | $(VERSION_HEADER) $(STDLIB_SYMS_HEADER) $(FRONTEND_ID_HEADER)
	@echo "Linking compiler..."
	@$(CC) $(COMPILER_OBJS) $(AETHERC_STD_OBJS) $(COLLECTIONS_OBJS) $(AETHERC_RUNTIME_OBJS) $(IO_POLLER_OBJS) $(MANIFEST_OBJ) -o $(BUILD_DIR)/aetherc$(EXE_EXT) $(AETHER_TOOL_LDFLAGS) $(LDFLAGS)
	@echo "Compiler built successfully"

# Fast compiler target (monolithic, for clean builds): the same sources and
# generated headers as the rule above, compiled in one command. The sources
# compiled with flags of their own (the vendored lzf and miniaudio, which
# relax warnings for them alone) come from their own rules; one command
# cannot give one file different flags.
COMPILER_FAST_OWN_SRC = std/lzf/lzf_c.c std/lzf/lzf_d.c std/lzf/aether_lzf.c std/audio/aether_audio.c
COMPILER_FAST_OWN_OBJS = $(patsubst %.c,$(OBJ_DIR)/%.o,$(filter $(COMPILER_FAST_OWN_SRC),$(STD_SRC)))
compiler-fast: $(COMPILER_FAST_OWN_OBJS) $(MANIFEST_OBJ) | $(VERSION_HEADER) $(STDLIB_SYMS_HEADER) $(FRONTEND_ID_HEADER)
ifdef WINDOWS_NATIVE
	@if not exist "$(BUILD_DIR)" mkdir "$(BUILD_DIR)"
else
	@$(MKDIR) $(BUILD_DIR)
endif
	$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) $(COMPILER_SRC) $(filter-out $(COMPILER_FAST_OWN_SRC) std/yaml/aether_yaml.c std/yaml/aether_libfyaml_vendored.c,$(STD_SRC)) $(COMPILER_FAST_OWN_OBJS) $(COLLECTIONS_SRC) $(AETHERC_RUNTIME_SRC) $(IO_POLLER_SRC) $(MANIFEST_OBJ) -o $(BUILD_DIR)/aetherc$(EXE_EXT) $(AETHER_TOOL_LDFLAGS) $(LDFLAGS)

test: $(TEST_OBJS) $(COMPILER_LIB_OBJS) $(RUNTIME_OBJS) $(STD_OBJS) $(STD_REACTOR_OBJS) $(COLLECTIONS_OBJS)
	@echo "==================================="
	@echo "Building Test Suite ($(DETECTED_OS))"
	@echo "==================================="
	@echo "Linking test runner..."
	@$(CC) $(TEST_OBJS) $(COMPILER_LIB_OBJS) $(RUNTIME_OBJS) $(STD_OBJS) $(STD_REACTOR_OBJS) $(COLLECTIONS_OBJS) -o $(BUILD_DIR)/test_runner$(EXE_EXT) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)
	@echo ""
	@echo "==================================="
	@echo "Running Tests"
	@echo "==================================="
ifneq ($(findstring MINGW,$(DETECTED_OS)),)
	@bash -c './$(BUILD_DIR)/test_runner$(EXE_EXT); exit $$?'
else ifneq ($(findstring MSYS,$(DETECTED_OS)),)
	@bash -c './$(BUILD_DIR)/test_runner$(EXE_EXT); exit $$?'
else
	./$(BUILD_DIR)/test_runner$(EXE_EXT)
endif

# Fast test target (monolithic)
test-fast: compiler-fast
	@echo "==================================="
	@echo "Building Test Suite ($(DETECTED_OS))"
	@echo "==================================="
	$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) $(TEST_SRC) $(COMPILER_LIB_SRC) $(RUNTIME_SRC) $(STD_SRC) $(STD_REACTOR_SRC) $(COLLECTIONS_SRC) -Icompiler -Istd -Istd/collections -o $(BUILD_DIR)/test_runner$(EXE_EXT) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)
	@echo ""
	@echo "==================================="
	@echo "Running Tests"
	@echo "==================================="
	./$(BUILD_DIR)/test_runner$(EXE_EXT)

# test-valgrind / test-asan / test-memory: link the test runner's own
# main() from TEST_SRC against pre-built flavoured archives instead of
# recompiling the full stdlib + compiler-lib sources every invocation.
# Each archive bakes the right instrumentation in once (asan, memory
# tracking, or -O0 -g for valgrind). See `stdlib-{asan,memory,dbg}`
# rules above. The archives must use COMPILER_LIB_SRC (no aetherc.c)
# so test_main.c's main() doesn't collide with aetherc's.
test-valgrind: compiler stdlib-dbg
	@echo "==================================="
	@echo "Running Tests with Valgrind"
	@echo "==================================="
	$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS_NO_OPT) $(DBG_OPT) $(TEST_SRC) $(BUILD_DIR)/dbg/libaether_compiler.a $(BUILD_DIR)/dbg/libaether.a -Icompiler -Istd -Istd/collections -o $(BUILD_DIR)/test_runner$(EXE_EXT) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)
	valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes --fair-sched=yes --error-exitcode=1 ./$(BUILD_DIR)/test_runner$(EXE_EXT)

# -----------------------------------------------------------------
# ci-coverage — build with `gcc --coverage`, run the C-level test
# suite, then walk the .gcda files with gcov to produce per-source
# `.c.gcov` and (thanks to PR #352's #line directives) `.ae.gcov`
# reports under build/coverage/. A summary is printed to stdout and
# written to build/coverage/SUMMARY for downstream tooling.
#
# Scope: the C-level test_runner only. The 397 `.ae` regression tests
# under `make test-ae` use the user-facing `ae build` pipeline which
# doesn't currently inject --coverage into gcc; extending coverage to
# that path is a follow-up (`ae build --coverage`).
#
# Optional richer reports: gcovr (HTML) and lcov+genhtml (browsable
# HTML) are picked up if installed, skipped with a notice if not.
# Probe-and-degrade matches the contrib_build.sh philosophy.
#
# Not part of `make ci` — coverage rebuild is slow and the test data
# only becomes useful when read by a human. Run on demand.
# -----------------------------------------------------------------
ci-coverage: compiler ae stdlib-cov
	@echo "==================================="
	@echo "  Building coverage-instrumented test runner"
	@echo "==================================="
	@$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS_NO_OPT) $(COV_OPT) $(COV_FLAGS) $(TEST_SRC) \
		$(BUILD_DIR)/cov/libaether_compiler.a $(BUILD_DIR)/cov/libaether.a \
		-Icompiler -Istd -Istd/collections \
		-o $(BUILD_DIR)/test_runner_cov$(EXE_EXT) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)
	@echo ""
	@echo "==================================="
	@echo "  [1/2] Running C-level tests with coverage counters"
	@echo "==================================="
	@./$(BUILD_DIR)/test_runner_cov$(EXE_EXT) || true
	@echo ""
	@echo "==================================="
	@echo "  [2/2] Running .ae regression tests with coverage counters"
	@echo "==================================="
	@# Forward --coverage to every per-test `ae build` invocation
	@# via the AE_BUILD_FLAGS env var. The test runner picks it up
	@# in the recipe-generated run_test.sh script.
	@AE_BUILD_FLAGS=--coverage $(MAKE) --no-print-directory test-ae || true
	@echo ""
	@bash tests/scripts/coverage_report.sh

ci-coverage-clean:
	@echo "Cleaning coverage data..."
	@find $(BUILD_DIR)/cov-obj -name '*.gcda' -delete 2>/dev/null || true
	@find $(BUILD_DIR) -maxdepth 2 -name '*.gcda' -delete 2>/dev/null || true
	@find $(BUILD_DIR) -maxdepth 2 -name '*.gcno' -delete 2>/dev/null || true
	@$(RM) -r $(BUILD_DIR)/coverage 2>/dev/null || true
	@echo "✓ Coverage data cleaned (cov-obj/.gcno files retained for reuse)"

# ci-coverage-html — wraps ci-coverage with an HTML/JSON report via
# gcovr. Auto-bootstraps gcovr in a project-local venv at
# build/cov-venv/ if it's not already on PATH (modern Debian/Ubuntu
# refuse `pip install` system-wide without --break-system-packages,
# so a self-contained venv is the friendliest path).
#
# After running, open build/coverage/index.html in a browser. JSON
# is also written to coverage.json for CI / dashboard pickup.
ci-coverage-html: ci-coverage
	@bash tests/scripts/coverage_html.sh

test-asan: compiler stdlib-asan
	@echo "==================================="
	@echo "Running Tests with AddressSanitizer"
	@echo "==================================="
	$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS_NO_OPT) $(ASAN_OPT) $(ASAN_FLAGS) $(TEST_SRC) $(BUILD_DIR)/asan/libaether_compiler.a $(BUILD_DIR)/asan/libaether.a -Icompiler -Istd -Istd/collections -o $(BUILD_DIR)/test_runner_asan$(EXE_EXT) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)
ifeq ($(shell uname -s),Linux)
	ASAN_OPTIONS=detect_leaks=1:halt_on_error=1 ./$(BUILD_DIR)/test_runner_asan$(EXE_EXT)
else
	ASAN_OPTIONS=halt_on_error=1 ./$(BUILD_DIR)/test_runner_asan$(EXE_EXT)
endif

# macOS leaks(1) gate (#468). Builds a curated set of memory-
# ownership regression programs and runs each under
# `MallocStackLogging=1 leaks --atExit`. Skips cleanly on non-Darwin
# (Linux gets leak coverage from test-valgrind + ASan-LSan). NOT
# folded into `make ci` — MallocStackLogging is ~10x slower; runs as
# its own macOS-CI step. See tests/run_macos_leaks.sh for the covered
# set and rationale.
test-macos-leaks: compiler ae stdlib
	@sh tests/run_macos_leaks.sh

test-memory: compiler stdlib-memory
	@echo "==================================="
	@echo "Running Memory Tracking Tests"
	@echo "==================================="
	$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) $(MEM_FLAGS) $(TEST_SRC) $(BUILD_DIR)/memory/libaether_compiler.a $(BUILD_DIR)/memory/libaether.a -Icompiler -Istd -Istd/collections -o $(BUILD_DIR)/test_runner_mem$(EXE_EXT) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)
	./$(BUILD_DIR)/test_runner_mem$(EXE_EXT)

test-manual-runtime: compiler
	@echo "Building manual runtime test..."
	$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) tests/runtime/test_runtime_manual.c $(RUNTIME_SRC) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS) -o $(BUILD_DIR)/test_runtime_manual$(EXE_EXT)
	@echo "Running manual runtime test..."
	./$(BUILD_DIR)/test_runtime_manual$(EXE_EXT)

# Cross-compilation smoke test (#1105): `ae build --target=<triple>` via
# the zig cc backend. Self-skips when zig is not installed, so it is safe
# to run anywhere (it is not part of the default `test` gate because CI
# does not carry the zig toolchain).
test-cross: ae stdlib
	@bash tests/scripts/cross_compile.sh

# Windows RUNTIME sweep (#1876): cross-build each test to a .exe on this host
# and execute it under Wine. Self-skips when zig or wine is missing, so it is
# safe to run anywhere. Not part of the default gate; CI runs it on Linux.
test-windows-wine: ae stdlib
	@bash tests/scripts/windows_wine_sweep.sh

.PHONY: fuzz-cbor
# Coverage-guided fuzzing of std.cbor's decoder (needs clang with libFuzzer).
# Not part of `make test` or CI; FUZZ_SECONDS sets the run time (default 60).
fuzz-cbor: compiler ae stdlib
	@sh tests/fuzz/cbor/run_fuzz_cbor.sh

.PHONY: fuzz-ipc-frames
# Coverage-guided fuzzing of std.ipc's frame reader over a socket pair, checked
# against a model of its contract (needs clang with libFuzzer, poll() and
# os.socketpair; not Windows).
# Not part of `make test` or CI; FUZZ_SECONDS sets the run time (default 60).
fuzz-ipc-frames: compiler ae stdlib
	@sh tests/fuzz/ipc_frames/run_fuzz_ipc_frames.sh

.PHONY: fuzz-ipc-frames-corpus
# Rewrite the frame-reader fuzzer's seed corpus from its generator
# (tests/fuzz/ipc_frames/gen_corpus.ae); the seeds are committed, so this is
# only for when the generator changes.
fuzz-ipc-frames-corpus: compiler ae stdlib
	@mkdir -p $(BUILD_DIR)/fuzz
	@./$(BUILD_DIR)/ae$(EXE_EXT) build tests/fuzz/ipc_frames/gen_corpus.ae 	    -o $(BUILD_DIR)/fuzz/gen_ipc_corpus$(EXE_EXT)
	@./$(BUILD_DIR)/fuzz/gen_ipc_corpus$(EXE_EXT) tests/fuzz/ipc_frames/corpus

# Test .ae source files - compiles and runs each test file.
#
# The shell tests run $(NPROC) at a time (SH_NPROC overrides). They were serial
# because they shared three things, all now fixed (#1920): the HTTP fixtures
# bound hardcoded ports, four tests cleared the one build cache while three
# others asserted HIT/MISS against it, and two ran `make install` in this tree,
# which cleaned build/ away from every other test. A test that needs a cache to
# itself sets AETHER_CACHE_DIR; a server fixture binds port 0 and prints the
# port it got.
#
# A parallel run makes an individual test slower without anything being wrong,
# so the per-test timeout is generous enough not to fail a merely contended one
# and still short enough to catch a hang (AE_SH_TEST_TIMEOUT below).
#
# A test that asserts on its own timing (one size's CPU time within a multiple
# of another's) cannot get that from a busy machine: with every core working,
# the larger case loses more to the shared caches and memory, and a linear
# check read 8x (#3604). A directory with a RUN_ALONE marker runs after the
# parallel shell phase, one at a time, still in its shard and in the verdict.
#
# The recipe exports CC because several integration tests compile a C host
# against libaether.a, and they default to `cc`. MSYS2's mingw64 ships a cc,
# but WinLibs does not -- and WinLibs is the toolchain `ae` itself downloads
# on a Windows box with no compiler (ensure_gcc_windows), so the tests could
# not build a C host on the toolchain Aether had just installed for them.
# BASE_CC is the plain compiler the build already resolved (gcc, else cc,
# else clang) WITHOUT the ccache prefix -- tests invoke it as "$CC", which a
# two-word "ccache gcc" would break. An explicit CC from the environment
# still wins.
#
# The helper scripts the sweep runs live in tests/scripts/ rather than being
# printf'd into a temp dir: doing the latter pushed this recipe past the 8 KB
# command line mingw32-make hands to sh -c, and the truncated tail broke
# `make test-ae` outright on Windows. See tests/scripts/run_ae_test.sh.
#
# AE_SWEEP_EXTRA_PRUNE's entries are fixed substrings of a path, where a
# trailing slash pins a directory (as in tests/ae_sweep_prune.txt). The shell
# test directories are matched with a slash appended: dirname prints none, so
# a pinned directory matched no shell test (#3539).
ifdef WINDOWS_NATIVE
test-ae: compiler ae stdlib
	@echo ===================================
	@echo   Running Aether Source Tests (.ae)
	@echo ===================================
	@.\build\ae.exe test
else
test-ae: compiler ae stdlib
	@echo "==================================="
	@echo "  Running Aether Source Tests (.ae)"
	@echo "  Parallel: $(NPROC) jobs$${AE_SWEEP_SHARD:+, shard $$AE_SWEEP_SHARD}"
	@echo "==================================="
	@# A bad AE_SWEEP_SHARD (#2757) must fail here: inside the pipelines below
	@# it would leave the sweep with nothing to run, and nothing reads as a pass.
	@sh tests/scripts/sweep_shard.sh < /dev/null
	@rm -f $(BUILD_DIR)/test-ae.verdict $(BUILD_DIR)/test-ae.unreported
	@tmpdir=$$(mktemp -d); \
	root=$$(pwd); \
	script="$$root/tests/scripts/run_ae_test.sh"; \
	CC="$${CC:-$(BASE_CC)}"; export CC; \
	MAKE="$(MAKE_COMMAND)"; export MAKE; \
	if [ -n "$(AE_SWEEP_EXTRA_PRUNE)" ]; then \
	  echo "  Extra prune list: $(AE_SWEEP_EXTRA_PRUNE) ($$(sed '/^#/d;/^$$/d' "$(AE_SWEEP_EXTRA_PRUNE)" | wc -l | tr -d ' ') patterns)"; \
	fi; \
	sh tests/scripts/ae_sweep_list.sh "$(AE_SWEEP_EXTRA_PRUNE)" | sh tests/scripts/sweep_shard.sh \
	    > "$$tmpdir/units_ae.txt"; \
	sh tests/scripts/sweep_cpu.sh mark "$$tmpdir" ae_start; \
	xargs -P $(NPROC) -I{} sh "$$script" "{}" "$$tmpdir" "$$root" < "$$tmpdir/units_ae.txt"; \
	sh tests/scripts/sweep_cpu.sh mark "$$tmpdir" ae_end; \
	sh_script="$$root/tests/scripts/run_ae_sh_dir.sh"; \
	sh_nproc=$${SH_NPROC:-$(NPROC)}; \
	if [ -n "$(AE_SWEEP_EXTRA_PRUNE)" ]; then \
	  sed '/^#/d;/^$$/d' "$(AE_SWEEP_EXTRA_PRUNE)" > "$$tmpdir/shprune.txt"; \
	else \
	  : > "$$tmpdir/shprune.txt"; \
	fi; \
	find tests/integration -name 'test_*.sh' 2>/dev/null | xargs -n1 dirname | sort -u | sed 's|$$|/|' \
	    | { if [ -s "$$tmpdir/shprune.txt" ]; then grep -v -F -f "$$tmpdir/shprune.txt"; else cat; fi; } \
	    | sed 's|/$$||' \
	    | { if [ -n "$(AE_SWEEP_OPTIONAL)" ]; then cat; else \
	          while read -r d; do [ -f "$$d/NEEDS_EXTERNAL_TOOLCHAIN" ] || echo "$$d"; done; fi; } \
	    > "$$tmpdir/shdirs.txt"; \
	{ for d in $$(cat "$$tmpdir/shdirs.txt"); do \
	    if [ -f "$$d/DRIVERS_INDEPENDENT" ]; then find "$$d" -maxdepth 1 -name 'test_*.sh' | sort; fi; \
	  done; \
	  for d in $$(cat "$$tmpdir/shdirs.txt"); do \
	    [ -f "$$d/DRIVERS_INDEPENDENT" ] || echo "$$d"; \
	  done; } | sh tests/scripts/sweep_shard.sh > "$$tmpdir/units_sh.txt"; \
	: > "$$tmpdir/units_sh_par.txt"; : > "$$tmpdir/units_sh_alone.txt"; \
	while read -r u; do \
	  d="$$u"; [ -d "$$d" ] || d=$$(dirname "$$u"); \
	  if [ -f "$$d/RUN_ALONE" ]; then echo "$$u" >> "$$tmpdir/units_sh_alone.txt"; \
	  else echo "$$u" >> "$$tmpdir/units_sh_par.txt"; fi; \
	done < "$$tmpdir/units_sh.txt"; \
	sh tests/scripts/sweep_cpu.sh mark "$$tmpdir" sh_start; \
	xargs -P $$sh_nproc -I{} sh "$$sh_script" "{}" "$$tmpdir" "$$root" < "$$tmpdir/units_sh_par.txt"; \
	xargs -P 1 -I{} sh "$$sh_script" "{}" "$$tmpdir" "$$root" < "$$tmpdir/units_sh_alone.txt"; \
	sh tests/scripts/sweep_cpu.sh mark "$$tmpdir" sh_end; \
	times > "$$tmpdir/times.txt"; \
	passed=$$(ls "$$tmpdir"/PASS_* 2>/dev/null | wc -l | tr -d ' '); \
	failed=$$(ls "$$tmpdir"/FAIL_* 2>/dev/null | wc -l | tr -d ' '); \
	skipped=$$(ls "$$tmpdir"/SKIP_* 2>/dev/null | wc -l | tr -d ' '); \
	total=$$((passed + failed + skipped)); \
	unrep="$$root/$(BUILD_DIR)/test-ae.unreported"; \
	expected=$$(sh "$$root/tests/scripts/sweep_unreported.sh" "$$tmpdir" "$$unrep"); \
	unreported=$$(wc -l < "$$unrep" | tr -d ' '); \
	echo ""; \
	if [ "$$failed" -gt 0 ]; then \
		echo "=== FAILURE DETAILS ==="; \
		for fail_file in "$$tmpdir"/FAIL_*; do \
			fname=$$(basename "$$fail_file" | sed 's/^FAIL_//'); \
			phase=$$(cat "$$tmpdir/phase_$$fname.txt" 2>/dev/null || echo unknown); \
			case "$$phase" in \
				compile) echo "--- $$fname (compile error) ---" ;; \
				runtime) rc=$$(cat "$$tmpdir/rc_$$fname.txt" 2>/dev/null || echo '?'); \
				         echo "--- $$fname (runtime error, exit $$rc) ---" ;; \
				timeout) echo "--- $$fname (TIMED OUT — hung; killed by per-test timeout) ---" ;; \
				signal)  echo "--- $$fname (KILLED BY A SIGNAL — see the [SIGNAL] line above) ---" ;; \
				shell)   echo "--- $$fname (shell test) ---" ;; \
				*)       echo "--- $$fname ---" ;; \
			esac; \
			if [ "$$phase" = "compile" ]; then \
				cat "$$tmpdir/build_$$fname.err" 2>/dev/null || echo "(no error output)"; \
			else \
				if [ -s "$$tmpdir/run_$$fname.out" ]; then \
					echo "(stdout)"; cat "$$tmpdir/run_$$fname.out"; \
				fi; \
				if [ -s "$$tmpdir/run_$$fname.err" ]; then \
					echo "(stderr)"; cat "$$tmpdir/run_$$fname.err"; \
				fi; \
				if [ ! -s "$$tmpdir/run_$$fname.out" ] && [ ! -s "$$tmpdir/run_$$fname.err" ]; then \
					echo "(no output)"; \
				fi; \
			fi; \
			echo ""; \
		done; \
	fi; \
	if [ "$$unreported" -gt 0 ]; then \
		echo "=== TESTS THAT NEVER REPORTED ($$unreported of the $$expected listed) ==="; \
		sed 's/^/  /' "$$unrep"; \
		echo ""; \
	fi; \
	sh "$$root/tests/scripts/sweep_timings.sh" "$$tmpdir"; \
	sh "$$root/tests/scripts/sweep_cpu.sh" report "$$tmpdir" $(NPROC) "$$sh_nproc"; \
	echo "Aether Tests: $$passed passed, $$failed failed, $$skipped skipped, $$total total"; \
	printf '%s %s %s %s %s\n' "$$passed" "$$failed" "$$skipped" "$$total" "$$expected" > "$$root/$(BUILD_DIR)/test-ae.verdict"; \
	rm -rf "$$tmpdir"; \
	if [ "$$failed" -gt 0 ] || [ "$$unreported" -gt 0 ]; then exit 1; fi
	@# A shell that stopped before its tally can still leave make with status
	@# 0, and an xargs that ran part of its list can return 0 (#3111): only a
	@# written tally with no failure, and a report from every listed test, is
	@# a pass.
	@sh tests/scripts/sweep_verdict.sh $(BUILD_DIR)/test-ae.verdict $(BUILD_DIR)/test-ae.unreported
endif

# Install smoke test: installs to a temp dir, runs ae init + ae run, cleans up
test-install: compiler ae stdlib
	@echo "==================================="
	@echo "  Install Smoke Test"
	@echo "==================================="
	@tmpdir=$$(mktemp -d) && \
	echo "  Installing to $$tmpdir..." && \
	{ ./install.sh "$$tmpdir" < /dev/null > "$$tmpdir/install.log" 2>&1 || \
	  { echo "  install.sh failed:"; tail -30 "$$tmpdir/install.log" | sed 's/^/      /'; false; }; } && \
	echo "  Testing ae version..." && \
	AETHER_HOME="$$tmpdir" "$$tmpdir/bin/ae$(EXE_EXT)" version > /dev/null 2>&1 && \
	echo "  Checking no co-located spec was installed..." && \
	shipped_specs=$$(find "$$tmpdir/share/aether/std" -type f -name 'test_*.ae' 2>/dev/null | head -5) && \
	{ test -z "$$shipped_specs" || (echo "  FAIL: install.sh shipped std/**/test_*.ae (#1584):"; echo "$$shipped_specs" | sed 's/^/        /'; exit 1); } && \
	echo "  Testing ae init + ae run..." && \
	projdir=$$(mktemp -d) && \
	cd "$$projdir" && \
	AETHER_HOME="$$tmpdir" "$$tmpdir/bin/ae$(EXE_EXT)" init smoketest > /dev/null 2>&1 && \
	cd smoketest && \
	output=$$(AETHER_HOME="$$tmpdir" "$$tmpdir/bin/ae$(EXE_EXT)" run 2>&1) && \
	echo "  Output: $$output" && \
	echo "$$output" | grep -q "Hello from smoketest" && \
	echo "  Cleaning up..." && \
	rm -rf "$$tmpdir" "$$projdir" && \
	echo "  [PASS] Install smoke test" || \
	(echo "  [FAIL] Install smoke test"; rm -rf "$$tmpdir" "$$projdir" 2>/dev/null; exit 1)
	@# install.sh --contrib-too, its unknown-flag refusal, and make install's
	@# refusal to default PREFIX as root.
	@MAKE="$(MAKE)" sh tests/scripts/check_install_options.sh

# Release archive smoke test: packages a tarball exactly like release.yml,
# extracts it (simulating `ae version install`), and verifies ae init + ae run
# work from the extracted layout. This catches archive structure bugs that
# test-install (which tests install.sh) would miss.
# #1395: a release archive built from an older tree than the sources it ships
# links fine for us and fails at the user's build, silently until someone calls
# the one function added last. Verified here, next to the archive packaging.
.PHONY: check-archive-exports
check-archive-exports: stdlib
	@echo "==================================="
	@echo "  Archive Export Check"
	@echo "==================================="
	@sh scripts/check_archive_exports.sh $(BUILD_DIR)/libaether.a

# #2207: check-archive-exports above only ever ran on a host that HAS zlib
# (every normal dev box and CI runner), so a symbol whose only definition
# was in std/zlib/aether_zlib.c's `#ifdef AETHER_HAS_ZLIB` branch went
# unexported by its `#else` stub branch from 0.714.0 on. Only the release
# workflow's lean, zlib-less FreeBSD sysroot caught it, and it failed there
# on every release from 0.714.0 to 0.731.0, none of which published. Check
# the archive as a zlib-less build would produce it too, so a std module
# missing a no-zlib stub fails a normal CI run instead.
#
# Only the std sources that branch on AETHER_HAS_ZLIB differ in such a
# build, so rather than rebuild the tree with ZLIB=0 (every object depends
# on the .build-flags stamp, so that recompiles everything), compile just
# them without the define, swap them into a COPY of the archive, and check
# the copy. build/ is never touched, so the ordinary build that later ci
# steps and the CI steps after `make ci` (the hardened leg's checksec, the
# macOS leaks gate) read is exactly what it was. The list is found by grep,
# so a new source that branches on AETHER_HAS_ZLIB is covered without
# anyone remembering to add it.
ZLIB_DEPENDENT_SRCS = $(shell find std -name '*.c' -exec grep -l 'AETHER_HAS_ZLIB' {} +)

.PHONY: check-archive-exports-nozlib
check-archive-exports-nozlib: stdlib
	@echo "==================================="
	@echo "  Archive Export Check (no zlib)"
	@echo "==================================="
	@[ -n "$(ZLIB_DEPENDENT_SRCS)" ] || { \
	  echo "  [FAIL] no std source branches on AETHER_HAS_ZLIB; this check would test nothing"; exit 1; }
	@tmp=$$(mktemp -d) && trap 'rm -rf "$$tmp"' EXIT && \
	cp $(BUILD_DIR)/libaether.a "$$tmp/libaether.a" && \
	for src in $(ZLIB_DEPENDENT_SRCS); do \
	  obj="$$tmp/$$(basename "$$src" .c).o"; \
	  $(CC) $(filter-out -DAETHER_HAS_ZLIB,$(AETHER_REQUIRED_CFLAGS)) $(CFLAGS) \
	    -c "$$src" -o "$$obj" || exit 1; \
	  ar r "$$tmp/libaether.a" "$$obj" || exit 1; \
	done && \
	sh scripts/check_archive_exports.sh "$$tmp/libaether.a"

# The archive release.yml ships, staged by the same script (scripts/
# stage-release.sh), packed, extracted and used: `ae init` + `ae run` against
# the extracted tree. It used to rebuild the layout here by hand, which drifted
# from what the release actually packed, so a packaging break (0.757.0 to
# 0.759.0) passed this test and failed the release.
test-release-archive: compiler ae stdlib check-archive-exports
	@echo "==================================="
	@echo "  Release Archive Smoke Test"
	@echo "==================================="
	@tmpdir=$$(mktemp -d) && \
	reldir="$$tmpdir/release" && \
	{ sh scripts/stage-release.sh $(BUILD_DIR) "$$reldir" --contrib-archives --module-artifacts $(BUILD_DIR)/aetherc$(EXE_EXT) > "$$tmpdir/stage.log" 2>&1 || \
	  { echo "  FAIL: scripts/stage-release.sh:"; tail -20 "$$tmpdir/stage.log" | sed 's/^/      /'; rm -rf "$$tmpdir"; exit 1; }; } && \
	echo "  Staged the release tree in $$reldir" && \
	echo "  Packing tarball..." && \
	(cd "$$reldir" && tar -czf "$$tmpdir/aether-test.tar.gz" *) && \
	echo "  Extracting to simulated version dir..." && \
	verdir="$$tmpdir/extracted" && mkdir -p "$$verdir" && \
	tar -xzf "$$tmpdir/aether-test.tar.gz" -C "$$verdir" && \
	echo "  Checking extracted layout..." && \
	test -f "$$verdir/bin/aetherc$(EXE_EXT)" || (echo "  FAIL: bin/aetherc missing"; exit 1) && \
	test -f "$$verdir/bin/ae$(EXE_EXT)"      || (echo "  FAIL: bin/ae missing"; exit 1) && \
	test -f "$$verdir/lib/libaether.a"       || (echo "  FAIL: lib/libaether.a missing"; exit 1) && \
	for h in include/*.h; do \
	  test -f "$$verdir/include/aether/$$(basename "$$h")" || { echo "  FAIL: include/aether/$$(basename "$$h") missing (#1420)"; exit 1; }; \
	done && \
	test -d "$$verdir/share/aether/runtime"  || (echo "  FAIL: share/aether/runtime missing"; exit 1) && \
	test -f "$$verdir/share/aether/runtime/coop_runtime_sources.txt" || (echo "  FAIL: the runtime list ae build --target=wasm reads is missing (#3383)"; exit 1) && \
	test -d "$$verdir/share/aether/std"      || (echo "  FAIL: share/aether/std missing"; exit 1) && \
	test -f "$$verdir/share/aether/tools/ae-fetch/main.ae" || (echo "  FAIL: the package fetcher's source is missing (#1362)"; exit 1) && \
	test -f "$$verdir/share/aether/contrib/sqlite/amalgamation/sqlite3.c" || (echo "  FAIL: the SQLite amalgamation is missing (#1372)"; exit 1) && \
	test -f "$$verdir/share/aether/contrib/quickjs/amalgamation/quickjs-amalgam.c" || (echo "  FAIL: the QuickJS amalgamation is missing"; exit 1) && \
	test -s "$$verdir/share/aether/MANIFEST" || (echo "  FAIL: share/aether/MANIFEST missing; ae cannot build from source without it"; exit 1) && \
	shipped_specs=$$(find "$$verdir/share/aether" -type f -name 'test_*.ae' | head -5) && \
	{ test -z "$$shipped_specs" || (echo "  FAIL: co-located specs shipped in the archive (#1584):"; echo "$$shipped_specs" | sed 's/^/        /'; exit 1); } && \
	echo "  Testing ae init + ae run from extracted archive..." && \
	projdir=$$(mktemp -d) && \
	cd "$$projdir" && \
	AETHER_HOME="$$verdir" "$$verdir/bin/ae$(EXE_EXT)" init archivetest > /dev/null 2>&1 && \
	cd archivetest && \
	output=$$(AETHER_HOME="$$verdir" "$$verdir/bin/ae$(EXE_EXT)" run 2>&1) && \
	echo "  Output: $$output" && \
	echo "$$output" | grep -q "Hello from archivetest" && \
	echo "  Testing ae add from extracted archive (no git, #1362)..." && \
	mkdir -p "$$projdir/mirror/example.com/acme/smoke/archive" "$$projdir/src/smoke-v1.0.0" "$$projdir/home" && \
	echo 'smoke() -> int { return 1 }' > "$$projdir/src/smoke-v1.0.0/smoke.ae" && \
	( cd "$$projdir/src" && tar -czf "$$projdir/mirror/example.com/acme/smoke/archive/v1.0.0.tar.gz" smoke-v1.0.0 ) && \
	{ mirror="$$projdir/mirror"; home="$$projdir/home"; \
	  if command -v cygpath >/dev/null 2>&1; then mirror=$$(cygpath -m "$$mirror"); home=$$(cygpath -m "$$home"); fi; \
	  HOME="$$projdir/home" USERPROFILE="$$home" AE_RELEASE_BASE_URL="file://$$mirror" AETHER_HOME="$$verdir" \
	    "$$verdir/bin/ae$(EXE_EXT)" add example.com/acme/smoke@v1.0.0 > "$$tmpdir/add.log" 2>&1 || true; } && \
	{ test -f "$$projdir/home/.aether/packages/example.com/acme/smoke/smoke.ae" || \
	  { echo "  FAIL: ae add from the extracted archive:"; sed 's/^/      /' "$$tmpdir/add.log"; exit 1; }; } && \
	echo "  Cleaning up..." && \
	rm -rf "$$tmpdir" "$$projdir" && \
	echo "  [PASS] Release archive smoke test" || \
	(echo "  [FAIL] Release archive smoke test"; rm -rf "$$tmpdir" "$$projdir" 2>/dev/null; exit 1)

# Run both C unit tests and .ae integration tests
# Syntax-and-warnings gate for the standalone sources. Compile only: several
# are benchmarks that take minutes, and what rots is the code, not the timing.
.PHONY: check-standalone
check-standalone:
	@echo "==================================="
	@echo "  Standalone sources (compile gate)"
	@echo "==================================="
	@fail=0; \
	for f in $(STANDALONE_SRC); do \
	  if $(CC) -fsyntax-only $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) -Werror \
	       -Itests/runtime -Itools/profiler -Istd/log $$f 2>$(BUILD_DIR)/standalone.err; then \
	    printf '  ok    %s\n' "$$f"; \
	  else \
	    printf '  FAIL  %s\n' "$$f"; \
	    head -5 $(BUILD_DIR)/standalone.err | sed 's/^/        /'; \
	    fail=1; \
	  fi; \
	done; \
	rm -f $(BUILD_DIR)/standalone.err; \
	if [ $$fail -ne 0 ]; then echo "check-standalone: FAILED"; exit 1; fi; \
	echo "check-standalone: all standalone sources compile clean"

test-all: test test-ae check-standalone
	@echo ""
	@echo "==================================="
	@echo "  All Tests Complete"
	@echo "==================================="

# Benchmark presets: full (10M), medium (1M), low (100K), stress (100M)
BENCHMARK_PRESET ?= low

# ---- Core benchmarks (#3518): sends, asks, strings, maps, JSON, ae ----
#
# bench-core                 runs benchmarks/core with this tree, best of
#                            BENCH_RUNS (default 5)
# bench-core-compare BASE=d  the same with the tree at d (built at the merge
#                            base) beside it, runs interleaved, change per row
#
# BENCH_ONLY=send,strings picks programs; the table also goes to
# build/bench-core.tsv. See benchmarks/core/run.ae.
.PHONY: bench-core bench-core-compare
bench-core: compiler ae stdlib
	@AETHER_HOME= ./$(BUILD_DIR)/ae run benchmarks/core/run.ae

bench-core-compare: compiler ae stdlib
ifndef BASE
	@echo "make bench-core-compare: set BASE to a tree built at the merge base"
	@echo "  e.g. git worktree add ../base \$$(git merge-base HEAD origin/main)"
	@echo "       make -C ../base compiler ae stdlib"
	@echo "       make bench-core-compare BASE=../base"
	@exit 1
endif
	@AETHER_HOME= BENCH_BASE="$(BASE)" ./$(BUILD_DIR)/ae run benchmarks/core/run.ae

# ---- JSON parser benchmark (standalone; no actor runtime needed) ----
#
# bench-json         — runs the current std/json parser against corpus/
# bench-json-compare — same + yyjson reference (auto-fetches yyjson to
#                      benchmarks/json/vendor/ on first use; vendor/ is
#                      gitignored so it never hits the repo)
# bench-json-gen     — (re)generates corpus fixtures including the 10 MB
#                      large.json. Idempotent and deterministic.
#
# The three targets are self-contained: they don't depend on `compiler`
# or `ae` because the bench runner links directly against the JSON source
# files it needs.

BENCH_JSON_CFLAGS := -O2 -Wall -Wextra \
  -Istd/json \
  -DAETHER_VERSION=\"bench\"
# The rewritten parser has zero stdlib-internal dependencies — no
# aether_collections, no aether_string. Keep the bench link small so
# changes to other stdlib files don't churn this build.
BENCH_JSON_SRCS := benchmarks/json/run_json_bench.c \
                   std/json/aether_json.c

.PHONY: bench-json bench-json-compare bench-json-gen bench-json-fetch-yyjson

$(BUILD_DIR)/gen_corpus: benchmarks/json/gen_corpus.c | $(BUILD_DIR)
	@$(CC) -O2 -Wall -Wextra $< -o $@

bench-json-gen: $(BUILD_DIR)/gen_corpus
	@mkdir -p benchmarks/json/corpus
	@$(BUILD_DIR)/gen_corpus api-response benchmarks/json/corpus/api-response.json
	@$(BUILD_DIR)/gen_corpus strings       benchmarks/json/corpus/strings-heavy.json
	@$(BUILD_DIR)/gen_corpus numbers       benchmarks/json/corpus/numbers-heavy.json
	@$(BUILD_DIR)/gen_corpus deep          benchmarks/json/corpus/deep.json
	@$(BUILD_DIR)/gen_corpus large         benchmarks/json/corpus/large.json
	@echo "✓ Corpus generated in benchmarks/json/corpus/"

$(BUILD_DIR)/run_json_bench: $(BENCH_JSON_SRCS) | $(BUILD_DIR)
	@echo "Compiling json bench runner..."
	@$(CC) $(BENCH_JSON_CFLAGS) $(BENCH_JSON_SRCS) -o $@ -lm

bench-json: $(BUILD_DIR)/run_json_bench
	@if [ ! -f benchmarks/json/corpus/large.json ]; then \
	  echo "Note: large.json missing — run 'make bench-json-gen' to create the full corpus."; \
	fi
	@$(BUILD_DIR)/run_json_bench

# Fetch yyjson (MIT) to benchmarks/json/vendor/ for apples-to-apples comparison.
# vendor/ is gitignored — yyjson is NOT vendored into the repo, it's a
# build-time fetch for this target only.
bench-json-fetch-yyjson:
	@mkdir -p benchmarks/json/vendor
	@if [ ! -f benchmarks/json/vendor/yyjson.c ]; then \
	  echo "Fetching yyjson for reference benchmark (not committed)..."; \
	  curl -sL -o benchmarks/json/vendor/yyjson.c https://raw.githubusercontent.com/ibireme/yyjson/master/src/yyjson.c || \
	    { echo "ERROR: could not fetch yyjson.c — network?"; exit 1; }; \
	  curl -sL -o benchmarks/json/vendor/yyjson.h https://raw.githubusercontent.com/ibireme/yyjson/master/src/yyjson.h || \
	    { echo "ERROR: could not fetch yyjson.h — network?"; exit 1; }; \
	fi

$(BUILD_DIR)/run_yyjson_bench: benchmarks/json/run_yyjson_bench.c benchmarks/json/vendor/yyjson.c | $(BUILD_DIR) bench-json-fetch-yyjson
	@echo "Compiling yyjson reference bench..."
	@$(CC) -O2 -Wall -Wextra -Ibenchmarks/json/vendor \
	  benchmarks/json/run_yyjson_bench.c \
	  benchmarks/json/vendor/yyjson.c \
	  -o $@

bench-json-compare: $(BUILD_DIR)/run_json_bench $(BUILD_DIR)/run_yyjson_bench
	@echo "=== current std.json parser ==="
	@$(BUILD_DIR)/run_json_bench
	@echo ""
	@echo "=== yyjson (reference, not vendored) ==="
	@$(BUILD_DIR)/run_yyjson_bench

# ---- JSON parser hardening targets ----
#
# test-json-asan  — parse every corpus fixture under AddressSanitizer
#                   + UndefinedBehaviorSanitizer. Portable across GCC
#                   ≥4.8 and every Clang (Linux + macOS).
# test-json-valgrind — same under Valgrind on Linux (macOS skips if no
#                      valgrind installed).
# The TLS conformance corpora (#1298), fetched at pinned commits into
# $(CONFORMANCE_CACHE) (default ~/.cache/aether-conformance), never committed.
# conformance-x509: x509-limbo and the bettertls suite it imports, against
# std.cryptography.tls13_cert (Linux CI runs it in ci-crypto-ct).
# conformance-bogo: BoringSSL's ssl/test/runner (BoGo) against the pure TLS
# client and server through tests/conformance/bogo/shim.ae; needs Go 1.27 and
# git, takes about five minutes, and is not run in CI. BOGO_FLAGS passes runner
# flags, e.g. BOGO_FLAGS="-test 'Basic-*'".
.PHONY: conformance-x509 conformance-bogo
conformance-x509: compiler ae stdlib
	@sh tests/conformance/x509_limbo/run.sh all

conformance-bogo: compiler ae stdlib
	@sh tests/conformance/bogo/run.sh $(BOGO_FLAGS)

# test-json-conformance — (Phase 4a) run JSONTestSuite if committed.

.PHONY: test-json-asan test-json-valgrind test-json-conformance

# Parser-focused ASan build: links only the parser + bench harness
# (same code paths as production), ignoring the broader stdlib so we
# don't pull in ASan-unfriendly subsystems.
$(BUILD_DIR)/run_json_bench_asan: $(BENCH_JSON_SRCS) | $(BUILD_DIR)
	@echo "Compiling json bench runner with ASan+UBSan..."
	@$(CC) -O1 -g -fsanitize=address,undefined -fno-omit-frame-pointer \
	  $(BENCH_JSON_CFLAGS) $(BENCH_JSON_SRCS) -o $@ -lm

test-json-asan: $(BUILD_DIR)/run_json_bench_asan
	@echo "==================================="
	@echo "  JSON parser: ASan + UBSan check"
	@echo "==================================="
	@if [ ! -f benchmarks/json/corpus/large.json ]; then \
	  $(MAKE) -s bench-json-gen >/dev/null; \
	fi
	@JSON_BENCH_WARMUP=2 JSON_BENCH_ITERS=10 $(BUILD_DIR)/run_json_bench_asan
	@echo "✓ JSON ASan+UBSan clean"

test-json-valgrind: $(BUILD_DIR)/run_json_bench
	@command -v valgrind >/dev/null 2>&1 || { \
	  echo "valgrind not installed — skipping (macOS and Windows usually don't have it)"; \
	  exit 0; \
	}
	@echo "==================================="
	@echo "  JSON parser: Valgrind leak + error check"
	@echo "==================================="
	@if [ ! -f benchmarks/json/corpus/large.json ]; then \
	  $(MAKE) -s bench-json-gen >/dev/null; \
	fi
	@JSON_BENCH_WARMUP=1 JSON_BENCH_ITERS=2 \
	  valgrind --error-exitcode=1 --leak-check=full --errors-for-leak-kinds=definite \
	  $(BUILD_DIR)/run_json_bench
	@echo "✓ JSON Valgrind clean"

test-json-conformance: $(BUILD_DIR)/run_json_conformance
	@if [ ! -d tests/conformance/json/cases ]; then \
	  echo "tests/conformance/json/cases/ not present."; \
	  exit 1; \
	fi
	@$(BUILD_DIR)/run_json_conformance tests/conformance/json/cases

$(BUILD_DIR)/run_json_conformance: tests/conformance/json/run_conformance.c std/json/aether_json.c | $(BUILD_DIR)
	@$(CC) -O2 -Wall -Wextra -Istd/json \
	  tests/conformance/json/run_conformance.c std/json/aether_json.c \
	  -o $@ -lm

# The suite without the results page: what the CI job runs
# (.github/workflows/benchmarks.yml), with BENCHMARK_MESSAGES, BENCH_RUNS,
# BENCH_WARMUP, BENCH_LANGS, BENCH_PATTERNS and BENCH_STRICT from the
# environment (benchmarks/cross-language/run_benchmarks.ae).
benchmark-results: compiler ae stdlib
	@echo "============================================"
	@echo "  Running Cross-Language Benchmark Suite"
	@echo "============================================"
	@echo ""
	@mkdir -p benchmarks/cross-language/build
	@echo "Building benchmark runner (Aether)..."
	@AETHER_HOME="" ./$(BUILD_DIR)/ae build benchmarks/cross-language/run_benchmarks.ae -o benchmarks/cross-language/build/bench_runner
	@cd benchmarks/cross-language && ./$(BUILD_DIR)/bench_runner

benchmark: benchmark-results
	@pkill -9 -f "benchmarks/cross-language/visualize/server" 2>/dev/null || true
	@echo ""
	@echo "Building Aether HTTP server..."
	@AETHER_HOME="" ./$(BUILD_DIR)/ae build benchmarks/cross-language/visualize/server.ae -o benchmarks/cross-language/visualize/server
	@echo "Server built successfully"
	@echo ""
	@echo "=========================================="
	@echo "  Launching Benchmark Visualization UI"
	@echo "=========================================="
	@echo ""
	@echo "Open your browser at http://localhost:8080"
	@echo "Press Ctrl+C to stop the server"
	@echo ""
	@cd benchmarks/cross-language/visualize && ./server

# `make examples` is the checker (check-examples below): every example built,
# run and compared with the output it says it prints. It used to build each
# file with aetherc and the C compiler alone, which an example run as a
# project, with --lib, by a script or through a contrib bridge cannot be.
# The checker's recipe is POSIX shell; under cmd.exe (WINDOWS_NATIVE)
# `make examples` builds every example with `ae examples`, as it always has.
ifdef WINDOWS_NATIVE
examples: compiler ae stdlib
	@.\$(BUILD_DIR)\ae.exe examples
else
examples: check-examples
endif


# Standalone aether-lsp binary — kept as a transitional alias for editor
# integrations that hardcode the binary name. The same code is also embedded
# in `aetherc` and runs via `aetherc lsp` (issue #327); new editor integrations
# should prefer that subcommand.
#
# `aether_lsp.c` is now part of `libaether_compiler.a` (so it's reusable
# across both binaries), so the link line just needs the 9-line wrapper
# at lsp/main.c plus the archive.
lsp: compiler stdlib
	@echo "==================================="
	@echo "Building Aether LSP Server ($(DETECTED_OS))"
	@echo "==================================="
	$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) lsp/main.c $(BUILD_DIR)/libaether_compiler.a $(BUILD_DIR)/libaether.a $(MANIFEST_OBJ) -Icompiler -Ilsp -Istd -Istd/collections -o $(BUILD_DIR)/aether-lsp$(EXE_EXT) $(AETHER_TOOL_LDFLAGS) $(LDFLAGS)
	@echo "✓ LSP Server built successfully: $(BUILD_DIR)/aether-lsp$(EXE_EXT)"

apkg:
	@echo "==================================="
	@echo "Building Aether Package Manager ($(DETECTED_OS))"
	@echo "==================================="
	$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) tools/apkg/main.c tools/apkg/apkg.c tools/apkg/toml_parser.c $(AETHER_TOOL_LDFLAGS) $(LDFLAGS) -o $(BUILD_DIR)/apkg$(EXE_EXT)
	@echo "✓ Package Manager built successfully: $(BUILD_DIR)/apkg$(EXE_EXT)"

# Per-object compile for the tools driver (#1221). Static pattern rule so it
# wins over the generic $(OBJ_DIR)/%.o rule (which uses CFLAGS, wrong include
# path and defines for tools). The order-only dir prereqs create the obj tree.
$(TOOLS_OBJS): $(OBJ_DIR)/%.o: %.c $(BUILD_FLAGS_STAMP) | $(OBJ_DIR)/tools $(OBJ_DIR)/tools/apkg
	@echo "Compiling $<..."
	@$(CC) $(TOOLS_CFLAGS) -c $< -o $@

ae: $(BUILD_DIR)/ae$(EXE_EXT) $(BUILD_TARGET_STAMP)

# A file target for the same reason as build/aetherc: `ae` was phony, so every
# `make` relinked the binary the rest of the test sweep is running.
$(BUILD_DIR)/ae$(EXE_EXT): $(BUILD_DIR)/aetherc$(EXE_EXT) $(TOOLS_OBJS) $(MANIFEST_OBJ)
	@echo "==================================="
	@echo "Building ae command-line tool ($(DETECTED_OS)) v$(VERSION)"
	@echo "==================================="
	@$(CC) $(TOOLS_OBJS) $(MANIFEST_OBJ) -o $(BUILD_DIR)/ae$(EXE_EXT) $(AETHER_TOOL_LDFLAGS) $(LDFLAGS) $(if $(AETHER_ENABLE_LLM),$(LLM_LDFLAGS))
	@echo "✓ Built successfully: $(BUILD_DIR)/ae$(EXE_EXT)"
	@echo ""
	@echo "Usage:"
	@echo "  ./$(BUILD_DIR)/ae run file.ae       Run a program"
	@echo "  ./$(BUILD_DIR)/ae build file.ae     Build an executable"
	@echo "  ./$(BUILD_DIR)/ae init myproject    Create a new project"
	@echo "  ./$(BUILD_DIR)/ae test              Run tests"
	@echo "  ./$(BUILD_DIR)/ae help              Show all commands"

profiler:
	@echo "==================================="
	@echo "Building Aether Profiler Dashboard ($(DETECTED_OS))"
	@echo "==================================="
	$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) -DAETHER_PROFILING tools/profiler/profiler_server.c tools/profiler/profiler_demo.c $(RUNTIME_SRC) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS) -o $(BUILD_DIR)/profiler_demo$(EXE_EXT)
	@echo "✓ Profiler built successfully: $(BUILD_DIR)/profiler_demo$(EXE_EXT)"
	@echo ""
	@echo "Run the demo and open http://localhost:8081"

docgen:
	@echo "==================================="
	@echo "Building Documentation Generator ($(DETECTED_OS))"
	@echo "==================================="
	@$(MKDIR) $(BUILD_DIR)
	$(CC) -O2 -Wall tools/docgen/docgen.c -o $(BUILD_DIR)/docgen$(EXE_EXT)
	@echo "✓ Documentation generator built: $(BUILD_DIR)/docgen$(EXE_EXT)"
	@echo ""
	@echo "Usage: ./$(BUILD_DIR)/docgen std docs/api"

docs-server: compiler
	@echo "==================================="
	@echo "Building Documentation Server ($(DETECTED_OS))"
	@echo "==================================="
	@./$(BUILD_DIR)/aetherc$(EXE_EXT) tools/docgen/server.ae $(BUILD_DIR)/docs_server_gen.c
	@# $(AETHER_REQUIRED_CFLAGS) for the same reason as the `release` target:
	@# this line compiles $(STD_SRC) directly, so without it the capability
	@# defines are absent and std/regex silently became no-op stubs.
	@$(CC) $(AETHER_REQUIRED_CFLAGS) -O2 -o $(BUILD_DIR)/docs-server$(EXE_EXT) $(BUILD_DIR)/docs_server_gen.c tools/docgen/server_ffi.c \
		$(RUNTIME_SRC) $(STD_SRC) $(STD_REACTOR_SRC) $(COLLECTIONS_SRC) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)
	@rm -f $(BUILD_DIR)/docs_server_gen.c
	@echo "✓ Documentation server built: $(BUILD_DIR)/docs-server$(EXE_EXT)"

docs: docgen
	@echo "==================================="
	@echo "Generating API Documentation"
	@echo "==================================="
	@# Everything in docs/api is docgen's output, so the folder is cleared
	@# first: a page for a module that no longer exists does not linger.
	@rm -rf docs/api
	@$(MKDIR) docs/api
	./$(BUILD_DIR)/docgen$(EXE_EXT) std docs/api
	@echo ""
	@echo "✓ Documentation generated in docs/api/"
	@echo "  Run 'make docs-serve' to view at http://localhost:3000"

docs-serve: docs docs-server
	@echo ""
	./$(BUILD_DIR)/docs-server$(EXE_EXT)

# ---- The shared runtime (#2297) ----
#
# The same objects as libaether.a, linked whole into one shared library, so a
# program and the --emit=lib libraries it imports in binary form share ONE
# runtime: one scheduler, one set of panic frames (a panic raised in a library
# reaches the program's catch), one config. A statically linked library keeps
# its own copy on every platform (on ELF `ae` links it -Bsymbolic, #3481).
# `ae build --shared-runtime` links against this.
#
# It lives in its own directory, never beside libaether.a: a linker searching
# -L<dir> for -laether takes a .so/.dylib/.dll.a there over the .a, and every
# default build must keep linking the static archive.
#
# On Windows the DLL is self-contained (AETHER_REQUIRED_LDFLAGS carries
# -static: libgcc, winpthread, OpenSSL and the rest are linked into it) and an
# import library is written next to it. Native builds only: a cross build has
# no use for a host shared library here.
SHARED_RT :=
ifeq ($(BUILD_DIR),build)
ifeq ($(PLATFORM),native)
ifneq ($(IS_WINDOWS),)
  SHARED_RT := $(BUILD_DIR)/shared/aether.dll
  SHARED_RT_LINK = -shared -Wl,--out-implib,$(BUILD_DIR)/shared/libaether.dll.a \
                   -Wl,--whole-archive $(BUILD_DIR)/libaether.a -Wl,--no-whole-archive
else ifeq ($(DETECTED_OS),Darwin)
  SHARED_RT := $(BUILD_DIR)/shared/libaether.dylib
  SHARED_RT_LINK = -dynamiclib -install_name @rpath/libaether.dylib \
                   -Wl,-force_load,$(BUILD_DIR)/libaether.a
else
  SHARED_RT := $(BUILD_DIR)/shared/libaether.so
  SHARED_RT_LINK = -shared -Wl,-soname,libaether.so \
                   -Wl,--whole-archive $(BUILD_DIR)/libaether.a -Wl,--no-whole-archive
endif
endif
endif

# Sandbox preload library (libaether_sandbox.so): the LD_PRELOAD
# interception layer spawn_sandboxed starts a child with, for cross-process
# containment. Built on Linux and FreeBSD; both have an rtld that honours
# LD_PRELOAD + dlsym(RTLD_NEXT, ...). Link flags differ: glibc needs -ldl
# -lrt; FreeBSD folds dlopen/shm_open into libc. Other platforms (macOS
# hardened runtime, Windows) have no preload path: spawn_sandboxed there is
# a stub. Its own rule (#3177), with its source and the two headers that
# source includes as prerequisites, so an edit to any of them or a deleted
# library rebuilds it. It was built inside the MANIFEST recipe, so only a
# change to the Makefile did, and a stale preload was tested and installed.
SANDBOX_PRELOAD :=
SANDBOX_PRELOAD_LIBS :=
ifeq ($(shell uname -s),Linux)
SANDBOX_PRELOAD := $(BUILD_DIR)/libaether_sandbox.so
SANDBOX_PRELOAD_LIBS := -ldl -lrt
else ifeq ($(shell uname -s),FreeBSD)
SANDBOX_PRELOAD := $(BUILD_DIR)/libaether_sandbox.so
endif
ifneq ($(SANDBOX_PRELOAD),)
$(SANDBOX_PRELOAD): runtime/libaether_sandbox_preload.c runtime/aether_sandbox_path.h runtime/aether_sandbox_match.h
	@echo "Building sandbox preload library..."
	@mkdir -p $(dir $@)
	@# The old library goes first: a rebuild that failed left it in place and
	@# reported it built, and install shipped a library its source no longer
	@# made. A failure is not fatal (spawn_sandboxed is then unavailable),
	@# and the compiler's output is kept beside it to say why.
	@rm -f $@
	@if $(CC) -shared -fPIC -o $@ runtime/libaether_sandbox_preload.c $(SANDBOX_PRELOAD_LIBS) > $@.log 2>&1; then \
	    rm -f $@.log; echo "✓ Sandbox preload: $@"; \
	else \
	    rm -f $@; echo "⚠ Sandbox preload: build failed, see $@.log (spawn_sandboxed will be unavailable)"; \
	fi
endif

# stunt (contrib/host/stunt): the test double a host bridge loads the way it
# loads an interpreter. `make stunt` builds libstunt and the stunt program
# into build/stunt/, for contrib-host-check's co-located spec; the tests in
# tests/integration/contrib_host_stunt build their own, with -Werror.
STUNT_DIR := $(BUILD_DIR)/stunt
ifneq ($(IS_WINDOWS),)
STUNT_LIB := $(STUNT_DIR)/stunt.dll
STUNT_SHARED := -shared
else ifeq ($(DETECTED_OS),Darwin)
STUNT_LIB := $(STUNT_DIR)/libstunt.dylib
STUNT_SHARED := -dynamiclib -fPIC
else
STUNT_LIB := $(STUNT_DIR)/libstunt.so
STUNT_SHARED := -shared -fPIC
endif
STUNT_LIBS := $(if $(filter Linux,$(DETECTED_OS)),-ldl,)
.PHONY: stunt
stunt: $(STUNT_LIB) $(STUNT_DIR)/stunt$(EXE_EXT)
$(STUNT_LIB): contrib/host/stunt/stunt.c contrib/host/stunt/stunt.h
	@mkdir -p $(dir $@)
	$(CC) -std=c11 -O1 -Wall -Wextra $(STUNT_SHARED) -o $@ contrib/host/stunt/stunt.c $(STUNT_LIBS)
$(STUNT_DIR)/stunt$(EXE_EXT): contrib/host/stunt/stunt.c contrib/host/stunt/stunt_main.c contrib/host/stunt/stunt.h
	@mkdir -p $(dir $@)
	$(CC) -std=c11 -O1 -Wall -Wextra -o $@ contrib/host/stunt/stunt.c contrib/host/stunt/stunt_main.c $(STUNT_LIBS)

# Precompiled stdlib archive — runtime + std for user programs.
stdlib: $(BUILD_DIR)/libaether.a $(MANIFEST_OBJ) $(LIB_MAIN_ARCHIVE) $(BUILD_TARGET_STAMP) $(SHARED_RT) $(SANDBOX_PRELOAD)

ifneq ($(SHARED_RT),)
$(SHARED_RT): $(BUILD_DIR)/libaether.a
	@echo "Linking the shared runtime..."
	@mkdir -p $(BUILD_DIR)/shared
	@$(CC) $(SHARED_RT_LINK) -o $@ $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)
	@echo "✓ Shared runtime: $@"

shared-runtime: $(SHARED_RT)
.PHONY: shared-runtime
endif

$(BUILD_DIR)/libaether_main.a: runtime/windows/aether_lib_main.c $(BUILD_FLAGS_STAMP)
	@mkdir -p $(OBJ_DIR)/runtime/windows
	@$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) -c runtime/windows/aether_lib_main.c -o $(OBJ_DIR)/runtime/windows/aether_lib_main.o
	@rm -f $@.tmp
	@$(AR) rcs $@.tmp $(OBJ_DIR)/runtime/windows/aether_lib_main.o
	@mv $@.tmp $@

$(BUILD_DIR)/aether_manifest.o: runtime/windows/aether.rc runtime/windows/aether.manifest
	@echo "Compiling the Windows application manifest..."
	@mkdir -p $(BUILD_DIR)
	@$(WINDRES) -I runtime/windows runtime/windows/aether.rc -O coff -o $@

# The archive is a FILE target, not a phony one. As a phony `stdlib` it was
# re-archived on every invocation, so anything that runs `make` in this tree
# (`make install` from two of the integration tests, say) rewrote it under
# whatever else was linking against it at that moment. A reader that catches
# the write half way through fails with `ld: ... member not 8-byte aligned`,
# in a test that has nothing to do with the one that ran make.
#
# Written to a temp name and renamed for the same reason: a rebuild that is
# genuinely needed still must not be observable as a partial archive. `ar` is
# also asked for a fresh archive rather than an update of the existing one, so
# a removed object cannot survive as a stale member.
$(BUILD_DIR)/libaether.a: $(STD_OBJS) $(STD_REACTOR_OBJS) $(COLLECTIONS_OBJS) $(RUNTIME_OBJS) $(BUILD_DIR)/libaether_compiler.a $(BUILD_DIR)/MANIFEST | $(VERSION_HEADER)
	@echo "Creating precompiled stdlib archive..."
	@rm -f $(BUILD_DIR)/libaether.a.tmp
	@$(AR) rcs $(BUILD_DIR)/libaether.a.tmp $(STD_OBJS) $(STD_REACTOR_OBJS) $(COLLECTIONS_OBJS) $(RUNTIME_OBJS)
	@mv $(BUILD_DIR)/libaether.a.tmp $(BUILD_DIR)/libaether.a
	@echo "✓ Stdlib archive created: $(BUILD_DIR)/libaether.a"

# Authoritative MANIFEST — list of link-suitable runtime + stdlib
# .c files for downstream consumers (aetherBuild and similar tools)
# that compile against the share/aether/ source tree. Generated
# from RUNTIME_SRC + STD_SRC so it stays in sync with what we
# actually link into libaether.a. Issue #329.
#
# Format: one path per non-comment, non-empty line. Paths are
# relative to share/aether/ in the install layout (and to the repo
# root in the source tree). Lines starting with `#` are comments.
$(BUILD_DIR)/MANIFEST: Makefile | $(BUILD_DIR)
	@echo "Generating MANIFEST..."
	@( \
	  echo "# Aether MANIFEST — link-suitable C source files for"; \
	  echo "# downstream consumers compiling against the runtime/std"; \
	  echo "# source tree (e.g. aetherBuild's aeb-link). Generated by"; \
	  echo "# the Makefile; do not edit by hand. Regenerated on every"; \
	  echo "# \`make stdlib\`."; \
	  echo "#"; \
	  echo "# Format: one path per non-comment, non-empty line. Paths"; \
	  echo "# are relative to this install root (share/aether/ on a"; \
	  echo "# system install; the repo root in the source tree)."; \
	  echo "# Lines starting with '#' are comments."; \
	  echo "#"; \
	  echo "# This file is the authoritative answer to 'which .c files"; \
	  echo "# do I compile to link against the Aether runtime?' — naive"; \
	  echo "# \`find runtime -name '*.c'\` walks pull in benchmarks /"; \
	  echo "# orphan poller hubs / etc. that aren't link-suitable."; \
	  echo ""; \
	  echo "# Runtime sources:"; \
	  for f in $(RUNTIME_SRC); do echo "$$f"; done; \
	  echo ""; \
	  echo "# Standard library sources:"; \
	  for f in $(STD_SRC); do echo "$$f"; done; \
	  echo ""; \
	  echo "# Collections sources:"; \
	  for f in $(COLLECTIONS_SRC); do echo "$$f"; done; \
	  echo ""; \
	  echo "# Reactor sources:"; \
	  for f in $(STD_REACTOR_SRC); do echo "$$f"; done; \
	) > $(BUILD_DIR)/MANIFEST
	@echo "✓ MANIFEST: $$(grep -c -v -E '^(#|$$)' $(BUILD_DIR)/MANIFEST) link-suitable files"

# Compiler-as-library archive — COMPILER_LIB_SRC without aetherc.c's main().
# Consumed by the LSP server and the sanitizer test runners. Kept separate
# from libaether.a because user programs never need the compiler embedded.
$(BUILD_DIR)/libaether_compiler.a: $(COMPILER_LIB_OBJS)
	@echo "Creating compiler-as-library archive..."
	@$(AR) rcs $@ $(COMPILER_LIB_OBJS)
	@echo "✓ Compiler-lib archive created: $@"

# Sanitizer / debug-flavoured archives.
#
# AddressSanitizer instrumentation only catches issues in code it touches
# at compile time — running asan-instrumented test code against an
# uninstrumented stdlib leaves any leak/UB in std/* invisible.
# Same logic for AETHER_MEMORY_TRACKING (the macro adds counters inside
# aether_memory.c that need to be defined when stdlib code calls into it)
# and for the -O0 -g shape that valgrind needs for legible traces.
#
# Building flavoured archives once per flavour lets each test runner
# link instantly while preserving full coverage. Pattern rules emit to
# `build/<flavour>-obj/...` so the default obj/ tree is untouched.

CFLAGS_NO_OPT := $(filter-out -O3 -O2 -O1 -O0,$(CFLAGS))
# Apple Clang on arm64 doesn't accept -fsanitize=leak (LeakSanitizer is
# bundled into ASan at runtime on Darwin). On Linux gcc/clang it must be
# requested explicitly. Platform-detect to keep both green.
ifeq ($(shell uname -s),Linux)
ASAN_FLAGS    := -fsanitize=address -fsanitize=leak -fno-omit-frame-pointer
else
ASAN_FLAGS    := -fsanitize=address -fno-omit-frame-pointer
endif
ASAN_OPT      := -O1 -g
MEM_FLAGS     := -DAETHER_MEMORY_TRACKING
DBG_OPT       := -O0 -g

ASAN_OBJ_DIR := $(BUILD_DIR)/asan-obj
MEM_OBJ_DIR  := $(BUILD_DIR)/memory-obj
DBG_OBJ_DIR  := $(BUILD_DIR)/dbg-obj
# Coverage variant — `gcc --coverage` is shorthand for
# `-fprofile-arcs -ftest-coverage` at compile and `-lgcov` at link.
# Produces .gcno files alongside .o (instrumentation) and .gcda
# files alongside the running binary (counters). gcov walks the .c
# (and follows #line directives — see PR #352) to produce both
# `<file>.c.gcov` and the `.ae.gcov` we actually want.
COV_FLAGS    := --coverage
COV_OPT      := -O0 -g
COV_OBJ_DIR  := $(BUILD_DIR)/cov-obj

ASAN_LIB_OBJS = $(STD_SRC:%.c=$(ASAN_OBJ_DIR)/%.o) \
                $(STD_REACTOR_SRC:%.c=$(ASAN_OBJ_DIR)/%.o) \
                $(COLLECTIONS_SRC:%.c=$(ASAN_OBJ_DIR)/%.o) \
                $(RUNTIME_SRC:%.c=$(ASAN_OBJ_DIR)/%.o)
ASAN_COMPILER_LIB_OBJS = $(COMPILER_LIB_SRC:%.c=$(ASAN_OBJ_DIR)/%.o)

MEM_LIB_OBJS = $(STD_SRC:%.c=$(MEM_OBJ_DIR)/%.o) \
               $(STD_REACTOR_SRC:%.c=$(MEM_OBJ_DIR)/%.o) \
               $(COLLECTIONS_SRC:%.c=$(MEM_OBJ_DIR)/%.o) \
               $(RUNTIME_SRC:%.c=$(MEM_OBJ_DIR)/%.o)
MEM_COMPILER_LIB_OBJS = $(COMPILER_LIB_SRC:%.c=$(MEM_OBJ_DIR)/%.o)

DBG_LIB_OBJS = $(STD_SRC:%.c=$(DBG_OBJ_DIR)/%.o) \
               $(STD_REACTOR_SRC:%.c=$(DBG_OBJ_DIR)/%.o) \
               $(COLLECTIONS_SRC:%.c=$(DBG_OBJ_DIR)/%.o) \
               $(RUNTIME_SRC:%.c=$(DBG_OBJ_DIR)/%.o)
DBG_COMPILER_LIB_OBJS = $(COMPILER_LIB_SRC:%.c=$(DBG_OBJ_DIR)/%.o)

COV_LIB_OBJS = $(STD_SRC:%.c=$(COV_OBJ_DIR)/%.o) \
               $(STD_REACTOR_SRC:%.c=$(COV_OBJ_DIR)/%.o) \
               $(COLLECTIONS_SRC:%.c=$(COV_OBJ_DIR)/%.o) \
               $(RUNTIME_SRC:%.c=$(COV_OBJ_DIR)/%.o)
COV_COMPILER_LIB_OBJS = $(COMPILER_LIB_SRC:%.c=$(COV_OBJ_DIR)/%.o)

$(ASAN_OBJ_DIR)/%.o: %.c | $(FRONTEND_ID_HEADER)
	@mkdir -p $(dir $@)
	@$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS_NO_OPT) $(ASAN_OPT) $(ASAN_FLAGS) -c $< -o $@

$(MEM_OBJ_DIR)/%.o: %.c | $(FRONTEND_ID_HEADER)
	@mkdir -p $(dir $@)
	@$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) $(MEM_FLAGS) -c $< -o $@

$(DBG_OBJ_DIR)/%.o: %.c | $(FRONTEND_ID_HEADER)
	@mkdir -p $(dir $@)
	@$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS_NO_OPT) $(DBG_OPT) -c $< -o $@

$(COV_OBJ_DIR)/%.o: %.c | $(FRONTEND_ID_HEADER)
	@mkdir -p $(dir $@)
	@$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS_NO_OPT) $(COV_OPT) $(COV_FLAGS) -c $< -o $@

$(BUILD_DIR)/asan/libaether.a: $(ASAN_LIB_OBJS)
	@mkdir -p $(BUILD_DIR)/asan
	@ar rcs $@ $(ASAN_LIB_OBJS)

$(BUILD_DIR)/asan/libaether_compiler.a: $(ASAN_COMPILER_LIB_OBJS)
	@mkdir -p $(BUILD_DIR)/asan
	@ar rcs $@ $(ASAN_COMPILER_LIB_OBJS)

$(BUILD_DIR)/memory/libaether.a: $(MEM_LIB_OBJS)
	@mkdir -p $(BUILD_DIR)/memory
	@ar rcs $@ $(MEM_LIB_OBJS)

$(BUILD_DIR)/memory/libaether_compiler.a: $(MEM_COMPILER_LIB_OBJS)
	@mkdir -p $(BUILD_DIR)/memory
	@ar rcs $@ $(MEM_COMPILER_LIB_OBJS)

$(BUILD_DIR)/dbg/libaether.a: $(DBG_LIB_OBJS)
	@mkdir -p $(BUILD_DIR)/dbg
	@ar rcs $@ $(DBG_LIB_OBJS)

$(BUILD_DIR)/dbg/libaether_compiler.a: $(DBG_COMPILER_LIB_OBJS)
	@mkdir -p $(BUILD_DIR)/dbg
	@ar rcs $@ $(DBG_COMPILER_LIB_OBJS)

$(BUILD_DIR)/cov/libaether.a: $(COV_LIB_OBJS)
	@mkdir -p $(BUILD_DIR)/cov
	@ar rcs $@ $(COV_LIB_OBJS)

$(BUILD_DIR)/cov/libaether_compiler.a: $(COV_COMPILER_LIB_OBJS)
	@mkdir -p $(BUILD_DIR)/cov
	@ar rcs $@ $(COV_COMPILER_LIB_OBJS)

stdlib-asan: $(BUILD_DIR)/asan/libaether.a $(BUILD_DIR)/asan/libaether_compiler.a
stdlib-memory: $(BUILD_DIR)/memory/libaether.a $(BUILD_DIR)/memory/libaether_compiler.a
stdlib-dbg: $(BUILD_DIR)/dbg/libaether.a $(BUILD_DIR)/dbg/libaether_compiler.a
stdlib-cov: $(BUILD_DIR)/cov/libaether.a $(BUILD_DIR)/cov/libaether_compiler.a

# Self-test: compiler on itself
self-test: compiler
	@echo "==================================="
	@echo "Running Compiler Self-Test"
	@echo "==================================="
	@echo "Testing compiler on complex syntax..."
	@./$(BUILD_DIR)/aetherc$(EXE_EXT) examples/02-actors/16-sharded-map.ae $(BUILD_DIR)/test_compile.c && \
		echo "✓ Complex syntax compilation successful"
	@echo ""
	@echo "Testing collections..."
	@$(MAKE) --no-print-directory test > /dev/null && echo "✓ All tests passed"
	@echo ""
	@echo "==================================="
	@echo "Self-test complete"
	@echo "==================================="

# Parallel link-time optimization for the release build. GCC's plain `-flto`
# runs the LTRANS partitions SERIALLY (`lto-wrapper: using serial compilation of
# N LTRANS jobs`), so the single monolithic release link pins one core and looks
# frozen while the other cores idle. Use parallel LTO where the toolchain
# supports it, falling back to plain `-flto` on older GCC so this never
# regresses a build that worked before:
#   clang     -> ThinLTO (`-flto=thin`, inherently parallel)
#   GCC >= 10 -> `-flto=auto` (fans LTRANS across all CPUs)
#   older GCC -> `-flto` (unchanged, serial but correct)
# Deferred (`=`) so the probe runs only when the release/install target actually
# builds (never for `make test` etc.) and sees the final $(CC) (incl. CC=).
LTO_FLAG = $(shell \
	if $(CC) --version 2>/dev/null | grep -qi clang; then echo -flto=thin; \
	elif [ "$$($(CC) -dumpversion 2>/dev/null | cut -d. -f1)" -ge 10 ] 2>/dev/null; then echo -flto=auto; \
	else echo -flto; fi)

# Release build with optimizations and warnings as errors.
#
# `release` wipes build/ first on purpose: what ships must not be assembled
# beside objects from a differently-configured build. That wipe is why it is a
# separate target from the compile below. `install` wants the optimized
# compiler, not the wipe -- and it used to get both, so `make install
# PREFIX=...` deleted build/ae out from under anything else using this tree,
# which is exactly what two integration tests do to the rest of the sweep.
#
# Sequential sub-makes rather than two prerequisites: under -j they are
# unordered, and `clean` racing $(STDLIB_SYMS_HEADER) deletes the header that
# was just generated.
release:
	@$(MAKE) clean
	@$(MAKE) release-build

release-build: $(BUILD_DIR)/aetherc-release$(EXE_EXT)

# A file target as well, so `make install` on a current tree does not spend a
# minute recompiling the whole compiler in one LTO link before copying.
$(BUILD_DIR)/aetherc-release$(EXE_EXT): $(COMPILER_SRC) $(STD_SRC) $(COLLECTIONS_SRC) $(AETHERC_RUNTIME_SRC) $(STDLIB_SYMS_HEADER) $(FRONTEND_ID_HEADER) $(VERSION_HEADER) $(MANIFEST_OBJ) Makefile
	@echo "==================================="
	@echo "Building Optimized Release"
	@echo "==================================="
	@$(MKDIR) $(BUILD_DIR)
	@echo "Compiling with -O3 -DNDEBUG $(LTO_FLAG) -Werror (parallel LTO; this can take a minute)..."
	@# -DAETHER_VERSION baked in from the same $(VERSION) the rest of
	@# the build uses (highest git tag → VERSION file fallback). Without
	@# this, compiler/aetherc.c falls back to the `v0.0.0-dev` sentinel,
	@# and since `make install` ships this exact binary as
	@# $(PREFIX)/bin/aetherc, every installed compiler reported the
	@# wrong version. The dev-build aetherc (compiled via the standard
	@# $(CFLAGS) pattern rule on line 133) has the flag and is correct;
	@# only the release-target hand-rolled gcc invocation was missing it.
	@# The capability CFLAGS have to come along: this hand-rolled line compiles
	@# $(STD_SRC) itself rather than reusing the pattern rule, so anything only
	@# $(AETHER_REQUIRED_CFLAGS) carries is otherwise absent. Missing
	@# $(PCRE2_CFLAGS) built std/regex as silent no-op stubs — every
	@# regex.compile in the SHIPPED aetherc failed at runtime while the build
	@# stayed clean. std.regex now refuses to compile stubs unless asked, which
	@# is what surfaced this. The matching LDFLAGS are already in $(LDFLAGS).
	@$(CC) -O3 -DNDEBUG $(LTO_FLAG) -Werror -Iinclude -Icompiler -Iruntime -Istd -Istd/collections \
		-DAETHER_VERSION=\"$(VERSION)\" \
		$(OPENSSL_CFLAGS) $(ZLIB_CFLAGS) $(NGHTTP2_CFLAGS) $(PCRE2_CFLAGS) $(YAML_CFLAGS) $(BROTLI_CFLAGS) $(ZSTD_CFLAGS) \
		$(COMPILER_SRC) $(filter-out std/yaml/aether_yaml.c std/yaml/aether_libfyaml_vendored.c,$(STD_SRC)) $(COLLECTIONS_SRC) $(AETHERC_RUNTIME_SRC) $(MANIFEST_OBJ) \
		-o $(BUILD_DIR)/aetherc-release$(EXE_EXT) $(AETHER_TOOL_LDFLAGS) $(LDFLAGS)
ifeq ($(DETECTED_OS),Linux)
	@echo "Stripping debug symbols..."
	@strip $(BUILD_DIR)/aetherc-release$(EXE_EXT)
else ifeq ($(DETECTED_OS),Darwin)
	@echo "Stripping debug symbols..."
	@strip -x $(BUILD_DIR)/aetherc-release$(EXE_EXT)
endif
	@echo "✓ Release build complete: $(BUILD_DIR)/aetherc-release$(EXE_EXT)"
	@ls -lh $(BUILD_DIR)/aetherc-release$(EXE_EXT)

# Install. The default prefix is the user's own ~/.aether, the same as
# install.sh and docs/install-layout.md, so an install needs no sudo and
# cannot leave a root-owned toolchain in /usr/local that every other checkout
# then falls back to (ae's last-resort compiler lookup and the compiler's
# last-resort std lookup both probe /usr/local). A system install says so:
# `sudo make install PREFIX=/usr/local`.
ifeq ($(origin PREFIX),undefined)
PREFIX := $(HOME)/.aether
PREFIX_DEFAULTED := 1
endif
# Under sudo, $(HOME) is usually root's, so a habitual `sudo make install`
# would land in /root/.aether. Refuse that and say what to type instead.
define REFUSE_ROOT_DEFAULT_PREFIX
	@if [ "$(PREFIX_DEFAULTED)" = 1 ] && [ "$$(id -u 2>/dev/null)" = 0 ]; then \
		echo "make $@: running as root with no PREFIX, which would install into $(PREFIX)."; \
		echo "  For your own user:  make $@               (no sudo; installs to ~/.aether)"; \
		echo "  For the system:     sudo make $@ PREFIX=/usr/local"; \
		exit 1; \
	fi
endef
install: $(VERSION_HEADER) release-build ae stdlib
	$(REFUSE_ROOT_DEFAULT_PREFIX)
	@echo "==================================="
	@echo "Installing Aether to $(PREFIX)"
	@echo "==================================="
	@install -d $(PREFIX)/bin
	@# Install WITH $(EXE_EXT) on both sides. Dropping it on the
	@# destination (which this used to do) is fatal on Windows: `ae`
	@# looks for its compiler as "aetherc" EXE_EXT — i.e. aetherc.exe —
	@# next to itself, so an extensionless install leaves `ae` unable to
	@# find `aetherc` even though the two sit in the same directory.
	@# `ae --version` keeps working (it never needs the compiler), so the
	@# box reports a healthy toolchain while every compile fails with the
	@# misleading "Aether compiler not found ... set AETHER_HOME".
	@# EXE_EXT is empty on POSIX, so this is a no-op there.
	@install -m 755 $(BUILD_DIR)/ae$(EXE_EXT) $(PREFIX)/bin/ae$(EXE_EXT)
	@install -m 755 $(BUILD_DIR)/aetherc-release$(EXE_EXT) $(PREFIX)/bin/aetherc$(EXE_EXT)
	@install -d $(PREFIX)/lib/aether
	@install -m 644 $(BUILD_DIR)/libaether.a $(PREFIX)/lib/aether/
	@# The shared runtime (#2297), in its own directory beside the archive:
	@# `ae build --shared-runtime` looks for it there.
	@if [ -d $(BUILD_DIR)/shared ]; then \
		install -d $(PREFIX)/lib/aether/shared && \
		cp $(BUILD_DIR)/shared/* $(PREFIX)/lib/aether/shared/; \
	fi
	@# Linux and FreeBSD: the sandbox's preload library, which spawn_sandboxed
	@# starts a child with; it looks for it here, under AETHER_HOME (#3177).
	@if [ -f $(BUILD_DIR)/libaether_sandbox.so ]; then \
		install -m 755 $(BUILD_DIR)/libaether_sandbox.so $(PREFIX)/lib/aether/; \
	fi
	@# Version stamp next to libaether.a. `ae build` reads this and
	@# compares it to the compiler's own version; a mismatch (the
	@# classic split where a stale `current` symlink shadows a fresh
	@# install) is reported up front instead of surfacing only as a
	@# cryptic `undefined reference to aether_*` at link time.
	@printf '%s\n' "$(VERSION)" > $(PREFIX)/lib/aether/VERSION
	@# Headers: walk the runtime/ and std/ trees and mirror every .h
	@# into $(PREFIX)/include/aether. Whole-tree copy (rather than the
	@# per-subdir enumeration this used to do) so new modules don't
	@# silently fall off the install — any module added under std/ or
	@# any new subdir under std/http/, std/collections/ etc. is
	@# captured automatically.
	@install -d $(PREFIX)/include/aether
	@# Generated C includes the slice helpers by their short header name. Keep
	@# this header at the public include root as well as under runtime/ so
	@# installed embedders using the normal -I$(PREFIX)/include/aether flag can
	@# compile slice-bearing generated code.
	@install -m 644 runtime/aether_slice.h $(PREFIX)/include/aether/aether_slice.h
	@# Sidecar VERSION next to the headers, mirroring lib/aether/VERSION and
	@# written by the SAME install step from the SAME $(VERSION), so the two
	@# cannot diverge. Language-agnostic: a build tool's include-root resolver
	@# (or a human) can read it with no compiler in the loop to detect a
	@# partial / shadowed install (the stale ~/.local/include/aether case).
	@printf '%s\n' "$(VERSION)" > $(PREFIX)/include/aether/VERSION
	@# The public embedder header lives in include/, outside the runtime/ and
	@# std/ trees the walks below cover, so it was never installed at all and
	@# runtime/libaether_caps.c could not find it in an install (#1420).
	@install -m 644 include/*.h $(PREFIX)/include/aether/ 2>/dev/null || true
	@cd runtime && find . -name '*.h' -print | while read h; do \
		install -d "$(PREFIX)/include/aether/runtime/$$(dirname $$h)"; \
		install -m 644 "$$h" "$(PREFIX)/include/aether/runtime/$$h"; \
	done
	@cd std && find . -name '*.h' -print | while read h; do \
		install -d "$(PREFIX)/include/aether/std/$$(dirname $$h)"; \
		install -m 644 "$$h" "$(PREFIX)/include/aether/std/$$h"; \
	done
	@# Sources + module.ae descriptors: same whole-tree copy. The
	@# compiler resolver looks for `share/aether/std/<mod>/module.ae`
	@# (compiler/aether_module.c:491) on every `import std.X`, so
	@# every module dir — including the Aether-only ones (file, dir,
	@# path, list, map, host, intarr, tcp) — needs its module.ae
	@# present here for the install to be functional.
	@install -d $(PREFIX)/share/aether
	@# Remove each destination subtree before copying over it. `cp` opens an
	@# existing destination file with O_TRUNC and writes THROUGH it, so if
	@# anything has hardlinked these files — a deduplicated ~/.aether/versions
	@# store (#1783), or a user's own linking — a reinstall silently rewrites
	@# every peer that shares the inode, corrupting other installed versions.
	@# `install -m` is safe because it unlinks first; plain `cp` is not, and
	@# `cp --remove-destination` is GNU-only, so remove-then-copy is the
	@# portable form. Cheap: these are re-copied wholesale anyway.
	@-$(RM_DIR) $(PREFIX)/share/aether/runtime
	@-$(RM_DIR) $(PREFIX)/share/aether/std
	@cp -R runtime $(PREFIX)/share/aether/
	@cp -R std     $(PREFIX)/share/aether/
	@# include/ too: share/aether/runtime/libaether_caps.c does
	@# `#include "../include/libaether.h"`, which resolves against
	@# share/aether/include/ — present in the source tree but, before this,
	@# absent from the install (headers go to include/aether/, a different
	@# root). Native builds add an extra -I that hides the gap; the cross
	@# path (which reuses tc.include_flags) does not, so a caps-runtime
	@# cross-build died on `'../include/libaether.h' file not found`. Mirror
	@# the source layout so the relative include resolves either way.
	@-$(RM_DIR) $(PREFIX)/share/aether/include
	@cp -R include $(PREFIX)/share/aether/
	@# Contrib module.ae descriptors + headers (issue #334). With these
	@# in place, `import contrib.X` resolves the same way `import std.X`
	@# does — share/aether/contrib/<X>/module.ae sits next to
	@# share/aether/std/<X>/module.ae and the resolver searches both
	@# (compiler/aether_module.c:436-484). The matching .a archives are
	@# still built+installed separately by `make install-contrib`, which
	@# probes for system dependencies (sqlite3-dev, etc.); without that
	@# step `ae build` compiles contrib.sqlite's veneer and the shipped
	@# amalgamation itself, and the other C-backed modules @source theirs.
	@-$(RM_DIR) $(PREFIX)/share/aether/contrib
	@cp -R contrib $(PREFIX)/share/aether/
	@# The package fetcher's source: `ae add` builds it with this toolchain
	@# the first time it fetches a package (#1362).
	@install -d $(PREFIX)/share/aether/tools/ae-fetch
	@install -m 644 tools/ae-fetch/main.ae $(PREFIX)/share/aether/tools/ae-fetch/main.ae
	@# Trim source-tree noise from the contrib install: tests, benchmarks,
	@# example .ae, $(BUILD_DIR)/CI scripts, and the .c/.m files (those compile
	@# into the libaether_<x>.a archives via `make contrib`; no value in
	@# also shipping the source). Mirrors the same trim install-contrib
	@# applies, kept here so `make install` alone yields a usable layout.
	@find $(PREFIX)/share/aether/contrib -type d -name tests       -exec rm -rf {} + 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type d -name benchmarks  -exec rm -rf {} + 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type f -name 'example_*.ae' -delete 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type f -name 'test_*.ae' -delete 2>/dev/null || true
	@# std module specs are co-located beside the modules they cover, so the
	@# install has to trim them the same way it trims contrib's — otherwise
	@# every user gets std/<mod>/test_<mod>.ae shipped with the toolchain.
	@find $(PREFIX)/share/aether/std -type f -name 'test_*.ae' -delete 2>/dev/null || true
	@# Compiled module artifacts (#1746): every Aether-authored std module,
	@# already parsed, under lib/aether/modules/ so an importer skips the
	@# parse. Built by the INSTALLED compiler binary, whose front-end
	@# fingerprint is the one that will check them. Removed first so an
	@# artifact for a module this release dropped cannot linger.
	@-$(RM_DIR) $(PREFIX)/lib/aether/modules
	@sh scripts/build_module_artifacts.sh $(BUILD_DIR)/aetherc-release$(EXE_EXT) . $(PREFIX)/lib/aether/modules
	@find $(PREFIX)/share/aether/contrib -type f -name 'test_*.sh' -delete 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type f -name 'build.sh'  -delete 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type f -name 'ci.sh'     -delete 2>/dev/null || true
	@# Drop .c / .m noise EXCEPT the host bridges. `make install`
	@# (no install-contrib) does NOT ship libaether_host_<lang>.a, so
	@# downstream apps that `import contrib.host.<lang>` need the bridge
	@# source to compile in. Without this carve-out the resolver finds
	@# module.ae / .h but the link step has no `aether_host_<lang>_*`
	@# symbols available — broken installed tree. The .c a module.ae
	@# names with @source stays too (#2208): contrib.vulkan and friends
	@# compile theirs into the program rather than linking an archive.
	@sh .github/scripts/trim_contrib_sources.sh $(PREFIX)/share/aether/contrib --keep-host-bridges 2>/dev/null || true
	@# Trim install-noise that confuses external consumers (aetherBuild
	@# and the like). runtime/examples/ holds standalone benches with
	@# their own main(), never link-suitable, so a naive
	@# `find runtime -name '*.c'` consumer would try to link them. See
	@# new_nic_consideration.md for the broader "drop sources from
	@# install" question (Option C in aetherBuild's ask 3).
	@rm -rf $(PREFIX)/share/aether/runtime/examples
	@# Authoritative MANIFEST listing link-suitable .c files (#329).
	@# Downstream consumers (aetherBuild's aeb-link et al.) read this
	@# instead of guessing via `find runtime -name '*.c'` — the find
	@# would naively pull in benchmarks / orphan poller hubs / etc.
	@install -m 644 $(BUILD_DIR)/MANIFEST $(PREFIX)/share/aether/MANIFEST
	@# Restore ownership of $(BUILD_DIR)/ to the invoking user when running
	@# under sudo. Otherwise `sudo make install` re-runs the `release ae
	@# stdlib` build deps as root, leaving every object/archive/binary in
	@# $(BUILD_DIR)/ root-owned — which then makes the next plain `make` fail
	@# with "Permission denied" until the user manually chowns. SUDO_USER
	@# is set by sudo on every platform we build on; absent (no sudo) →
	@# this is a silent no-op. Failure (no chown perms, weird FS) → also
	@# a no-op so we never break the install summary.
	@if [ -n "$$SUDO_USER" ] && [ -d build ]; then \
		chown -R "$$SUDO_USER:$$(id -gn $$SUDO_USER 2>/dev/null || echo $$SUDO_USER)" build 2>/dev/null || true; \
	fi
	@# Prove the INSTALLED ae can actually reach its compiler, by
	@# compiling something. `ae version` is not sufficient: it never needs
	@# aetherc, so it reports a healthy toolchain even when `ae` cannot
	@# find the compiler at all — which is exactly how the Windows
	@# extensionless-install bug shipped, presenting as 57 red spec suites
	@# rather than a failed install. A trivial `ae build` exercises the
	@# lookup that actually matters.
	@# Non-fatal by design: a sandboxed or read-only TMPDIR must not fail
	@# an otherwise good install. It prints a loud warning instead.
	@tmpd="$${TMPDIR:-/tmp}/ae-install-check-$$$$"; \
	if mkdir -p "$$tmpd" 2>/dev/null; then \
	  printf 'main() {\n    println("ok")\n}\n' > "$$tmpd/smoke.ae"; \
	  if "$(PREFIX)/bin/ae$(EXE_EXT)" build "$$tmpd/smoke.ae" -o "$$tmpd/smoke$(EXE_EXT)" >"$$tmpd/out.txt" 2>&1; then \
	    echo "✓ Install check: the installed ae found aetherc and compiled a test program"; \
	  else \
	    echo "!! Install check FAILED: the installed ae could not compile."; \
	    echo "!! `ae version` may still work — it does not need the compiler."; \
	    echo "!! Check that $(PREFIX)/bin holds ae$(EXE_EXT) AND aetherc$(EXE_EXT):"; \
	    ls -l "$(PREFIX)/bin" 2>/dev/null | sed 's/^/!!   /'; \
	    sed 's/^/!!   /' "$$tmpd/out.txt" 2>/dev/null | head -12; \
	  fi; \
	  rm -rf "$$tmpd" 2>/dev/null || true; \
	fi
	@echo "✓ Installed successfully"
	@echo ""
	@echo "Run: ae version"
	@# Stale-`current`-symlink shadow check. `make install` writes the
	@# flat layout ($(PREFIX)/{bin,lib,include,share}/aether), but `ae`
	@# prefers $(PREFIX)/current/ whenever that symlink resolves to a
	@# tree with lib/aether or share/aether (tools/ae.c — the
	@# `ae version use` version-manager hook). A `current` left over
	@# from an older install or a past `ae version use` therefore
	@# silently shadows this fresh install: the dev rebuilds, installs,
	@# and `ae` keeps linking the stale toolchain. `ae` only warns when
	@# `current` is half-populated — a complete-but-stale tree looks
	@# valid and draws no diagnostic. Surface it loudly here so the
	@# `make && sudo make install` loop can't silently no-op. Warn
	@# only when `current` resolves to a real directory other than
	@# $(PREFIX) itself (a `current` -> $(PREFIX) symlink is harmless;
	@# a broken symlink doesn't shadow because `ae` stat-checks it).
	@cur=$$(cd "$(PREFIX)/current" 2>/dev/null && pwd -P); \
	pfx=$$(cd "$(PREFIX)" 2>/dev/null && pwd -P); \
	if [ -n "$$cur" ] && [ "$$cur" != "$$pfx" ]; then \
		echo ""; \
		echo "⚠  WARNING: $(PREFIX)/current shadows this install."; \
		echo "   $(PREFIX)/current -> $$(readlink "$(PREFIX)/current" 2>/dev/null || echo '?')"; \
		echo "   'ae' prefers current/ over the freshly-installed flat tree,"; \
		echo "   so it will keep using the stale toolchain above — not this build."; \
		echo "   Fix:  sudo rm $(PREFIX)/current      (use this flat install), or"; \
		echo "         ae version use <version>       (re-point the symlink)"; \
		echo ""; \
	fi

# -----------------------------------------------------------------
# contrib — build per-module static libs (libaether_<x>.a) for every
# contrib module whose system dependency is installed on this machine.
#
# contrib/ is a source-tree organising prefix; downstream consumes
# individual artifacts, not a bundled lib. Each module's bridge .c
# compiles to its own .a, named after the module — sqlite →
# libaether_sqlite.a, host/stunt → libaether_host_stunt.a, etc.
#
# Probe-and-build by design: machines without sqlite3-dev get no
# libaether_sqlite.a. The same module.ae still installs (so
# `import contrib.sqlite` resolves), but the link step fails loudly
# if the user actually imports a module whose .a wasn't built.
# Matches the per-build --with= capability-opt-in philosophy.
#
# Modules covered (v1):
#   - sqlite                    (-lsqlite3)
#   - avcodec                   (FFmpeg's decode libraries)
#   - host/stunt                (the test double; dlopens libstunt)
#   - host/aether               (fork+exec sandboxed child via LD_PRELOAD;
#                                libc + in-tree sandbox runtime only)
# The language bridges (host/{lua,python,tcl,perl,ruby,duktape,js,quickjs,
# go,tinygo,java,factor,racket,rhombus}) moved to
# https://github.com/aether-lang-dev/aether-guest-languages, which builds
# them itself (`ae add` it, then `import <lang>`). The widget toolkit
# (formerly contrib/aether_ui) spun out to
# https://github.com/aether-lang-dev/aether-ui and is no longer in this repo.
# The Servirtium climate-API record/replay harness (formerly
# contrib/climate_http_tests) moved to the servirtium-vcr repo's
# integration/climate_interop, where the VCR tapes + replay tests live.
# -----------------------------------------------------------------
contrib:
	@bash tests/scripts/contrib_build.sh

# install-contrib — install the .a archives built by `make contrib`
# plus each module's module.ae and headers. Trims test/example noise
# the same way `install:` trims runtime/examples.
#
# Layout:
#   $(PREFIX)/lib/aether/libaether_<module>.a       — link target
#   $(PREFIX)/share/aether/contrib/<module>/module.ae — import resolver
#   $(PREFIX)/share/aether/contrib/<module>/*.h     — public headers
#
# Downstream aether.toml then references the module by name:
#   [build]
#   link_flags = "-laether_sqlite -lsqlite3"
install-contrib: contrib
	$(REFUSE_ROOT_DEFAULT_PREFIX)
	@echo "==================================="
	@echo "Installing contrib modules to $(PREFIX)"
	@echo "==================================="
	@if [ ! -f $(BUILD_DIR)/contrib/MANIFEST ]; then \
		echo "  No manifest — run 'make contrib' first."; exit 1; \
	fi
	@install -d $(PREFIX)/lib/aether
	@install -d $(PREFIX)/share/aether/contrib
	@# Install built archives. Manifest lines: <name> <path> [<installed name>]
	@# (tab-separated). The third column overrides libaether_<name>.a: the
	@# vendored SQLite must stay libsqlite3.a for the module's -lsqlite3 (#1372).
	@awk -F'\t' 'NF>=2 { print $$1, $$2, (NF>=3 ? $$3 : "libaether_" $$1 ".a") }' $(BUILD_DIR)/contrib/MANIFEST | \
		while read -r name path inst; do \
			[ -z "$$name" ] && continue; \
			install -m 644 "$$path" "$(PREFIX)/lib/aether/$$inst"; \
			printf "  lib/aether/%s\n" "$$inst"; \
		done
	@# Mirror the contrib source tree for module.ae + headers.
	@# Trim noise: tests, benchmarks, example .ae, build scripts and
	@# CI scripts. host/{stunt,aether} and tinyweb ARE shipped.
	@-$(RM_DIR) $(PREFIX)/share/aether/contrib
	@cp -R contrib $(PREFIX)/share/aether/
	@find $(PREFIX)/share/aether/contrib -type d -name tests       -exec rm -rf {} + 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type d -name benchmarks  -exec rm -rf {} + 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type f -name 'example_*.ae' -delete 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type f -name 'test_*.ae' -delete 2>/dev/null || true
	@# std module specs are co-located beside the modules they cover, so the
	@# install has to trim them the same way it trims contrib's — otherwise
	@# every user gets std/<mod>/test_<mod>.ae shipped with the toolchain.
	@find $(PREFIX)/share/aether/std -type f -name 'test_*.ae' -delete 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type f -name 'test_*.sh' -delete 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type f -name 'build.sh'  -delete 2>/dev/null || true
	@find $(PREFIX)/share/aether/contrib -type f -name 'ci.sh'     -delete 2>/dev/null || true
	@# Drop the .c files now that they're compiled into .a — no
	@# reason to ship sources alongside the archive. Keep .h so
	@# downstream callers that #include the bridge header can, and the
	@# .c a module.ae names with @source (#2208), which no archive holds.
	@sh .github/scripts/trim_contrib_sources.sh $(PREFIX)/share/aether/contrib 2>/dev/null || true
	@# See the same SUDO_USER chown rationale on the `install:` target.
	@if [ -n "$$SUDO_USER" ] && [ -d build ]; then \
		chown -R "$$SUDO_USER:$$(id -gn $$SUDO_USER 2>/dev/null || echo $$SUDO_USER)" build 2>/dev/null || true; \
	fi
	@echo "✓ Contrib installed"

# Run an Aether program (compile + execute)
run: compiler
ifndef FILE
	@echo "Error: FILE not specified"
	@echo "Usage: make run FILE=examples/01-language/01-hello.ae"
	@exit 1
endif
	@echo "Compiling $(FILE) to C..."
	@./$(BUILD_DIR)/aetherc$(EXE_EXT) $(FILE) $(BUILD_DIR)/output.c
	@echo "Building executable..."
	@$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) $(BUILD_DIR)/output.c $(RUNTIME_SRC) $(STD_SRC) $(STD_REACTOR_SRC) $(COLLECTIONS_SRC) -o $(BUILD_DIR)/output$(EXE_EXT) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)
	@echo "Running..."
	@./$(BUILD_DIR)/output$(EXE_EXT)

# Compile an Aether program to executable
compile: compiler
ifndef FILE
	@echo "make compile: missing required FILE argument."
	@echo ""
	@echo "Usage:"
	@echo "  make compile FILE=path/to/script.ae [OUTPUT=name]"
	@echo ""
	@echo "Example:"
	@echo "  make compile FILE=examples/01-language/01-hello.ae"
	@echo "  make compile FILE=examples/02-actors/01-first-actor.ae OUTPUT=first_actor"
	@echo ""
	@echo "If you wanted to build the toolchain instead, run:"
	@echo "  make ae         # just the CLI"
	@echo "  make compiler   # just the compiler"
	@echo "  make            # everything"
	@exit 1
endif
ifndef OUTPUT
	OUTPUT := $(basename $(notdir $(FILE)))
endif
	@echo "Compiling $(FILE) to C..."
	@./$(BUILD_DIR)/aetherc$(EXE_EXT) $(FILE) $(BUILD_DIR)/$(OUTPUT).c
	@echo "Building executable..."
	@$(CC) $(AETHER_REQUIRED_CFLAGS) $(CFLAGS) $(BUILD_DIR)/$(OUTPUT).c $(RUNTIME_SRC) $(STD_SRC) $(STD_REACTOR_SRC) $(COLLECTIONS_SRC) -o $(BUILD_DIR)/$(OUTPUT)$(EXE_EXT) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)
	@echo "✓ Built: $(BUILD_DIR)/$(OUTPUT)$(EXE_EXT)"

# Interactive REPL — integrated into ae CLI, no external dependencies
repl: ae
	@./$(BUILD_DIR)/ae$(EXE_EXT) repl

# Build statistics
stats:
	@echo "==================================="
	@echo "Build Statistics"
	@echo "==================================="
	@echo "Object files:        $$(find $(OBJ_DIR) -name '*.o' 2>/dev/null | wc -l)"
	@echo "Dependency files:    $$(find $(OBJ_DIR) -name '*.d' 2>/dev/null | wc -l)"
	@echo "Source files:"
	@echo "  Compiler:          $$(echo $(COMPILER_SRC) | wc -w)"
	@echo "  Runtime:           $$(echo $(RUNTIME_SRC) | wc -w)"
	@echo "  Stdlib:            $$(echo $(STD_SRC) $(COLLECTIONS_SRC) | wc -w)"
	@echo "  Tests:             $$(echo $(TEST_SRC) | wc -w)"
	@echo ""
	@echo "Lines of code:"
	@find compiler runtime std -name '*.c' -o -name '*.h' | xargs wc -l | tail -1
	@echo ""
	@if [ -d $(OBJ_DIR) ]; then \
		echo "Build directory size:"; \
		du -sh build 2>/dev/null || echo "N/A"; \
	fi
	@echo "==================================="

# Parallel test execution
test-parallel:
	@echo "==================================="
	@echo "Running Tests in Parallel"
	@echo "==================================="
	@echo "Testing by category..."
	@for cat in compiler runtime collections network memory stdlib parser; do \
		echo "  Testing $$cat..."; \
		./$(BUILD_DIR)/test_runner$(EXE_EXT) --category=$$cat & \
	done; \
	wait
	@echo ""
	@echo "All parallel tests complete!"

clean:
ifdef WINDOWS_NATIVE
	@if exist build $(RM_DIR) build
else
	$(RM_DIR) build
endif

help:
	@echo "Aether Build System ($(DETECTED_OS))"
	@echo ""
	@echo "Quick Start:"
	@echo "  make ae             - Build 'ae' CLI tool (recommended)"
	@echo "  ./$(BUILD_DIR)/ae run file.ae      - Run a program (Go-style)"
	@echo "  ./$(BUILD_DIR)/ae build file.ae    - Build executable"
	@echo ""
	@echo "Or use Make directly:"
	@echo "  make                - Build compiler"
	@echo "  make run FILE=...   - Compile and run an Aether program"
	@echo "  make compile FILE=...- Compile Aether program to executable"
	@echo "  make test           - Run test suite"
	@echo ""
	@echo "Build Targets:"
	@echo "  make compiler       - Build compiler (incremental)"
	@echo "  make compiler-fast  - Build compiler (monolithic, faster for clean)"
	@echo "  make -j8            - Parallel build with 8 jobs (faster on multi-core hosts)"
	@echo "  make release        - Optimized release build (-O3, parallel LTO)"
	@echo "  make stdlib         - Build precompiled stdlib archive"
	@echo ""
	@echo "Run Targets:"
	@echo "  make run FILE=path/to/file.ae    - Compile and execute program"
	@echo "  make compile FILE=file.ae        - Compile to executable"
	@echo "  make repl                        - Start interactive REPL"
	@echo ""
	@echo "Test Targets:"
	@echo "  make test           - Run C unit tests (incremental)"
	@echo "  make test-ae        - Run .ae integration tests"
	@echo "  make test-all       - Run both C and .ae tests"
	@echo "  make check-standalone - Compile every standalone C main (benches, demos)"
	@echo "  make check-docs       - Compile the documentation's complete examples"
	@echo "  make check-tests      - The test suite can fail: verdicts reach the exit code, prune list is consistent, every std module has tests, listeners bind loopback, shell tests end background programs through server_jobs.sh and compare files with same_bytes, no `VAR=x shell_function` prefix (it leaks under macOS /bin/sh), test programs write temp files under names of their own and ask the build for the platform"
	@echo "  make check-extern-widths - Every extern bound to C in this tree agrees with the C definition on each width; no plain C long in a bound signature; no shared C function defined twice"
	@echo "  make check-raw-calls     - No file calls or re-declares a raw C binding another module declares"
	@echo "  make check-warnings      - Every .ae file under std and contrib type-checks without a warning"
	@echo "  make check-examples      - Every example builds clean and prints the output it says it prints"
	@echo "  make check-contrib-modules - Type-check every non-host contrib module"
	@echo "  make conformance-x509 - x509-limbo and bettertls against tls13_cert (fetched, pinned)"
	@echo "  make conformance-bogo - BoringSSL BoGo against the pure TLS stack (needs Go 1.27; not in CI)"
	@echo "  make check-changelog  - Validate changelog fragments, catch a release-fold"
	@echo "  make add-changelog    - Write a new_changelogs/ fragment (SECTION=, SLUG=)"
	@echo "  make collect-changelogs - Fold settled fragments into CHANGELOG.md"
	@echo "  make test-fast      - Run C tests (monolithic build)"
	@echo "  make test-install   - Install smoke test (init + run)"
	@echo "  make test-valgrind  - Run tests with Valgrind"
	@echo "  make test-asan      - Run tests with AddressSanitizer"
	@echo "  make test-ubsan     - C unit tests + .ae corpus with everything under UBSan; fails on any report (Linux, macOS)"
	@echo "  make self-test      - Test compiler on complex examples"
	@echo ""
	@echo "CI/CD Targets:"
	@echo "  make ci             - Full CI suite (build + test + install smoke test)"
	@echo "  make docker-ci      - Run CI in Docker (with Valgrind)"
	@echo "  make docker-build-ci- Build Docker CI image"
	@echo "  make valgrind-check - Run Valgrind memory leak detection (Linux only)"
	@echo "  ./scripts/run-ci-local.sh - Full CI with Docker (recommended)"
	@echo ""
	@echo "Tool Targets:"
	@echo "  make lsp            - Build LSP server"
	@echo "  make apkg           - Build project tooling"
	@echo "  make profiler       - Build profiler dashboard"
	@echo "  make docgen         - Build documentation generator"
	@echo "  make docs           - Generate API documentation (in docs/api/)"
	@echo "  make docs-serve     - Serve docs at http://localhost:3000"
	@echo ""
	@echo "Web Servers (localhost):"
	@echo "  make docs-serve     - API Documentation    :3000"
	@echo "  make benchmark      - Benchmark Dashboard  :8080"
	@echo "  make profiler       - Profiler Dashboard   :8081"
	@echo ""
	@echo "Other Targets:"
	@echo "  make benchmark-results - Run the cross-language benchmarks, no dashboard"
	@echo "  make examples       - Build and run every example (make check-examples)"
	@echo "  make install        - Install to $(PREFIX)"
	@echo "  make stats          - Show build statistics"
	@echo ""
	@echo "  make clean          - Remove build artifacts"
	@echo "  make help           - Show this help message"
	@echo ""
	@echo "Examples:"
	@echo "  make run FILE=examples/01-language/01-hello.ae"
	@echo "  make compile FILE=myapp.ae OUTPUT=myapp"
	@echo "  make -j8 test       - Build and test with 8 parallel jobs"
	@echo ""
	@echo "Platform: $(DETECTED_OS)"
	@echo "Compiler: $(CC)"

test-build: $(TEST_OBJS) $(COMPILER_LIB_OBJS) $(RUNTIME_OBJS) $(STD_OBJS) $(STD_REACTOR_OBJS) $(COLLECTIONS_OBJS)
	@echo "Building test runner..."
	@$(CC) $(TEST_OBJS) $(COMPILER_LIB_OBJS) $(RUNTIME_OBJS) $(STD_OBJS) $(STD_REACTOR_OBJS) $(COLLECTIONS_OBJS) -o $(BUILD_DIR)/test_runner$(EXE_EXT) $(AETHER_REQUIRED_LDFLAGS) $(LDFLAGS)

# Docker CI/CD targets
docker-build-ci:
	@echo "Building Docker CI image..."
	docker build -f docker/Dockerfile.ci -t aether-ci:latest .

docker-ci: docker-build-ci
	@echo "Running full CI suite + Valgrind + ASan in Docker..."
	docker run --rm -v $(PWD):/aether -w /aether aether-ci bash -c "make ci && make valgrind-check && make asan-check"

# Cross-compile with MinGW (replicates Windows CI without needing a Windows host)
# Step 1: Build native aetherc, generate .c from all examples
# Step 2: Cross-compile compiler sources with MinGW -Werror
# Step 3: Syntax-check generated .c files with MinGW
ci-windows: clean compiler
	@echo "==================================="
	@echo "  Windows Cross-Compilation Test"
	@echo "==================================="
	@echo ""
	@echo "[1/3] Generating C from all examples with native aetherc..."
	@mkdir -p $(BUILD_DIR)/win
	@pass=0; fail=0; \
	for src in $$(find examples -name '*.ae' | grep -v '/lib/' | grep -v '/packages/' | sort | xargs grep -L -e '^// Part of:' -e '^// Run: sh ' -e '^// Run: ae [^r]' -e '^// Run: ae run [^ ]*[^e] *$$' -e '^// Run: ae run .* --lib ' -e '^import contrib\.'); do \
		name=$$(echo $$src | sed 's|examples/||;s|\.ae$$||'); \
		printf "  %-30s " "$$name"; \
		mkdir -p "$(BUILD_DIR)/win/examples/$$(dirname $$name)"; \
		out_c="$(BUILD_DIR)/win/examples/$$name.c"; \
		rm -f "$$out_c"; \
		if ./$(BUILD_DIR)/aetherc "$$src" "$$out_c" 2>/tmp/ae_err.txt && [ -f "$$out_c" ]; then \
			echo "OK"; \
			pass=$$((pass + 1)); \
		else \
			echo "FAIL"; \
			cat /tmp/ae_err.txt 2>/dev/null | head -5; \
			fail=$$((fail + 1)); \
		fi; \
	done; \
	echo ""; \
	echo "  $$pass passed, $$fail failed"; \
	if [ "$$fail" -gt 0 ]; then exit 1; fi
	@echo ""
	@echo "[2/3] Cross-compiling compiler sources with MinGW -Werror..."
	@for f in $(COMPILER_LIB_SRC); do \
		printf "  %-50s " "$$f"; \
		if x86_64-w64-mingw32-gcc -O2 -Werror -c \
			-Icompiler -Iruntime -Iruntime/actors -Iruntime/scheduler \
			-Iruntime/utils -Iruntime/memory -Iruntime/config \
			-Istd -Istd/string -Istd/io -Istd/math -Istd/net -Istd/collections -Istd/json \
			-Wall -Wextra -Wno-unused-parameter -Wno-unused-function \
			-DAETHER_VERSION=\"test\" \
			"$$f" -o /dev/null 2>/tmp/mingw_err.txt; then \
			echo "OK"; \
		else \
			echo "FAIL"; \
			cat /tmp/mingw_err.txt 2>/dev/null | head -10; \
			exit 1; \
		fi; \
	done
	@echo "  All compiler sources clean under MinGW -Werror"
	@echo ""
	@echo "[3/3] Syntax-checking generated C with MinGW..."
	@pass=0; fail=0; \
	for src in $$(find examples -name '*.ae' | grep -v '/lib/' | grep -v '/packages/' | sort | xargs grep -L -e '^// Part of:' -e '^// Run: sh ' -e '^// Run: ae [^r]' -e '^// Run: ae run [^ ]*[^e] *$$' -e '^// Run: ae run .* --lib ' -e '^import contrib\.'); do \
		name=$$(echo $$src | sed 's|examples/||;s|\.ae$$||'); \
		out_c="$(BUILD_DIR)/win/examples/$$name.c"; \
		printf "  %-30s " "$$name"; \
		if [ ! -f "$$out_c" ]; then \
			echo "SKIP"; \
		elif x86_64-w64-mingw32-gcc -O2 -fsyntax-only \
			-Iruntime -Iruntime/actors -Iruntime/scheduler \
			-Iruntime/utils -Iruntime/memory -Iruntime/config \
			-Istd -Istd/string -Istd/io -Istd/math -Istd/net -Istd/collections -Istd/json \
			-Wall -Wextra -Wno-unused-parameter -Wno-unused-function \
			-Wno-missing-field-initializers -Wno-unused-variable -Wno-unused-label \
			"$$out_c" 2>/tmp/mingw_err.txt; then \
			echo "OK"; \
			pass=$$((pass + 1)); \
		else \
			echo "FAIL"; \
			cat /tmp/mingw_err.txt 2>/dev/null | head -10; \
			fail=$$((fail + 1)); \
		fi; \
	done; \
	echo ""; \
	echo "  $$pass passed, $$fail failed"; \
	if [ "$$fail" -gt 0 ]; then exit 1; fi
	@echo ""
	@echo "==================================="
	@echo "  Windows Cross-Compilation PASSED"
	@echo "==="

docker-ci-windows: docker-build-ci
	@echo "Running Windows cross-compilation tests in Docker..."
	docker run --rm -v $(PWD):/aether -w /aether aether-ci make ci-windows

# Each stage of `ci` outside the .ae sweep (whose tests and builds have bounds
# of their own) runs under a time bound, so a hang fails the stage by name
# instead of running until the job is lost (#2608). See run_stage.sh.
CI_STAGE = sh tests/scripts/run_stage.sh

# The test sweep of `make ci` alone, for a CI leg split in two (#2757): the
# toolchain built as `make ci` builds it, then test-ae with AE_SWEEP_SHARD
# (which tests/scripts/sweep_shard.sh reads). On Windows the other job runs
# `make ci`, which runs everything else once. CI_SWEEP_UNIT=1 runs the C unit
# tests too, for the macOS x86_64 leg, whose two jobs are both sweeps: the
# rest of `make ci` does not depend on the architecture, and the ARM64 leg
# runs it on macOS (#2772).
ci-sweep: clean
	@$(MAKE) audio-cache-restore
	@$(MAKE) -j$(NPROC) compiler EXTRA_CFLAGS=-Werror
	@$(MAKE) audio-cache-save
	@$(MAKE) -j$(NPROC) ae
	@$(MAKE) -j$(NPROC) stdlib
	@if [ "$(CI_SWEEP_UNIT)" = 1 ]; then $(CI_STAGE) 1200 "C unit tests" $(MAKE) -j$(NPROC) test; fi
	@$(MAKE) test-ae

ci: clean
	@echo "==================================="
	@echo "  Aether CI — Full Test Suite"
	@echo "  Parallel: $(NPROC) jobs (build) / $(NPROC) (.ae tests) / $${SH_NPROC:-$(NPROC)} (shell tests)"
	@echo "==================================="
	@echo ""
	@echo "[0/11] Restoring miniaudio object cache (if valid)..."
	@$(MAKE) audio-cache-restore
	@echo ""
	@echo "[1/11] Building compiler (-Werror)..."
	@$(MAKE) -j$(NPROC) compiler EXTRA_CFLAGS=-Werror
	@$(MAKE) audio-cache-save
	@echo ""
	@echo "[2/11] Building ae CLI..."
	@$(MAKE) -j$(NPROC) ae
	@echo ""
	@echo "[3/11] Building stdlib..."
	@$(MAKE) -j$(NPROC) stdlib
	@echo ""
	@echo "[4/11] Running C unit tests..."
	@$(CI_STAGE) 1200 "C unit tests" $(MAKE) -j$(NPROC) test
	@$(CI_STAGE) 900 check-standalone $(MAKE) check-standalone
	@$(CI_STAGE) 900 check-docs $(MAKE) check-docs
	@$(CI_STAGE) 900 check-tests $(MAKE) check-tests
	@$(CI_STAGE) 900 check-extern-widths $(MAKE) check-extern-widths
	@$(CI_STAGE) 600 check-raw-calls $(MAKE) check-raw-calls
	@$(CI_STAGE) 600 check-crypto-wipe $(MAKE) check-crypto-wipe
	@$(CI_STAGE) 900 check-warnings $(MAKE) check-warnings
	@echo ""
	@echo "[5/11] Running .ae integration tests..."
	@$(MAKE) test-ae
	@echo ""
	@echo "[6/11] Checking examples..."
	@$(CI_STAGE) 900 check-examples $(MAKE) check-examples
	@echo ""
	@echo "[7/11] Install smoke test..."
	@$(CI_STAGE) 900 test-install $(MAKE) test-install
	@echo ""
	@echo "[8/11] ae test smoke check..."
	@out=$$(AETHER_HOME="" $(CI_STAGE) 300 "ae test smoke" ./$(BUILD_DIR)/ae test examples/01-language/01-hello.ae 2>&1) || { echo "$$out"; exit 1; }; echo "$$out" | tail -1
	@echo "  [PASS] ae test runs correctly"
	@echo ""
	@echo "[9/11] Differential test (lowering paths agree)..."
	@$(CI_STAGE) 600 test-differential $(MAKE) test-differential
	@echo ""
	@echo "[10/11] Release archive smoke test..."
	@$(CI_STAGE) 900 test-release-archive $(MAKE) test-release-archive
	@echo ""
	@echo "[11/11] Archive export check without zlib (#2207)..."
	@$(CI_STAGE) 900 check-archive-exports-nozlib $(MAKE) check-archive-exports-nozlib
	@echo ""
	@echo "==================================="
	@echo "  CI PASSED — all checks green"
	@echo "==================================="

# -----------------------------------------------------------------
# Differential testing (#523)
#
# Runs every tests/differential/cases/*.ae through both lowering paths
# (--emit=exe and --emit=lib) and compares stdout + exit code. Per-path
# correctness is weaker than cross-path agreement: a bug that miscompiles
# one path passes today, because that path's expected output was generated
# from the same build. See docs/differential-testing.md.
# -----------------------------------------------------------------
.PHONY: test-differential
test-differential: ae
	@sh tests/differential/run_differential.sh

# The ownership grid (tests/ownership_grid/README.md): one generated program
# per value kind x place x transfer, built with a poisoning allocator linked
# in, run as it is and poisoned, and classified (OK, LEAK, UAF, WRONG,
# NOCOMPILE, CRASH, TIMEOUT). `ownership-grid` writes
# build/ownership_grid/report.md and report.csv; `ownership-grid-check` also
# fails when a cell is worse than tests/ownership_grid/baseline.txt and lists
# the cells that got better. windows.yml runs the check in three shards
# (OWNERSHIP_GRID_SHARD=k/n). The generator and the runner are Aether
# (tests/ownership_grid/gen.ae and run.ae), built here into
# build/ownership_grid/run; OWNERSHIP_GRID_ARGS passes options to it
# (`--mode both`, `--only 'K3-*'`, `--update-baseline`).
# -----------------------------------------------------------------
OWNERSHIP_GRID_RUNNER := $(BUILD_DIR)/ownership_grid/run$(EXE_EXT)
.PHONY: ownership-grid ownership-grid-check
ownership-grid ownership-grid-check: compiler ae stdlib
	@mkdir -p $(BUILD_DIR)/ownership_grid
	@./$(BUILD_DIR)/ae$(EXE_EXT) build tests/ownership_grid/run.ae --lib tests/ownership_grid \
	    -o $(OWNERSHIP_GRID_RUNNER)
	NPROC=$(NPROC) ./$(OWNERSHIP_GRID_RUNNER) \
	    $(if $(filter ownership-grid-check,$@),--check) $(OWNERSHIP_GRID_ARGS)

# -----------------------------------------------------------------
# Extern widths (#3097): every extern bound to a C function of this tree
# agrees with the C definition on the width of each argument and of the
# result, and no bound C signature uses a plain `long` (32 bits on Windows,
# 64 elsewhere). A size_t is pointer-sized, which a `long` is not on wasm32
# and ESP32 (#3185). No C compiler sees an extern's prototype beside the C
# definition, so nothing else catches a disagreement: the call is made with
# the wrong width, or on wasm32 replaced by a trap. Nor is a C function the
# shared runtime, std and contrib define in two directories, which a program
# that links both has twice. The checker is Aether
# (tests/extern_widths/check.ae). Its self-test first: the fixture holds
# exactly 13 findings, one of each kind, among definitions that agree.
# -----------------------------------------------------------------
EXTERN_WIDTHS_CHECKER := $(BUILD_DIR)/extern_widths/check$(EXE_EXT)
EXTERN_WIDTHS_DIRS := std contrib runtime tests examples tools lsp benchmarks
.PHONY: check-extern-widths
check-extern-widths: compiler ae stdlib
	@mkdir -p $(BUILD_DIR)/extern_widths
	@./$(BUILD_DIR)/ae$(EXE_EXT) build tests/extern_widths/check.ae -o $(EXTERN_WIDTHS_CHECKER)
	@./$(EXTERN_WIDTHS_CHECKER) --root tests/extern_widths/fixture --expect 13 tests/extern_widths/fixture \
	    > $(BUILD_DIR)/extern_widths/self_test.log 2>&1 || \
	    { cat $(BUILD_DIR)/extern_widths/self_test.log; exit 1; }
	@./$(EXTERN_WIDTHS_CHECKER) --exclude tests/extern_widths/fixture $(EXTERN_WIDTHS_DIRS)

# -----------------------------------------------------------------
# Raw calls (#3107): a std module binds C through `*_raw` externs and
# builds its public functions on them (error results, ownership of what
# is stored, bounds). No std or contrib file calls such a binding that
# another module declares; it calls that module's public function. The
# checker is Aether (tests/raw_calls/check.ae). Its self-test first: the
# fixture holds exactly 6 such calls and re-declarations among uses that
# are not.
# -----------------------------------------------------------------
# Every .ae file under std and contrib type-checks without a warning: an
# unused value there was often a test's error result nobody checked. The
# examples have their own gate (check-examples). tests/warnings/check.ae.
WARNINGS_CHECKER := $(BUILD_DIR)/warnings/check$(EXE_EXT)
.PHONY: check-warnings
check-warnings: compiler ae stdlib
	@mkdir -p $(BUILD_DIR)/warnings
	@./$(BUILD_DIR)/ae$(EXE_EXT) build tests/warnings/check.ae -o $(WARNINGS_CHECKER)
	@./$(WARNINGS_CHECKER) ./$(BUILD_DIR)/ae$(EXE_EXT) --jobs $(NPROC) --expect 4 tests/warnings/fixture \
	    > $(BUILD_DIR)/warnings/self_test.log 2>&1 || \
	    { cat $(BUILD_DIR)/warnings/self_test.log; exit 1; }
	@./$(WARNINGS_CHECKER) ./$(BUILD_DIR)/ae$(EXE_EXT) --jobs $(NPROC) std contrib

RAW_CALLS_CHECKER := $(BUILD_DIR)/raw_calls/check$(EXE_EXT)
.PHONY: check-raw-calls
check-raw-calls: compiler ae stdlib
	@mkdir -p $(BUILD_DIR)/raw_calls
	@./$(BUILD_DIR)/ae$(EXE_EXT) build tests/raw_calls/check.ae -o $(RAW_CALLS_CHECKER)
	@./$(RAW_CALLS_CHECKER) --expect 6 tests/raw_calls/fixture \
	    > $(BUILD_DIR)/raw_calls/self_test.log 2>&1 || \
	    { cat $(BUILD_DIR)/raw_calls/self_test.log; exit 1; }
	@./$(RAW_CALLS_CHECKER) --exclude tests/raw_calls/fixture std contrib tests examples

# Every buffer the cryptography modules free is wiped first (#3402, #3414):
# a module under std/cryptography frees a std.bytes buffer with
# bytes.wipe_free, never bytes.free, since a rule decided call by call
# missed one secret after another. The checker is Aether
# (tests/crypto_wipe/check.ae); its self-test first, over a fixture with
# exactly 3 plain frees.
CRYPTO_WIPE_CHECKER := $(BUILD_DIR)/crypto_wipe/check$(EXE_EXT)
.PHONY: check-crypto-wipe
check-crypto-wipe: compiler ae stdlib
	@mkdir -p $(BUILD_DIR)/crypto_wipe
	@./$(BUILD_DIR)/ae$(EXE_EXT) build tests/crypto_wipe/check.ae -o $(CRYPTO_WIPE_CHECKER)
	@./$(CRYPTO_WIPE_CHECKER) --expect 3 tests/crypto_wipe/fixture \
	    > $(BUILD_DIR)/crypto_wipe/self_test.log 2>&1 || \
	    { cat $(BUILD_DIR)/crypto_wipe/self_test.log; exit 1; }
	@./$(CRYPTO_WIPE_CHECKER) std/cryptography

# -----------------------------------------------------------------
# Examples (#3105): examples/ is the path a learner follows, so each example
# must still be true. Every example builds without a warning; each one that
# ends in an `// Output:` block runs and prints exactly that block; one that
# cannot run unattended says what it needs; examples/README.md links every
# example and each of its links resolves; every file there is source. The
# checker is Aether (tests/examples/check.ae). Its self-test first: the
# fixture holds exactly 15 problems, one of each kind.
# -----------------------------------------------------------------
EXAMPLES_CHECKER := $(BUILD_DIR)/examples_check/check$(EXE_EXT)
EXAMPLES_TIMEOUT ?= 60
.PHONY: check-examples
check-examples: compiler ae stdlib
	@mkdir -p $(BUILD_DIR)/examples_check
	@./$(BUILD_DIR)/ae$(EXE_EXT) build tests/examples/check.ae -o $(BUILD_DIR)/examples_check/check
	@./$(EXAMPLES_CHECKER) --ae ./$(BUILD_DIR)/ae$(EXE_EXT) --timeout 2 --jobs $(NPROC) --expect 15 tests/examples/fixture \
	    > $(BUILD_DIR)/examples_check/self_test.log 2>&1 || \
	    { cat $(BUILD_DIR)/examples_check/self_test.log; exit 1; }
	@PATH="$$(pwd)/$(BUILD_DIR):$$PATH" ./$(EXAMPLES_CHECKER) --ae ./$(BUILD_DIR)/ae$(EXE_EXT) \
	    --timeout $(EXAMPLES_TIMEOUT) --jobs $(NPROC) examples

# The C a program gets when the C compiler is not GCC-compatible
# (AETHER_GCC_COMPAT 0, which is what MSVC compiles): strict C11 under gcc,
# and under cl.exe too when it is on PATH (#2725). CI runs the gcc half on the
# Linux / GCC leg and the cl half in windows.yml's MSVC job. MSVC_COMPAT_CC
# (gcc, cl or all) picks; see the script.
.PHONY: test-msvc-compat
test-msvc-compat: compiler
	@bash tests/compiler/test_msvc_compat.sh

# The .ae corpus at -O0 against -O2 (#2488). Builds every program `test-ae`
# builds (the list is tests/scripts/ae_sweep_list.sh, shared with it) at -O2
# and at --quick (-O0 -g), runs both, and diffs stdout and the exit code.
# `ae run` compiles at -O0 and the sweep only ever at -O2, so a bug that shows
# only at -O0 passed every run. Not part of `ci`: CI runs it as its own step
# on the Linux / GCC leg, after `make ci`, whose sweep has already put the -O2
# builds in the build cache. CC is exported as `test-ae` exports it.
.PHONY: test-ae-opt-diff
test-ae-opt-diff: compiler ae stdlib
	@CC="$${CC:-$(BASE_CC)}" NPROC=$(NPROC) sh tests/differential/run_opt_diff.sh "$(AE_SWEEP_EXTRA_PRUNE)"

# The C unit tests and the `test-ae` sweep under UndefinedBehaviorSanitizer
# (#2488). Rebuilds the toolchain and libaether instrumented, into this tree's
# build/ (CC becomes build/ubsan/bin/gcc, so the build-flags digest moves and
# the next plain build recompiles), then runs `test` and `test-ae` with every
# compile and link going through that sanitizing compiler. Fails on any test
# failure and on any UBSan report (build/ubsan/reports). Linux or macOS: it
# needs a UBSan runtime, which MinGW lacks. Not part of `ci`: ubsan.yml runs
# it. See tests/scripts/sanitizer_sweep.sh and docs/differential-testing.md.
# UBSAN_CHECKS are the -fsanitize groups: gcc's `undefined` leaves out
# float-cast-overflow, a float converted to an integer type it does not fit
# (#3524), so it is named too.
UBSAN_CHECKS ?= undefined,float-cast-overflow
.PHONY: test-ubsan
test-ubsan:
	@SAN=ubsan MAKE="$(MAKE)" NPROC=$(NPROC) BASE_CC="$(BASE_CC)" UBSAN_CHECKS="$(UBSAN_CHECKS)" \
	    sh tests/scripts/sanitizer_sweep.sh

# The same, under AddressSanitizer and LeakSanitizer (#3539): a heap overflow,
# a use after free or a double free in libaether, std or the generated code of
# any program the sweep builds stops that program, and a block it never freed
# is reported when it exits (build/asan/reports) and fails the run (#3547);
# SAN_LEAKS=report lists the leaks without failing. `test-asan` above runs
# only the C unit runner; this one runs the .ae corpus too. AE_SWEEP_SHARD=k/n
# splits the corpus (asan.yml runs it in shards). Linux or macOS.
SAN_LEAKS ?= fail
.PHONY: test-asan-ae
test-asan-ae:
	@SAN=asan SAN_LEAKS="$(SAN_LEAKS)" MAKE="$(MAKE)" NPROC=$(NPROC) BASE_CC="$(BASE_CC)" sh tests/scripts/sanitizer_sweep.sh

# -----------------------------------------------------------------
# contrib/host bridge check
#
# Each contrib/host/<lang>/ directory ships a C bridge (and usually a
# module.ae) that embeds a foreign language runtime. Every bridge
# compiles in two modes:
#
#   - stub mode (no dev library available): always compiles clean
#     because the AETHER_HAS_<LANG> guard selects stub implementations.
#     Useful as a universal syntax check.
#
#   - linked mode (dev library + header available): probed via
#     pkg-config or a header-existence check. Compiles the bridge
#     with -DAETHER_HAS_<LANG> and tries to link a minimal demo.
#
# Goals:
#   - Fast ($0 marginal CI cost): always-on syntax sweep proves the
#     bridges compile on every build.
#   - Opportunistic: where dev libs are installed, link and run demos
#     end-to-end as a real integration check.
#   - No hard dependency: missing dev libs degrade gracefully to a
#     "skipped" status, never a failure.
# -----------------------------------------------------------------

# The host bridges left in this tree, syntax-checked by contrib-host-check:
# `aether` (Aether hosting Aether, fork+exec) and `stunt`, the test double
# (contrib/host/stunt/README.md). Both compile against libc + the in-tree
# sandbox runtime alone. The language bridges moved to
# https://github.com/aether-lang-dev/aether-guest-languages.
CONTRIB_HOST_LANGS = aether stunt

# CONTRIB_HOST_STRICT=1 turns "bridge archive unavailable" from a SKIP into a
# FAILURE in the co-located-spec phase of contrib-host-check.
#
# The default (0) is right for portable CI runners and dev boxes, which cannot
# be expected to have every language's dev kit installed — there, a missing
# bridge genuinely is nothing to report. It is wrong for a dedicated build box
# that has been provisioned with all of them: a spec that silently does not run
# is indistinguishable from one that passes, so the coverage quietly shrinks
# without turning anything red. The CachyOS nightly sets this to 1.
CONTRIB_HOST_STRICT ?= 0

# Documentation examples that are supposed to work (#1500, #1522).
#
# Three gates, all cheap. `check_doc_examples.py` reads the stdlib module doc
# comments, which are deliberately fragments and cannot be compiled, and
# catches the two defects that do not need compiling: a block introduced by a
# word that is not a keyword, and a documented `mod.fn(` the module does not
# have. `check_stdlib_index.py` holds the reference page's module index to the
# tree it describes, which it had drifted from in eleven counts and a whole
# module. `check_doc_blocks.py` compiles every ```aether block in docs/ and the
# README that is labelled complete, and asserts the ones labelled `fails`
# still fail.
.PHONY: check-docs check-changelog check-tests add-changelog collect-changelogs

check-changelog:
	@sh tests/scripts/check_changelog_fold.sh
	@py=""; \
	for cand in python3 python "py -3"; do \
	    if $$cand -c "import sys" >/dev/null 2>&1; then py="$$cand"; break; fi; \
	done; \
	if [ -n "$$py" ]; then \
	    $$py tests/scripts/collect_changelogs.py --check; \
	else \
	    echo "changelog fragments: no python3, skipped"; \
	fi

# Write a changelog fragment (#2002). A PR drops a file of its own in
# new_changelogs/ instead of editing the shared `## [current]` lines, which
# is exactly what a release renames out from under every open branch.
#
#   make add-changelog SECTION=fixed SLUG=2162-struct-collision
add-changelog:
	@if [ -z "$(SLUG)" ]; then \
	    echo "usage: make add-changelog SECTION=<added|changed|fixed|removed|security|performance> SLUG=<issue-and-words>"; \
	    exit 1; \
	fi
	@mkdir -p new_changelogs
	@f="new_changelogs/$$(date -u +%Y%m%dT%H%M%SZ)-$(or $(SECTION),fixed)-$(SLUG).md"; \
	printf -- '- **Say what changed, and why it mattered.**\n' > "$$f"; \
	echo "wrote $$f"

# Fold settled fragments into CHANGELOG.md. This is what the daily job runs;
# a release runs it with --all, because cutting a release must not leave a
# merged change unrecorded.
collect-changelogs:
	@py=""; \
	for cand in python3 python "py -3"; do \
	    if $$cand -c "import sys" >/dev/null 2>&1; then py="$$cand"; break; fi; \
	done; \
	if [ -n "$$py" ]; then \
	    $$py tests/scripts/collect_changelogs.py ; \
	else \
	    echo "changelog fragments: no python3, skipped"; \
	fi

# docs/api is generated from std by tools/docgen and committed. Nothing
# compared the two, so after #2976 and #3014 the reference still documented
# hundreds of removed exports and had no page for std.quote. This
# regenerates it into a temporary folder and compares every file by
# checksum (coreutils only: the MSYS2 legs have no diff), naming each file
# that differs. The fix is `make docs` and committing docs/api.
.PHONY: check-api-docs
check-api-docs: docgen
	@tmp=$$(mktemp -d); \
	./$(BUILD_DIR)/docgen$(EXE_EXT) std "$$tmp/api" >/dev/null || { rm -rf "$$tmp"; exit 1; }; \
	(cd "$$tmp/api" && find . -type f | LC_ALL=C sort | xargs cksum) | LC_ALL=C sort > "$$tmp/want"; \
	(cd docs/api && find . -type f | LC_ALL=C sort | xargs cksum) | LC_ALL=C sort > "$$tmp/have"; \
	stale=$$(LC_ALL=C comm -3 "$$tmp/want" "$$tmp/have" | awk '{print $$NF}' | LC_ALL=C sort -u); \
	rm -rf "$$tmp"; \
	if [ -z "$$stale" ]; then \
	    echo "  [PASS] docs/api is what docgen writes for std"; \
	else \
	    echo "  [FAIL] docs/api differs from docgen's output for std; run 'make docs' and commit docs/api:"; \
	    printf '%s\n' "$$stale" | sed 's/^/           /'; \
	    exit 1; \
	fi

check-docs: compiler ae stdlib check-api-docs
	@echo "==================================="
	@echo "  documentation examples"
	@echo "==================================="
	@# The checkers are Python, and MSYS2 on the Windows runners has no
	@# python3 — `make ci` calls this target on every platform, so without a
	@# guard the whole Windows build dies with "python3: No such file or
	@# directory" (exit 127) before it reaches anything Aether.
	@#
	@# The guard RUNS a candidate rather than asking `command -v` whether it
	@# exists, because on Windows existing and working are different things.
	@# Windows 10/11 ship "app execution aliases" for python.exe/python3.exe,
	@# on by default, that are NOT Python: they print an advert for the
	@# Microsoft Store and exit 49. `command -v python3` finds one, the old
	@# guard concluded Python was present, ran the stub, and `make ci` died at
	@# check-docs — on a box with a perfectly good Python installed, just not
	@# named python3 (C:\PythonXXX ships python.exe only). Hence also the
	@# candidate list: python3, then python, then the `py -3` launcher.
	@#
	@# Skipping there costs nothing: what these check is whether a
	@# documentation block still compiles, which does not vary by platform.
	@# A block that compiles on the Linux and macOS legs compiles anywhere,
	@# and those legs run the same `make ci`. The skip is announced rather
	@# than silent, so a box that has quietly lost python3 is visible in the
	@# log instead of reading as a pass.
	@#
	@# check_std_silent (#3131) holds std to the stdlib-module-pattern rule
	@# that a module writes nothing to stdout or stderr unasked. It reads the
	@# tree, so the same reasoning covers it.
	@py=""; \
	for cand in python3 python "py -3"; do \
	    if $$cand -c "import sys" >/dev/null 2>&1; then py="$$cand"; break; fi; \
	done; \
	if [ -n "$$py" ]; then \
	    $$py tests/scripts/check_doc_examples.py && \
	    $$py tests/scripts/check_stdlib_index.py && \
	    $$py tests/scripts/check_module_readmes.py && \
	    $$py tests/scripts/check_shipped_module_leaves.py && \
	    $$py tests/scripts/test_check_std_silent.py && \
	    $$py tests/scripts/check_std_silent.py && \
	    NPROC=$(NPROC) $$py tests/scripts/check_doc_blocks.py; \
	else \
	    echo "  [SKIP] documentation examples — no working Python found"; \
	    echo "         (checked on the Linux/macOS legs, which run the same target)"; \
	fi

# The test suite itself (#2132): every sweep-run .ae that prints a failure
# marker can exit non-zero (25 could not — printed FAIL, exited 0, counted
# as a pass on every run), and the sweep prune list is consistent with the
# tree (a pruned directory has the driver the list promises; a fixture that
# only makes sense under a driver is not run standalone). Python, probed the
# same way check-docs does; the checks read the tree, so they do not vary
# by platform and the Linux/macOS legs cover a Windows box without Python.
# Also the std module census (#1584): every module.ae under std/ has a
# co-located std/<mod>/test_*.ae, or a central test that imports it, or a
# waiver in check_module_specs.py; its own unit tests run first.
# And every listener the suites start (tests, std and contrib tests, the
# examples, run doc blocks) binds loopback (#2639): on Windows each new
# executable listening on every interface opens a firewall prompt; its own
# unit tests run first too.
# Test directories the default sweep leaves out because they cannot run
# without a toolchain this repository does not provision (#2132 §3): a test
# that can only "pass" by skipping is not a gate. They carry a
# NEEDS_EXTERNAL_TOOLCHAIN marker file naming what they need; this target
# runs exactly those, and reports a skip as a skip.
#
#   make test-optional        # what the sweep leaves out
#   AE_SWEEP_OPTIONAL=1 make test-ae   # the whole sweep, these included
.PHONY: test-optional
test-optional: compiler ae stdlib
	@tmpdir=$$(mktemp -d); \
	root=$$(pwd); \
	sh_script="$$root/tests/scripts/run_ae_sh_dir.sh"; \
	dirs=$$(find tests/integration -name NEEDS_EXTERNAL_TOOLCHAIN | xargs -n1 dirname | sort -u); \
	if [ -z "$$dirs" ]; then echo "No optional test directories."; rm -rf "$$tmpdir"; exit 0; fi; \
	for d in $$dirs; do \
	  echo "--- $$d: $$(head -1 $$d/NEEDS_EXTERNAL_TOOLCHAIN)"; \
	  sh "$$sh_script" "$$d" "$$tmpdir" "$$root"; \
	done; \
	passed=$$(ls "$$tmpdir"/PASS_* 2>/dev/null | wc -l | tr -d ' '); \
	failed=$$(ls "$$tmpdir"/FAIL_* 2>/dev/null | wc -l | tr -d ' '); \
	skipped=$$(ls "$$tmpdir"/SKIP_* 2>/dev/null | wc -l | tr -d ' '); \
	echo ""; \
	echo "Optional tests: $$passed passed, $$failed failed, $$skipped skipped"; \
	rm -rf "$$tmpdir"; \
	[ "$$failed" -eq 0 ]

check-tests:
	@echo "==================================="
	@echo "  test suite (verdicts, prune list, loopback listeners, shell kills, shell tools, shell function prefixes, temp names, platform)"
	@echo "==================================="
	@py=""; \
	for cand in python3 python "py -3"; do \
	    if $$cand -c "import sys" >/dev/null 2>&1; then py="$$cand"; break; fi; \
	done; \
	if [ -n "$$py" ]; then \
	    $$py tests/scripts/test_check_test_verdicts.py && \
	    $$py tests/scripts/check_test_verdicts.py && \
	    $$py tests/scripts/check_sweep_prune.py && \
	    $$py tests/scripts/test_check_module_specs.py && \
	    $$py tests/scripts/check_module_specs.py && \
	    $$py tests/scripts/test_check_loopback_listeners.py && \
	    $$py tests/scripts/check_loopback_listeners.py && \
	    $$py tests/scripts/test_check_shell_kills.py && \
	    $$py tests/scripts/check_shell_kills.py && \
	    $$py tests/scripts/test_check_shell_tools.py && \
	    $$py tests/scripts/check_shell_tools.py && \
	    $$py tests/scripts/test_check_shell_prefix.py && \
	    $$py tests/scripts/check_shell_prefix.py && \
	    $$py tests/scripts/test_check_shell_tmp.py && \
	    $$py tests/scripts/check_shell_tmp.py && \
	    $$py tests/scripts/test_check_ae_tmp.py && \
	    $$py tests/scripts/check_ae_tmp.py && \
	    $$py tests/scripts/test_check_platform_env.py && \
	    $$py tests/scripts/check_platform_env.py; \
	else \
	    echo "  [SKIP] test suite checks — no working Python found"; \
	    echo "         (checked on the Linux/macOS legs, which run the same target)"; \
	fi

# Every non-host contrib module's Aether surface, type-checked (#1442).
#
# `make contrib` build-probes each module's C shim and `contrib-check` RUNS the
# ones with tests, but a module whose native library is absent skips both, and
# nothing else ever feeds its module.ae to the compiler: tinyweb's builder-DSL
# serving path was broken for a long stretch with CI green throughout. Type
# checking needs no native library (externs are declarations), so this covers
# every module on every box, including the ones whose runtime tests skip.
.PHONY: check-contrib-modules
check-contrib-modules: compiler ae stdlib
	@echo "==================================="
	@echo "  contrib modules (type check)"
	@echo "==================================="
	@pass=0; fail=0; \
	for m in $$(find contrib -name module.ae -not -path 'contrib/host/*' | sort); do \
		printf '  %-44s ' "$$m"; \
		if err="$$(AETHER_HOME="" ./$(BUILD_DIR)/ae$(EXE_EXT) check "$$m" 2>&1)"; then \
			echo "ok"; pass=$$((pass + 1)); \
		else \
			echo "FAIL"; \
			printf '%s\n' "$$err" | grep -E "error" | head -4 | sed 's/^/        /'; \
			fail=$$((fail + 1)); \
		fi; \
	done; \
	echo ""; \
	echo "  $$pass ok, $$fail failed"; \
	if [ "$$fail" -gt 0 ]; then \
		echo "  A contrib module no longer type-checks against the current stdlib."; \
		exit 1; \
	fi

contrib-host-check: compiler ae stdlib stunt
	@echo "==================================="
	@echo "  contrib/host bridge check"
	@echo "==================================="
	@echo ""
	@echo "[1/2] Syntax check — every bridge..."
	@pass=0; fail=0; \
	for lang in $(CONTRIB_HOST_LANGS); do \
		src="contrib/host/$$lang/aether_host_$$lang.c"; \
		if [ ! -f "$$src" ]; then \
			printf "  %-10s SKIP (no bridge)\n" "$$lang"; \
			continue; \
		fi; \
		printf "  %-10s " "$$lang"; \
		if $(CC) -fsyntax-only -Wall -Wextra -I. "$$src" 2>/tmp/contrib_host_err.txt; then \
			echo "OK"; \
			pass=$$((pass + 1)); \
		else \
			echo "FAIL (stub mode)"; \
			head -5 /tmp/contrib_host_err.txt; \
			fail=$$((fail + 1)); \
		fi; \
	done; \
	echo "  $$pass passed, $$fail failed"; \
	if [ "$$fail" -gt 0 ]; then exit 1; fi
	@echo ""
	@echo "[2/2] Co-located bridge specs (contrib/host/*/test_*.ae)..."
	@rc=0; found=0; \
	for t in $$(find contrib/host -maxdepth 2 -name 'test_*.ae' 2>/dev/null | sort); do \
	  found=$$((found + 1)); \
	  lang=$$(basename $$(dirname "$$t")); \
	  echo "  --- $$lang ---"; \
	  case "$$lang" in \
	    stunt) AETHER_STUNT_LIB="$(CURDIR)/$(STUNT_LIB)"; export AETHER_STUNT_LIB; ;; \
	  esac; \
	  if [ ! -f "$(BUILD_DIR)/contrib/libaether_host_$$lang.a" ]; then \
	    MODULES="$$lang" bash tests/scripts/contrib_build.sh >/dev/null 2>&1 || true; \
	  fi; \
	  if [ ! -f "$(BUILD_DIR)/contrib/libaether_host_$$lang.a" ]; then \
	    if [ "$(CONTRIB_HOST_STRICT)" = "1" ]; then \
	      echo "    FAIL: libaether_host_$$lang.a unavailable (CONTRIB_HOST_STRICT=1)"; \
	      rc=1; \
	    else \
	      echo "    SKIP: libaether_host_$$lang.a unavailable (bridge deps not installed)"; \
	    fi; \
	    continue; \
	  fi; \
	  out="$$(./$(BUILD_DIR)/ae$(EXE_EXT) run "$$t" 2>&1)"; trc=$$?; \
	  echo "$$out" | sed 's/^/  /'; \
	  if [ "$$trc" -ne 0 ]; then rc=1; fi; \
	done; \
	if [ "$$found" -eq 0 ]; then echo "  (none yet)"; fi; \
	exit $$rc
	@echo ""
	@echo "==================================="
	@echo "  contrib/host check PASSED"
	@echo "==================================="

# aether_ui has been spun out into its own repo. The widget toolkit
# now lives at https://github.com/aether-lang-dev/aether-ui and is
# consumed as a downstream package, not built from this repo. The
# previous `contrib-aether-ui-check` and `benchmark-aether-ui` targets
# (along with their CI step) were removed when the spin-out happened.
# Anyone bisecting old failures: see the repo's git history pre-
# spin-out for the GTK4 / AppKit / Win32 backend build recipes.

valgrind-check: clean
	@echo "==================================="
	@echo "Running Valgrind Memory Check"
	@echo "==================================="
	@$(MAKE) compiler CFLAGS="-O0 -g"
	@$(MAKE) test-build CFLAGS="-O0 -g"
	@valgrind --leak-check=full \
		--show-leak-kinds=all \
		--track-origins=yes \
		--fair-sched=yes \
		--error-exitcode=1 \
		--suppressions=.valgrind-suppressions \
		./$(BUILD_DIR)/test_runner$(EXE_EXT) || (echo "Valgrind errors detected!" && exit 1)
	@echo "✓ Valgrind clean — no leaks or uninitialised reads"

asan-check: clean
	@echo "==================================="
	@echo "Running AddressSanitizer Check"
	@echo "==================================="
	@$(MAKE) compiler CFLAGS="-fsanitize=address -fno-omit-frame-pointer -g" \
	                  LDFLAGS="-fsanitize=address -pthread -lm"
	@$(MAKE) test-build CFLAGS="-fsanitize=address -fno-omit-frame-pointer -g" \
	                    LDFLAGS="-fsanitize=address -pthread -lm"
	@ASAN_OPTIONS=detect_leaks=1:check_initialization_order=1 \
	  ./$(BUILD_DIR)/test_runner$(EXE_EXT) 2>&1 | tee asan.log; \
	  if grep -q "ERROR: AddressSanitizer" asan.log; then \
	    echo "ERROR: AddressSanitizer detected errors!"; \
	    exit 1; \
	  fi
	@echo "✓ ASan clean — no memory errors detected"

.PHONY: all compiler lsp apkg ae release release-build profiler docgen docs-server docs docs-serve test test-build test-valgrind test-asan test-macos-leaks test-memory test-manual-runtime test-cross test-install test-release-archive benchmark benchmark-results benchmark-ui examples run compile repl clean help self-test install stats stdlib stdlib-asan stdlib-memory stdlib-dbg ci ci-windows docker-ci docker-ci-windows docker-build-ci valgrind-check asan-check ci-coop ci-wasm ci-embedded ci-esp32 ci-portability docker-ci-wasm docker-ci-embedded contrib-host-check contrib install-contrib stdlib-cov ci-coverage ci-coverage-clean ci-coverage-html

# Cross-language benchmark UI (alias for benchmark)
benchmark-ui: benchmark

# ============================================================================
# Platform Portability CI
# ============================================================================

# Test cooperative scheduler on native (no Docker needed — fast)
ci-coop: clean compiler ae
	@echo "==================================="
	@echo "  Cooperative Scheduler CI"
	@echo "==================================="
	@echo ""
	@echo "[1/4] Building stdlib with -DAETHER_NO_THREADING..."
	@$(MAKE) stdlib EXTRA_CFLAGS="-DAETHER_NO_THREADING"
	@echo ""
	@echo "[2/4] Running actor tests in cooperative mode..."
	@pass=0; fail=0; \
	for src in tests/syntax/test_platform_caps.ae \
	           tests/syntax/test_coop_chain.ae \
	           tests/syntax/test_coop_many_actors.ae \
	           tests/syntax/test_coop_ask_reply.ae \
	           tests/syntax/test_coop_self_send.ae \
	           tests/syntax/test_coop_stubs.ae \
	           tests/syntax/test_coop_wait_for_idle_timeout.ae \
	           examples/02-actors/02-state.ae \
	           examples/02-actors/04-actor-refs.ae \
	           examples/02-actors/03-ask-reply.ae \
	           examples/02-actors/07-worker-pool.ae \
	           tests/regression/test_actor_down_notices.ae \
	           tests/regression/test_actor_links.ae \
	           tests/regression/test_ask_failure_reasons.ae \
	           tests/regression/test_actor_step_reentry.ae \
	           tests/regression/test_owned_panic_unwind.ae \
	           tests/regression/test_step_panic_drop.ae \
	           tests/regression/test_step_drop_context.ae \
	           examples/01-language/01-hello.ae; do \
		printf "  %-50s " "$$src"; \
		if AETHER_HOME="" ./$(BUILD_DIR)/ae run "$$src" >/tmp/ae_coop_out.txt 2>&1; then \
			echo "PASS"; \
			pass=$$((pass + 1)); \
		else \
			echo "FAIL"; \
			cat /tmp/ae_coop_out.txt | head -10; \
			fail=$$((fail + 1)); \
		fi; \
	done; \
	printf "  %-50s " "end of main, countdown armed (#3219)"; \
	if sh tests/integration/exit_armed_timeout/test_exit_armed_timeout.sh >/tmp/ae_coop_out.txt 2>&1; then \
		echo "PASS"; \
		pass=$$((pass + 1)); \
	else \
		echo "FAIL"; \
		cat /tmp/ae_coop_out.txt | head -10; \
		fail=$$((fail + 1)); \
	fi; \
	printf "  %-50s " "an export's ask steps actors outside it (#3392)"; \
	if sh tests/integration/emit_lib_actor_step_context/test_emit_lib_actor_step_context.sh >/tmp/ae_coop_out.txt 2>&1; then \
		echo "PASS"; \
		pass=$$((pass + 1)); \
	else \
		echo "FAIL"; \
		cat /tmp/ae_coop_out.txt | head -10; \
		fail=$$((fail + 1)); \
	fi; \
	printf "  %-50s " "bytes, mem, strbuilder, sync link from the list"; \
	if sh tests/integration/coop_runtime_modules/test_coop_runtime_modules.sh >/tmp/ae_coop_out.txt 2>&1; then \
		echo "PASS"; \
		pass=$$((pass + 1)); \
	else \
		echo "FAIL"; \
		cat /tmp/ae_coop_out.txt | head -10; \
		fail=$$((fail + 1)); \
	fi; \
	echo ""; \
	echo "  $$pass passed, $$fail failed"; \
	if [ "$$fail" -gt 0 ]; then exit 1; fi
	@echo ""
	@echo "[3/4] Testing no-filesystem + no-networking stubs..."
	@$(MAKE) stdlib EXTRA_CFLAGS="-DAETHER_NO_FILESYSTEM -DAETHER_NO_NETWORKING"
	@printf "  %-50s " "hello.ae (no-fs/no-net)"; \
	if AETHER_HOME="" ./$(BUILD_DIR)/ae run examples/01-language/01-hello.ae >/dev/null 2>&1; then \
		echo "PASS"; \
	else \
		echo "FAIL"; \
		exit 1; \
	fi
	@echo ""
	@echo "[4/4] Restoring default stdlib..."
	@$(MAKE) stdlib
	@echo ""
	@echo "==================================="
	@echo "  Cooperative Scheduler CI PASSED"
	@echo "==================================="

# WASM cross-compilation test (requires Emscripten — use Docker or local emsdk)
# Builds native aetherc, generates .c, then compiles with emcc
# The programs ci-wasm takes through aetherc, emcc and node: one list the
# three steps share. Each step used to name its own files, and when hello
# moved to examples/01-language/01-hello.ae the first step wrote
# 01-hello.c while the second still compiled hello.c.
WASM_CI_PROGRAMS := examples/01-language/01-hello.ae examples/02-actors/02-state.ae \
                    tests/syntax/test_platform_caps.ae tests/syntax/test_coop_chain.ae
# The runtime those programs link, the list ci-esp32's CMakeLists reads too.
COOP_RUNTIME_SOURCES := $(shell sed -e '/^\#/d' runtime/coop_runtime_sources.txt)

ci-wasm: clean compiler ae
	@echo "==================================="
	@echo "  WebAssembly (Emscripten) CI"
	@echo "==================================="
	@echo ""
	@echo "[1/4] Generating C from test programs..."
	@mkdir -p $(BUILD_DIR)/wasm
	@pass=0; fail=0; \
	for src in $(WASM_CI_PROGRAMS); do \
		name=$$(basename $$src .ae); \
		printf "  %-40s " "$$name → .c"; \
		if ./$(BUILD_DIR)/aetherc "$$src" "$(BUILD_DIR)/wasm/$$name.c" 2>/tmp/ae_wasm_err.txt; then \
			echo "OK"; \
			pass=$$((pass + 1)); \
		else \
			echo "FAIL"; \
			cat /tmp/ae_wasm_err.txt | head -5; \
			fail=$$((fail + 1)); \
		fi; \
	done; \
	echo "  $$pass generated, $$fail failed"; \
	if [ "$$fail" -gt 0 ]; then exit 1; fi
	@echo ""
# wasm-ld only warns when a call and its definition disagree on the
# signature (an int64_t where the definition takes a 32-bit size_t), and
# links a stub that traps when the call runs: --fatal-warnings makes that
# the build error it is.
	@echo "[2/4] Compiling runtime + generated C with emcc..."
	@WASM_CFLAGS="-O2 -DAETHER_NO_THREADING -DAETHER_NO_FILESYSTEM -DAETHER_NO_NETWORKING \
		-Iinclude -Iruntime -Iruntime/actors -Iruntime/scheduler -Iruntime/utils -Iruntime/memory \
		-Iruntime/config -Istd -Istd/string -Istd/io -Istd/math -Istd/net -Istd/collections -Istd/json \
		-Wall -Wextra -Wno-unused-parameter -Wno-unused-function \
		-Wno-unused-variable -Wno-missing-field-initializers -Wno-unused-label"; \
	pass=0; fail=0; \
	RUNTIME_FILES="$(COOP_RUNTIME_SOURCES)"; \
	for src in $(WASM_CI_PROGRAMS); do \
		name=$$(basename $$src .ae); \
		printf "  %-40s " "emcc $$name"; \
		if emcc $$WASM_CFLAGS "$(BUILD_DIR)/wasm/$$name.c" $$RUNTIME_FILES \
			-Wl,--fatal-warnings -o "$(BUILD_DIR)/wasm/$$name.js" -lm 2>/tmp/emcc_err.txt; then \
			echo "OK"; \
			pass=$$((pass + 1)); \
		else \
			echo "FAIL"; \
			cat /tmp/emcc_err.txt | head -10; \
			fail=$$((fail + 1)); \
		fi; \
	done; \
	echo "  $$pass compiled, $$fail failed"; \
	if [ "$$fail" -gt 0 ]; then exit 1; fi
	@echo ""
	@echo "[3/4] Running WASM programs with Node.js..."
	@pass=0; fail=0; \
	for src in $(WASM_CI_PROGRAMS); do \
		name=$$(basename $$src .ae); \
		printf "  %-40s " "node $$name"; \
		if node "$(BUILD_DIR)/wasm/$$name.js" >/tmp/wasm_out.txt 2>&1; then \
			echo "PASS"; \
			pass=$$((pass + 1)); \
		else \
			echo "FAIL"; \
			cat /tmp/wasm_out.txt | head -10; \
			fail=$$((fail + 1)); \
		fi; \
	done; \
	echo "  $$pass passed, $$fail failed"; \
	if [ "$$fail" -gt 0 ]; then exit 1; fi
	@echo ""
# The steps above compile with this Makefile's own command; a user's
# `ae build --target=wasm` composes its own, from the runtime list ae reads
# (#3383: ae's copy of the list had drifted, and nothing here built a
# program the way a user does).
	@echo "[4/4] ae build --target=wasm, as a user builds..."
	@if ! command -v emcc > /dev/null 2>&1; then echo "  emcc not on PATH, skipped"; exit 0; fi; \
	printf '  %-40s ' "ae build 02-state"; \
	if ./$(BUILD_DIR)/ae build --target=wasm examples/02-actors/02-state.ae \
			-o "$(BUILD_DIR)/wasm/ae_state" > /tmp/ae_wasm_build.txt 2>&1 && \
	   node "$(BUILD_DIR)/wasm/ae_state.js" > /tmp/ae_wasm_run.txt 2>&1 && \
	   grep -q "counter: Current value: 18 after 3 changes" /tmp/ae_wasm_run.txt; then \
		echo "PASS"; \
	else \
		echo "FAIL"; \
		cat /tmp/ae_wasm_build.txt /tmp/ae_wasm_run.txt | head -20; \
		exit 1; \
	fi
	@echo ""
	@echo "==================================="
	@echo "  WebAssembly CI PASSED"
	@echo "==================================="

# Embedded cross-compilation test (requires arm-none-eabi-gcc — use Docker or local install)
# Syntax-checks only — no runtime to execute on bare-metal
ci-embedded: clean compiler
	@echo "==================================="
	@echo "  Embedded (ARM) CI"
	@echo "==================================="
	@echo ""
	@echo "[1/2] Syntax-checking runtime sources with arm-none-eabi-gcc..."
	@EMB_CFLAGS="-fsyntax-only -O2 -mcpu=cortex-m4 -mthumb -ffreestanding \
		-DAETHER_NO_THREADING -DAETHER_NO_FILESYSTEM -DAETHER_NO_NETWORKING \
		-DAETHER_NO_GETENV -DAETHER_NO_SIMD -DAETHER_NO_AFFINITY -DAETHER_NO_NUMA \
		-Iruntime -Iruntime/actors -Iruntime/scheduler -Iruntime/utils -Iruntime/memory \
		-Iruntime/config -Istd -Istd/string -Istd/io -Istd/math -Istd/net -Istd/collections -Istd/json \
		-Wall -Wextra -Wno-unused-parameter -Wno-unused-function"; \
	pass=0; fail=0; \
	for f in runtime/scheduler/aether_scheduler_coop.c \
	         runtime/config/aether_optimization_config.c \
	         runtime/utils/aether_cpu_detect.c \
	         runtime/utils/aether_spawn.c \
	         runtime/aether_numa.c \
	         runtime/actors/aether_send_message.c \
	         runtime/actors/aether_send_buffer.c \
	         runtime/aether_locale_num.c \
	         std/string/aether_string.c \
	         std/math/aether_math.c \
	         std/fs/aether_fs.c \
	         std/io/aether_io.c \
	         std/os/aether_os.c \
	         std/net/aether_http.c \
	         std/net/aether_net.c \
	         std/net/aether_http_server.c; do \
		printf "  %-55s " "$$f"; \
		if arm-none-eabi-gcc $$EMB_CFLAGS "$$f" 2>/tmp/emb_err.txt; then \
			echo "OK"; \
			pass=$$((pass + 1)); \
		else \
			echo "FAIL"; \
			cat /tmp/emb_err.txt | head -10; \
			fail=$$((fail + 1)); \
		fi; \
	done; \
	echo ""; \
	echo "  $$pass passed, $$fail failed"; \
	if [ "$$fail" -gt 0 ]; then exit 1; fi
	@echo ""
	@echo "[2/2] Generating and syntax-checking example programs..."
	@mkdir -p $(BUILD_DIR)/embedded
	@pass=0; fail=0; \
	for src in examples/01-language/01-hello.ae examples/02-actors/02-state.ae; do \
		name=$$(basename $$src .ae); \
		printf "  %-55s " "$$name → syntax-check"; \
		./$(BUILD_DIR)/aetherc "$$src" "$(BUILD_DIR)/embedded/$$name.c" 2>/dev/null && \
		if arm-none-eabi-gcc -fsyntax-only -O2 -mcpu=cortex-m4 -mthumb -ffreestanding \
			-DAETHER_NO_THREADING -DAETHER_NO_FILESYSTEM -DAETHER_NO_NETWORKING \
			-DAETHER_NO_GETENV -DAETHER_NO_SIMD -DAETHER_NO_AFFINITY -DAETHER_NO_NUMA \
			-Iruntime -Iruntime/actors -Iruntime/scheduler -Iruntime/utils -Iruntime/memory \
			-Iruntime/config -Istd -Istd/string -Istd/io -Istd/math -Istd/net -Istd/collections -Istd/json \
			-Wall -Wextra -Wno-unused-parameter -Wno-unused-function \
			-Wno-unused-variable -Wno-missing-field-initializers -Wno-unused-label \
			"$(BUILD_DIR)/embedded/$$name.c" 2>/tmp/emb_err.txt; then \
			echo "OK"; \
			pass=$$((pass + 1)); \
		else \
			echo "FAIL"; \
			cat /tmp/emb_err.txt | head -10; \
			fail=$$((fail + 1)); \
		fi; \
	done; \
	echo "  $$pass passed, $$fail failed"; \
	if [ "$$fail" -gt 0 ]; then exit 1; fi
	@echo ""
	@echo "==================================="
	@echo "  Embedded CI PASSED"
	@echo "==================================="

# RISC-V 64-bit Linux cross-compile + run-under-qemu CI (issue #397).
#
# Cross-compiles aetherc, ae, and stdlib via riscv64-linux-gnu-gcc,
# then runs the C unit-test suite under qemu-riscv64-static. Catches
# portability bugs that an x86_64-only matrix can never surface —
# pointer-width / struct-padding / atomic-instruction-availability
# differences DO show up between x86_64 and riscv64.
#
# Why not the full `make test-ae`: that target invokes aetherc + ae
# (riscv64 binaries under qemu) which then invoke gcc to compile
# generated .c. Doable, but doubles CI time for limited extra
# coverage — most portability bugs surface in the C unit tests
# which we DO run end-to-end here. Adding test-ae is a follow-up if
# a riscv64-specific .ae integration bug ever escapes.
#
# Toolchain expected on the runner (apt install on ubuntu-22.04):
#   gcc-riscv64-linux-gnu     — host x86_64 binary, targets riscv64
#   libc6-dev-riscv64-cross   — riscv64 libc/headers
#   qemu-user-static          — qemu-riscv64-static binary
#
# Optional libs (OpenSSL, zlib, nghttp2, PCRE2, GTK4) are disabled for
# the riscv64 build — pkg-config on the host runner returns x86_64 lib
# paths that wouldn't link against riscv64 objects. Disabling them
# matches the std.* feature-detection pattern: the wrappers fall
# into their "unavailable" stubs cleanly. The portability check is
# about Aether's *own* C compiling for riscv64, not about
# revalidating every third-party lib.
ci-riscv64: clean
	@echo "==================================="
	@echo "  RISC-V 64 cross-CI"
	@echo "==================================="
	@echo ""
	@echo "[1/3] Cross-compiling compiler + ae + stdlib for riscv64..."
	# Variables passed as make COMMAND-LINE args (after `$(MAKE)`),
	# not as the leading-VAR=VAL environment-export form. Make's
	# command-line overrides beat the Makefile's `CC := gcc`
	# (immediate assignment); environment variables do NOT, so
	# the env-export form would silently fall through to the host
	# gcc and pass `-mabi=lp64d` to it, which it rejects.
	@$(MAKE) compiler ae stdlib \
	    CC=riscv64-linux-gnu-gcc \
	    EXTRA_CFLAGS="-march=rv64gc -mabi=lp64d" \
	    OPENSSL=0 ZLIB=0 NGHTTP2=0 PCRE2=0 BROTLI=0 ZSTD=0
	@echo ""
	@echo "[2/3] Verifying cross-built binaries are riscv64 ELF..."
	@file $(BUILD_DIR)/aetherc | grep -q "RISC-V" || { echo "  FAIL: aetherc not riscv64 ELF"; file $(BUILD_DIR)/aetherc; exit 1; }
	@file $(BUILD_DIR)/ae      | grep -q "RISC-V" || { echo "  FAIL: ae not riscv64 ELF"; file $(BUILD_DIR)/ae;      exit 1; }
	@echo "  $(BUILD_DIR)/aetherc and $(BUILD_DIR)/ae are riscv64 ELF — cross-compile worked"
	@echo ""
	@echo "[3/3] Smoke-running aetherc --version under qemu-riscv64-static..."
	@qemu-riscv64-static -L /usr/riscv64-linux-gnu ./$(BUILD_DIR)/aetherc --version || { \
	    echo "  FAIL: cross-built aetherc could not run under qemu"; exit 1; }
	@qemu-riscv64-static -L /usr/riscv64-linux-gnu ./$(BUILD_DIR)/ae --version 2>&1 | head -3 || { \
	    echo "  FAIL: cross-built ae could not run under qemu"; exit 1; }
	@echo "  cross-built binaries run cleanly under qemu-riscv64-static"
	@echo ""
	@echo "==================================="
	@echo "  RISC-V 64 cross-CI PASSED"
	@echo "==================================="

# Docker wrappers for cross-platform CI
docker-ci-wasm:
	@echo "Building WASM Docker image..."
	docker build -f docker/Dockerfile.wasm -t aether-wasm:latest .
	@echo "Running WASM CI in Docker..."
	docker run --rm -v $(PWD):/aether -w /aether aether-wasm make ci-wasm

# ESP32 (Xtensa) under emulation: ESP-IDF builds a few programs into
# firmware and Espressif's QEMU runs them. Needs podman or docker; pulls
# espressif/idf (see tests/esp32/test_esp32.sh).
ci-esp32: compiler
	@echo "==================================="
	@echo "  ESP32 (Xtensa) CI"
	@echo "==================================="
	@sh tests/esp32/test_esp32.sh

docker-ci-embedded:
	@echo "Building embedded Docker image..."
	docker build -f docker/Dockerfile.embedded -t aether-embedded:latest .
	@echo "Running embedded CI in Docker..."
	docker run --rm -v $(PWD):/aether -w /aether aether-embedded make ci-embedded

# Run ALL portability checks (native coop + Docker WASM + Docker embedded)
ci-portability: ci-coop docker-ci-wasm docker-ci-embedded
	@echo ""
	@echo "==================================="
	@echo "  ALL PORTABILITY CHECKS PASSED"
	@echo "  - Cooperative scheduler (native)"
	@echo "  - WebAssembly (Emscripten)"
	@echo "  - Embedded (ARM Cortex-M4)"
	@echo "==================================="