@shd101wyy/yo 0.1.30 → 0.1.31

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shd101wyy/yo",
   "displayName": "Yo",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "main": "./out/cjs/index.cjs",
   "module": "./out/esm/index.mjs",
   "types": "./out/types/src/index.d.ts",

package/std/build.yo

@@ -47,7 +47,9 @@ Sanitize :: enum(
   /// AddressSanitizer — detects memory errors and leaks.
   Address,
   /// LeakSanitizer — detects memory leaks only.
-  Leak
+  Leak,
+  /// ThreadSanitizer — detects data races in multi-threaded code.
+  Thread
 );
 export(Sanitize);
 // ── Step kinds ───────────────────────────────────────────────────────
@@ -281,7 +283,8 @@ executable :: (fn(comptime(config) : Executable) -> comptime(Step))({
     config.sanitize,
     .None => "none",
     .Address => "address",
-    .Leak => "leak"
+    .Leak => "leak",
+    .Thread => "thread"
   );
   __yo_build_executable(config.name, config.root, config.target, opt_str, alloc_str, san_str);
   Step(name : config.name, kind : StepKind.Executable)

package/std/imm/list.yo

@@ -28,7 +28,7 @@ ListNode :: (fn(comptime(T) : Type, where(T <: Send)) -> comptime(Type))(
     )
   )
 );
-// Manual Acyclic impl — ListNode is self-referential, so auto-derivation skips it.
+// SAFETY: Manual Acyclic impl — ListNode is self-referential, so auto-derivation skips it.
 // This is safe because ListNode is immutable: all operations create new nodes and never
 // mutate existing ones, making it impossible to form cycles at runtime.
 impl(forall(T : Type), where(T <: Send), ListNode(T), Acyclic());

package/std/imm/sorted_map.yo

@@ -40,7 +40,7 @@ RBNode :: (
     )
   )
 );
-// Manual Acyclic impl — RBNode is self-referential, so auto-derivation skips it.
+// SAFETY: Manual Acyclic impl — RBNode is self-referential, so auto-derivation skips it.
 // This is safe because RBNode is immutable: all tree operations create new nodes
 // and never mutate existing ones, making it impossible to form cycles at runtime.
 impl(forall(K : Type, V : Type), where(K <: (Eq(K), Ord(K), Send), V <: Send), RBNode(K, V), Acyclic());

package/std/libc/stdatomic.yo

@@ -138,6 +138,209 @@ c_include(
   ATOMIC_LLONG_LOCK_FREE : i32,
   ATOMIC_POINTER_LOCK_FREE : i32
 );
