feat: teach numpy view/copy on the canvas (curriculum phase 1)

Add the numpy series. An ndarray is a window over a separate buffer box, so
.copy() mints a new buffer, a slice is a view that shares the buffer, a + 1
vectorizes into a new buffer, and .sum() folds the buffer to a scalar. New
isNdarray / sharesBuffer / independentBuffer predicates and a 5-level series.

Also, as part of this increment:
- split the level catalog into per-series modules under src/levels/
- tag every level with an ELI band and make the level tests invariant-based
- add the RAM-view data model (addr / byteSize / refCount / seg) to heap objects

Author: alisadeghiaghili

README.md

@@ -41,7 +41,7 @@ Type Python-subset statements. Meta-commands:
 | Command | Effect |
 |---------|--------|
 | `help` | subset + meta overview |
-| `levels` | list the 35 levels / 9 series |
+| `levels` | list the 40 levels / 10 series |
 | `level <id>` | load a level (e.g. `level first-name`) |
 | `lesson` | open the current level's lesson text |
 | `goal` / `guide` | focus the right-hand guide panel |
@@ -63,22 +63,23 @@ A deliberately small, pedagogically sharp subset — not CPython:
 - **Methods:** `.append` `.insert` `.extend` `.pop` `.remove` `.copy` `.get` `.update` `.keys` `.clear`
 - **Functions:** `def` / call / `return`, local frames, nested calls
 - **Builtins:** `print` `len` `type` `id` `str` `int` `bool` `list` `dict` `set`
-- **Modules:** `import copy as cp` — `cp.copy` (shallow) and `cp.deepcopy`; `import collections as c` — `c.defaultdict`; `import functools as f` — `f.reduce`
+- **Modules:** `import copy as cp` — `cp.copy` (shallow) and `cp.deepcopy`; `import collections as c` — `c.defaultdict`; `import functools as f` — `f.reduce`; `import numpy as np` — `np.array`, `.copy()`, slicing (views), `+`, `.sum()`
 - **Iterators:** `iter(x)` and `next(it)` — a stateful iterator object you advance by hand
 - **Functional:** `map(fn, it)` / `filter(pred, it)` — lazy iterator objects; `f.reduce(fn, it)` — an eager fold
+- **NumPy:** `np.array` → an ndarray *window* over a separate **buffer** box; `.copy()` mints a new buffer; a slice is a *view* sharing the same buffer; `a + 1` vectorizes into a new buffer; `a.sum()` folds to a scalar
 - **Plotting:** `scatter(xs, ys, "title")` `line(xs, ys, "title")`
 - **Operators:** arithmetic, comparisons, `is`, `==`
 
-Not in v0: classes, real module imports (only the simulated `copy`, `collections`, `functools`), control flow (`if`/`for`/`while`), exceptions (beyond clean parse/runtime errors), comprehensions, I/O, async, `range`/`sorted`/`min`/`max`, full CPython semantics.
+Not in v0: classes, real module imports (only the simulated `copy`, `collections`, `functools`, `numpy`), control flow (`if`/`for`/`while`), exceptions (beyond clean parse/runtime errors), comprehensions, I/O, async, `range`/`sorted`/`min`/`max`, full CPython semantics.
 
