allocator interface (first pass)

LANGUAGE.md

@@ -18,18 +18,19 @@ roadmap and milestone history.
 
 ### scalar, aggregate, and pointer types
 
-- exact-width integers, `isize`, `usize`, `f32`, `f64`, `bool`, `void`, and contextual `int`, `float`, and `range` constraints
+- exact-width integers, `isize`, `usize`, `f32`, `f64`, `bool`, `void`, `anyopaque`, and contextual `int`, `float`, and `range` constraints
 - target-dependent C scalar primitives from `c_char` through `c_longdouble`, kept semantically distinct from native scalars
 - contextual integer/float/character literals, backward type-demand inference through names and arithmetic, and compile-time folding for numeric constant expressions
 - strict numeric conversion by default, widening where valid, C scalar coercions at C boundaries, and explicit scalar keyword casts such as `i32(x)` / `c_float(x)`
 - arrays `[N]T`, inferred-count arrays `[_]T`, sentinel arrays `[N;S]T`, compile-time expression array counts, slices `[]T` / `[;S]T`, single-item pointers `@T`, many-item pointers `*T`, and sentinel many-item pointers `[*;S]T`
 - pointer mutability via `mut`, optional pointers as nullable pointers, pointer arithmetic for many-item pointers, postfix dereference `^`, and trapping optional unwrap `?`
 - pointer-to-array `.len`, indexing, slicing, `.ptr` on slices and pointers-to-arrays, implicit address-taking for array-variable slices, and pointer/slice sentinel weakening
+- `ptr_cast(T, ptr)` as a first-pass pointer-child retype that preserves optionality, pointer kind, mutability, and sentinel shape
 - UTF-8 string literals as immutable pointers to static zero-terminated byte arrays, plus raw backtick multiline strings
 - narrow immutable zero-terminated byte pointer/slice conversion to `*c_char` / `?*c_char` without general `u8`/`c_char` interchange
 - optionals with `none`, `orelse`, postfix `?`, conditional unwraps, guarded unwraps, and left-to-right short-circuiting multi-unwraps
 - nominal distinct types with exact backing construction, native enums with optional explicit integer backing, contextual enum literals, and imported C enums as target-backed integer aliases
-- source-order native structs, defined/opaque `c_struct`, keyed record literals, native untagged unions, and native tagged unions `union(Enum)` / `union(enum)`
+- source-order native structs, opaque nominal records with `Name :: opaque`, complete `c_struct { ... }`, keyed record literals, native untagged unions, and native tagged unions `union(Enum)` / `union(enum)`
 - void-payload tagged-union variants, anonymous struct payloads, contextual `.variant`, `.variant{payload}`, and `.variant{field = value}` construction
 - native sum composition with `A | B` for unbacked enums and tagged unions, using program-global `u16` variant ids
 - fallible channel types `T ! E`, where `E` is a native enum/tagged union or supported sum composition
@@ -58,9 +59,9 @@ roadmap and milestone history.
 - comptime execution for bodyful Brolang functions with mutable locals, loops, `defer`, `match`, `try`/`catch`, pointer/slice storage mutation, pointer captures, and calls through comptime-known function values
 - bodyful `c_func` definitions and bodyless `c_func` declarations with exact external symbol names
 - concrete-only C signatures, C variadic declarations/calls, and C default argument promotions
-- native function pointer values and types with `*func(...) R`, fallible `*func(...) R ! E`, optional `?*func(...) R`, and non-variadic native indirect calls
+- native function pointer values and types with `@func(...) R`, fallible `@func(...) R ! E`, optional `?@func(...) R`, and non-variadic native indirect calls
 - Apple Silicon C ABI lowering for scalars, pointers, fixed-signature plain records/unions, small aggregates, homogeneous float aggregates, and indirect aggregate returns
-- imported C typedefs, scalar constants, enum constants, fixed arrays, complete plain structs/unions, and pointers to opaque records
+- imported C typedefs, scalar constants, enum constants, fixed arrays, complete plain structs/unions, C `void*` as nullable `anyopaque` pointers, and pointers to opaque records
 - imported external C object variables, including mutable variables and immutable object globals
 - object-like scalar and plain record/union macro constants
 - supported static inline C functions through generated external wrappers
@@ -71,7 +72,8 @@ roadmap and milestone history.
 
 ### standard packages
 
-- `std/mem/heap` v1 byte allocation over libc: `alloc(size usize) ?*mut u8` and `free(ptr ?*mut u8)`
+- `std/mem` allocator contract over byte allocation: `Allocator` with `?*mut anyopaque` context, `heap`, `alloc(allocator, size, alignment) ?*mut u8`, and `free(allocator, ptr, size, alignment)`
+- `std/mem/heap` legacy compatibility wrappers: `alloc(size usize) ?*mut u8` and `free(ptr ?*mut u8)`
 
 ### compiler behavior
 
@@ -88,7 +90,8 @@ roadmap and milestone history.
 - tuples and native Brolang variadic functions
 - exporting Brolang functions to C and broader target-specific C ABI lowering
 - non-plain C record layouts such as bitfields, packed records, flexible arrays, qualified fields, and C variadic record arguments
-- typed heap allocation, allocator parameters, arenas, pools, build-mode heap policy, and escaping-allocation diagnostics
+- typed heap allocation helpers, arenas, pools, build-mode heap policy, and escaping-allocation diagnostics
+- broader Zig-style pointer/result casts beyond V1 `ptr_cast(T, ptr)`
 - sum-type ABI/layout polish, including dynamic tag-width shrinking, all-void channel collapse, and cross-module global-id determinism
 - backed/C enum composition and must-consume fallible linting
 - result-to-argument type-demand propagation through function call boundaries