@shd101wyy/yo 0.1.28 → 0.1.30

package/.github/skills/yo-syntax/syntax-cheatsheet.md

@@ -78,7 +78,7 @@ if(done, println("done"), println("pending"));
 - Always write `match(...)`, never bare `match ...`
 - `if(a, b)` and `if(a, b, c)` are macro forms over `cond`
 - Write `return(value)` or `return()`; `return value` is invalid.
-- Write `escape(value)` or `escape()`; `escape value` is invalid.
+- Write `unwind(value)` or `unwind()`; `unwind value` is invalid.
 - If a `match`/`cond` branch returns an enum variant and inference fails, qualify
   the variant with its enum type: `TypeValue.Unit` instead of `.Unit`.
 - Do not match enum payload literals directly, e.g. avoid `.Some(false)` and
@@ -121,12 +121,22 @@ masked := ((A | B) | C);
 - Yo has no operator precedence; fully parenthesize binary expressions
 - Preserve grouping around infix expressions on operator RHS positions: `true => (x / y)`, `value := (x + y)`, `(ptr &+ 1).*`
 - Line breaks can disambiguate operator chains; keep line-leading operators like `(4\n| 5\n| 6)` and newlines after `:` before a lambda unless you add equivalent grouping
-- When an operator ends a line, indent its RHS one level as a continuation: `(given(x) : T) =\n  (v) -> { ... }`
+- When an operator ends a line, indent its RHS one level as a continuation: `(x : T) =\n  (v) -> { ... }`
 - Prefix operators (`!`, `&`, `-`, `~`) require parenthesized operands: `func(&(s), a, b)`, `!(ready)`, `-(value)`.
 - Tight special forms also require immediate parentheses: `#(expr)`, `?*(u8)`, `T <: !(Runtime)`
 - Dynamic field access with unquote must keep grouping after the dot: `value.(#(field_expr))`, not `value.#(field_expr)`.
 - Unquote splicing is the tight operator `...#(exprs)`; do not insert a space between `...` and `#`.
 - Canonical pointer dereference is `ptr.*`; formatter should canonicalize legacy `ptr.(*)` to `ptr.*`.
