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
+8
View File
@@ -156,6 +156,14 @@ Key invariants in the code:
- **Pedagogy wins ties.** When a design choice trades clarity
for raw capability, prefer clarity. Real RDBMS power-user
features exist; this app is not the place to teach them.
- **No engine name in user-facing strings.** The choice of
database engine is an implementation detail per ADR-0002
(User-facing posture). Error messages, success notes,
help text, and any other user-visible string refer to
"the database" or "the engine" in the abstract — never
the specific product (SQLite, STRICT, rusqlite, PRAGMA).
ADR-internal prose and code comments may name it where
technically necessary for precision.
- **Confirm commits.** Per the user's global rules, every
`git commit` is preceded by an explicit message proposal
and user approval. No AI attribution in commit messages.