@shd101wyy/yo 0.1.32 → 0.1.34

package/.github/skills/yo-async-effects/async-effects-recipes.md

@@ -160,13 +160,13 @@ process_dir :: (fn(root: Path, ctx : WalkCtx) -> Impl(Future(unit, WalkCtx)))(
     stack := ArrayList(Path).new();
     { stack.push(root); };
 
-    while(runtime((stack.len() > usize(0))), {
+    while(stack.len() > usize(0), {
       cur := match(stack.pop(), .Some(p) => p, .None => return());
       entries := ctx.io.await(read_dir(cur, ctx.io), ctx.io);
       // process `entries`, push subdirectories to `stack`
       n := entries.len();
       i := usize(0);
-      while(runtime((i < n)), {
+      while(i < n, {
         match(entries.get(i),
           .None => (),
           .Some(e) => {

package/.github/skills/yo-core-patterns/SKILL.md

@@ -29,7 +29,7 @@ Use this skill when you need to:
 
 ## High-signal rules
 
-- `"` creates `str` in runtime code; template strings create `String`. In `comptime` functions, `"hello"` is `comptime_string` (distinct from `str`).
+- `"` creates `str` in runtime code; template strings create `String`. In `comptime` functions, `"hello"` is `comptime_str` (distinct from `str`).
 - Prefer template strings for constant `String` values.
 - Prefer `print`/`println` from `std/fmt` over `printf`.
 - `Option(T)` and `Result(T, E)` are the default nullable/error carriers.

package/.github/skills/yo-core-patterns/core-patterns-cheatsheet.md

@@ -24,14 +24,14 @@ println("plain str is also fine");
 
 | Type              | When you see it                              | Key behavior                           |
 | ----------------- | -------------------------------------------- | -------------------------------------- |
-| `str`             | `"hello"` in runtime contexts                | Slice of bytes, no ownership           |
+| `str`             | `"hello"` in runtime contexts                | View of STATIC bytes, no constraints   |
 | `String`          | Template strings `` `hello` ``               | Owned UTF-8, reference-counted         |
-| `comptime_string` | `"hello"` inside `comptime` functions/macros | Compile-time only, distinct from `str` |
+| `comptime_str` | `"hello"` inside `comptime` functions/macros | Compile-time only, distinct from `str` |
 
 Key rules:
 
 - In **runtime** code, `"hello"` is always `str`. Mixing literal and variable branches in `cond`/`match` works fine.
-- In **comptime** functions (return type `comptime(...)`), `"hello"` is `comptime_string`. It does NOT auto-convert to `str`. Use `str.from_raw_parts(*(u8)("..."), usize(N))` if a comptime function needs to return `str`.
+- In **comptime** functions (return type `comptime(...)`), `"hello"` is `comptime_str`. It does NOT auto-convert to `str`. A comptime function returning `str` materializes its `comptime_str` result automatically.
 - For `String` constants, prefer `` `hello` `` over `String.from("hello")`.
 - **PITFALL:** Never write `String.from(`hello`)` — backtick strings are already `String`, not `str`. `String.from` takes `str`, so wrapping a backtick in `String.from` causes a type error ("Cannot unify String and str"). Only use `String.from(str_expr)` for actual `str` values.
 
@@ -78,6 +78,30 @@ text := match(parsed,
 - Prefer combinators for straight-line transforms: `map`, `and_then`, `map_err`, `or_else`
 - Switch to `match(...)` when branches need different logic or side effects
 
+### Match destructuring: prefer curly `{field}`, avoid positional `_` padding
+
+For a variant with **2+ fields**, destructure by **name** with curly braces —
+name only the fields the arm uses. Do NOT count positions and pad with `_`.
+
+```rust
+// ✅ Curly — names only what you need; order-free; partial matches OK.
+//    Robust: adding a field to the variant later doesn't shift anything.
+match(v,
+  .FuncVal({ func_id }) => use(func_id),          // bind field `func_id`
+  .Struct({ id, name: n }) => use2(id, n),        // rename via `field: alias`
+  .EnumT({ id }) => use3(id),                     // ignore the other 6 fields
+  _ => ()
+)
+
+// ❌ Avoid — positional with many `_`; brittle and unreadable:
+//    .FuncVal(_, _, _, _, _, _, _, _, func_id) => …   // count the 8 _'s!
+```
+
+`{a}` = bind field `a`; `{a: x}` = rename to `x`; `{a: _}` = assert-exists-ignore.
+Empty `{}` and bare `{_}` are rejected. Spec: `tests/match_curly.test.yo`.
+(Full rules: `.github/instructions/yo-syntax.instructions.md` § Match
+destructuring forms.)
+
 ## Collections
 
 ```rust
@@ -237,6 +261,29 @@ impl(forall(T), where(T <: ToString), Box(T),
 - `forall(T)` + `where(T <: Trait)` for generic impls
 - Trait impls: `impl(MyType, MyTrait(args), : trait_field_bindings...)`
 
+### Method overloading: inherent NO, trait YES
+
+Inherent methods cannot be overloaded — a second same-name inherent method is
+rejected ("Method already defined" across impl blocks, "variable shadowing"
+within one). But **trait-provided methods may share a name** with an inherent
+method and with same-name methods from other traits; dispatch picks by
+argument types. This is how std gives `String` both `contains(String)`
+(inherent) and `contains(str)` (via the `StrPattern` trait), and both
+`Eq(String)` and `Eq(str)` `(==)` overloads:
+
+```rust
+PickStr :: trait(pick : (fn(self : Self, x : str) -> i32));
+impl(V, pick : (fn(self : Self, x : V) -> i32)(i32(1)));        // inherent
+impl(V, PickStr(pick : (fn(self : Self, x : str) -> i32)(i32(2))));
+v.pick(v);    // 1 — inherent overload
+v.pick("s");  // 2 — trait overload, chosen by argument type
+```
+
+- Heterogeneous parametric-trait impls work: `impl(String, Eq(str)(...))`
+  beside `impl(String, Eq(String)(...))`; `x == "lit"` dispatches by RHS type.
+- Provide only `(==)`; `(!=)` comes from the `Eq` trait's `?=` default and
+  resolves to the right overload by argument types.
+
 ## Partial application
 
 ```rust
@@ -303,7 +350,7 @@ node_eq :: (fn(a : Node, b : Node) -> bool)(
             true => {
               (i : usize) = usize(0);
               (ok : bool) = true;
-              while(runtime(((i < acs.len()) && ok)), {
+              while(((i < acs.len()) && ok), {
                 match(acs.get(i),
                   .Some(ac) => match(bcs.get(i),
                     .Some(bc) => { ok = recur(ac, bc); },
@@ -376,8 +423,10 @@ safe_div :: (fn(a : i32, b : i32) -> Result(i32, DivError))(
 result := inc(i32(5));
 
 transform :: (fn(values : ArrayList(i32), f : Impl(Fn(x : i32) -> i32)) -> unit)({
-  for(values, ref(x) => {
-    x = f(x);
+  i := usize(0);
+  while(i < values.len(), {
+    values(i) = f(values(i));
+    i = (i + usize(1));
   });
 });
 ```
@@ -396,27 +445,28 @@ list := ArrayList(i32).new();
 list.push(i32(1));
 list.push(i32(2));
 
-// Value form — implicit .into_iter().
+// Value form — implicit .into_iter(). The only form.
 for(list, (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(10));
+// In-place element mutation: index writes.
+i := usize(0);
+while(i < list.len(), {
+  list(i) = (list(i) + i32(10));
+  i = (i + usize(1));
 });
 ```
 
-| Form                          | Expansion                                  | When to use                                   |
-| ----------------------------- | ------------------------------------------ | --------------------------------------------- |
-| `for(coll, (x) => …)`         | `coll.into_iter()`, yields `T` by value    | Read-only iteration; combinator chains        |
-| `for(coll, ref(x) => …)`      | `coll.iter()` + `coll.project(pos)` borrow | Mutation in place; writes propagate to `coll` |
-| `for(chain.map(f), (x) => …)` | Treats chain as the iterator (value form)  | Computed values; chains support only value    |
+| Form                          | Expansion                                 | When to use                                                                  |
+| ----------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------- |
+| `for(coll, (x) => …)`         | `coll.into_iter()`, yields `T` by value   | All iteration; object elements are handles and mutate in place               |
+| index loop + `coll(i) = v`    | Index trait read/write                    | In-place struct/scalar element mutation                                       |
+| `for(chain.map(f), (x) => …)` | Treats chain as the iterator (value form) | Computed values                                                               |
 
+- The borrow form `for(coll, ref(x) => …)` was REMOVED (v4, plans/BORROW_EXCLUSIVITY.md — no interior refs); it emits a teaching compile error.
 - `Iterator` trait — defines `next() -> Option(Item)`. Custom iterables impl this.
 - `IntoIterator` trait — defines `into_iter() -> IntoIter`. Collections impl this so `for(coll, ...)` works.
-- `Indexable(Position)` trait — defines `project(pos) -> ref(Element)`. Collections impl this to support the borrow form.
 
 ## Module-level mutable variables
 
@@ -450,13 +500,17 @@ result := my_module.helper(i32(5));
 
 Several `yo-self/` APIs take `String` (not `str`) parameters even when the argument is conceptually a name:
 
-- `get_variables_from_env(env, name: String)` — pass the `String` directly, do NOT call `.as_str()` first
+- `get_variables_from_env(env, name: String)` — pass the `String` directly
 - Most other env/value/type lookup functions follow the same convention
+- (`as_str()` no longer exists — heap Strings can never become `str`.)
 
 ```rust
-// ❌ Wrong — .as_str() converts String → str but the param is String
-vars := get_variables_from_env(env, prop_name_su.as_str());
-
-// ✅ Correct — pass the String directly
+// ✅ Pass the String directly
 vars := get_variables_from_env(env, prop_name_su);
 ```
+
+String/str comparisons never need `as_str()` either (slice-rework step 2
+swept all of them): `token.value == "fn"`, `name != other_string`, and
+`"lit" == x` all dispatch directly via the heterogeneous `Eq(str)`/
+`Eq(String)` impls. `as_str()` itself is slated for deletion
+(plans/SLICE_REWORK.md) — do not introduce new calls to it.

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

@@ -50,7 +50,7 @@ Use this skill when you need to:
 - Unary operators need parenthesized operands: `!(ready)`, `&(value)`.
 - Use `while(true, { ... })` for infinite runtime loops; use `while(comptime(cond), { ... })` only for compile-time unrolling.
 - A single-expression lambda body should not be wrapped in `{ ... }` unless semicolons make it a begin block.
-- `"hello"` is `comptime_string` inside `comptime` functions, not `str`. In runtime code, `"hello"` is always `str`.
+- `"hello"` is `comptime_str` inside `comptime` functions, not `str`. In runtime code, `"hello"` is always `str`.
 - Calls in match/cond branches must use immediate `(...)`; this avoids trailing-comma ambiguity.
 
 ## Resource

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

@@ -95,7 +95,7 @@ if(done, println("done"), println("pending"));
 | Syntax             | Type              | Context                          |
 | ------------------ | ----------------- | -------------------------------- |
 | `"hello"`          | `str`             | Runtime contexts (most code)     |
-| `"hello"`          | `comptime_string` | Inside `comptime` functions      |
+| `"hello"`          | `comptime_str` | Inside `comptime` functions      |
 | `` `hello ${x}` `` | `String`          | Always (template string)         |
 | `` `hello` ``      | `String`          | Always (template without interp) |
 | `*(u8)("hello")`   | `*(u8)`           | Pointer cast for C interop       |
@@ -103,7 +103,7 @@ if(done, println("done"), println("pending"));
 Key rules:
 
 - In **runtime** code, `"hello"` is `str`. Mixing literals and variables in `cond`/`match` branches is fine.
-- In **comptime** functions (return type `comptime(...)`), `"hello"` is `comptime_string` — it does NOT auto-convert to `str`.
+- In **comptime** functions (return type `comptime(...)`), `"hello"` is `comptime_str` — it does NOT auto-convert to `str`.
 - For `String` constants, prefer `` `hello` `` over `String.from("hello")`.
 - **`String.from(`` `...` ``)` is WRONG**: `` `...` `` is already `String`; `String.from` takes `str`. Use `` `...` `` directly or `String.from("...")` with double quotes.
 - **`assert` takes `str`, not `String`**: `assert(cond, "message")` — always use `""`. Passing a template string `` `...` `` causes a type mismatch. Use a custom `check_str` helper when you need `String` diagnostics.
@@ -130,10 +130,11 @@ masked := ((A | B) | C);
 - **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.
+- **Byte-buffer params:** for SAFE public signatures use owned collections (`ArrayList(u8)`/`String`). For pragma'd internals/FFI, `RawSlice(u8)` carries ptr+len (construct with `RawSlice(u8)(ptr : &(buf(0)), len : n)`; read `.ptr`/`.len` fields). 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`.
+- **Static-str model (post slice-rework):** builtin `Slice(T)`, `as_str()`, `as_slice()` are DELETED. `str` = static string view (no flow constraints); ranges COPY (`arr(a..b)` → ArrayList, String range → String, str range → str window); safe windows = `ListView(T)`; pragma'd ptr+len = `RawSlice(T)` (naming any raw-ptr-carrying type in an annotation requires the pragma). See `docs/en-US/FLOWABILITY.md`.
+- **`ref` is PARAMETER-ONLY (v4.1, plans/BORROW_EXCLUSIVITY.md).** `-> ref(T)`, `-> (ref(name) : T)`, `-> (name : ref(T))` AND the local binding form `ref(r) := lvalue` are all rejected (both compilers, teaching errors). Refs exist ONLY as `ref(name) : T` parameters. Migrations: return the value (object values are handles that mutate in place; struct values copy); read/write fields directly (`h.s = v`); bind the handle (`b := a.b`) to keep an object alive; or take a callback parameter receiving `ref(v) : T` (`Mutex.with_lock` pattern). A ref ARGUMENT is a simple lvalue place: a variable, or `var.field` rooted at a local/param — intermediate-OBJECT hops and module-level field roots are rejected (bind to a local first). `comptime` return modifiers go on the LABEL when labeled: `-> comptime(T)` / `-> (comptime(name) : T)` valid; `-> (name : comptime(T))` rejected. See `tests/ref_return_ban.test.yo`, `tests/ref_local_binding.test.yo`, `tests/ref_field_borrow.test.yo`.
 - **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).
@@ -226,8 +227,10 @@ caller :: (fn() -> i32)({
 result := closure(i32(5));
 
 transform :: (fn(list : ArrayList(i32), f : Impl(Fn(x : i32) -> i32)) -> unit)({
-  for(list, ref(x) => {
-    x = f(x);
+  i := usize(0);
+  while(i < list.len(), {
+    list(i) = f(list(i));
+    i = (i + usize(1));
   });
 });
 ```
@@ -381,29 +384,34 @@ while(comptime((i < 10)), {
   // body evaluated/unrolled at compile time
 });
 
-// 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()
+// for loop — 2-arg prelude macro iterating BY VALUE (implicit
+// .into_iter()). Object elements are handles: mutating them in the
+// body mutates the element in place.
+for(list, (x) => {
   process(x);
 });
+for(names, (s) => {
+  s.push_str("!");            // String element mutated in place
+});
 
-for(list, ref(x) => {         // borrow form: iter() + project(pos)
-  x = transform(x);           // writes propagate back into list
+// In-place struct/scalar element mutation: index loop + index writes.
+i := usize(0);
+while(i < list.len(), {
+  list(i) = transform(list(i));
+  i = (i + usize(1));
 });
 
 // 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));
+// computed values; pass them as the first arg:
+for(list.into_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(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()`.
+- **`for(coll, (x) => body)`** — the only form; macro expands to `coll.into_iter()` then iterates by value (`x : T`; a handle for object element types).
+- **The borrow form `for(coll, ref(x) => body)` was REMOVED** (v4, plans/BORROW_EXCLUSIVITY.md — no interior refs); it emits a teaching compile error with the migration recipe.
 - **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
@@ -443,7 +451,7 @@ get_value :: (fn(opt : Option(i32)) -> i32)(
 ## String concatenation pitfall
 
 ```rust
-// WRONG — str + str causes "comptime_string vs str" type unification error:
+// WRONG — str + str causes "comptime_str vs str" type unification error:
 content := String.from("line1\n" + "line2\n");
 
 // CORRECT — use .concat() on String objects:
@@ -454,7 +462,7 @@ content := String.from("line1\nline2\n");
 ```
 
 - `"hello" + "world"` at runtime uses `+` on `str` values, which can cause type mismatches
-- The `str + str` operator can produce a `comptime_string` in some contexts, which is not always compatible with `str`
+- The `str + str` operator can produce a `comptime_str` in some contexts, which is not always compatible with `str`
 - Prefer `.concat()` method on `String` objects when building multi-part strings at runtime
 
 ## Iterator and for loop
@@ -466,22 +474,23 @@ list := ArrayList(i32).new();
 list.push(i32(10));
 list.push(i32(20));
 
-// Value form — implicit .into_iter().
+// Value form — implicit .into_iter(). The only form.
 for(list, (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));
+// In-place element mutation: index writes (struct/scalar elements) or
+// mutate the handle (object elements).
+i := usize(0);
+while(i < list.len(), {
+  list(i) = (list(i) + i32(1));
+  i = (i + usize(1));
 });
 ```
 
-- `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.
+- `for(coll, (x) => body)` — macro expands to `coll.into_iter()` and yields elements by value (a handle for object element types — mutating it mutates the element in place).
+- The borrow form `for(coll, ref(x) => body)` was REMOVED (v4); it emits a teaching compile error.
+- Combinator chains (`coll.into_iter().map(f).filter(g)`) work as the first arg with `(x) => body`.
 
 ## Testing
 
@@ -524,7 +533,9 @@ divide :: (fn(x : i32, y : i32, requires(y != i32(0)), ensures(result == (x / y)
 increment :: (fn(ref(n) : i32, ensures(n == (old(n) + i32(1)))) -> unit)({ n = (n + i32(1)); });
 
 // invariant(...) must be the FIRST statement of a while body.
-while(runtime(i < n), {
+// NOTE: do NOT wrap the condition in runtime(...) — while conditions are
+// runtime by default, so `while(runtime(i < n), …)` is redundant; use `while(i < n, …)`.
+while(i < n, {
   invariant(i <= n, acc >= i32(0));
   i = (i + i32(1)); acc = (acc + i);
 });
@@ -638,7 +649,7 @@ Variable :: object(name : String, ty : TypeValue);
 
 ### 1-element array literals require a trailing comma
 
-`[expr]` without a trailing comma is **parsed as a Slice type** `Slice(expr)`, not an array literal. To create a 1-element array value, add a trailing comma:
+`[expr]` without a trailing comma is **parsed as a slice-type form** (now an error — the builtin Slice type is deleted, so it surfaces "Variable \"Slice\" not found"), not an array literal. To create a 1-element array value, add a trailing comma:
 
 ```rust
 // WRONG — parsed as Slice type, not array literal:
@@ -859,19 +870,12 @@ but cannot rebind the variable (`env = other_env`).
 
 ### String cloning
 
-Calling `.clone()` on a `String` field from a struct/method chain requires a
-reference — take `&` first:
+`.clone()` on a `String` works directly, including on struct fields and
+method-chain results (the historical `*(Self)`-overload ambiguity no
+longer reproduces; verified 2026-06):
 
 ```rust
-// WRONG — .clone() requires *(Self) but gets Self value from field access:
-name := token.value.clone();            // ERROR
-
-// CORRECT — take reference first:
-tok := some_fn_call();
-name := (&tok.value).clone();           // OK
-
-// ALSO CORRECT — use String.from on the str slice:
-name := String.from(token.value.as_str());
+name := token.value.clone();            // OK
 ```
 
 ### Template strings produce `String`, literals are `str`
@@ -879,13 +883,13 @@ name := String.from(token.value.as_str());
 ```rust
 // Template string `` `...` `` → String
 // String literal "..." → str
-
-// If a function takes `str`, call .as_str() on a template string:
-fn_taking_str((`prefix_${value}`).as_str());
-
-// Or change the function to take String
 ```
 
+A heap `String` can NEVER become `str` (`as_str()` is deleted — `str` is
+the STATIC string view; plans/SLICE_REWORK.md). If a function must accept
+runtime text, its parameter should be `String`; `str` parameters are for
+literals/static text only.
+
 These features are powerful but less commonly used. Consult the linked docs for full details.
 
 | Feature                    | Syntax hint                                              | Documentation                                                                                                          |
@@ -940,25 +944,13 @@ The `+` operator does not accept mixed `String`/`str` operands.
 ```rust
 // ❌ Type error
 result := (parts + ", ");
-result := (parts + item.as_str());
+result := (parts + item);
 
 // ✅ Template strings
 result := `${parts}, `;
 result := `${parts}${item}`;
 ```
 
-### `clone()` on extracted String fields is ambiguous
-
-When a `String` field is bound in a match arm, calling `.clone()` triggers an ambiguity error (two impls: `fn(self: String)` and `fn(self: *(String))`).
-
-```rust
-// ❌ Ambiguous
-.StructVal(name, fields) => name.clone()
-
-// ✅ Use from + as_str
-.StructVal(name, fields) => String.from(name.as_str())
-```
-
 ### `box(val)` is a move — cannot box the same value twice
 
 ```rust
@@ -1014,17 +1006,17 @@ lines.push(`**Implements:** ${sep.join(names)}`);
 
 ### Pushing RC struct fields into ArrayList does not need `.clone()`
 
-String (and other RC object) fields of structs can be passed directly to `ArrayList.push()`. Calling `.clone()` triggers an ambiguity error between `fn(self: String)` and `fn(self: *(String))` overloads.
+String (and other RC object) fields of structs can be passed directly to `ArrayList.push()` — the RC bump happens automatically:
 
 ```rust
-// ❌ Ambiguous clone call
-names.push(param.name.clone());
-
-// ✅ Push directly — RC bump happens automatically
 names.push(param.name);
 ```
 
-If explicit clone is needed elsewhere, use `(&field).clone()` to select the pointer overload.
+`.clone()` on String fields also works (`names.push(param.name.clone())`,
+`h.name.clone()` — verified 2026-06); the historical
+`fn(self: String)` vs `fn(self: *(String))` ambiguity error no longer
+reproduces. `x.clone()` is the idiomatic replacement for the retired
+`String.from(x.as_str())` roundtrip.
 
 ### `.Some(expr)` in expression position is parsed as a 2-arg property access
 
@@ -1144,13 +1136,13 @@ You cannot write `.Some(.IntLit(n))` — this is a parser error.
 ```rust
 // ❌ WRONG — nested enum pattern, parser error:
 match(v.get(usize(0)),
-  .Some(.IntLit(n)) => assert(n.as_str() == "3", "ok"),
+  .Some(.IntLit(n)) => assert(n == "3", "ok"),
   _ => assert(false, "err")
 )
 
 // ✅ CORRECT — two-level match:
 match(v.get(usize(0)),
-  .Some(x) => match(x, .IntLit(n) => assert(n.as_str() == "3", "ok"), _ => assert(false, "err")),
+  .Some(x) => match(x, .IntLit(n) => assert(n == "3", "ok"), _ => assert(false, "err")),
   .None => assert(false, "err")
 )
 ```