+- **Pointer deref (`p.*`), arithmetic (`&+`, `&-`, `&/`), and `consume(p.* = v)` require `unsafe(...)`, AND the file must declare `pragma(Pragma.AllowUnsafe);` at the top before `unsafe(...)` is usable.** Pointer comparison (`&==`, `&<`, etc.) and pointer-type casts (`*(u8)(p)`) stay safe. `unsafe(expr)` is a one-arg builtin call: `v := unsafe(p.*);`, `unsafe(p.* = i32(5));`, `unsafe(p &+ usize(1))`. Every file in `std/`, `yo-self/`, and `tests/` declares the pragma explicitly. User code (default) does not, so attempts to use `unsafe(...)` are rejected with a hint to add the pragma. See `plans/MEMORY_SAFETY.md`.
+- **In-place mutation without raw pointers:** use the `ref(name) : T` parameter modifier (parallel to `own(name)`). `swap :: (fn(ref(a) : i32, ref(b) : i32) -> unit)({ tmp := a; a = b; b = tmp; });` — caller writes `swap(x, y)` with no `&()` syntax. The compiler lowers `ref(name) : T` to `T*` in C and inserts `&(arg)` at the call site automatically. Cannot combine with `own(...)` or with `forall`/`using` (those are erased at runtime — no binding to mutate). CAN combine with `comptime` as `comptime(ref(name)) : T` — the parameter is erased at runtime and mutations propagate via the evaluator's compile-time binding update path (used by prelude `ComptimeIndex`). See `plans/MEMORY_SAFETY.md` Phase B.
+- **Object-type params:** use plain `name : Type`, NOT `*(Type)` or `ref(name) : Type`. Object types (`Environment`, `EvalContext`, `CodegenContext`, `Emitter`, `HashMap`, `ArrayList`, …) carry reference semantics — passing by name already shares the underlying RC state, so mutations through the param propagate to the caller. `*(Type)` requires `pragma(Pragma.AllowUnsafe);` for the `.* ` derefs and clutters the API; `ref(name) : Type` is redundant since object semantics already share state. Use the plain form: `foo :: (fn(ctx : EvalContext) -> unit)(ctx.method());`. The same applies at call sites — don't wrap object arguments with `&(obj)`; just pass `obj`. For receivers on object methods, plain `self : Self` is the idiom (`yo-self/env.yo`, `yo-self/codegen/context.yo`, `yo-self/emitter.yo` all follow this). `ref(self) : Self` is reserved for receivers on value-type methods (the form used by `Hash`, `Clone`, `ToString`, `Index`, `ComptimeIndex`, `Writer`, `Reader`).
+- **Byte-buffer params:** prefer `Slice(u8)` over `*(u8) + usize` for public signatures (e.g. `random_bytes`, `fnv1a_hash_bytes`). `Slice` carries the length, eliminating the (`ptr`, `wrong-size`) footgun. Convert at the FFI seam with `slice.ptr()` and `slice.len()`; construct from existing storage with `Slice(u8).from_raw_parts(&(buf(0)), len)`. The `_cstr` family is the explicit raw-pointer variant — those names signal raw-pointer use by contract.
+- **Audit public stdlib safety with `./yo-cli public-safe-report [path]`.** Flags every top-level public `fn(...)` whose params or return type expose `*(T)` outside an `extern(...)` block. Skips FFI-by-construction directories (`libc/`, `linux/`, `darwin/`, `cuda/`, `sys/`, `sync/`) and names that signal raw-pointer use by contract (`*_cstr`, `*_ptr`, `*_raw`, `raw_*`, `from_raw_parts`, `as_ptr`, `argv`, `argc`). Currently reports 0 findings on `./std` and `./yo-self`; keep it that way when adding new APIs.
+- **Extern "c" call sites require `unsafe(...)` even in pragma'd files.** `unsafe(memcpy(dst, src, n))`, `unsafe(strlen(s))`, etc. The pragma authorizes DECLARING the FFI symbol via `extern(...)` / `c_include(...)`; the wrap is the per-call audit marker so `yo unsafe-report` lines up with UB-capable lines. `asm(...)` and `extern(...)` / `c_include(...)` declarations themselves do NOT need a wrap (the keyword / declaration syntax is its own marker). See `plans/EXTERN_UNSAFE_WRAP.md`.
+- **Slice-flowability rule:** a function returning a slice-bearing type (`Slice(T)`, `str`, a struct wrapping a Slice, ...) must root the returned value in caller-owned storage (a `ref`-bound parameter, any non-`ref` parameter, a `comptime`/literal source, or a flowable projection chain). `(fn() -> Option(Slice(i32)))({ arr := ArrayList(i32).new(); arr.as_slice() })` is rejected; `(fn(ref(arr) : ArrayList(i32)) -> Option(Slice(i32)))(arr.as_slice())` is accepted. See `plans/SLICE_FLOWABILITY.md`.
+- **Signed-integer overflow is defined (wrap-around).** Yo passes `-fwrapv` to clang/gcc/zig by default so `x + i32(1)` on `i32(MAX)` wraps to `i32(MIN)` instead of UB. Opt-out: `--cflags='-fno-wrapv'`.
+- **`// SAFETY:` comment convention.** Every non-obvious `unsafe(...)` site in stdlib should have a `// SAFETY:` comment in the previous ~8 lines explaining the contract. `yo unsafe-report` picks them up and shows them inline under each finding.
+- **User-facing memory-safety guide:** `docs/en-US/MEMORY_SAFETY.md` (English) and `docs/zh-CN/MEMORY_SAFETY.md` (Chinese). Refer users there instead of `plans/MEMORY_SAFETY.md` (which is the design document — not shipped via npm).
 - Keep single-line array and tuple literals compact during formatting: `[1, 2, 3]`, `(1, 2, 3)`.
 - Parenthesize other unary operands too: `!(ready)`, `-(value)`
 - **`!x && y` is parsed as `!(x && y)`**, not `(!x) && y`. Prefix `!` greedily consumes the full right-hand expression. To get `(!x) && y`, write `((!x) && y)` with explicit inner parens.
