rdbms-playground/docs/handoff/20260517-handoff-15.md

# Session handoff — 2026-05-17 (15)

Fifteenth handover. This session implemented **ADR-0025
(Indexes)** end to end — a fresh feature off the
`docs/requirements.md` roadmap — and fixed an input-history
navigation bug found while testing it.

**Headline: indexes are a real DSL feature now.** `add index`
/ `drop index`, rebuild-safe, persisted in `project.yaml`,
shown in the structure view and a new nested items panel.
ADR-0025 is Accepted and fully implemented. The natural next
job is **QA1 — `EXPLAIN QUERY PLAN`** — now unblocked because
there is finally an index for a plan to use; see §4.

## State at handoff

**Branch:** `main`. Working tree clean. `origin/main` is at
`0dc159f` (the ADR-0025 commit — the user pushed it); local
HEAD is **1 commit ahead** (`4e4dbbf`, the history fix —
unpushed; the user pushes asynchronously).

Commits since handoff-14:

```
4e4dbbf Input history: reset the nav cursor on every submit
0dc159f Indexes: add index / drop index, persistence, display (ADR-0025)
```

**Tests:** **1039 passing, 0 failing, 1 ignored** (`cargo
test` — up from 1006/1007). The ignored test is the
long-standing `` ```ignore `` doc-test in
`src/friendly/mod.rs`. The typing-surface matrix is now **152
cells** (was 144).

**Clippy:** clean with `nursery` lints + `-D warnings`.

## §1. What shipped

### ADR-0025 — indexes (`0dc159f`)

A new ADR (`docs/adr/0025-indexes.md`, Accepted) and its full
implementation. The four design forks were settled by the user
before drafting:

- **Naming:** optional, `add index [as <name>] on <T>
  (<cols>)`; auto-name `<Table>_<col…>_idx` when omitted.
  Mirrors the ADR-0013 `as`-name convention.
- **UNIQUE:** out of scope — plain non-unique indexes only;
  `UNIQUE` stays a separate `C3` sub-item.
- **Items list (S2):** the left panel is now a nested tree —
  each table with its index names indented beneath it.
- **`drop column`:** refuses an indexed column by default; a
  new `--cascade` flag opts into dropping the covering indexes.

What landed:

- **Grammar** (`src/dsl/grammar/ddl.rs`): `add index` is a
  third branch of `add`; `drop index` a fourth branch of
  `drop`; both drop forms (`drop index <name>` /
  `drop index on <T> (<cols>)`). `drop column` gained an
  optional `--cascade` flag.
- **AST** (`src/dsl/command.rs`): `Command::AddIndex` /
  `Command::DropIndex`, an `IndexSelector` enum (`Named` /
  `Columns`, mirroring `RelationshipSelector`), and a
  `cascade: bool` field on `Command::DropColumn`.
- **db layer** (`src/db.rs`): `do_add_index` / `do_drop_index`;
  index reads via the engine's native catalog
  (`pragma_index_list` / `pragma_index_info`, origin `c`
  only) — **no metadata table**, unlike relationships;
  `IndexInfo` added to `TableDescription`; friendly errors for
  duplicate name, redundant column set, missing table/column,
  unknown / ambiguous index.
- **Rebuild safety:** `rebuild_table_with_copy` now captures a
  table's indexes before the `DROP TABLE` and recreates them
  after the rename — so `change column` and the relationship
  operations no longer silently drop indexes.
- **`drop column --cascade`:** `do_drop_column` detects
  covering indexes, refuses without the flag, drops them with
  it. Returns a new `DropColumnResult { description,
  dropped_indexes }`; the runtime reports each dropped index.
- **Persistence:** an additive `indexes:` list in
  `project.yaml` (`version:` unchanged — older files default
  it empty). `read_schema_snapshot` writes it,
  `do_rebuild_from_text` recreates indexes on rebuild;
  `export` / `import` carry them.
- **Display:** an `Indexes:` section in `render_structure`;
  the nested items panel via a new `SchemaCache::table_indexes`
  map.
- **Tests:** 30 new across tiers — 6 parser, 13 db
  integration (real in-memory SQLite), 2 `output_render`, 1
  full project rebuild round-trip (`tests/iteration3_rebuild.rs`),
  8 typing-surface matrix cells (`tests/typing_surface/index_ops.rs`).

### Input-history cursor fix (`4e4dbbf`)

See §2.

## §2. Bug found and fixed this session

**Input-history cursor stranded on re-submit.**
`App::push_history` did its `history_cursor` / `history_draft`
reset *after* the consecutive-duplicate early-return. So
recalling a command with Up and re-submitting it unchanged (a
duplicate → not appended → reset skipped) left the cursor
pinned at that entry; the next Up then stepped *backwards*
from there (`Some(i) => i-1`) instead of restarting at the
newest entry — the next Up appeared to "skip" an entry.

Fixed by moving the reset ahead of the early-return guards —
submitting a command always ends history navigation. Tier-1
regression test
`app::tests::resubmitting_a_recalled_command_does_not_strand_the_cursor`
drives the recall/resubmit keystroke sequence.

## §3. Notes for the next agent

**Two ADR-0025 deviations are recorded** in that ADR's
`## Implementation notes` section — read them, the decision
text and the code agree there but the sketch above it does not:

- `rename column` / `drop column` use native `ALTER TABLE`,
  not the rebuild primitive. SQLite's `RENAME COLUMN` already
  rewrites index definitions, so rename needs no index code;
  `drop column` handles covering indexes directly. Only
  `change column` (and the relationship ops) go through the
  rebuild primitive, where the column set is unchanged, so
  indexes are recreated verbatim — no rename-map needed.
- The S2 panel carries per-table index names in
  `SchemaCache::table_indexes` rather than restructuring
  `app.tables` and the `TablesRefreshed` event.

