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

									
										docs/adr/README.md
									
		+1
		
												View File
												
				@@ -22,3 +22,4 @@ This directory contains the project's ADRs, recorded per

				- [ADR-0014 — Data operations, value literals, and the auto-show pattern](0014-data-operations-and-value-model.md)

				- [ADR-0015 — Project storage runtime](0015-project-storage-runtime.md)

				- [ADR-0016 — Pretty table rendering for data and structure views](0016-pretty-table-rendering.md)

				- [ADR-0017 — Column type-change compatibility](0017-column-type-change-compatibility.md)