@@ -180,12 +190,12 @@ create_user(name: `Bob`, age: 30);
 - Named arguments must keep the same order as the definition
 - Default values use `?=` and must be compile-time known
 
-### Implicit parameters (`using` / `given`)
+### Effect parameters (explicit)
 
 ```rust
-Raise :: (fn(msg : String) -> i32);
+Raise :: (ctl(msg : String) -> i32);
 
-safe_divide :: (fn(x : i32, y : i32, using(raise : Raise)) -> i32)(
+safe_divide :: (fn(x : i32, y : i32, raise : Raise) -> i32)(
   cond(
     (y == i32(0)) => raise(`divide by zero`),
     true => (x / y)
@@ -193,18 +203,20 @@ safe_divide :: (fn(x : i32, y : i32, using(raise : Raise)) -> i32)(
 );
 
 caller :: (fn() -> i32)({
-  (given(raise) : Raise) = (fn(msg : String) -> i32)({
-    return(i32(0));
+  // Handler value bound to a local. Lambdas on the RHS of `=` need outer parens.
+  (raise : Raise) = ((msg) -> {
+    unwind(i32(0));
   });
 
-  safe_divide(i32(10), i32(0))
+  safe_divide(i32(10), i32(0), raise)
 });
 ```
 
-- `using(name : Type)` declares an implicit parameter (effect)
-- `given(name) := Type(fields...)` installs a handler in the caller's scope
-- Effects are matched by **type**, not by name
-- The handler is auto-resolved at call sites; pass explicitly with `using(name)`
+- Effect handlers are regular parameters — pass them explicitly at the call site.
+- `ctl(args) -> R` types a handler that may `unwind` (discard the continuation).
+  Use plain `fn(args) -> R` for handlers that always resume.
+- Bundle multiple effects into a struct (`Ctx :: struct(raise : Raise, log : Log)`)
+  and pass one parameter when there are many.
 
 ### Closures and anonymous functions
 