+// SAFETY: C11 atomic typedefs (atomic_bool, atomic_int, etc.) are opaque C
+// types backed by _Atomic-qualified primitives. They contain no heap
+// allocations or thread-local state — they are trivially safe to send
+// across threads. They are Acyclic because they don't participate in Yo's
+// ARC reference-counting cycle analysis.
+impl(atomic_bool, Send());
+impl(atomic_bool, Acyclic());
+impl(atomic_char, Send());
+impl(atomic_char, Acyclic());
+impl(atomic_schar, Send());
+impl(atomic_schar, Acyclic());
+impl(atomic_uchar, Send());
+impl(atomic_uchar, Acyclic());
+impl(atomic_short, Send());
+impl(atomic_short, Acyclic());
+impl(atomic_ushort, Send());
+impl(atomic_ushort, Acyclic());
+impl(atomic_int, Send());
+impl(atomic_int, Acyclic());
+impl(atomic_uint, Send());
+impl(atomic_uint, Acyclic());
+impl(atomic_long, Send());
+impl(atomic_long, Acyclic());
+impl(atomic_ulong, Send());
+impl(atomic_ulong, Acyclic());
+impl(atomic_llong, Send());
+impl(atomic_llong, Acyclic());
+impl(atomic_ullong, Send());
+impl(atomic_ullong, Acyclic());
+impl(atomic_char16_t, Send());
+impl(atomic_char16_t, Acyclic());
+impl(atomic_char32_t, Send());
+impl(atomic_char32_t, Acyclic());
+impl(atomic_wchar_t, Send());
+impl(atomic_wchar_t, Acyclic());
+impl(atomic_int_least8_t, Send());
+impl(atomic_int_least8_t, Acyclic());
+impl(atomic_uint_least8_t, Send());
+impl(atomic_uint_least8_t, Acyclic());
+impl(atomic_int_least16_t, Send());
+impl(atomic_int_least16_t, Acyclic());
+impl(atomic_uint_least16_t, Send());
+impl(atomic_uint_least16_t, Acyclic());
+impl(atomic_int_least32_t, Send());
+impl(atomic_int_least32_t, Acyclic());
+impl(atomic_uint_least32_t, Send());
+impl(atomic_uint_least32_t, Acyclic());
+impl(atomic_int_least64_t, Send());
+impl(atomic_int_least64_t, Acyclic());
+impl(atomic_uint_least64_t, Send());
+impl(atomic_uint_least64_t, Acyclic());
+impl(atomic_int_fast8_t, Send());
+impl(atomic_int_fast8_t, Acyclic());
+impl(atomic_uint_fast8_t, Send());
+impl(atomic_uint_fast8_t, Acyclic());
+impl(atomic_int_fast16_t, Send());
+impl(atomic_int_fast16_t, Acyclic());
+impl(atomic_uint_fast16_t, Send());
+impl(atomic_uint_fast16_t, Acyclic());
+impl(atomic_int_fast32_t, Send());
+impl(atomic_int_fast32_t, Acyclic());
+impl(atomic_uint_fast32_t, Send());
+impl(atomic_uint_fast32_t, Acyclic());
+impl(atomic_int_fast64_t, Send());
+impl(atomic_int_fast64_t, Acyclic());
+impl(atomic_uint_fast64_t, Send());
+impl(atomic_uint_fast64_t, Acyclic());
+impl(atomic_intptr_t, Send());
+impl(atomic_intptr_t, Acyclic());
+impl(atomic_uintptr_t, Send());
+impl(atomic_uintptr_t, Acyclic());
+impl(atomic_size_t, Send());
+impl(atomic_size_t, Acyclic());
+impl(atomic_ptrdiff_t, Send());
+impl(atomic_ptrdiff_t, Acyclic());
+impl(atomic_intmax_t, Send());
+impl(atomic_intmax_t, Acyclic());
+impl(atomic_uintmax_t, Send());
+impl(atomic_uintmax_t, Acyclic());
+// Phase C (THREAD_SAFETY): int-specific atomic operations. The c_include
+// block only declares load/store/exchange for atomic_bool. These Yo-runtime
+// wrappers forward to the C11 _Generic macros in <stdatomic.h> so AtomicI32
+// can use the full atomic API.
+extern(
+  "Yo",
+  __yo_atomic_load_int :
+    fn(obj : *(atomic_int), order : memory_order) -> i32,
+  __yo_atomic_store_int :
+    fn(obj : *(atomic_int), desired : i32, order : memory_order) -> unit,
+  __yo_atomic_exchange_int :
+    fn(obj : *(atomic_int), desired : i32, order : memory_order) -> i32,
+  __yo_atomic_compare_exchange_int :
+    fn(
+      obj : *(atomic_int),
+      expected : *(i32),
+      desired : i32,
+      success : memory_order,
+      failure : memory_order
+    ) -> bool
+);
+// Phase C: size_t-specific atomic operations (for AtomicUsize)
+extern(
+  "Yo",
+  __yo_atomic_load_size_t :
+    fn(obj : *(atomic_size_t), order : memory_order) -> usize,
+  __yo_atomic_store_size_t :
+    fn(obj : *(atomic_size_t), desired : usize, order : memory_order) -> unit,
+  __yo_atomic_exchange_size_t :
+    fn(obj : *(atomic_size_t), desired : usize, order : memory_order) -> usize,
+  __yo_atomic_compare_exchange_size_t :
+    fn(
+      obj : *(atomic_size_t),
+      expected : *(usize),
+      desired : usize,
+      success : memory_order,
+      failure : memory_order
+    ) -> bool
+);
+// Phase C: long-long-specific atomic operations (for AtomicI64)
+extern(
+  "Yo",
+  __yo_atomic_load_llong :
+    fn(obj : *(atomic_llong), order : memory_order) -> i64,
+  __yo_atomic_store_llong :
+    fn(obj : *(atomic_llong), desired : i64, order : memory_order) -> unit,
+  __yo_atomic_exchange_llong :
+    fn(obj : *(atomic_llong), desired : i64, order : memory_order) -> i64,
+  __yo_atomic_compare_exchange_llong :
+    fn(
+      obj : *(atomic_llong),
+      expected : *(i64),
+      desired : i64,
+      success : memory_order,
+      failure : memory_order
+    ) -> bool
+);
+// Phase C: remaining atomic type wrappers
+extern(
+  "Yo",
+  __yo_atomic_load_schar :
+    fn(obj : *(atomic_schar), order : memory_order) -> i8,
+  __yo_atomic_store_schar :
+    fn(obj : *(atomic_schar), desired : i8, order : memory_order) -> unit,
+  __yo_atomic_exchange_schar :
+    fn(obj : *(atomic_schar), desired : i8, order : memory_order) -> i8,
+  __yo_atomic_compare_exchange_schar :
+    fn(obj : *(atomic_schar), expected : *(i8), desired : i8,
+       success : memory_order, failure : memory_order) -> bool,
+  __yo_atomic_load_short :
+    fn(obj : *(atomic_short), order : memory_order) -> i16,
+  __yo_atomic_store_short :
+    fn(obj : *(atomic_short), desired : i16, order : memory_order) -> unit,
+  __yo_atomic_exchange_short :
+    fn(obj : *(atomic_short), desired : i16, order : memory_order) -> i16,
+  __yo_atomic_compare_exchange_short :
+    fn(obj : *(atomic_short), expected : *(i16), desired : i16,
+       success : memory_order, failure : memory_order) -> bool,
+  __yo_atomic_load_uchar :
+    fn(obj : *(atomic_uchar), order : memory_order) -> u8,
+  __yo_atomic_store_uchar :
+    fn(obj : *(atomic_uchar), desired : u8, order : memory_order) -> unit,
+  __yo_atomic_exchange_uchar :
+    fn(obj : *(atomic_uchar), desired : u8, order : memory_order) -> u8,
+  __yo_atomic_compare_exchange_uchar :
+    fn(obj : *(atomic_uchar), expected : *(u8), desired : u8,
+       success : memory_order, failure : memory_order) -> bool,
+  __yo_atomic_load_ushort :
+    fn(obj : *(atomic_ushort), order : memory_order) -> u16,
+  __yo_atomic_store_ushort :
+    fn(obj : *(atomic_ushort), desired : u16, order : memory_order) -> unit,
+  __yo_atomic_exchange_ushort :
+    fn(obj : *(atomic_ushort), desired : u16, order : memory_order) -> u16,
+  __yo_atomic_compare_exchange_ushort :
+    fn(obj : *(atomic_ushort), expected : *(u16), desired : u16,
+       success : memory_order, failure : memory_order) -> bool,
+  __yo_atomic_load_uint :
+    fn(obj : *(atomic_uint), order : memory_order) -> u32,
+  __yo_atomic_store_uint :
+    fn(obj : *(atomic_uint), desired : u32, order : memory_order) -> unit,
+  __yo_atomic_exchange_uint :
+    fn(obj : *(atomic_uint), desired : u32, order : memory_order) -> u32,
+  __yo_atomic_compare_exchange_uint :
+    fn(obj : *(atomic_uint), expected : *(u32), desired : u32,
+       success : memory_order, failure : memory_order) -> bool,
+  __yo_atomic_load_ullong :
+    fn(obj : *(atomic_ullong), order : memory_order) -> u64,
+  __yo_atomic_store_ullong :
+    fn(obj : *(atomic_ullong), desired : u64, order : memory_order) -> unit,
+  __yo_atomic_exchange_ullong :
+    fn(obj : *(atomic_ullong), desired : u64, order : memory_order) -> u64,
+  __yo_atomic_compare_exchange_ullong :
+    fn(obj : *(atomic_ullong), expected : *(u64), desired : u64,
+       success : memory_order, failure : memory_order) -> bool,
+  __yo_atomic_load_ptrdiff :
+    fn(obj : *(atomic_ptrdiff_t), order : memory_order) -> isize,
+  __yo_atomic_store_ptrdiff :
+    fn(obj : *(atomic_ptrdiff_t), desired : isize, order : memory_order) -> unit,
+  __yo_atomic_exchange_ptrdiff :
+    fn(obj : *(atomic_ptrdiff_t), desired : isize, order : memory_order) -> isize,
+  __yo_atomic_compare_exchange_ptrdiff :
+    fn(obj : *(atomic_ptrdiff_t), expected : *(isize), desired : isize,
+       success : memory_order, failure : memory_order) -> bool
+);
 export(
   // Atomic types
   atomic_bool,
@@ -238,5 +441,51 @@ export(
   ATOMIC_LLONG_LOCK_FREE,
   ATOMIC_POINTER_LOCK_FREE,
   // Kill dependency
-  kill_dependency
+  kill_dependency,
+  // Phase C (THREAD_SAFETY): int-specific atomic wrappers
+  __yo_atomic_load_int,
+  __yo_atomic_store_int,
+  __yo_atomic_exchange_int,
+  __yo_atomic_compare_exchange_int,
+  // Phase C: size_t atomic wrappers
+  __yo_atomic_load_size_t,
+  __yo_atomic_store_size_t,
+  __yo_atomic_exchange_size_t,
+  __yo_atomic_compare_exchange_size_t,
+  // Phase C: llong atomic wrappers
+  __yo_atomic_load_llong,
+  __yo_atomic_store_llong,
+  __yo_atomic_exchange_llong,
+  __yo_atomic_compare_exchange_llong,
+  // Phase C: signed narrow atomics
+  __yo_atomic_load_schar,
+  __yo_atomic_store_schar,
+  __yo_atomic_exchange_schar,
+  __yo_atomic_compare_exchange_schar,
+  __yo_atomic_load_short,
+  __yo_atomic_store_short,
+  __yo_atomic_exchange_short,
+  __yo_atomic_compare_exchange_short,
+  // Phase C: unsigned atomics
+  __yo_atomic_load_uchar,
+  __yo_atomic_store_uchar,
+  __yo_atomic_exchange_uchar,
+  __yo_atomic_compare_exchange_uchar,
+  __yo_atomic_load_ushort,
+  __yo_atomic_store_ushort,
+  __yo_atomic_exchange_ushort,
+  __yo_atomic_compare_exchange_ushort,
+  __yo_atomic_load_uint,
+  __yo_atomic_store_uint,
+  __yo_atomic_exchange_uint,
+  __yo_atomic_compare_exchange_uint,
+  __yo_atomic_load_ullong,
+  __yo_atomic_store_ullong,
+  __yo_atomic_exchange_ullong,
+  __yo_atomic_compare_exchange_ullong,
+  // Phase C: isize
+  __yo_atomic_load_ptrdiff,
+  __yo_atomic_store_ptrdiff,
+  __yo_atomic_exchange_ptrdiff,
+  __yo_atomic_compare_exchange_ptrdiff
 );

package/std/prelude.yo

@@ -732,6 +732,13 @@ ComptimeToString :: trait(
   to_comptime_string : (fn(comptime(self) : Self) -> comptime(comptime_string)),
   where(Self <: Comptime)
 );
+// SAFETY: All builtin primitive types (unit, void, comptime_int,
+// comptime_float, comptime_string, bool, i8/i16/i32/i64, u8/u16/u32/u64,
+// f32/f64, isize/usize, char/int/uint/short/ushort/long/ulong/longlong/
+// ulonglong/longdouble) are plain value types with no heap allocations
+// or thread-local state. They are trivially safe to send across threads
+// and cannot form reference cycles. For these types, Send and Acyclic are
+// structural properties of the underlying C types.
 // === Builtin types ===
 /// unit
 impl(unit, Acyclic());
@@ -5475,6 +5482,11 @@ impl(
 _longdouble :: longdouble;
 export(longdouble : _longdouble);
 /// Ptr
+// SAFETY: A raw pointer *(T) is Send only when the pointee T is Send —
+// the pointer itself is a plain value (an address), and Send implies
+// that any T reachable through it is safe to access from another thread.
+// *(T) is unconditionally Acyclic because raw pointers do not participate
+// in Yo's ARC reference-counting cycle analysis.
 impl(forall(T : Type), where(T <: Send), *(T), Send());
 impl(forall(T : Type), *(T), Acyclic());
 impl(forall(T : Type), where(T <: Comptime), *(T), Comptime());
@@ -5536,6 +5548,10 @@ impl(
   )
 );
 /// Array
+// SAFETY: Array(T, U) is a fixed-size array value type. It is Send when T
+// is Send because an array value is copied across threads (each thread
+// gets an independent copy). It is unconditionally Acyclic because arrays
+// are value-typed — they do not participate in ARC reference counting.
 impl(forall(T : Type, U : usize), where(T <: Send), Array(T, U), Send());
 impl(forall(T : Type, U : usize), Array(T, U), Acyclic());
 impl(forall(T : Type, U : usize), where(T <: Comptime), Array(T, U), Comptime());
@@ -5619,6 +5635,12 @@ impl(
   )
 );
 /// Slice