**One defensively-unreachable branch.** `do_drop_index`'s
"more than one index matches these columns" arm cannot be
reached via the app's own commands — `do_add_index` refuses a
redundant index over an identical column set. It is reachable
only via a hand-edited `project.yaml`, which the project does
defend against elsewhere. Left in, untested.

## §4. What's next — QA1 is unblocked

`docs/requirements.md` was reconciled this session: the index
portion of `C3` is done, **`S2` moved to `[x]`**, the `QA1`
note updated, test baseline refreshed to 1039.

**The natural next pick is `QA1` — `EXPLAIN QUERY PLAN`.**
Until this session there was no index for a plan to be
interesting about; now `show data <T> where <col> = <val>`
(the C5 filtered form, already implemented) is a query whose
plan visibly flips between a full scan and an index search.
But QA1 has an unmet dependency of its own: **`QA2`** (plan
rendering — tree layout, annotation taxonomy, colour scheme)
is `[~]` and **needs an ADR before any implementation**. So
QA1 is "write the QA2 ADR, then build" — not a self-contained
drop-in. **Prioritisation is a user product decision — ask,
don't assume.**

Other open clusters in `requirements.md` (unchanged from
handoff-14 §4, minus indexes):

- **Complex WHERE expressions** (`C5a`, `[~]`) — AND/OR /
  comparison / LIKE in UPDATE/DELETE/show-data filters. Needs
  an ADR. The bridge from DSL toward real SQL.
- **SQL in advanced mode** (`Q1`/`Q4`, `[~]`) — `sqlparser-rs`
  + a defined subset. Needs an ADR.
- **Snapshot / undo** (`U1`/`U2`) — designed in ADR-0006, not
  built.
- **m:n convenience** (`C4`), **modify relationship** (`C3a`,
  `[~]`), **table rename** (`C1`).
- **Friendly error layer** (`H1`) — partial. **Syntax-help in
  parse errors** (`H1a`) — piecemeal.
- **Session log + Markdown export** (`V4`, `[~]`),
  **multi-line input** (`I1`), **readline shortcuts**
  (`I1b`), **seeding** (`SD1`), **CI** (`TT5`),
  **tutorial system** (`TU1`, `[~]`).

## §5. Architectural delta (vs. handoff-14)

### New `Command` variants / fields

- `Command::AddIndex { name: Option<String>, table, columns }`.
- `Command::DropIndex { selector: IndexSelector }`.
- `IndexSelector` enum — `Named` / `Columns`.
- `Command::DropColumn` gained `cascade: bool`.

### New grammar surface

- `IdentSource::Indexes` — completion source for existing
  index names.
- `add` / `drop` `Choice`s gained index branches;
  `drop column` gained the `--cascade` flag node.

### New db surface

- `IndexInfo` (public) — on `TableDescription::indexes`.
- `DropColumnResult { description, dropped_indexes }` — the
  new return type of `Database::drop_column` /
  `Request::DropColumn` / `do_drop_column`.
- `Request::AddIndex` / `DropIndex`; `Database::add_index` /
  `drop_index`.
- `read_table_indexes` / `read_index_columns` helpers;
  `do_add_index` / `do_drop_index`.
- `rebuild_table_with_copy` is now index-preserving.

### New event / outcome / friendly surface

- `AppEvent::DslDropColumnSucceeded { command, result }`;
  `App::handle_dsl_drop_column_success`.
- `CommandOutcome::DropColumn(DropColumnResult)`.
- `friendly::Operation::AddIndex` / `DropIndex`.

### `SchemaCache`

- `indexes: Vec<String>` — flat index-name list (for
  `drop index <name>` completion).
- `table_indexes: HashMap<String, Vec<String>>` — per-table
  index names (for the S2 panel).

### Persistence

- `IndexSchema { name, table, columns }`;
  `SchemaSnapshot.indexes`; a `indexes:` block in the
  `project.yaml` writer + an optional `#[serde(default)]`
  field in the reader.

### Catalog

- Added: `parse.usage.add_index`, `parse.usage.drop_index`,
  `ok.index_dropped_with_column`. Modified: `help.ddl.add`,
  `help.ddl.drop`. New keys registered in
  `src/friendly/keys.rs`.

### Tests

- New matrix file `tests/typing_surface/index_ops.rs` (8
  cells) → 152 matrix cells total.

## §6. How to take over

1. **Read this file, then handoff-14, then 13** for the chain.
2. **Read `CLAUDE.md`** — the working-style rules. This
   session escalated all four index design forks to the user
   before drafting the ADR.
3. **Read `docs/requirements.md`** — reconciled this session;
   the authoritative "what's open" tracker.
4. **Read `docs/adr/0025-indexes.md`** — including its
   `## Implementation notes` (§3 above).
5. **Run `cargo test`** — 1039 passing, 0 failing, 1 ignored.
6. **Run `cargo clippy --all-targets -- -D warnings`** — clean.
7. **`4e4dbbf` is unpushed** — the user pushes; don't treat it
   as blocking.
8. **Pick the next work from §4** — `QA1` is the natural pick
   but it needs the `QA2` rendering ADR first, and
   prioritisation is a user product decision. Ask, don't
   assume.

### Note on the typing-surface matrix

`tests/typing_surface/` (now 152 cells) is the regression net
for everything walker/hint/completion. After any grammar or
walker change: a failing cell with *correct* new behaviour →
update its snapshot
(`INSTA_UPDATE=always cargo test --test typing_surface_matrix
<family>`); a failing cell with *wrong* behaviour → the cell
earned its keep. Adding `add index` shifted one
`add_relationship` cell's snapshot this session (the `add `
candidate set gained `index`) — that was a correct update.