-A planned curriculum extends this with numpy, pandas, re, datetime and more — all drawn on the same memory canvas. See `docs/ENGINE-EXTENSION.md` and `docs/adr/002-library-modules.md`.
+A planned curriculum extends this with pandas, re, datetime and more — all drawn on the same memory canvas. See `docs/ENGINE-EXTENSION.md` and `docs/adr/002-library-modules.md`.
 
 ## Architecture
 
 ```
 src/engine/    simulated runtime (tokenizer, parser, evaluator, memory, session)
                + goal checks (checks.ts) — the "TreeCompare" analogue
-src/levels/    9-series / 35-level catalog + per-level goals, par, solutions
+src/levels/    10-series / 40-level catalog + per-level goals, par, solutions
 src/ui/        app shell, memory canvas, plot board, REPL, dialog, script editor
 src/style.css  design tokens + layout
 tests/         vitest unit + level-solution tests
@@ -90,7 +91,7 @@ The engine is intentionally a **teaching subset**, not CPython. Every state tran
 
 ## Levels
 
-Nine series — Names & Bindings, Aliasing & Copy, Containers in Memory, **Copy Semantics** (shallow vs deep), **Iterators & Iterables**, **Defaults & Functional** (defaultdict, map, filter), Mutation & Methods, Functions & Frames, Plotting & Capstone. Each of the 35 levels has a brief, optional hint, a goal (predicate or target snapshot), a statement-par for golf, and a worked solution.
+Ten series — Names & Bindings, Aliasing & Copy, Containers in Memory, **Copy Semantics** (shallow vs deep), **Iterators & Iterables**, **Defaults & Functional** (defaultdict, map, filter), **NumPy: Buffers & Views** (ndarray, buffer, `.copy()`, slice-as-view), Mutation & Methods, Functions & Frames, Plotting & Capstone. Each of the 40 levels has a brief, optional hint, a goal (predicate or target snapshot), a statement-par for golf, and a worked solution.
 
 ## Tech
 

docs/ENGINE-EXTENSION.md

@@ -165,7 +165,7 @@ Every library `L` is built by filling this contract:
 | Library | `type` | `value` shape | Canvas box |
 |---------|--------|---------------|------------|
 | `copy` | *(none — reuses list/dict)* | — | *(existing)* |
-| `numpy` | `ndarray` | `{ buffer: id, shape, dtype, view?: bool }` | ndarray box → buffer box (grid) |
+| `numpy` | `ndarray` / `buffer` | ndarray `{ buffer: id, offset, shape, dtype, view }` → buffer `{ data: number[], dtype }` | ndarray box → buffer box; a slice shares the buffer (view), `.copy()` mints a new one |
 | `pandas` | `Series` / `DataFrame` | `{ buffer: id, index, columns?, dtype }` | box → buffer; DF shows column headers |
 | `beautifulsoup` | `DomNode` | `{ tag, children: id[] }` | **heap tree** (parent→child edges) |
 | `re` | `Pattern` / `Match` | `{ source }` / `{ span, groups: id[] }` | box + group chips |

src/engine/checks.ts

@@ -233,6 +233,38 @@ export const preds = {
     };
   },
 
+  /** `name` is a numpy ndarray. */
+  isNdarray(name: string) {
+    return (snapshot: Snapshot, _runtime: MemoryState): boolean | string => {
+      const view = slotView(name, snapshot);
+      return view?.type === 'ndarray' ? true : `'${name}' is not an ndarray.`;
+    };
+  },
+
+  /**
+   * Two ndarrays point at the SAME buffer (a view shares its source's buffer).
+   */
+  sharesBuffer(name: string, other: string) {
+    return (snapshot: Snapshot, _runtime: MemoryState): boolean | string => {
+      const a = ndarrayBufferId(name, snapshot);
+      const b = ndarrayBufferId(other, snapshot);
+      if (a === null || b === null) return `Bind both '${name}' and '${other}' as ndarrays.`;
+      return a === b;
+    };
+  },
+
+  /**
+   * Two ndarrays point at DIFFERENT buffers (an independent copy).
+   */
+  independentBuffer(name: string, other: string) {
+    return (snapshot: Snapshot, _runtime: MemoryState): boolean | string => {
+      const a = ndarrayBufferId(name, snapshot);
+      const b = ndarrayBufferId(other, snapshot);
+      if (a === null || b === null) return `Bind both '${name}' and '${other}' as ndarrays.`;
+      return a !== b;
+    };
+  },
+
   /**
    * A plot has been drawn (optionally of a specific kind).
    */
@@ -303,6 +335,18 @@ export const preds = {
   },
 };
 
+/** Read an ndarray's normalized `buffer` id from the snapshot, or null. */
+function ndarrayBufferId(name: string, snapshot: Snapshot): string | null {
+  const module = snapshot.frames[snapshot.frames.length - 1];
+  if (!module) return null;
+  const id = module.locals[name];
+  if (typeof id !== 'string' || !snapshot.heap[id]) return null;
+  const obj = snapshot.heap[id];
+  if (obj.type !== 'ndarray') return null;
+  const v = obj.value as { buffer?: unknown };
+  return typeof v.buffer === 'string' ? v.buffer : null;
+}
+
 /** Read an iterator's `{ source, index }` from the normalized snapshot. */
 function iteratorValue(name: string, snapshot: Snapshot): { source: string; index: number } | null {
   const module = snapshot.frames[snapshot.frames.length - 1];

src/engine/evaluator.ts

@@ -4,7 +4,7 @@
  * Mutates a memory state (frames + heap) and records stdout / errors.
  */
 
-import { allocObject, cloneState, createModuleState } from './memory';
+import { allocObject, cloneState, computeRefCounts, createModuleState } from './memory';
 import { parse } from './parser';
 import type {
   AstNode,
@@ -30,6 +30,8 @@ export function run(source: string, state: MemoryState): MemoryState {
     // leaving a parent container's cached repr stale. Recompute container
     // reprs so display, print, and goal checks all see the current value.
     refreshReprs(state);
+    // Recompute the refcount column for the RAM view from the now-final graph.
+    computeRefCounts(state);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     state.errors.push(message);
@@ -47,6 +49,21 @@ function refreshReprs(state: MemoryState): void {
     if (obj.type === 'list' || obj.type === 'dict' || obj.type === 'tuple' || obj.type === 'set' || obj.type === 'defaultdict') {
       obj.repr = formatObject(obj, state);
     }
+    if (obj.type === 'ndarray') {
+      obj.repr = numpyRepr(ndarrayWindow(obj.id, state));
+    }
+  }
+}
+
+/**
+ * Recompute the cached repr of every ndarray window AND its buffer after a
+ * buffer write, so a mutation through one window is visible through every
+ * other window (the whole point of a view).
+ */
+function refreshNdarrayReprs(state: MemoryState): void {
+  for (const obj of Object.values(state.heap)) {
+    if (obj.type === 'ndarray') obj.repr = numpyRepr(ndarrayWindow(obj.id, state));
+    if (obj.type === 'buffer') obj.repr = `[${(obj.value as NumpyBufferValue).data.join(', ')}]`;
   }
 }
 
@@ -162,6 +179,17 @@ function bindTarget(target: AstNode, value: RtValue, state: MemoryState): void {
       obj.repr = formatObject(obj, state);
       return;
     }
+    if (obj.type === 'ndarray') {
+      const v = obj.value as NdarrayValue;
+      const n = Number(value);
+      if (Number.isNaN(n)) throw new Error(`TypeError: cannot assign non-number to ndarray (line 0)`);
+      const i = index as number;
+      const data = (state.heap[v.buffer].value as NumpyBufferValue).data;
+      data[v.offset + i] = n;
+      // A buffer write is seen by every ndarray window over it — refresh them all.
+      refreshNdarrayReprs(state);
+      return;
+    }
     if (obj.type === 'dict' || obj.type === 'defaultdict') {
       const keyRepr = dictKeyRepr(index, state);
       const entries = dictEntries(obj);
@@ -444,6 +472,17 @@ function callMethod(objId: RtValue, method: string, args: RtValue[], state: Memo
     throw new Error(`AttributeError: module 'copy' has no attribute '${method}' (line ${line})`);
   }
 
+  if (obj.type === 'module' && (obj.value as { name: string }).name === 'numpy') {
+    if (method === 'array') return makeNdarray(args, state, line);
+    throw new Error(`AttributeError: module 'numpy' has no attribute '${method}' (line ${line})`);
+  }
+
+  if (obj.type === 'ndarray') {
+    if (method === 'copy') return copyNdarray(objId as string, state, line);
+    if (method === 'sum') return ndarraySum(objId as string, state, line);
+    throw new Error(`AttributeError: 'ndarray' object has no attribute '${method}' (line ${line})`);
+  }
+
   if (obj.type === 'list') {
     const value = obj.value as RtValue[];
     if (method === 'append') {
@@ -849,6 +888,123 @@ function reduce(args: RtValue[], state: MemoryState, line: number): RtValue {
   }
 }
 
+/**
+ * A numpy buffer's payload: a flat run of numbers. Rendered as a separate
+ * box on the canvas so a view-vs-copy distinction becomes visible — the
+ * ndarray points at a buffer, and a copy mints a *second* buffer.
+ */
+interface NumpyBufferValue {
+  data: number[];
+  dtype: string;
+}
+
+/**
+ * An ndarray's payload: a *window* onto a buffer. `buffer` is the id of the
+ * heap buffer box; `offset` + `shape` carve the view's slice out of that
+ * buffer's flat run. `view` is true when this window is not the buffer's full
+ * extent (i.e. it is a slice) and false when it owns its own full buffer.
+ */
+interface NdarrayValue {
+  buffer: string;
+  offset: number;
+  shape: number;
+  dtype: string;
+  view: boolean;
+}
+
+/** numpy-style repr of a number run: `[1. 2. 3.]` (float-ish, trailing dot). */
+function numpyRepr(data: number[]): string {
+  const body = data.map((n) => (Number.isInteger(n) ? `${n}.` : String(n)));
+  return `[${body.join(' ')}]`;
+}
+
+/** The numeric window an ndarray currently shows (offset+shape over buffer). */
+function ndarrayWindow(ndId: string, state: MemoryState): number[] {
+  const v = state.heap[ndId].value as NdarrayValue;
+  const data = (state.heap[v.buffer].value as NumpyBufferValue).data;
+  return data.slice(v.offset, v.offset + v.shape);
+}
+
+/** Allocate a buffer object holding a flat numeric run. */
+function makeBuffer(data: number[], dtype: string, state: MemoryState): string {
+  const obj = allocObject('buffer', { data, dtype } as NumpyBufferValue, `[${data.join(', ')}]`);
+  state.heap[obj.id] = obj;
+  return obj.id;
+}
+
+/**
+ * `np.array([...])` → a fresh buffer + an ndarray that owns its full buffer.
+ */
+function makeNdarray(args: RtValue[], state: MemoryState, line: number): RtValue {
+  if (args.length !== 1) throw new Error(`TypeError: array() takes exactly one argument (line ${line})`);
+  const data = readNumberSeries(args[0], state);
+  const bufId = makeBuffer(data, 'float64', state);
+  const obj = allocObject('ndarray', { buffer: bufId, offset: 0, shape: data.length, dtype: 'float64', view: false } as NdarrayValue, '');
+  state.heap[obj.id] = obj;
+  obj.repr = numpyRepr(data);
+  return obj.id;
+}
+
+/**
+ * `a.copy()` → a new buffer holding the array's current window. The new
+ * buffer is fully independent: mutating one is invisible to the other.
+ */
+function copyNdarray(ndId: string, state: MemoryState, line: number): RtValue {
+  const nd = state.heap[ndId];
+  if (!nd || nd.type !== 'ndarray') throw new Error(`TypeError: ${typeName(ndId, state)} has no .copy() (line ${line})`);
+  const data = ndarrayWindow(ndId, state);
+  const bufId = makeBuffer([...data], (nd.value as NdarrayValue).dtype, state);
+  const obj = allocObject('ndarray', { buffer: bufId, offset: 0, shape: data.length, dtype: 'float64', view: false } as NdarrayValue, '');
+  state.heap[obj.id] = obj;
+  obj.repr = numpyRepr(data);
+  return obj.id;
+}
+
+/**
+ * `a[start:stop]` → a *view*: a new ndarray window onto the SAME buffer. This
+ * is the flagship identity idea — slicing does not copy the data, it makes a
+ * second window onto it. Writing through the view edits the shared buffer.
+ */
+function ndarraySlice(ndId: string, start: RtValue, stop: RtValue, state: MemoryState, line: number): RtValue {
+  const nd = state.heap[ndId];
+  if (!nd || nd.type !== 'ndarray') throw new Error(`TypeError: ${typeName(ndId, state)} is not sliceable (line ${line})`);
+  const v = nd.value as NdarrayValue;
+  const full = (state.heap[v.buffer].value as NumpyBufferValue).data;
+  const s = start === null ? 0 : Number(start);
+  const e = stop === null ? v.shape : Number(stop);
+  const offset = v.offset + s;
+  const shape = Math.max(0, e - s);
+  const obj = allocObject('ndarray', { buffer: v.buffer, offset, shape, dtype: v.dtype, view: true } as NdarrayValue, '');
+  state.heap[obj.id] = obj;
+  obj.repr = numpyRepr(full.slice(offset, offset + shape));
+  void line;
+  return obj.id;
+}
+
+/**
+ * `a + scalar` (vectorized) → a brand-new buffer holding the element-wise
+ * result. The operand is read; a new buffer is minted for the result.
+ */
+function vecAdd(left: RtValue, right: RtValue, state: MemoryState, line: number): RtValue {
+  const a = state.heap[left as string];
+  if (!a || a.type !== 'ndarray') throw new Error(`TypeError: unsupported operand (line ${line})`);
+  const b = Number(right);
+  if (Number.isNaN(b)) throw new Error(`TypeError: cannot add ${typeName(right, state)} to ndarray (line ${line})`);
+  const data = ndarrayWindow(left as string, state).map((n) => n + b);
+  const bufId = makeBuffer(data, 'float64', state);
+  const obj = allocObject('ndarray', { buffer: bufId, offset: 0, shape: data.length, dtype: 'float64', view: false } as NdarrayValue, '');
+  state.heap[obj.id] = obj;
+  obj.repr = numpyRepr(data);
+  return obj.id;
+}
+
+/** `a.sum()` → fold the array's window into a scalar. */
+function ndarraySum(ndId: string, state: MemoryState, line: number): RtValue {
+  const nd = state.heap[ndId];
+  if (!nd || nd.type !== 'ndarray') throw new Error(`TypeError: ${typeName(ndId, state)} has no .sum() (line ${line})`);
+  return ndarrayWindow(ndId, state).reduce((acc, n) => acc + n, 0);
+}
+
 /**
  * Python-style string repr using single quotes.
  */
@@ -917,6 +1073,7 @@ function lengthOf(v: RtValue, state: MemoryState): number {
     const obj = state.heap[v];
     if (['list', 'tuple', 'set', 'dict'].includes(obj.type)) return (obj.value as unknown[]).length;
     if (obj.type === 'defaultdict') return dictEntries(obj).length;
+    if (obj.type === 'ndarray') return (obj.value as NdarrayValue).shape;
     if (obj.type === 'str') return (obj.value as string).length;
   }
   if (typeof v === 'string') return v.length;
@@ -963,6 +1120,15 @@ function binOp(op: string, left: RtValue, right: RtValue, state: MemoryState, li
   // string concatenation
   const lt = typeName(left, state);
   const rt = typeName(right, state);
+
+  // vectorized ndarray + scalar → a fresh buffer
+  if (op === '+' && (lt === 'ndarray' || rt === 'ndarray')) {
+    const scalar = lt === 'ndarray' ? right : left;
+    const arr = lt === 'ndarray' ? left : right;
+    if (typeof scalar !== 'number') throw new Error(`TypeError: unsupported operand for + (line ${line})`);
+    return vecAdd(arr, scalar, state, line);
+  }
+
   if (op === '+' && lt === 'str' && rt === 'str') {
     const lv = state.heap[left as string].value as string;
     const rv = state.heap[right as string].value as string;
@@ -1049,6 +1215,13 @@ function subscriptGet(objId: RtValue, index: RtValue, state: MemoryState, line:
     }
     return value[idx];
   }
+  if (obj.type === 'ndarray') {
+    const v = obj.value as NdarrayValue;
+    const i = Number(index);
+    const idx = i < 0 ? v.shape + i : i;
+    if (idx < 0 || idx >= v.shape) throw new Error(`IndexError: index out of range (line ${line})`);
+    return (state.heap[v.buffer].value as NumpyBufferValue).data[v.offset + idx]!;
+  }
   if (obj.type === 'dict' || obj.type === 'defaultdict') {
     const keyRepr = dictKeyRepr(index, state);
     const entries = dictEntries(obj);
@@ -1086,6 +1259,9 @@ function sliceGet(objId: RtValue, start: RtValue, stop: RtValue, state: MemorySt
     out.repr = formatObject(out, state);
     return out.id;
   }
+  if (obj.type === 'ndarray') {
+    return ndarraySlice(objId as string, start, stop, state, line);
+  }
   if (obj.type === 'str') {
     return allocString((obj.value as string).slice(s, e), state);
   }