+// SAFETY: Slice(T) is a value-typed view (pointer + length) over a backing
+// array. Sending a slice across threads copies the header; both threads
+// can independently read the backing array. The backing array's lifetime
+// is managed by its owning collection (which must itself be Send to cross
+// threads). Slice is always Acyclic — it is a value type with no ARC.
+impl(forall(T : Type), where(T <: Send), Slice(T), Send());
 impl(forall(T : Type), Slice(T), Acyclic());
 impl(forall(T : Type), where(T <: Comptime), Slice(T), Comptime());
 impl(forall(T : Type), where(T <: Runtime), Slice(T), Runtime());
@@ -7499,13 +7521,21 @@ export(
   box
 );
 /// Iso — an isolated reference-counted value that can be sent across threads.
+// SAFETY: Iso(T) is unconditionally Send (no `T <: Send` bound) because
+// Iso's public API exposes no operation on the inner T except extract(),
+// which atomically verifies rc == 1 before returning. If you add any new
+// method to Iso(T) that touches the inner T (map, peek, read, &self
+// borrow, etc.), this Send claim becomes unsound and must be revoked.
+// See plans/THREAD_SAFETY.md "Iso(T) design notes — precedent and known
+// risks" for the full argument.
 impl(forall(T : Type), Iso(T), Send());
 impl(forall(T : Type), where(T <: Acyclic), Iso(T), Acyclic());
 impl(
   forall(T : Type),
   Iso(T),
-  /// Attempt to extract the inner value if this `Iso` holds the only reference.
-  extract : (fn(self : Self) -> Option(T))(
+  /// Extract the inner value if this `Iso` holds the only reference.
+  /// Panics if rc != 1 or if this Iso has already been extracted.
+  extract : (fn(self : Self) -> T)(
     __yo_iso_extract(self)
   )
 );
@@ -7581,6 +7611,9 @@ Arc :: (fn(comptime(V) : Type, where(V <: (Send, Acyclic))) -> comptime(Type))(
 );
 /// Allocate a value inside an Arc, returning an `Arc(V)`.
 arc :: (fn(forall(V : Type), own(value) : V, where(V <: (Send, Acyclic))) -> Arc(V))(Arc(V)(value));
+// SAFETY: Arc(T) is an atomic reference-counted wrapper. It is Send when
+// the inner T is Send (all fields of the atomic-object must be Send per
+// auto-derive) and Acyclic (prevents permanent leaks from Arc cycles).
 impl(forall(T : Type), where(T <: (Send, Acyclic)), Arc(T), Send());
 export(Arc, arc);
 /// === MaybeUninit ===
@@ -8325,6 +8358,8 @@ FutureState :: enum(
   /// The future was aborted (e.g., via `unwind`).
   Aborted = -(2)
 );
+// SAFETY: FutureState is a plain enum of integer values (Pending, Done,
+// Aborted) with no heap allocations. It is trivially Send and Acyclic.
 impl(FutureState, Acyclic());
 impl(FutureState, Runtime());
 impl(FutureState, Send());
@@ -8345,6 +8380,10 @@ JoinHandle :: (fn(comptime(T) : Type) -> comptime(Type))(
     __future : *(T)
   )
 );
