18c860c | plum

git clone https://git.pyrossh.dev/plum

A statically typed, imperative programming language inspired by rust, python

18c860c — Peter John 2026-07-24T07:42:28+05:30

docs: add implementation plan for wiring up List's methods

Files changed (1) hide show

docs/superpowers/plans/2026-07-24-list-methods.md +1155 -0

docs/superpowers/plans/2026-07-24-list-methods.md ADDED Viewed

@@ -0,0 +1,1155 @@
+# List Methods Implementation Plan
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+**Goal:** Wire up `libs/std/list.plum`'s remaining `todo` methods (`add`, `set`, `removeAt`, `remove`, `clear`, `reverse`) plus a rewritten `join`, using the mutable `Node`/`head`/`tail`/`size` design already in place.
+**Architecture:** Each method is implemented directly against the existing `Node(a)`/`List(a)` shapes using field assignment (`self.head = ...`, `node.next = ...`) and, for `add`, variadic iteration (`for v in values`). No type/grammar changes. Tests use small, self-contained inline fixtures (a minimal `Option`/`Node`/`List` trio plus whichever methods a test needs) — matching this project's established codegen-test convention — rather than depending on cross-file loading of the real `libs/std` files, which is a separate concern.
+**Tech Stack:** Rust, the existing `plum-checker`/`plum-wasm-codegen` pipeline. No new dependencies.
+## Global Constraints
+- Spec: `docs/superpowers/specs/2026-07-24-list-methods-design.md`
+- `add` appends to the tail (fixing the stale "to the start" doc comment); `reverse<List>(self) -> List` drops its predicate parameter.
+- Every fresh-empty-list construction (including the PRE-EXISTING `init<List>`/`map<List>` methods' bare `List()` calls) must use explicit fields: `List(head: None, tail: None, size: 0)` — bare `List()` leaves `head`/`tail` as zero-filled memory, which likely decodes as a garbage `Some(...)` rather than `None` (see spec's "Additional fix" section).
+- Default parameter values (`sep: Str = ","`) are parsed but NOT consulted at call sites for arity checking or substitution anywhere in the checker/codegen today (confirmed: no code path reads `Param.default` except monomorphization's structural clone) — this is a separate, un-scoped gap. Every test in this plan that calls a method with a defaulted param passes the argument explicitly; do not rely on omitting it.
+- Out of scope: `sort`, `find`, `contains`, `flatMap`, `retain`, `reject`, `any`, `every`, `reduce`, `sublist`, `take`, `skip`, `drop`, `sample`, `shuffle`, `partition`, `chunk`, `groupBy`, and anything in `Map`.
+- Run `cargo test --workspace` after every task — all pre-existing tests must keep passing throughout.
+---
+### Task 1: `add<List>` (+ fix `init`/`map`'s bare `List()`)
+**Files:**
+- Test: `plum-wasm-codegen/tests/codegen_tests.rs`
+- Modify: `libs/std/list.plum` (`init`, `add`, `map`)
+**Interfaces:**
+- Consumes: field assignment (`self.field = ...`, `obj.field = ...`), variadic `for v in values` iteration — both already implemented.
+- Produces: `add<List>(self, values: ...a)` — appends each value to the tail, in call order, updating `self.head`/`self.tail`/`self.size`. Later tasks' tests build lists via `add` (or via `List(head: None, tail: None, size: 0)` directly, as needed).
+This is the riskiest task in the plan: `add` constructs a `Node(a)` instance (a class literal for one generic class) *inside* a method of a *different* generic class (`List`'s own `add<List>`), with `List`'s type parameter needing to flow into `Node`'s specialization. No existing test covers this exact shape (existing generic tests cover a class's method reading its own field, or a generic function call chain, not nested generic-class construction across two classes). If the RED step below fails with something other than a straightforward "method not implemented" trap — e.g. a monomorphization error about `Node`'s type parameter, or a codegen panic — **stop and report BLOCKED** rather than trying to work around it; that would mean this plan's risk assessment was right and the controller needs to decide how to proceed (fix a compiler gap first, or reshape the approach), not something to paper over inside this task.
+- [ ] **Step 1: Write the failing test**
+Add to `plum-wasm-codegen/tests/codegen_tests.rs`:
+```rust
+#[test]
+fn list_add_appends_values_in_order_runs_correctly() {
+    let src = "\
+enum Option =
+  | Some(a)
+  | None
+type Node(a) =
+  value: a
+  prev: Option[Node]
+  next: Option[Node]
+type List(a) =
+  head: Option[Node]
+  tail: Option[Node]
+  size: Int
+get<List>(self, i: Int) -> Option(a) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          return Some(node.value)
+        current = node.next
+        index = index + 1
+      None =>
+        break
+  None
+length<List>(self) -> Int =
+  self.size
+add<List>(self, values: ...a) =
+  for v in values
+    newNode = Node(value: v, prev: self.tail, next: None)
+    match self.tail
+      Some(oldTail) =>
+        oldTail.next = Some(newNode)
+      None =>
+        self.head = Some(newNode)
+    self.tail = Some(newNode)
+    self.size = self.size + 1
+unwrapOr(o: Option, default: Int) -> Int =
+  match o
+    Some(v) => v
+    None => default
+main() -> Int =
+  l = List(head: None, tail: None, size: 0)
+  l.add(1, 2, 3)
+  a = unwrapOr(l.get(0), -1)
+  b = unwrapOr(l.get(1), -1)
+  c = unwrapOr(l.get(2), -1)
+  d = l.length()
+  a * 1000 + b * 100 + c * 10 + d
+";
+    let source = parse(src);
+    let bytes = compile_source(&source).expect("compile failed");
+    assert_eq!(run_main(&bytes), 1233);
+}
+```
+- [ ] **Step 2: Run the test to verify it fails**
+Run: `cargo test -p plum-wasm-codegen list_add_appends_values_in_order 2>&1 | tail -60`
+Expected: FAIL — `add`'s body in this inline test source already has the real implementation (Step 1 writes the test with the real `add` body directly in the test source, since this test doesn't depend on `libs/std/list.plum` at all), so this run is really the first real exercise of the nested-generic-construction risk described above. If it fails with a clear codegen/checker error about `Node`'s type resolution, that confirms the risk; if it fails only because you haven't run it yet (trivial), re-check you actually ran the command.
+- [ ] **Step 3: If it passes (or fails only for a benign reason), apply the same `add` implementation to `libs/std/list.plum`**
+In `libs/std/list.plum`, replace:
+```
+init<List>(self, values: ...a) -> List =
+  List().add(values)
+```
+with:
+```
+init<List>(self, values: ...a) -> List =
+  List(head: None, tail: None, size: 0).add(values)
+```
+Replace:
+```
+# adds the specified elements to the start of the list
+add<List>(self, values: ...a) =
+  todo
+```
+with:
+```
+# adds the specified elements to the end of the list
+add<List>(self, values: ...a) =
+  for v in values
+    newNode = Node(value: v, prev: self.tail, next: None)
+    match self.tail
+      Some(oldTail) =>
+        oldTail.next = Some(newNode)
+      None =>
+        self.head = Some(newNode)
+    self.tail = Some(newNode)
+    self.size = self.size + 1
+```
+And in `map<List>`, replace:
+```
+map<List>(self, cb: fn(a) -> b) -> List(b) =
+  nl = List()
+```
+with:
+```
+map<List>(self, cb: fn(a) -> b) -> List(b) =
+  nl = List(head: None, tail: None, size: 0)
+```
+(Leave the rest of `map`'s body unchanged.)
+- [ ] **Step 4: Run the test to verify it passes**
+Run: `cargo test -p plum-wasm-codegen list_add_appends_values_in_order 2>&1 | tail -60`
+Expected: PASS (`1233`).
+- [ ] **Step 5: Run the full workspace test suite**
+Run: `cargo test --workspace 2>&1 | tail -100`
+Expected: all tests PASS (no existing test compiles the real `libs/std/list.plum`, so the `init`/`add`/`map` edits there have no effect on the Rust test suite — this step exists to catch the unexpected case where something does reference it).
+- [ ] **Step 6: Commit**
+```bash
+git add plum-wasm-codegen/tests/codegen_tests.rs libs/std/list.plum
+git commit -m "feat(libs/std): implement List.add, fix List() zero-field construction in init/map"
+```
+---
+### Task 2: `set<List>`
+**Files:**
+- Test: `plum-wasm-codegen/tests/codegen_tests.rs`
+- Modify: `libs/std/list.plum` (`set`)
+**Interfaces:**
+- Consumes: `add<List>` (Task 1, for building test fixtures), field assignment on a match-bound local (`node.value = v`).
+- Produces: `set<List>(self, i: Int, v: a) -> Option(a)` — replaces the value at index `i`, returning the old value wrapped in `Some`, or `None` if `i` is out of range.
+- [ ] **Step 1: Write the failing tests**
+Add to `plum-wasm-codegen/tests/codegen_tests.rs` (reusing the same `Option`/`Node`/`List`/`get`/`length`/`add`/`unwrapOr` preamble as Task 1's test — repeated here in full since each test source is self-contained):
+```rust
+#[test]
+fn list_set_in_range_replaces_value_and_returns_old_runs_correctly() {
+    let src = "\
+enum Option =
+  | Some(a)
+  | None
+type Node(a) =
+  value: a
+  prev: Option[Node]
+  next: Option[Node]
+type List(a) =
+  head: Option[Node]
+  tail: Option[Node]
+  size: Int
+get<List>(self, i: Int) -> Option(a) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          return Some(node.value)
+        current = node.next
+        index = index + 1
+      None =>
+        break
+  None
+length<List>(self) -> Int =
+  self.size
+add<List>(self, values: ...a) =
+  for v in values
+    newNode = Node(value: v, prev: self.tail, next: None)
+    match self.tail
+      Some(oldTail) =>
+        oldTail.next = Some(newNode)
+      None =>
+        self.head = Some(newNode)
+    self.tail = Some(newNode)
+    self.size = self.size + 1
+set<List>(self, i: Int, v: a) -> Option(a) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          oldValue = node.value
+          node.value = v
+          return Some(oldValue)
+        current = node.next
+        index = index + 1
+      None =>
+        break
+  None
+unwrapOr(o: Option, default: Int) -> Int =
+  match o
+    Some(v) => v
+    None => default
+main() -> Int =
+  l = List(head: None, tail: None, size: 0)
+  l.add(1, 2, 3)
+  old = unwrapOr(l.set(1, 99), -1)
+  new = unwrapOr(l.get(1), -1)
+  old * 1000 + new
+";
+    let source = parse(src);
+    let bytes = compile_source(&source).expect("compile failed");
+    assert_eq!(run_main(&bytes), 2099);
+}
+#[test]
+fn list_set_out_of_range_returns_none_runs_correctly() {
+    let src = "\
+enum Option =
+  | Some(a)
+  | None
+type Node(a) =
+  value: a
+  prev: Option[Node]
+  next: Option[Node]
+type List(a) =
+  head: Option[Node]
+  tail: Option[Node]
+  size: Int
+length<List>(self) -> Int =
+  self.size
+add<List>(self, values: ...a) =
+  for v in values
+    newNode = Node(value: v, prev: self.tail, next: None)
+    match self.tail
+      Some(oldTail) =>
+        oldTail.next = Some(newNode)
+      None =>
+        self.head = Some(newNode)
+    self.tail = Some(newNode)
+    self.size = self.size + 1
+set<List>(self, i: Int, v: a) -> Option(a) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          oldValue = node.value
+          node.value = v
+          return Some(oldValue)
+        current = node.next
+        index = index + 1
+      None =>
+        break
+  None
+main() -> Int =
+  l = List(head: None, tail: None, size: 0)
+  l.add(1, 2, 3)
+  result = l.set(10, 99)
+  match result
+    Some(v) =>
+      1
+    None =>
+      0
+";
+    let source = parse(src);
+    let bytes = compile_source(&source).expect("compile failed");
+    assert_eq!(run_main(&bytes), 0);
+}
+```
+- [ ] **Step 2: Run the tests to verify they fail**
+Run: `cargo test -p plum-wasm-codegen list_set_ 2>&1 | tail -80`
+Expected: FAIL to compile (crate-internal `set`'s body is already written directly in the test source in Step 1, so this exercises the real implementation immediately — same reasoning as Task 1). If it fails for a reason other than "these tests don't exist yet before you add them," re-check.
+- [ ] **Step 3: Apply the same `set` implementation to `libs/std/list.plum`**
+Replace:
+```
+# sets the element at i'th index of the list
+set<List>(self, i: Int, v: a) -> Option(a) =
+  todo
+```
+with:
+```
+# sets the element at i'th index of the list
+set<List>(self, i: Int, v: a) -> Option(a) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          oldValue = node.value
+          node.value = v
+          return Some(oldValue)
+        current = node.next
+        index = index + 1
+      None =>
+        break
+  None
+```
+- [ ] **Step 4: Run the tests to verify they pass**
+Run: `cargo test -p plum-wasm-codegen list_set_ 2>&1 | tail -80`
+Expected: both PASS (`2099`, `0`).
+- [ ] **Step 5: Run the full workspace test suite**
+Run: `cargo test --workspace 2>&1 | tail -100`
+Expected: all tests PASS.
+- [ ] **Step 6: Commit**
+```bash
+git add plum-wasm-codegen/tests/codegen_tests.rs libs/std/list.plum
+git commit -m "feat(libs/std): implement List.set"
+```
+---
+### Task 3: `removeAt<List>` and `remove<List>`
+**Files:**
+- Test: `plum-wasm-codegen/tests/codegen_tests.rs`
+- Modify: `libs/std/list.plum` (`removeAt`, `remove`)
+**Interfaces:**
+- Consumes: `add<List>` (Task 1, for building test fixtures).
+- Produces: `removeAt<List>(self, i: Int)` and `remove<List>(self, v: a)` — both unlink the target node (by index / by value) from the doubly-linked chain, fixing up `self.head`/`self.tail`/neighboring `prev`/`next`, and decrement `self.size`. Both are a no-op if no matching node is found (no error), matching `get`'s existing out-of-range convention.
+- [ ] **Step 1: Write the failing tests**
+Add to `plum-wasm-codegen/tests/codegen_tests.rs`:
+```rust
+#[test]
+fn list_remove_at_head_updates_list_correctly() {
+    let src = "\
+enum Option =
+  | Some(a)
+  | None
+type Node(a) =
+  value: a
+  prev: Option[Node]
+  next: Option[Node]
+type List(a) =
+  head: Option[Node]
+  tail: Option[Node]
+  size: Int
+get<List>(self, i: Int) -> Option(a) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          return Some(node.value)
+        current = node.next
+        index = index + 1
+      None =>
+        break
+  None
+length<List>(self) -> Int =
+  self.size
+add<List>(self, values: ...a) =
+  for v in values
+    newNode = Node(value: v, prev: self.tail, next: None)
+    match self.tail
+      Some(oldTail) =>
+        oldTail.next = Some(newNode)
+      None =>
+        self.head = Some(newNode)
+    self.tail = Some(newNode)
+    self.size = self.size + 1
+removeAt<List>(self, i: Int) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          match node.prev
+            Some(p) =>
+              p.next = node.next
+            None =>
+              self.head = node.next
+          match node.next
+            Some(n) =>
+              n.prev = node.prev
+            None =>
+              self.tail = node.prev
+          self.size = self.size - 1
+          return
+        current = node.next
+        index = index + 1
+      None =>
+        break
+unwrapOr(o: Option, default: Int) -> Int =
+  match o
+    Some(v) => v
+    None => default
+main() -> Int =
+  l = List(head: None, tail: None, size: 0)
+  l.add(1, 2, 3)
+  l.removeAt(0)
+  a = unwrapOr(l.get(0), -1)
+  b = unwrapOr(l.get(1), -1)
+  c = l.length()
+  a * 100 + b * 10 + c
+";
+    let source = parse(src);
+    let bytes = compile_source(&source).expect("compile failed");
+    assert_eq!(run_main(&bytes), 232);
+}
+#[test]
+fn list_remove_at_tail_relinks_tail_pointer_correctly() {
+    let src = "\
+enum Option =
+  | Some(a)
+  | None
+type Node(a) =
+  value: a
+  prev: Option[Node]
+  next: Option[Node]
+type List(a) =
+  head: Option[Node]
+  tail: Option[Node]
+  size: Int
+get<List>(self, i: Int) -> Option(a) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          return Some(node.value)
+        current = node.next
+        index = index + 1
+      None =>
+        break
+  None
+length<List>(self) -> Int =
+  self.size
+add<List>(self, values: ...a) =
+  for v in values
+    newNode = Node(value: v, prev: self.tail, next: None)
+    match self.tail
+      Some(oldTail) =>
+        oldTail.next = Some(newNode)
+      None =>
+        self.head = Some(newNode)
+    self.tail = Some(newNode)
+    self.size = self.size + 1
+removeAt<List>(self, i: Int) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          match node.prev
+            Some(p) =>
+              p.next = node.next
+            None =>
+              self.head = node.next
+          match node.next
+            Some(n) =>
+              n.prev = node.prev
+            None =>
+              self.tail = node.prev
+          self.size = self.size - 1
+          return
+        current = node.next
+        index = index + 1
+      None =>
+        break
+unwrapOr(o: Option, default: Int) -> Int =
+  match o
+    Some(v) => v
+    None => default
+main() -> Int =
+  l = List(head: None, tail: None, size: 0)
+  l.add(1, 2, 3)
+  l.removeAt(2)
+  l.add(4)
+  a = unwrapOr(l.get(0), -1)
+  b = unwrapOr(l.get(1), -1)
+  c = unwrapOr(l.get(2), -1)
+  d = l.length()
+  a * 1000 + b * 100 + c * 10 + d
+";
+    let source = parse(src);
+    let bytes = compile_source(&source).expect("compile failed");
+    assert_eq!(run_main(&bytes), 1243);
+}
+#[test]
+fn list_remove_by_value_removes_middle_element_runs_correctly() {
+    let src = "\
+enum Option =
+  | Some(a)
+  | None
+type Node(a) =
+  value: a
+  prev: Option[Node]
+  next: Option[Node]
+type List(a) =
+  head: Option[Node]
+  tail: Option[Node]
+  size: Int
+get<List>(self, i: Int) -> Option(a) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          return Some(node.value)
+        current = node.next
+        index = index + 1
+      None =>
+        break
+  None
+length<List>(self) -> Int =
+  self.size
+add<List>(self, values: ...a) =
+  for v in values
+    newNode = Node(value: v, prev: self.tail, next: None)
+    match self.tail
+      Some(oldTail) =>
+        oldTail.next = Some(newNode)
+      None =>
+        self.head = Some(newNode)
+    self.tail = Some(newNode)
+    self.size = self.size + 1
+remove<List>(self, v: a) =
+  current = self.head
+  while current != None
+    match current
+      Some(node) =>
+        if node.value == v
+          match node.prev
+            Some(p) =>
+              p.next = node.next
+            None =>
+              self.head = node.next
+          match node.next
+            Some(n) =>
+              n.prev = node.prev
+            None =>
+              self.tail = node.prev
+          self.size = self.size - 1
+          return
+        current = node.next
+      None =>
+        break
+unwrapOr(o: Option, default: Int) -> Int =
+  match o
+    Some(v) => v
+    None => default
+main() -> Int =
+  l = List(head: None, tail: None, size: 0)
+  l.add(1, 2, 3)
+  l.remove(2)
+  a = unwrapOr(l.get(0), -1)
+  b = unwrapOr(l.get(1), -1)
+  c = l.length()
+  a * 100 + b * 10 + c
+";
+    let source = parse(src);
+    let bytes = compile_source(&source).expect("compile failed");
+    assert_eq!(run_main(&bytes), 132);
+}
+```
+- [ ] **Step 2: Run the tests to verify they fail**
+Run: `cargo test -p plum-wasm-codegen list_remove 2>&1 | tail -100`
+Expected: FAIL to compile (the tests don't exist before you add them; their bodies already contain the real implementation, matching Task 1/2's pattern).
+- [ ] **Step 3: Apply the same implementations to `libs/std/list.plum`**
+Replace:
+```
+# removes the element at i'th index of the list
+removeAt<List>(self, i: Int) =
+  todo
+```
+with:
+```
+# removes the element at i'th index of the list
+removeAt<List>(self, i: Int) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          match node.prev
+            Some(p) =>
+              p.next = node.next
+            None =>
+              self.head = node.next
+          match node.next
+            Some(n) =>
+              n.prev = node.prev
+            None =>
+              self.tail = node.prev
+          self.size = self.size - 1
+          return
+        current = node.next
+        index = index + 1
+      None =>
+        break
+```
+Replace:
+```
+# removes the element v from list
+remove<List>(self, v: a) =
+  todo
+```
+with:
+```
+# removes the element v from list
+remove<List>(self, v: a) =
+  current = self.head
+  while current != None
+    match current
+      Some(node) =>
+        if node.value == v
+          match node.prev
+            Some(p) =>
+              p.next = node.next
+            None =>
+              self.head = node.next
+          match node.next
+            Some(n) =>
+              n.prev = node.prev
+            None =>
+              self.tail = node.prev
+          self.size = self.size - 1
+          return
+        current = node.next
+      None =>
+        break
+```
+- [ ] **Step 4: Run the tests to verify they pass**
+Run: `cargo test -p plum-wasm-codegen list_remove 2>&1 | tail -100`
+Expected: all 3 PASS (`232`, `1243`, `132`).
+- [ ] **Step 5: Run the full workspace test suite**
+Run: `cargo test --workspace 2>&1 | tail -100`
+Expected: all tests PASS.
+- [ ] **Step 6: Commit**
+```bash
+git add plum-wasm-codegen/tests/codegen_tests.rs libs/std/list.plum
+git commit -m "feat(libs/std): implement List.removeAt and List.remove"
+```
+---
+### Task 4: `clear<List>` and `reverse<List>`
+**Files:**
+- Test: `plum-wasm-codegen/tests/codegen_tests.rs`
+- Modify: `libs/std/list.plum` (`clear`, `reverse`)
+**Interfaces:**
+- Consumes: `add<List>` (Task 1).
+- Produces: `clear<List>(self)` — resets `head`/`tail` to `None`, `size` to `0`. `reverse<List>(self) -> List` (predicate parameter dropped, per the spec) — returns a NEW list with elements in reverse order, built via `add`, leaving `self` unmodified.
+- [ ] **Step 1: Write the failing tests**
+Add to `plum-wasm-codegen/tests/codegen_tests.rs`:
+```rust
+#[test]
+fn list_clear_resets_list_to_empty_runs_correctly() {
+    let src = "\
+enum Option =
+  | Some(a)
+  | None
+type Node(a) =
+  value: a
+  prev: Option[Node]
+  next: Option[Node]
+type List(a) =
+  head: Option[Node]
+  tail: Option[Node]
+  size: Int
+get<List>(self, i: Int) -> Option(a) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          return Some(node.value)
+        current = node.next
+        index = index + 1
+      None =>
+        break
+  None
+length<List>(self) -> Int =
+  self.size
+add<List>(self, values: ...a) =
+  for v in values
+    newNode = Node(value: v, prev: self.tail, next: None)
+    match self.tail
+      Some(oldTail) =>
+        oldTail.next = Some(newNode)
+      None =>
+        self.head = Some(newNode)
+    self.tail = Some(newNode)
+    self.size = self.size + 1
+clear<List>(self) =
+  self.head = None
+  self.tail = None
+  self.size = 0
+unwrapOr(o: Option, default: Int) -> Int =
+  match o
+    Some(v) => v
+    None => default
+main() -> Int =
+  l = List(head: None, tail: None, size: 0)
+  l.add(1, 2, 3)
+  l.clear()
+  a = l.length()
+  b = unwrapOr(l.get(0), -1)
+  a * 100 + b
+";
+    let source = parse(src);
+    let bytes = compile_source(&source).expect("compile failed");
+    assert_eq!(run_main(&bytes), -1);
+}
+#[test]
+fn list_reverse_returns_new_reversed_list_and_leaves_original_unchanged() {
+    let src = "\
+enum Option =
+  | Some(a)
+  | None
+type Node(a) =
+  value: a
+  prev: Option[Node]
+  next: Option[Node]
+type List(a) =
+  head: Option[Node]
+  tail: Option[Node]
+  size: Int
+get<List>(self, i: Int) -> Option(a) =
+  current = self.head
+  index = 0
+  while current != None
+    match current
+      Some(node) =>
+        if index == i
+          return Some(node.value)
+        current = node.next
+        index = index + 1
+      None =>
+        break
+  None
+length<List>(self) -> Int =
+  self.size
+add<List>(self, values: ...a) =
+  for v in values
+    newNode = Node(value: v, prev: self.tail, next: None)
+    match self.tail
+      Some(oldTail) =>
+        oldTail.next = Some(newNode)
+      None =>
+        self.head = Some(newNode)
+    self.tail = Some(newNode)
+    self.size = self.size + 1
+reverse<List>(self) -> List =
+  nl = List(head: None, tail: None, size: 0)
+  current = self.tail
+  while current != None
+    match current
+      Some(node) =>
+        nl.add(node.value)
+        current = node.prev
+      None =>
+        break
+  nl
+unwrapOr(o: Option, default: Int) -> Int =
+  match o
+    Some(v) => v
+    None => default
+main() -> Int =
+  l = List(head: None, tail: None, size: 0)
+  l.add(1, 2, 3)
+  r = l.reverse()
+  ra = unwrapOr(r.get(0), -1)
+  rb = unwrapOr(r.get(1), -1)
+  rc = unwrapOr(r.get(2), -1)
+  rlen = r.length()
+  oa = unwrapOr(l.get(0), -1)
+  olen = l.length()
+  ra * 100000 + rb * 10000 + rc * 1000 + rlen * 100 + oa * 10 + olen
+";
+    let source = parse(src);
+    let bytes = compile_source(&source).expect("compile failed");
+    assert_eq!(run_main(&bytes), 321313);
+}
+```
+- [ ] **Step 2: Run the tests to verify they fail**
+Run: `cargo test -p plum-wasm-codegen list_clear list_reverse 2>&1 | tail -80`
+Expected: FAIL to compile (tests don't exist yet).
+- [ ] **Step 3: Apply the same implementations to `libs/std/list.plum`**
+Replace:
+```
+# removes all objects from this list
+clear<List>(self) =
+  todo
+```
+with:
+```
+# removes all objects from this list
+clear<List>(self) =
+  self.head = None
+  self.tail = None
+  self.size = 0
+```
+Replace:
+```
+# returns a new list with the elements in reverse order.
+reverse<List>(self, v: fn(a) -> Bool) -> List =
+  todo
+```
+with:
+```
+# returns a new list with the elements in reverse order.
+reverse<List>(self) -> List =
+  nl = List(head: None, tail: None, size: 0)
+  current = self.tail
+  while current != None
+    match current
+      Some(node) =>
+        nl.add(node.value)
+        current = node.prev
+      None =>
+        break
+  nl
+```
+- [ ] **Step 4: Run the tests to verify they pass**
+Run: `cargo test -p plum-wasm-codegen list_clear list_reverse 2>&1 | tail -80`
+Expected: both PASS (`-1`, `321313`).
+- [ ] **Step 5: Run the full workspace test suite**
+Run: `cargo test --workspace 2>&1 | tail -100`
+Expected: all tests PASS.
+- [ ] **Step 6: Commit**
+```bash
+git add plum-wasm-codegen/tests/codegen_tests.rs libs/std/list.plum
+git commit -m "feat(libs/std): implement List.clear and List.reverse"
+```
+---
+### Task 5: `join<List>` (rewritten, no `Buffer`)
+**Files:**
+- Test: `plum-wasm-codegen/tests/codegen_tests.rs`
+- Modify: `libs/std/list.plum` (`join`)
+**Interfaces:**
+- Consumes: `add<List>` (Task 1); the existing `run_main_str` test helper (already defined in `plum-wasm-codegen/tests/codegen_tests.rs`, used elsewhere in this file to read a `Str`-returning `main`'s result).
+- Produces: `join<List>(self, sep: Str = ",") -> Str` — concatenates each element's `Str` interpolation with `sep` after it (including after the last element — this matches the ORIGINAL `Buffer`-based version's existing behavior of always appending a trailing separator, not a regression).
+- [ ] **Step 1: Write the failing test**
+Add to `plum-wasm-codegen/tests/codegen_tests.rs`:
+```rust
+#[test]
+fn list_join_concatenates_elements_with_separator_runs_correctly() {
+    let src = "\
+enum Option =
+  | Some(a)
+  | None
+type Node(a) =
+  value: a
+  prev: Option[Node]
+  next: Option[Node]
+type List(a) =
+  head: Option[Node]
+  tail: Option[Node]
+  size: Int
+add<List>(self, values: ...a) =
+  for v in values
+    newNode = Node(value: v, prev: self.tail, next: None)
+    match self.tail
+      Some(oldTail) =>
+        oldTail.next = Some(newNode)
+      None =>
+        self.head = Some(newNode)
+    self.tail = Some(newNode)
+    self.size = self.size + 1
+join<List>(self, sep: Str) -> Str =
+  result = \"\"
+  current = self.head
+  while current != None
+    match current
+      Some(node) =>
+        result = \"{result}{node.value}{sep}\"
+        current = node.next
+      None =>
+        break
+  result
+main() -> Str =
+  l = List(head: None, tail: None, size: 0)
+  l.add(1, 2, 3)
+  l.join(\",\")
+";
+    let source = parse(src);
+    let bytes = compile_source(&source).expect("compile failed");
+    assert_eq!(run_main_str(&bytes), "1,2,3,");
+}
+```
+(Note: this test declares `join<List>(self, sep: Str) -> Str` — no default value on `sep` — and always passes the separator explicitly at the call site, per this plan's Global Constraints: default parameter values aren't consulted at call sites anywhere in the checker/codegen today, so a test relying on omitting `sep` would fail for that unrelated, out-of-scope reason. `libs/std/list.plum`'s own declaration keeps its existing `sep: Str = ","` default in the signature — the default annotation is harmless to leave in place since nothing reads it, it's just never *usable* at a call site yet, which is not new or introduced by this task.)
+- [ ] **Step 2: Run the test to verify it fails**
+Run: `cargo test -p plum-wasm-codegen list_join_concatenates 2>&1 | tail -60`
+Expected: FAIL to compile (test doesn't exist yet).
+- [ ] **Step 3: Apply the same implementation to `libs/std/list.plum`**
+Replace:
+```
+join<List>(self, sep: Str = ",") -> Str =
+  res = Buffer()
+  self.each(|v|
+    res.write(v.toStr())
+    res.write(sep)
+  )
+  res.toStr()
+```
+with:
+```
+join<List>(self, sep: Str = ",") -> Str =
+  result = ""
+  current = self.head
+  while current != None
+    match current
+      Some(node) =>
+        result = "{result}{node.value}{sep}"
+        current = node.next
+      None =>
+        break
+  result
+```
+- [ ] **Step 4: Run the test to verify it passes**
+Run: `cargo test -p plum-wasm-codegen list_join_concatenates 2>&1 | tail -60`
+Expected: PASS (`"1,2,3,"`).
+- [ ] **Step 5: Run the full workspace test suite**
+Run: `cargo test --workspace 2>&1 | tail -100`
+Expected: all tests PASS.
+- [ ] **Step 6: Commit**
+```bash
+git add plum-wasm-codegen/tests/codegen_tests.rs libs/std/list.plum
+git commit -m "feat(libs/std): rewrite List.join using string interpolation instead of Buffer"
+```
+---
+### Task 6: README — close the gap
+**Files:**
+- Modify: `README.md` (the "Known gaps" section)
+**Interfaces:**
+- Consumes: nothing.
+- Produces: nothing (docs only).
+- [ ] **Step 1: Update the Known gaps bullet**
+Run: `grep -n "List" README.md` to find the current bullet, which reads along the lines of:
+```
+- `libs/std`'s actual `List`/`Map` still don't fully compile — cross-file `import` resolution now works (`import <path>` resolves against `--lib-path`, defaulting to `./libs`), and variadic parameters work, but `List`'s methods beyond `get`/`length` (`add`, `set`, `removeAt`, `remove`, `clear`, `reverse`) are still `todo`; separately, `List`'s own `join` method (and `Map`) reference a `Buffer` type and trait-bounded dispatch (`Stringable`) that don't exist yet — `plum-checker` doesn't process trait declarations at all currently
+```
+Replace it with:
+```
+- `libs/std/map.plum`'s `Map` still doesn't fully compile — it references a `Buffer` type that doesn't exist and relies on trait-bounded dispatch (`Stringable`) that `plum-checker` doesn't process at all currently. `List` (`libs/std/list.plum`) is otherwise fully wired up: `get`, `length`, `each`, `map`, `first`, `last`, `add`, `set`, `removeAt`, `remove`, `clear`, `reverse`, and `join` all compile and run (`join` was rewritten to use string interpolation instead of `Buffer`). `List`'s remaining extras (`sort`, `find`, `flatMap`, `retain`, and similar) are still `todo` — a much longer tail that was never part of this gap's original scope.
+```
+- [ ] **Step 2: Commit**
+```bash
+git add README.md
+git commit -m "docs: List's core methods are wired up; Map remains blocked on Buffer/traits"
+```