docs: ADR-0036 revised to surgical "validate-and-retain"; +X4/X5 open questions

Narrow ADR-0036 from "bind literals via the DSL path" to "validate literal
values (shared validators) + retain them; execute verbatim, keep auto-fill
and command identity mode-specific" — after a concrete auto-fill difference
(non-PK serial) confirmed the modes aren't identical even for single-row
literals. Augments (no longer supersedes) ADR-0030 §4 / ADR-0033 §10;
Amendment 3 stands. README + forward-notes on 0030/0033 updated. Records
requirements.md X4 (serial auto-fill — possible bug) and X5 (framework
cohesion / share-mechanics-not-commands).
This commit is contained in:
claude@clouddev1
2026-05-26 21:58:19 +00:00
parent 3e3a2fb171
commit dc9a4759ce
5 changed files with 239 additions and 207 deletions
+13 -9
View File
@@ -10,15 +10,19 @@ for the phase-exit report and the filled cross-cut matrix in
`docs/plans/20260520-adr-0033-phase-3.md`. Amendments 13 below
are part of this acceptance.
> **Forward note (2026-05-26).** The **Proposed ADR-0036** narrows the
> §10 verbatim-execution model for **literal data values**: rather than
> handing the user's literal text to the engine, `INSERT`/`UPDATE` should
> parse literal values to typed `Value`s, validate them, retain them on
> the command (for binding *and* error enrichment), and bind them as
> parameters — as the simple-mode DSL already does. Expressions, `WHERE`
> predicates, `INSERT … SELECT`, `RETURNING`, UPSERT, and `SELECT` stay
> verbatim text. The `Sql*` command variants and worker handlers remain;
> only the literal-value execution path changes. Pending acceptance.
> **Forward note (2026-05-26, ADR-0036 Accepted).** ADR-0036 **augments**
> the §10 model — it does **not** change verbatim execution and does
> **not** collapse the two-command identity of **Amendment 3** (which
> stands). It adds a *value-validation* step: `INSERT`/`UPDATE` literal
> values are parsed to typed `Value`s, **validated** against the column
> type (sharing the DSL's validators), and **retained** on the command
> (so a constraint error can show the offending value) — then the
> statement still executes **verbatim**. `Command::SqlInsert` gains a
> captured-literals payload; its execution and `plan_shortid_autofill`
> are unchanged. Expressions, `WHERE`, `INSERT … SELECT`, `RETURNING`,
> UPSERT, and `SELECT` are untouched. (The serial/shortid auto-fill
> difference vs simple mode is tracked separately as `requirements.md`
> X4.)
## Context