@@ -214,8 +226,8 @@ caller :: (fn() -> i32)({
 result := closure(i32(5));
 
 transform :: (fn(list : ArrayList(i32), f : Impl(Fn(x : i32) -> i32)) -> unit)({
-  for(list.iter(), (ptr) => {
-    ptr.* = f(ptr.*);
+  for(list, ref(x) => {
+    x = f(x);
   });
 });
 ```
@@ -369,25 +381,29 @@ while(comptime((i < 10)), {
   // body evaluated/unrolled at compile time
 });
 
-// for loop — 2-arg prelude macro; first arg MUST be an iterator (has .next()):
-for(list.iter(), x => {    // ArrayList, array → call .iter() first
+// for loop — 2-arg prelude macro. First arg is the collection
+// directly; the macro dispatches on the body's binding shape to
+// pick value-form vs borrow-form iteration:
+for(list, (x) => {            // value form: implicit .into_iter()
   process(x);
 });
 
-for(map.into_iter(), bucket => {
-  println(bucket.key);
+for(list, ref(x) => {         // borrow form: iter() + project(pos)
+  x = transform(x);           // writes propagate back into list
 });
 
-for(list.iter(), (ptr) => { // ptr is a mutable reference to each element
-  ptr.* = transform(ptr.*);
-});
+// Combinator chains (.map / .filter / .into_iter / etc.) yield
+// computed values; pass them as the first arg in the value form:
+for(list.iter().map((x) => (x + i32(1))), (y) => println(y));
 ```
 
 - Use `recur(...)` for self-recursion
 - `while(cond, body)` is **always a runtime loop** — use this for open-ended loops (e.g., server accept loops, event loops)
 - `while(comptime(cond), body)` explicitly unrolls at compile time — `cond` must be a compile-time-known value
 - Using a comptime-only (`::`) variable in a bare `while` condition without `comptime()` is a **compile error** (would be an infinite loop at runtime)
-- **`for(arr, item => { body })`** — correct 2-arg prelude macro form. The `item => { body }` is an anonymous closure.
+- **`for(coll, (x) => body)`** — value form; macro expands to `coll.into_iter()` then iterates by value (`x : T`).
+- **`for(coll, ref(x) => body)`** — borrow form; macro expands to `coll.iter()` (position iterator) + `coll.project(pos)` (`Indexable.project` impl) so `x` is a writable binding. Writes propagate back into the collection.
+- **Do NOT write `for(coll.iter(), (x) => …)` for the value form** — `.iter()` yields positions (usize), not the collection's elements. Use the bare collection or `.into_iter()`.
 - **Do NOT use `for(x, arr, { body })`** — this older 3-arg form is an evaluator-internal representation, not valid top-level Yo syntax. (The self-hosted evaluator currently only understands the 3-arg form in its internal for-loop handler; track issue: `issues/eval-for-loop-3arg-vs-2arg.md`)
 
 ## Return and branch safety
@@ -450,18 +466,22 @@ list := ArrayList(i32).new();
 list.push(i32(10));
 list.push(i32(20));
 
-for(list.iter(), (ptr) => {
-  println(ptr.*);
+// Value form — implicit .into_iter().
+for(list, (value) => {
+  println(value);
 });
 
-for(list.into_iter(), (value) => {
-  println(value);
+// Borrow form — implicit .iter() + .project(pos). `x` is a writable
+// binding into the collection; assignments propagate back.
+for(list, ref(x) => {
+  x = (x + i32(1));
 });
 ```
 
-- `for(collection, (variable) => { body })` iterates via the `Iterator` trait
-- `.iter()` borrows the collection and yields pointers
-- `.into_iter()` takes ownership and yields values
+- `for(coll, (x) => body)` — value form. Macro expands to `coll.into_iter()` and yields elements by value.
+- `for(coll, ref(x) => body)` — borrow form. Macro expands to `coll.iter()` (a position iterator yielding `usize`) + `coll.project(pos)` (from the `Indexable` trait) so the body sees a writable binding.
+- Combinator chains (`coll.iter().map(f).filter(g)`) only support the value form — pass the chain as the first arg with `(x) => body`.
+- The for macro accepts the collection directly; do NOT call `.iter()` for the value form, that yields positions (usize), not elements.
 
 ## Testing
 
@@ -480,7 +500,7 @@ test("Async test", {
 });
 ```
 
-- `test("description", { body })` defines a test — `io : IO` is automatically available
+- `test("description", { body })` defines a test — `io : Io` is automatically available
 - All tests can use `io.async(...)`, `io.await(...)`, etc. without a `using` clause
 - `assert(condition, "message")` — runtime assertion (always include a message)
 - `comptime_assert(condition)` — compile-time assertion
@@ -602,11 +622,11 @@ list := ArrayList(i32).new();
 list.push(i32(42));
 
 val := list(usize(0));         // → i32  (value copy via Index trait)
-list(usize(0)) = i32(99);     // mutate in place directly
+list(usize(0)) = i32(99);      // mutate in place directly
 
 // When you need the pointer explicitly:
-ptr := &(list(usize(0)));     // → *(i32)
-ptr.* = i32(99);              // also works
+ptr := &(list(usize(0)));      // → *(i32)
+ptr.* = i32(99);               // also works
 
 // Safe access (returns Option(T)):
 match(list.get(usize(0)),
@@ -620,6 +640,26 @@ match(list.get(usize(0)),
 - `&(list(i))` returns `*(T)` if you need the pointer explicitly
 - `list.get(i)` returns `Option(T)` for safe bounds-checked access
 
+**Don't write `(&(X)).index(i).*` or `X.get(i).unwrap()` when you mean
+`X(i)`.** Use the call-syntax form everywhere it works:
+
+```rust
+// ✗ Verbose, scans like raw-pointer code (and requires the file's
+//   pragma(Pragma.AllowUnsafe); because `.*` is gated):
+(&(self.field)).index(i).* = value;
+elem := (&(self.field)).index(i).*;
+v := list.get(usize(0)).unwrap();
+
+// ✓ Same semantics, no `.*`, no pragma needed:
+self.field(i) = value;
+elem := self.field(i);
+v := list(usize(0));
+```
+
+Both forms call the same `Index` trait method. The call-syntax form
+is shorter, doesn't need raw-pointer plumbing in user code, and
+panics on out-of-bounds identically to `.unwrap()` on `.get(...)`.
+
 ### Named fields required for `struct`/`object` constructors
 
 ```rust
@@ -724,46 +764,38 @@ if(!cond, { do_thing(); });
 if((!cond), { do_thing(); });
 ```
 
-### `escape` requires a nested-function context
+### `unwind` requires a nested-function context
 
-`escape(value)` exits the **enclosing function** — the nearest `fn(...)` that
-wraps the current code. It requires that the code is inside a nested function
-(e.g., a closure or `given` handler lambda), NOT at the top level of a
-standalone function definition.
+`unwind(value)` exits the **install frame** — the function that bound the
+`ctl(...) -> R` value being called. It is only valid inside the body of a
+`ctl(...) -> R` value (an effect handler).
 
 ```rust
-// CORRECT — escape inside a given handler lambda (lambda has enclosing fn):
-given(exn) := Exception(throw: ((err) -> {
-  escape(result); // exits the outer function that contains this given()
-}));
-do_something(using(exn));
+Raise :: (ctl(msg : String) -> i32);
 
-// CORRECT — even after process-exit helpers, satisfy the handler's resume type:
-given(exn2) := Exception(throw: ((err) -> {
-  eprintln(err.to_string());
-  exit(int(1));
-  escape(); // required because exit() returns unit, not the handler ResumeType
-}));
+caller :: (fn() -> i32)({
+  // The handler is a `ctl` value bound in `caller`. `unwind` exits `caller`.
+  (raise : Raise) = ((msg) -> {
+    eprintln(msg);
+    unwind(i32(-1));
+  });
+  safe_divide(i32(10), i32(0), raise)  // call site: handler is passed explicitly
+});
 
-// CORRECT — escape inside a closure passed as argument:
-result := match(opt, .Some(x) => x, .None => {
-  // This is NOT a nested function — use return:
-  // WRONG: escape(default_val)  // ERROR: no enclosing fn
-  return(default_val); // CORRECT: return exits the enclosing fn directly
+// WRONG — `unwind` in a regular `fn` body (no install frame here) is rejected.
+bad :: (fn() -> unit)({
+  unwind(());  // ERROR: unwind requires a ctl(...) body
 });
 
-// WRONG — escape inside a match arm (not a nested fn):
-match(opt,
-  .Some(x) => { escape(x); }  // ERROR: "can only be used inside a function that has an enclosing function"
+// WRONG — capturing a `ctl` value into a closure is rejected (closures escape).
+make_closure :: (fn(raise : Raise) -> Impl(Fn() -> unit))(
+  () => { raise(`x`); }  // ERROR: closure captures a control-bound value
 );
 ```
 
-**Rule of thumb**: Use `escape` only inside lambdas passed to `given()` handlers.
-In all other contexts (match arms, if blocks, begin blocks, top-level fn bodies),
-use `return` for early exit.
-
-`return` inside a lambda exits that lambda only; `escape` exits the OUTER function
-(the one that installed the `given` handler).
+**Rule of thumb**: `unwind` belongs only inside the lambda bound to a
+`ctl(...) -> R` handler. From any other position, use `return` to exit the
+current `fn`.
 
 ### Parameter reassignment
 
@@ -818,19 +850,19 @@ fn_taking_str((`prefix_${value}`).as_str());
 
 These features are powerful but less commonly used. Consult the linked docs for full details.
 
-| Feature                | Syntax hint                                              | Documentation                                                                                                          |
-| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Higher-Kinded Types    | `forall(F : (fn(comptime(T) : Type) -> comptime(Type)))` | [DESIGN.md § HKT](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DESIGN.md#higher-kinded-types-hkt)           |
-| GADTs                  | `enum(IntVal(i : i32) -> recur(i32))`                    | [GADTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/GADTS.md)                                           |
-| Derive traits          | `derive(MyType, Eq, Hash, Clone, Ord, ToString)`         | [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md)                           |
-| Type reflection        | `Type.get_info(T)` returns `TypeInfo`                    | [TYPE_REFLECTION.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/TYPE_REFLECTION.md)                       |
-| Inline assembly        | `asm("mov {0}, #42", out(reg, i32))`                     | [INLINE_ASSEMBLY.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/INLINE_ASSEMBLY.md)                       |
-| Metaprogramming        | `quote(...)`, `unquote(...)`, `unquote_splicing(...)`    | [DESIGN.md § Meta](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DESIGN.md#meta-programming)                 |
-| Effect row variables   | `forall(...(E))` with `using(...(E))`                    | [ALGEBRAIC_EFFECTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ALGEBRAIC_EFFECTS.md)                   |
-| Custom derive rules    | `derive_rule(MyTrait, (fn(...) -> unquote(Expr)){...})`  | [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md#user-defined-derive-rules) |
-| Isolated types         | `Iso(T)` for data-race-free parallelism                  | [ISOLATED.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ISOLATED.md)                                     |
-| Arc (atomic ref count) | `arc(value)`, `shared.(*)` for cross-thread sharing      | [ARC.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ARC.md)                                               |
-| Parallelism            | Thread pool, `io.spawn` for parallel work                | [PARALLELISM.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/PARALLELISM.md)                               |
+| Feature                    | Syntax hint                                              | Documentation                                                                                                          |
+| -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Higher-Kinded Types        | `forall(F : (fn(comptime(T) : Type) -> comptime(Type)))` | [DESIGN.md § HKT](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DESIGN.md#higher-kinded-types-hkt)           |
+| GADTs                      | `enum(IntVal(i : i32) -> recur(i32))`                    | [GADTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/GADTS.md)                                           |
+| Derive traits              | `derive(MyType, Eq, Hash, Clone, Ord, ToString)`         | [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md)                           |
+| Type reflection            | `Type.get_info(T)` returns `TypeInfo`                    | [TYPE_REFLECTION.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/TYPE_REFLECTION.md)                       |
+| Inline assembly            | `asm("mov {0}, #42", out(reg, i32))`                     | [INLINE_ASSEMBLY.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/INLINE_ASSEMBLY.md)                       |
+| Metaprogramming            | `quote(...)`, `unquote(...)`, `unquote_splicing(...)`    | [DESIGN.md § Meta](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DESIGN.md#meta-programming)                 |
+| Effect bundle polymorphism | `forall(E : Type.Struct)` over a bundle struct           | [ALGEBRAIC_EFFECTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ALGEBRAIC_EFFECTS.md)                   |
+| Custom derive rules        | `derive_rule(MyTrait, (fn(...) -> unquote(Expr)){...})`  | [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md#user-defined-derive-rules) |
+| Isolated types             | `Iso(T)` for data-race-free parallelism                  | [ISOLATED.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ISOLATED.md)                                     |
+| Arc (atomic ref count)     | `arc(value)`, `shared.(*)` for cross-thread sharing      | [ARC.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ARC.md)                                               |
+| Parallelism                | Thread pool, `io.spawn` for parallel work                | [PARALLELISM.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/PARALLELISM.md)                               |
 
 ---
 
@@ -997,26 +1029,6 @@ Always merge them into a single destructuring import:
 { Foo, Bar } :: import("../../mod.yo");
 ```
 
-### Implicit (`using`) parameters cannot be used with `:=` assignment
-
-Implicit effect parameters introduced via `using(name : Type)` cannot be bound
-to a discarded variable with `:= name`. They can only be passed via `using()`.
-To suppress "unused parameter" warnings for an implicit param, simply omit the
-discard assignment — implicit params never trigger unused-variable errors.
-
-```rust
-// WRONG — implicit variable cannot be used in assignment:
-foo :: (fn(using(exn : Exception)) -> unit)({
-  _ := exn;   // ERROR: Cannot use implicit variable "exn" in assignment
-  ()
-});
-
-// CORRECT — just omit the discard line:
-foo :: (fn(using(exn : Exception)) -> unit)({
-  ()
-});
-```
-
 ### Nested `Option` patterns require staging
 
 `match` does not support nested destructuring patterns like `.Some(.TypeVal(x))`.

package/README.md

@@ -8,6 +8,8 @@
 
 https://shd101wyy.github.io/Yo
 
+**LLM-friendly to write, human-friendly to read.**
+
 A multi-paradigm, general-purpose, compiled programming language.
 Yo aims to be **Simple** and **Fast** (around 0% - 15% slower than C).
 
@@ -53,7 +55,8 @@ Below is a non-exhaustive list of features that Yo supports:
 - Homoiconicity and metaprogramming (**Yo** syntax is inspired by the **Lisp** S expression. Simple syntax rule, Human & AI friendly).
 - Closure.
 - [Algebraic Effects and Handlers](./docs/en-US/ALGEBRAIC_EFFECTS.md) (One-shot delimited continuation. Tail-Resumptive. Implicit parameters via `using`/`given`, effect handlers with `return`/`escape`, by [Evidence Passing](https://xnning.github.io/papers/multip.pdf)).
-- [Async/await](./docs/en-US/ASYNC_AWAIT.md) (Builtin `IO` effect. Stackless coroutine & Cooperative multi-tasking. Lazy Futures, multi-await, single-threaded concurrency via state machine transformation).
+- [Async/await](./docs/en-US/ASYNC_AWAIT.md) (Builtin `Io` effect. Stackless coroutine & Cooperative multi-tasking. Lazy Futures, multi-await, single-threaded concurrency via state machine transformation).
+- [Memory safety by default](./docs/en-US/MEMORY_SAFETY.md) — user code can't write UB (no raw pointers, no FFI, no inline assembly) without an explicit `pragma(Pragma.AllowUnsafe);` opt-in. `ref(name)` for in-place mutation; `yo unsafe-report` for auditing the unsafe surface.
 - `object` type with [Non-atomic Reference Counting and Thread-Local Cycle Collection](./docs/en-US/CYCLE_COLLECTION.md).
 - [Compile-time Reference Counting with Ownership and Lifetime Analysis](./docs/en-US/COMPILE_TIME_RC_WITH_OWNERSHIP_ANALYSIS.md).
 - Thread-per-core parallelism model (see [PARALLELISM.md](./docs/en-US/PARALLELISM.md)).
@@ -232,7 +235,7 @@ Every Yo file automatically imports **[std/prelude.yo](./std/prelude.yo)**, whic
 - **C-compatible types**: `int`, `uint`, `short`, `long`, `longlong`, `char`, etc.
 - **Core traits**: `Eq`, `Ord`, `Add`, `Sub`, `Mul`, `Div`, `Iterator`, `IntoIterator`, `TryFrom`, `TryInto`, `Dispose`, `Send`, `Rc`, `Acyclic`, etc.
 - **Metaprogramming**: `Type`, `Expr`, `ExprList`, `Var`
-- **Async**: `IO`, `FutureState`, `JoinHandle`
+- **Async**: `Io`, `FutureState`, `JoinHandle`
 - **Utilities**: `assert`, `unsafe`, `try`, `for`, `not`, `arc`, `Box`, `box`
 - etc.
 
@@ -376,7 +379,7 @@ This repository ships a set of **agent skill files** that teach AI agents how to
 | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | [`yo-syntax`](.github/skills/yo-syntax/SKILL.md)                     | Core language syntax: curly braces, cond/match, structs, enums, operators, modules |
 | [`yo-core-patterns`](.github/skills/yo-core-patterns/SKILL.md)       | Everyday patterns: types, generics, traits, error handling, collections, iterators |
-| [`yo-async-effects`](.github/skills/yo-async-effects/SKILL.md)       | Async/await, algebraic effects, Exception, IO, spawning tasks                      |
+| [`yo-async-effects`](.github/skills/yo-async-effects/SKILL.md)       | Async/await, algebraic effects, Exception, Io, spawning tasks                      |
 | [`yo-project-workflow`](.github/skills/yo-project-workflow/SKILL.md) | `yo` CLI commands, `build.yo` project files, dependency management                 |
 
 ### Using in your own project