ADR-0017 + ADR-0002 amendment: type-change compatibility + engine-agnostic posture

Specifies the curated per-cell classification (clean /
lossy / incompatible) for column type changes, the static
transformer matrix (numeric chains, text↔structured types,
always-clean stringifications), and the PK / shortid /
uniqueness-bearing handling. Replaces the B2/C2
placeholder of "rely on engine STRICT and surface its
errors" with a learner-friendly model that:

* refuses incompatibles up-front,
* refuses lossy conversions by default with a re-run-with-
  --force-conversion hint,
* refines the PK refusal: an inbound-FK PK is only refused
  when the new type would change the FK target type
  (so `serial → int` and `shortid → text` on FK-referenced
  PKs are allowed; `int → text` etc. still refuse),
* adds a post-transformation uniqueness check for PK and
  shortid columns,
* uses the pretty-table renderer (ADR-0016) for all
  diagnostic row lists,
* emits a `[client-side] …` note in the success summary
  whenever the transformer rewrote any cell.

`--force-conversion` accepts loss; `--dont-convert` skips
the client-side layer entirely; mutually exclusive.

Forward-look: a future iteration may add resolution flags
(`--default 0`, `--on-incompatible '<value>'`).

Also amends ADR-0002 with a new "User-facing posture"
section cementing that the database engine choice is an
implementation detail and is never named in user-visible
strings. Adds a corresponding bullet to CLAUDE.md's
working-style rules so every session picks it up.

Implementation lands as a follow-up.
This commit is contained in:
claude@clouddev1
2026-05-08 10:53:20 +00:00
parent 7b97786ab7
commit c3e5f9014f
4 changed files with 510 additions and 0 deletions
+24
View File
@@ -39,6 +39,30 @@ Use **SQLite** via the `rusqlite` crate. All tables are created as
Simplified user-facing column types (see ADR-0005) are mapped to
the underlying SQLite STRICT types at parse time.
## User-facing posture
The choice of SQLite is an implementation detail. The
playground's user-facing surface — error messages, success
notes, help text, and any other string the user sees —
never names the underlying engine. "The database" or "the
engine" in the abstract is the canonical phrasing; the
specific product (SQLite, STRICT, rusqlite, PRAGMA) is
ADR-internal and code-comment vocabulary only.
Rationale: students should leave with knowledge that
generalises. Naming the engine in user-visible strings
ties their mental model to a specific product when the
lessons are about relational concepts. The friendly-error
layer (H1) wraps engine error text before surfacing;
advanced mode's SQL surface doesn't expose the engine name
either — the user writes SQL because SQL is the language,
not because SQLite is the engine.
This commitment is referenced from later ADRs (notably
ADR-0017 §6 on the client-side conversion note); when in
doubt about a user-facing string's wording, this section
governs.
## Consequences
- Tight, low-friction packaging — `rusqlite` bundles SQLite.