+// Phase L (THREAD_SAFETY): JoinHandle is NOT Send — the inner future state
+// machine lives on the spawner's event-loop thread. Cross-thread result
+// delivery uses Channel(T).
+impl(forall(T : Type), JoinHandle(T), !(Send()));
 export(JoinHandle);
 /// Io module — the async runtime effect.
 ///
@@ -8360,6 +8399,10 @@ Io :: struct(
   /// Spawn a `Future` as an independent task, returning a `JoinHandle`.
   spawn : (fn(forall(T : Type, E : Type.Struct), fut : Impl(Future(T, E)), e : E) -> JoinHandle(T))
 );
+// Phase L (THREAD_SAFETY): Io is NOT Send — the async runtime it represents
+// is per-thread (per AGENTS.md). Sending Io across a thread boundary would
+// reference a scheduler on the wrong thread.
+impl(Io, !(Send()));
 export(Io);
 extern(
   "Yo",

package/std/string/rune.yo

@@ -1,4 +1,5 @@
 //! Unicode code point type (`rune`) for representing individual characters.
+pragma(Pragma.AllowUnsafe);
 /// Unicode code point (U+0000 to U+10FFFF, excluding surrogates).
 /// Similar to Go's `rune` or Rust's `char`.
 rune :: newtype(
@@ -93,5 +94,8 @@ impl(
     (>=) : ((a, b) -> (a.char >= b.char))
   )
 );
+// SAFETY: rune is a newtype over u32. u32 is a plain value type with no
+// internal heap allocations or thread-local state — it is trivially safe
+// to send across threads.
 impl(rune, Send());
 export(rune);