# Cursor Cells: columnar calculation and P2P exchange

Status: **SHIPPED** Cells IR, deterministic JS evaluator, dependency planner, typed column chunks, SQLite schema/transaction contract, Linda executor advertisements, and exchange-only Cap’n Web/WebRTC capability. **EXPERIMENTAL** Worker capability pool and Nelua/Wasm accelerator. **PLANNED** Univer UI, browser Worker lifecycle, SQLite Worker persistence, Blockly/Lua authoring, and attenuated peer compute.

```text
Excel-like formula ─┐
restricted Lua ─────┼─▶ Cells IR v0 ─▶ dependency levels ─▶ column chunks
Blockly metadata ───┘                         │
                                  SIMD Wasm / scalar Wasm / JS
                                              │
                        local Workers ────────┴────── peer cache candidates
                                              │
                SQLite transaction + outbox ◀─┴─▶ Cap'n Web / WebRTC
                                              │
                      Linda leased executor discovery (no authority implied)
```

## Formula safety

The formula parser accepts literals, cells, ranges, arithmetic/comparison operators, conditionals, and an allowlist of aggregate/logical/array functions. It has no property access, imports, host objects, clock, randomness, regex, SQL, network calls, or dynamic evaluation.

Numbers do not silently become authority. Integer operations use checked `i64`; decimal literals retain coefficient and scale in IR; floating results bind canonical bits in result roots. Later compilers must consume the same IR instead of treating Excel syntax, Lua, or Blockly JSON as executable truth.

## Parallel execution

The planner computes dirty closure, detects cycles, and produces lexically stable topological levels. Only independent cells in one level can run concurrently. A level is divided by measured/selected chunk size and available Worker capabilities; completion order does not change admission order.

`SharedArrayBuffer` is a future optimization when cross-origin isolation exists. Transferable `ArrayBuffer` remains the baseline. The current `Float64Array` column descriptor already fixes shape, strides, validity, and row-major order so the storage layout is not an object-per-cell accident.

## SQLite body

`CELLS_SQLITE_SCHEMA` uses ordinary strict tables for workbooks, formulas, reverse dependency indexes, immutable chunk descriptors, receipts, and a transactional outbox. `commitCalculation()` records the result and enqueues its effect in one body transaction. Network publication starts after commit and can retry with the stable effect ID.

SQLite remains hot mutable state. Arrow-compatible descriptors are interchange; Parquet is cold immutable history; DuckDB is an analytical reader. None replaces SQLite for formula edits, dirty state, leases, receipts, or outbox mutation.

## P2P boundary

The existing browser peer API now exposes `cells()` over the Cap’n Web RTCDataChannel capability tree:

- `describe`
- `haveChunks`
- `fetchChunk`
- `publishChunk`
- `publishDelta`
- `publishReceipt`

Received immutable chunks are only **unverified cache candidates**. Deltas and receipts explicitly stop at `requires-cursors-validation`. There is no remote compute method yet.

Linda tuples advertise renewable capacity:

```text
["cells-executor", peer, abi, engine, lanes, capacity]
```

Expiry removes stale peers. Observation and discovery grant no computation authority. The next peer-compute phase requires an attenuated grant binding evaluator/ABI versions, workbook/formula roots, lanes, cells, bytes, steps, memory, wall time, expiry, and no delegation.

## Reproduce measurements

Run `node bench/cells-engine.mjs 10000`. Output is raw JSON with runtime, platform, workload, planning time, local evaluation, and 1/2/4/8-worker partition overhead. The current local-worker figures are overhead measurements, not claims of browser thread speedup.