rdbms-playground/docs/handoff/20260519-handoff-23.md

# Session handoff — 2026-05-19 (23)

Twenty-third handover. This session **finished ADR-0029** —
column constraints (`NOT NULL` / `UNIQUE` / `CHECK` /
`DEFAULT`). Commits 5–6, planned in full in handoff-22 §4, are
implemented, tested and committed. **ADR-0029 is complete**;
requirement `C3` (schema constraints) is now ticked in
`docs/requirements.md`.

## §1. State at handoff

**Branch:** `main`. Working tree clean (after this docs
commit). **3 commits** since handoff-22 (`102dff0`) — two
feature commits plus this handoff — all local; push
asynchronously, not blocking.

```
<this file>  docs: handoff 23 — ADR-0029 complete; tick C3
5e97f6a constraints: CHECK-violation friendly error + typing-surface matrix (ADR-0029 §10)
abce118 constraints: `add constraint` / `drop constraint` on existing columns (ADR-0029 §2.2)
```

**Tests:** **1240 passing, 0 failing, 1 ignored** (`cargo
test`). The ignored test is the long-standing `` ```ignore ``
doc-test in `src/friendly/mod.rs`. Typing-surface matrix:
**188 cells** (was 174 — +14 for the constraint grammar).

**Clippy:** clean (`cargo clippy --all-targets -- -D
warnings`, nursery group).

## §2. What ADR-0029 delivered (full picture)

Commits 1–4 (handoff-22) landed the constraint *suffix* —
`not null` / `unique` / `default <lit>` / `check (<expr>)`
after a column's `(type)` group on `create table` and `add
column`, the db-layer DDL/round-trip, and the §6 `add column`
routing. This session added the rest:

**Commit 5 (`abce118`) — `add constraint` / `drop constraint`.**
The §2.2 surface for modifying an *existing* column's
constraints:

```
add constraint not null   to <T>.<col>
add constraint unique     to <T>.<col>
add constraint default <literal> to <T>.<col>
add constraint check ( <expr> )  to <T>.<col>
drop constraint (not null | unique | default | check) from <T>.<col>
```

- **Grammar** (`src/dsl/grammar/ddl.rs`): `ADD_CONSTRAINT` /
  `DROP_CONSTRAINT` join the `add` / `drop` `Choice`s,
  discriminated by the `constraint` form word. `add
  constraint` reuses the §2.1 `COLUMN_CONSTRAINT` Choice;
  `drop constraint` uses a payload-free `DROP_CONSTRAINT_KIND`
  Choice. `CONSTRAINT_TARGET` is the dotted `<T>.<col>`
  (`table_name` / `column_name` roles — distinct from the
  CHECK expression's `expr_column`, so the target column
  never collides with an expression column).
- **AST** (`src/dsl/command.rs`): `Command::AddConstraint` /
  `DropConstraint`; `Constraint` (payload-carrying) /
  `ConstraintKind` (payload-free) enums.
- **Worker** (`src/db.rs`): `do_add_constraint` /
  `do_drop_constraint` apply the change through the
  rebuild-table primitive. `do_add_constraint` runs the §5
  **dry-run first** — `dry_run_not_null` / `dry_run_unique` /
  `dry_run_check` scan the existing rows and, on a violation,
  refuse *before any write* with a pretty-printed table of
  offending rows (the `db.diagnostic.add_*_summary` catalog
  keys + `render_diagnostic_table`, mirroring
  `do_change_column_type`). §9 redundant-on-PK declarations
  and §6 `default` on a `serial` / `shortid` column are
  friendly refusals.
- Both return `TableDescription` → `CommandOutcome::Schema` →
  the existing auto-show path (no new `AppEvent`).

**Commit 6 (`5e97f6a`) — CHECK friendly error + matrix.**

- **CHECK-violation friendly error (ADR §10).** The friendly
  layer already had a `translate_check` + `error.check.*`
  catalog entries (placeholder from an earlier session), but
  nothing filled the column in. `enrich_dsl_failure`
  (`src/runtime.rs`) gained a CHECK branch:
  `enrich_check_violation` reads the column from the engine's
  `CHECK constraint failed: <column>` message, then resolves
  the table, the offending value, and the column's compiled
  `CHECK` expression. `FailureContext` / `TranslateContext`
  carry a new `check_rule` field; `translate_check` renders
  "the value `<v>` breaks the rule `<rule>`" when the rule is
  known, falling back to the plain hint otherwise.
- **Typing-surface matrix.** New `tests/typing_surface/
  constraints.rs` — 14 cells covering the create-table /
  add-column constraint suffix and `add` / `drop constraint`.

## §3. Decisions / deviations this session

1. **`schema_to_ddl` UNIQUE bug fixed** (`abce118`). It
   suppressed `UNIQUE` for *every* PK column. A *compound*-PK
   member is **not** individually unique, so an explicit
   `UNIQUE` on it must survive the rebuild. The condition is
   now "suppress only for a *single-column* PK". Caught by the
   `add_constraint_unique_on_compound_pk_member_is_allowed`
   test. Pre-existing latent bug.
2. **"Nothing to drop" is a friendly refusal** (`abce118`) —
   `drop constraint` on a constraint the column never carried
   refuses ("`T.col` has no UNIQUE constraint to drop")
   instead of a silent no-op rebuild. This was *not* spelled
   out in handoff-22 §4; it is consistent with ADR-0029 §9's
   "clarity over permissiveness" and was an autonomous
   call — flagged here and accepted by the user at commit
   time.
3. **CHECK friendly error went full ADR §10** (`5e97f6a`) —
   the user chose, when asked, to surface the rule + offending
   value rather than the minimal handoff-§4 scope. ADR §10's
   prose said "DSL-form expression"; deviation §7 had removed
   the DSL-text form, so §10 was updated to say the rule is
   shown in its **compiled-SQL form** — consistent with §7/§8.

## §4. Key reusable pieces (this session)

- `src/db.rs`: `do_add_constraint` / `do_drop_constraint`;
  `read_constraint_dry_run_rows` + `dry_run_not_null` /
  `dry_run_unique` / `dry_run_check`; `render_constraint_
  dry_run` and the `dry_run_id_*` helpers; `value_to_default_
  sql` (factored out of `default_sql_literal`). `DryRunRow`
  type alias.
- `src/runtime.rs`: `enrich_check_violation`.
- `src/friendly/`: `FailureContext.check_rule` /
  `TranslateContext.check_rule`; `error.check.*.hint_with_rule`
  catalog keys.
- `Operation::AddConstraint` / `DropConstraint` in
  `src/friendly/translate.rs`.

## §5. What's next

ADR-0029 closes requirement `C3`. No feature is in flight.
Open clusters (prioritisation is a **user decision — ask**):

- Snapshot / undo / replay `U`-series (designed in ADR-0006,
  not yet implemented).
- m:n convenience `C4`; modify-relationship `C3a` (drop+add
  covers it today).
- Project storage Iter 5–6: `export` / `import`, `--resume`,
  persistent input history, migration-framework scaffold.
- SQL handling in advanced mode (`sqlparser-rs`, its own ADR).
- Friendly-error layer `H1` (the remaining SQL→English
  sweep); strong syntax-help in parse errors `H1a`.
- Session-log / Markdown export `V4`; ER diagram export `V3`.
- CI workflow `TT5`; readline shortcuts `I1b`; multi-line
  input `I1`; Tab completion polish `I3`.

## §6. How to take over

1. **Read this file**, then `CLAUDE.md` (working-style
   rules), then `docs/requirements.md` (per-item progress —
   `C3` now ticked).
2. **Run `cargo test`** — 1240 passing, 0 failing, 1 ignored.
3. **Run `cargo clippy --all-targets -- -D warnings`** —
   clean.
4. Pick the next cluster *with the user* — §5 has no default.

### Note on the typing-surface matrix

`tests/typing_surface/` is **188 cells**. The matrix-snapshot
discipline stands: a failing cell with *correct* new
behaviour → update its snapshot; with *wrong* behaviour → the
cell earned its keep. `cargo insta` is not installed —
regenerate with `INSTA_UPDATE=always cargo test --test
typing_surface_matrix <filter>` and review the written
`.snap` files before committing.