Merge branch 'main' into website (Gitea migration + ADR renumber)
Brings website up to date with main (18 commits): H1a parse-error pedagogy, V5/H3/V5a show+help commands, ADR-0043 compound-PK FK, handoffs 58-59, and the GitHub->Gitea doc scrub (Cargo.toml repository, CLAUDE.md, ADR-0001 amendment, requirements). Conflict: docs/adr/README.md. main and website had each created an ADR-0042 (main: H1a parse-error pedagogy; website: public website & docs site). Renumbered the website ADR to 0044 (next free after main's 0042/0043) and updated all references (ADR file, plan file, STYLE.md, astro.config.mjs, README index). Website build verified green.
This commit is contained in:
claude@clouddev1
@@ -45,3 +45,25 @@ package managers (`cargo binstall`, Homebrew, Scoop, `winget`).
|
||||
- TUI styling will require explicit work to match the polish that
|
||||
Bubble Tea / Lipgloss give for free; budget for it in the design
|
||||
pass.
|
||||
|
||||
## Amendment 1 — Distribution channel is open after the Gitea migration (2026-06-09)
|
||||
|
||||
The *Decision* block above assumed prebuilt binaries would ship "via
|
||||
GitHub releases plus package managers." Since then the repository has
|
||||
been migrated off GitHub to a self-hosted Gitea instance
|
||||
(`git.lazyeval.net/oli/rdbms-playground`), and `tea` is the forge CLI
|
||||
in use. The "GitHub releases" half of that sentence is therefore no
|
||||
longer a settled assumption.
|
||||
|
||||
This amendment does **not** pick a replacement. Binary distribution is
|
||||
not built yet (no release pipeline, no CI — `requirements.md` TT5/E*
|
||||
remain open), so the channel for prebuilt binaries is an **open
|
||||
choice** — Gitea releases, a GitHub mirror's releases, or both — to be
|
||||
settled by a dedicated ADR when distribution is actually implemented.
|
||||
The package-manager channels named in the Decision (`cargo binstall`,
|
||||
Homebrew, Scoop, `winget`) are independent of the forge and are
|
||||
unaffected.
|
||||
|
||||
(For the same supersede-don't-rewrite reason, the Decision block also
|
||||
still names `sqlparser-rs`, which ADRs 0030–0036 replaced with a
|
||||
hand-rolled grammar; that is recorded there, not by editing this ADR.)
|
||||
|
||||
@@ -2,7 +2,29 @@
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
**Superseded by ADR-0024** (2026-05-14). Accepted then superseded
|
||||
without being implemented.
|
||||
|
||||
> **Superseding note (2026-06-03).** This ADR was never built. It
|
||||
> specifies a `chumsky`-over-tokens architecture — a separate lexer
|
||||
> producing `Vec<Token>`, a `define_keywords!` macro, and chumsky
|
||||
> grammar combinators consuming `&[Token]`. ADR-0024 (unified grammar
|
||||
> tree) instead adopted a **scannerless hand-rolled walker** that
|
||||
> operates directly on source bytes, and **removed chumsky from the
|
||||
> project entirely** (it is no longer a dependency). The lexer,
|
||||
> `keyword.rs`, and the token model described below do not exist.
|
||||
>
|
||||
> What this ADR got *right* survives in ADR-0024: the
|
||||
> expected-set aggregation it wanted (one branch's report no longer
|
||||
> swallowing the others) is delivered by the walker's structural
|
||||
> `expected` derivation, and the I3 (completion) / I4 (highlighting)
|
||||
> hooks it anticipated are served by the same walker. Read ADR-0024
|
||||
> for the architecture as built; this ADR remains as institutional
|
||||
> memory of the path not taken and the reasoning that led there.
|
||||
|
||||
---
|
||||
|
||||
*Original status (historical):* Accepted.
|
||||
|
||||
Amends ADR-0001 (language and TUI framework) by adding a
|
||||
tokenization layer between the source string and the chumsky
|
||||
|
||||
@@ -2,7 +2,37 @@
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
**Mechanism superseded by ADR-0024; H1a scope continued in ADR-0042.**
|
||||
Accepted then superseded.
|
||||
|
||||
> **Superseding note (2026-06-03).** The *intent* of this ADR — surface
|
||||
> the grammar of the command at the point of error, not just the next
|
||||
> token — survived and is largely delivered. The *mechanism* did not.
|
||||
> This ADR specifies a `chumsky`-based design: a separate `UsageEntry`
|
||||
> registry in `src/dsl/usage.rs`, `parse.token.*` catalog keys driven
|
||||
> by chumsky's `RichPattern<Token>` expected sets, and a renderer over
|
||||
> chumsky output. ADR-0024 (unified grammar tree) replaced chumsky with
|
||||
> a scannerless walker and **folded usage info onto the grammar nodes
|
||||
> themselves**: `usage_ids` live on each `CommandNode`, the per-command
|
||||
> `parse.usage.*` templates and the `parse.available_commands` fallback
|
||||
> ship as designed here, and the expected-set vocabulary
|
||||
> (`format_expectation` in `parser.rs`) renders directly from walker
|
||||
> `Expectation` variants — no `UsageEntry` registry, no `parse.token.*`
|
||||
> keys, no `src/dsl/usage.rs`.
|
||||
>
|
||||
> So: the §1 usage registry, §3 "deepest consumed keyword" mechanism,
|
||||
> §4 `parse.token.*` catalog, and §7 validator details below describe
|
||||
> code that does not exist. What shipped equivalently: §1's per-command
|
||||
> templates (as `usage_ids` + `parse.usage.*`), §2's three-block render
|
||||
> (echo+caret / structural error / usage), and §5's available-commands
|
||||
> fallback. **ADR-0042 picks up H1a from here** — it records what is
|
||||
> actually shipped and defines the remaining systematic-pass scope
|
||||
> against the grammar-tree architecture. Read ADR-0042 for the live
|
||||
> plan; this ADR remains as the design rationale for the pedagogy goal.
|
||||
|
||||
---
|
||||
|
||||
*Original status (historical):* Accepted.
|
||||
|
||||
Builds on ADR-0020 (tokenization layer). Addresses H1a from
|
||||
`requirements.md` — the parse-error pedagogy gap that
|
||||
|
||||
@@ -0,0 +1,385 @@
|
||||
# ADR-0042: H1a parse-error pedagogy in the grammar-tree era
|
||||
|
||||
## Status
|
||||
|
||||
**Accepted** — 2026-06-03.
|
||||
|
||||
Continues H1a (`requirements.md`) from **ADR-0021**, whose
|
||||
chumsky-based mechanism was superseded by **ADR-0024** (unified
|
||||
grammar tree). ADR-0021's *intent* — surface the grammar of the
|
||||
command at the point of error, not just the next token — is
|
||||
re-stated here against the architecture as actually built, with
|
||||
an inventory of what already ships and a definition of done for
|
||||
the remaining work.
|
||||
|
||||
Cross-references ADR-0019 (friendly-error layer + i18n catalog
|
||||
conventions; H1a output shares the catalog), ADR-0022 (ambient
|
||||
typing assistance, which shares the walker's expected-set
|
||||
machinery), ADR-0024 (the grammar tree), and ADR-0009 (DSL
|
||||
surface conventions; usage templates render in the documented
|
||||
surface form).
|
||||
|
||||
## Context
|
||||
|
||||
### Why a new ADR rather than amending ADR-0021
|
||||
|
||||
ADR-0021 specifies a `UsageEntry` registry in `src/dsl/usage.rs`,
|
||||
`parse.token.*` catalog keys, and a renderer over chumsky's
|
||||
`RichPattern<Token>` expected sets. None of that exists. ADR-0024
|
||||
removed chumsky from the project, deleted `usage.rs`, and folded
|
||||
usage information onto the grammar nodes themselves. Amending
|
||||
ADR-0021 in place would force every reader to mentally translate a
|
||||
dead mechanism; a fresh ADR records the live state directly.
|
||||
ADR-0020 and ADR-0021 keep their superseding notes and remain as
|
||||
institutional memory.
|
||||
|
||||
### What H1a is
|
||||
|
||||
When a learner types something near-correct, the error should
|
||||
*name the missing keyword or clause* and *show the shape of the
|
||||
command*, rather than point a caret at the unexpected character.
|
||||
The user-reported gap: typing `create` once produced
|
||||
`parse error: after \`create\`, expected \`table\`` — structurally
|
||||
true, pedagogically silent.
|
||||
|
||||
### What already ships (the baseline — do not re-build)
|
||||
|
||||
Verified against code on 2026-06-03. The grammar-tree migration
|
||||
delivered most of ADR-0021's intent through different machinery:
|
||||
|
||||
1. **Per-command usage block.** Every `CommandNode` carries
|
||||
`usage_ids: &'static [&'static str]`
|
||||
(`src/dsl/grammar/mod.rs`). On any parse error the renderer
|
||||
emits a `usage:` block listing every form of the matched
|
||||
command family — 38 templates under `parse.usage.*`
|
||||
(`src/friendly/strings/en-US.yaml:499-571`), resolved by
|
||||
`grammar::usage_keys_for_input` and rendered by
|
||||
`render_usage_block` (`src/app.rs:2560`).
|
||||
|
||||
2. **Available-commands fallback.** When no command keyword was
|
||||
consumed, the block becomes
|
||||
`available commands: …` (`parse.available_commands`,
|
||||
`en-US.yaml:493`; `app.rs:2593`).
|
||||
|
||||
3. **Structural error names the consumed prefix and expected
|
||||
set.** `format_walker_error` (`src/dsl/parser.rs:289`) renders
|
||||
`after \`<consumed>\`, expected <set>, found <token|end of
|
||||
input>`, distinguishing incomplete-at-EOF (`at_eof = true`,
|
||||
more input would help) from a definite mid-input mismatch.
|
||||
|
||||
4. **Friendly slot labels for identifiers.** `format_expectation`
|
||||
(`src/dsl/parser.rs:262`) renders `Ident` slots by source —
|
||||
"table name", "column name", "relationship name", "index
|
||||
name", "type" — instead of a bare "identifier" (ADR-0022 stage
|
||||
8c).
|
||||
|
||||
5. **Curated custom messages** for high-value near-misses under
|
||||
`parse.custom.*` (`en-US.yaml:443-478`): `create_table_needs_pk`,
|
||||
`insert_form_a_missing_values` ("looks like Form A — add
|
||||
`values (...)`"), `change_column_flags_exclusive`,
|
||||
`bind_type_mismatch`, the redundant-constraint and
|
||||
alter-add-primary-key cases, etc.
|
||||
|
||||
6. **Schema-aware pre-flight diagnostics** that light the
|
||||
`[ERR]` validity indicator *at typing time* (ADR-0027 /
|
||||
ADR-0033 / ADR-0036): INSERT arity for Forms A/B/C, unknown
|
||||
table/column, type mismatch, `= NULL`, NOT-NULL-missing, and —
|
||||
on the advanced-SQL surface — `cte_arity_mismatch`,
|
||||
`compound_arity_mismatch`, and `projection_alias_misplaced`
|
||||
(`diagnostic.*`, `en-US.yaml:577-620`; walker logic in
|
||||
`src/dsl/walker/mod.rs`).
|
||||
|
||||
7. **Ambient "Next:" hints** and the **simple→advanced cross-mode
|
||||
pointer** (ADR-0022 / `advanced_alternative_note`,
|
||||
`src/input_render.rs`).
|
||||
|
||||
So H1a is *substantially* delivered at the intent level. The
|
||||
handoff's two canonical examples already behave: `insert into T
|
||||
('Oli')` → custom Form-A message; `update T set x=1` → structural
|
||||
"expected `where` or `--all-rows`" + usage block.
|
||||
|
||||
### What remains — the genuine gap
|
||||
|
||||
The remaining work is **systematic verification plus targeted
|
||||
polish**, not a missing feature:
|
||||
|
||||
- **No enumerated coverage guarantee.** Coverage is curated
|
||||
case-by-case; nothing asserts that *every required slot in every
|
||||
command* produces a pedagogically-sound near-miss message.
|
||||
- **Literal expectations render terse.** `Word`/`Literal`/`Punct`/
|
||||
`Flag` slots come out as backticked literals (`` `where` ``,
|
||||
`` `=` ``, `` `--all-rows` ``). Correct, but a learner is helped
|
||||
more by a short prose gloss in select high-value positions.
|
||||
- **Advanced-mode SQL parse pedagogy is thinner** than the DSL
|
||||
surface (RETURNING scope, CTE-arity diagnostic positioning,
|
||||
`CROSS JOIN … ON`, INSERT…SELECT column-count). No other ADR or
|
||||
open issue covers this (ADR-0019 §OOS-2 covers advanced-SQL
|
||||
*engine-error sanitisation* — a different layer).
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. Definition of done — a verified near-miss matrix
|
||||
|
||||
H1a is "done" when there is a test matrix that, for **every
|
||||
command in the REGISTRY**, exercises its salient near-miss inputs
|
||||
and asserts the rendered output reads pedagogically. "Salient
|
||||
near-misses" per command means at minimum:
|
||||
|
||||
- the bare entry keyword alone (`create`, `add`, `update`);
|
||||
- each required clause omitted (e.g. `update T set x=1` with no
|
||||
filter rail; `insert into T (cols)` with no `values`);
|
||||
- a wrong token where a specific slot is expected (e.g. a number
|
||||
where a table name belongs);
|
||||
- the zero-prefix / unknown-command case (available-commands
|
||||
fallback).
|
||||
|
||||
The matrix lives in the existing surfaces — `tests/typing_surface/`
|
||||
(snapshot-based, the standalone `typing_surface_matrix` binary) for
|
||||
the typing-time hint/validity view, and
|
||||
`tests/it/parse_error_pedagogy.rs` (the consolidated `it` binary)
|
||||
for the submit-time rendered three-block output. New integration
|
||||
tests go in `tests/it/` per the handoff-57 §3 layout rule — **not**
|
||||
as new top-level `tests/*.rs`.
|
||||
|
||||
Work is **test-first**: add the matrix entry, observe the current
|
||||
rendering, and only then adjust wording/labels where it reads
|
||||
poorly. A near-miss whose current rendering is already good is
|
||||
locked by a snapshot, not rewritten.
|
||||
|
||||
### 2. Friendlier literal expectation labels
|
||||
|
||||
`format_expectation` gains, for high-value keyword/punct positions,
|
||||
an optional prose gloss while **always keeping the exact literal
|
||||
visible** — a learner must still see the precise token to type.
|
||||
The principle: a label may *add* role context, never *replace* the
|
||||
literal.
|
||||
|
||||
Illustrative target (final wording settled per-case against the
|
||||
matrix, as is normal for pedagogical text):
|
||||
|
||||
- `expected \`where\` or \`--all-rows\`` →
|
||||
`expected a filter clause: \`where …\` or \`--all-rows\``
|
||||
- `expected \`values\`` (after a Form-A column list) →
|
||||
already covered by `parse.custom.insert_form_a_missing_values`;
|
||||
the matrix confirms it fires.
|
||||
|
||||
Mechanism (illustrative, finalised at implementation time): a
|
||||
grammar `Word`/`Punct` node may carry an optional expectation-label
|
||||
key, mirroring how `Ident` slots derive a label from
|
||||
`IdentSource`. Absent an override, rendering is unchanged (the
|
||||
backticked literal). This keeps the change additive and per-slot —
|
||||
no blanket reword that would churn the anchor-phrase tests
|
||||
needlessly.
|
||||
|
||||
New glosses are catalog-sourced (`parse.expect.*` or reuse of
|
||||
`parse.usage.*` fragments — chosen at implementation time) so
|
||||
wording stays in `en-US.yaml`, not in code, consistent with
|
||||
ADR-0019.
|
||||
|
||||
### 3. Advanced-mode SQL parse pedagogy — in scope
|
||||
|
||||
The same matrix discipline (§1) extends to the advanced-mode SQL
|
||||
surface. Two of the relevant arity diagnostics **already exist** and
|
||||
must not be re-built — `cte_arity_mismatch` and
|
||||
`compound_arity_mismatch` (`en-US.yaml:590-591`); for these the work
|
||||
is matrix coverage and, for CTE, auditing whether the diagnostic is
|
||||
*positioned at the CTE name* (easiest to fix) rather than the body.
|
||||
The remaining items were re-checked empirically at implementation
|
||||
time (2026-06-05) and **most turned out already handled** — see the
|
||||
Implementation-outcome section's advanced-SQL paragraph for the
|
||||
corrected picture. The `:` one-shot escape (a simple-mode line run
|
||||
once in advanced mode) is part of the advanced surface and is
|
||||
covered by the mode-aware usage threading (G3).
|
||||
|
||||
This stays clear of ADR-0019 §OOS-2 (advanced-SQL *engine-error*
|
||||
sanitisation): §OOS-2 reworks errors raised by *executing* SQL;
|
||||
H1a here concerns errors raised while *parsing* it. If a near-miss
|
||||
turns out to be an engine error rather than a parse error, it is
|
||||
out of H1a scope and noted against §OOS-2 instead.
|
||||
|
||||
### 4. Catalog and anchor-phrase discipline
|
||||
|
||||
All new or reworded user-facing strings go through the i18n catalog
|
||||
(`en-US.yaml`) and the `KEYS_AND_PLACEHOLDERS` validator, per
|
||||
ADR-0019. No engine vocabulary in any string (CLAUDE.md).
|
||||
|
||||
Two anchor styles constrain §2's glosses and both are preserved by
|
||||
its "literal always visible" rule:
|
||||
|
||||
- The **substring assertions** in `src/dsl/parser.rs` tests
|
||||
("after `…`", "expected table name", "found end of input",
|
||||
"unknown type", "expected one of").
|
||||
- The **substring assertions** in `tests/it/parse_error_pedagogy.rs`,
|
||||
which check for backticked literals and usage fragments
|
||||
(e.g. `` `column` ``, `` `1` ``, "create table", "with pk"). This
|
||||
test is `.contains()`-based, not snapshot-based, so a §2 gloss
|
||||
that dropped the bare literal would fail it — which is precisely
|
||||
the regression §2's rule prevents.
|
||||
|
||||
The snapshot-based `tests/typing_surface/` matrix will re-baseline
|
||||
on any §2 wording change (expected; reviewed via `cargo insta`),
|
||||
but the two substring suites above must stay green without edits to
|
||||
their assertions.
|
||||
|
||||
## Implementation outcome (2026-06-05)
|
||||
|
||||
The baseline capture (§Implementation notes step 1) triaged four
|
||||
gaps; all four are fixed test-first, locked by the near-miss matrix
|
||||
in `tests/it/parse_error_pedagogy.rs`:
|
||||
|
||||
- **G1** — the bare `1` cardinality literal opening `add 1:n
|
||||
relationship …` rendered cryptically. Render it as
|
||||
`` `1:n relationship` `` in `format_expectation` (error wording
|
||||
only; completion still offers the literal `1`).
|
||||
- **G2** — bare `select` dumped the 14-item expression first-set.
|
||||
Collapse it to "a projection: `*`, a column, or an expression"
|
||||
in `format_walker_error`, detected by the `distinct`+`all`
|
||||
quantifier pair being *jointly* expectable — a signature unique
|
||||
to a projection start (empirically verified not to misfire at
|
||||
`count(`, `union`, `union all`, `select distinct`, or mid-list).
|
||||
Render-only; the completion/hint layer still expands the full
|
||||
set.
|
||||
- **G3** — the usage block was mode-blind (`render_usage_block`
|
||||
resolved shared entry words to the first-registered Simple node).
|
||||
`usage_key(s)_for_input` gain mode-aware `_in_mode` variants.
|
||||
|
||||
**Decision (user-confirmed, after the DA pass).** In advanced
|
||||
mode the DSL forms remain *valid input* via fallback — verified:
|
||||
`create table Foo with pk`, `drop column from table T: c`,
|
||||
`drop relationship r`, `add column …` all parse and dispatch in
|
||||
advanced mode. So the advanced usage block shows **every form
|
||||
valid in the mode, mode-primary (SQL) first, then the DSL
|
||||
fallback forms** — a usage hint must never hide input that works.
|
||||
(An initial implementation that showed SQL-only was flagged by
|
||||
the DA pass as hiding `create table … with pk` / `drop column …`
|
||||
and corrected.) Simple mode shows DSL forms only — the SQL-only
|
||||
forms hit the "this is SQL" rail and are unreachable.
|
||||
|
||||
- **G4** — `with` borrowed `select`'s usage; it gains its own
|
||||
`parse.usage.with` CTE template.
|
||||
|
||||
**Advanced-SQL pedagogy (§3) — empirical re-check (2026-06-05).**
|
||||
§3 (drafted from a code survey) listed `RETURNING` scope,
|
||||
`CROSS JOIN … ON`, and INSERT…SELECT column-count as absences.
|
||||
Verifying each against the running app **reversed two of three**:
|
||||
|
||||
- **INSERT…SELECT column-count** is *already handled* — a count
|
||||
mismatch fires `verdict = Error` with "the column list names N
|
||||
column(s) but M value(s) are given" (walker test
|
||||
`insert_select_arity_mismatch_fires`). It is a structural
|
||||
list-vs-list check, so it fires even without a schema. Not a gap.
|
||||
*Caveat (pre-existing, not addressed here):* a `SELECT *`
|
||||
projection is not expanded for arity, so `insert into T (one_col)
|
||||
select * from Multi` is not pre-caught — the engine rejects it at
|
||||
execution. Star-expansion for pre-flight arity would be a separate
|
||||
enhancement (and brushes ADR-0019 §OOS-2 engine-error territory).
|
||||
- **RETURNING scope** is *already handled* — at a bare `returning`
|
||||
position completion offers the table's columns; `returning
|
||||
<unknown>` fires the `unknown_column` diagnostic. Not a gap.
|
||||
- **`CROSS JOIN … ON`** *was* a genuine residual: the grammar
|
||||
rejects the `on` but the structural error said only "expected end
|
||||
of input". **Fixed** — `parse.cross_join_no_on` renders "a CROSS
|
||||
JOIN has no ON clause — …" when the failing token is `on` and the
|
||||
most recent consumed join is a CROSS join (a precise signature:
|
||||
every other join requires `on`, so there `on` is expected, not a
|
||||
failure). Render-only, no grammar change; two misfire guards
|
||||
(plain join still asks for `on`; a stray `on` with no join does
|
||||
not fire). The CTE/compound arity diagnostics noted above remain
|
||||
present and correct.
|
||||
|
||||
**Known low-priority residual (user-confirmed to defer).** At
|
||||
*submit* time, an incomplete expression position that is not a
|
||||
SELECT projection (bare `where `, `returning `, `having `, `set
|
||||
col=`) still renders the raw ~14-item expression first-set; only the
|
||||
SELECT projection is glossed (G2, keyed on the `distinct`+`all`
|
||||
quantifier pair). This is low-impact because *typing*-time
|
||||
completion already offers the correct candidates (columns,
|
||||
functions, expression keywords) at those positions. Generalising the
|
||||
gloss was considered and deferred — the payoff is small and a
|
||||
broader render-side collapse adds misfire surface.
|
||||
|
||||
Coverage: the matrix covers, in both modes, every entry word's bare
|
||||
/ missing-clause / wrong-token near-misses, the app-lifecycle
|
||||
trailing-junk cases, **and** the committed *multi-form* variants
|
||||
(`add index` / `add constraint` / `add 1:n relationship`, `drop
|
||||
index` / `drop constraint` / `drop relationship`, `show table`,
|
||||
`change column …`, `create index`, `alter table … add` / `… drop`).
|
||||
The committed forms were audited 2026-06-05 and each renders its own
|
||||
form-specific missing-keyword message + usage (e.g. `add index` →
|
||||
"expected `on` or `as`"; `drop constraint` → "expected `not`,
|
||||
`unique`, `default`, or `check`"), regression-locked in
|
||||
`near_miss_matrix_committed_multiforms`.
|
||||
|
||||
## Out of scope
|
||||
|
||||
1. **Advanced-SQL engine-error sanitisation** — ADR-0019 §OOS-2.
|
||||
2. **Tab completion (I3) and syntax highlighting (I4)** as
|
||||
features — they share the walker but are separate ADRs.
|
||||
3. **Schema-aware "did you mean `Customers`?" spell-correction** —
|
||||
ADR-0021's out-of-scope §2; belongs with I3.
|
||||
4. **Multi-error reporting.** The walker reports the first error
|
||||
and stops; unchanged.
|
||||
5. **`messages`-style verbosity gating of the usage block.** Per
|
||||
ADR-0021 §8 the usage block is always shown; parse errors are
|
||||
exactly when pedagogical surface should be maximal. Unchanged.
|
||||
6. **Auto-generating usage/help text from the grammar.** ADR-0024
|
||||
left help prose hand-curated; templates stay hand-written.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- H1a gains an explicit, enumerated definition of done instead of
|
||||
an open-ended "systematic pass still pending".
|
||||
- The matrix becomes a regression lock: future grammar changes
|
||||
that degrade a near-miss message fail a snapshot.
|
||||
- Literal-label glosses close the last terse-wording gap without a
|
||||
blanket reword.
|
||||
- The advanced-SQL surface reaches parity with the DSL surface for
|
||||
the audience that has switched to raw SQL.
|
||||
|
||||
### Costs
|
||||
|
||||
- Wording iteration across many near-miss cases — but cheap,
|
||||
catalog-driven, and snapshot-guarded.
|
||||
- The §2 per-node label field is one more annotation a new command
|
||||
may set (optional; default unchanged).
|
||||
- Snapshot volume grows; acceptable given the existing ~160-entry
|
||||
typing-surface matrix.
|
||||
|
||||
### Neutral
|
||||
|
||||
- No public API change. `parse_command*` signatures, the
|
||||
`ParseError` shape, and the three-block render path are all
|
||||
unchanged; this ADR adds wording, labels, and tests within them.
|
||||
|
||||
## Implementation notes
|
||||
|
||||
Order of operations (test-first throughout):
|
||||
|
||||
1. Enumerate the per-command near-miss matrix (§1) as failing/asserting
|
||||
tests in `tests/typing_surface/` + `tests/it/parse_error_pedagogy.rs`.
|
||||
Capture current rendering as the starting baseline.
|
||||
2. Triage: which entries read poorly? Only those get wording work.
|
||||
3. Add the optional expectation-label mechanism (§2) and apply it
|
||||
to the high-value keyword/punct positions surfaced in triage.
|
||||
4. Advanced-SQL near-miss audit + fixes (§3), distinguishing parse
|
||||
from engine errors as they arise.
|
||||
5. Catalog validator + anchor-phrase checks stay green (§4).
|
||||
6. Update `requirements.md` H1a with the matrix as the done-marker;
|
||||
flip to `[x]` only when the matrix is complete and green.
|
||||
|
||||
## See also
|
||||
|
||||
- ADR-0021 — Parser-as-source-of-truth for H1a (mechanism
|
||||
superseded; intent continued here).
|
||||
- ADR-0020 — Tokenization layer (superseded by the scannerless
|
||||
walker).
|
||||
- ADR-0024 — Unified grammar tree (the architecture H1a is built
|
||||
on).
|
||||
- ADR-0022 — Ambient typing assistance (shares the expected-set
|
||||
machinery).
|
||||
- ADR-0019 — Friendly-error layer and i18n catalog (§OOS-2 is the
|
||||
adjacent engine-error scope).
|
||||
- ADR-0009 — DSL command-syntax conventions (usage surface form).
|
||||
- `requirements.md` — H1a tracking entry.
|
||||
@@ -0,0 +1,339 @@
|
||||
# ADR-0043: Compound-primary-key foreign-key references (T3)
|
||||
|
||||
## Status
|
||||
|
||||
**Accepted + implemented** — 2026-06-09. Implementation landed the
|
||||
same day: the relationship model went list-based through all six
|
||||
layers (refactor commit `b14f019`, single-column preserved), then
|
||||
the DSL + SQL grammars gained multi-column parsing and the
|
||||
executor the full-PK/auto-expand/per-pair-type-compat/auto-name/
|
||||
`--create-fk`-per-column logic. Verified by 12 integration tests in
|
||||
`tests/it/compound_fk.rs` (parse both surfaces, engine-enforced FK,
|
||||
arity + partial-PK refusal, `--create-fk`, single-column
|
||||
preserved) on top of the existing single-column relationship
|
||||
suite. `requirements.md` **T3** is `[x]`. All four genuine forks
|
||||
confirmed by the user at the recommended option: **F-A** full PK in order, **F-B**
|
||||
house-style uniform column lists (no migration; back-compat not
|
||||
required), **F-C** parenthesized DSL lists, **F-D** bare table-level
|
||||
SQL FK auto-expands to the parent's full PK. Closes the one open
|
||||
leg of
|
||||
`requirements.md` **T3** ("compound primary keys handled
|
||||
end-to-end (DSL, storage, display, **FK reference**)"): a foreign
|
||||
key that *references* a compound (multi-column) primary key.
|
||||
|
||||
Cross-references **ADR-0011** (FK column type compatibility —
|
||||
`Type::fk_target_type`), **ADR-0013** (relationships, naming, the
|
||||
rebuild-table strategy, and the `__rdbms_playground_relationships`
|
||||
metadata table), **ADR-0035 §4b** (the SQL `FOREIGN KEY` surface),
|
||||
**ADR-0004 / ADR-0015** (`project.yaml` as the authoritative
|
||||
format; `playground.db` is a derived artifact), and **ADR-0009**
|
||||
(DSL surface conventions).
|
||||
|
||||
## Context
|
||||
|
||||
Compound PRIMARY KEYs are declared, stored, and displayed today
|
||||
(`create table T with pk a(int), b(int)` → `primary_key:
|
||||
Vec<String>`). The missing leg is the *reference*: a child table
|
||||
whose foreign key points at a parent's compound PK. A 2026-06-09
|
||||
codebase audit found single-column FK is a pervasive assumption —
|
||||
~15–20 sites across 6+ files:
|
||||
|
||||
- **Metadata** — `__rdbms_playground_relationships` stores scalar
|
||||
`parent_column TEXT` / `child_column TEXT`
|
||||
(`PRIMARY KEY (child_table, child_column)`).
|
||||
- **Persistence** — `RelationshipSchema { parent_column: String,
|
||||
child_column: String }`; `project.yaml` `RawEndpoint { table,
|
||||
column }`.
|
||||
- **Grammar** — `add 1:n relationship … from <P>.<col> to
|
||||
<C>.<col>` (one ident per side); SQL `FOREIGN KEY (<col>)
|
||||
REFERENCES <P>(<col>)` (parens that hold exactly one ident).
|
||||
- **AST** — `Command::AddRelationship { parent_column: String,
|
||||
child_column: String }`; `SqlForeignKey { child_column: String,
|
||||
parent_column: Option<String> }`.
|
||||
- **Executor** — `schema_to_ddl` emits a single-column
|
||||
`FOREIGN KEY (c) REFERENCES P(p)`; `check_fk_type_compat`
|
||||
compares one parent type to one child type; bare
|
||||
`REFERENCES <P>` on a compound-PK parent is refused as
|
||||
ambiguous (`resolve_create_table_fks`,
|
||||
`do_alter_add_foreign_key`).
|
||||
- **Display** — `RelationshipEnd { other_column: String,
|
||||
local_column: String }`.
|
||||
|
||||
This is not a sweep-sized change, which is why it earns an ADR
|
||||
rather than an inline build. The decisions below also turn the
|
||||
audit's worst-case framing (a metadata-schema + yaml-format
|
||||
migration via the F3 framework) into a **no-migration** change.
|
||||
|
||||
### Why no migration is needed
|
||||
|
||||
**Decision input (user, 2026-06-09): back-compatibility with
|
||||
existing saved projects is not required.** The project is
|
||||
pre-release; there is no installed base of `project.yaml` /
|
||||
`playground.db` files to preserve. This removes the only force
|
||||
that would have demanded an F3 migrator or a version bump, and —
|
||||
more importantly — it lets the representation be chosen for
|
||||
*cleanliness and consistency* rather than for byte-identical
|
||||
back-compat. The consequence is explicit and accepted: a
|
||||
`project.yaml` written before this change that contains
|
||||
relationships will not load under the new format.
|
||||
|
||||
Freed of back-compat, the storage follows the convention the file
|
||||
**already uses** for ordered column lists rather than inventing a
|
||||
new one:
|
||||
|
||||
- `project.yaml` already writes `primary_key: [id]` (a compound PK
|
||||
is `primary_key: [a, b]`) and index `columns: [a, b]`
|
||||
(`RawIndex { columns: Vec<String> }`). The relationship endpoint
|
||||
is the lone multi-column-capable slot still using a scalar
|
||||
`column:`. It joins the house style (D5).
|
||||
- The metadata columns are `TEXT`; SQLite has no array type, so a
|
||||
list lives in a text cell as JSON regardless. That JSON is now a
|
||||
*uniform* encoding (a one-element array for the single-column
|
||||
case), not a "bare-name-or-JSON, sniff which" fallback — the
|
||||
fallback only existed to keep old rows identical, which is no
|
||||
longer a goal.
|
||||
|
||||
So this is not a clever back-compat dodge; it is "use the existing
|
||||
list convention, uniformly." No version bump, no F3 migrator.
|
||||
|
||||
## Decision
|
||||
|
||||
Support a foreign key that references a parent's **full** compound
|
||||
primary key, matched **positionally** to an equal-length child
|
||||
column list, with per-pair type compatibility — across both the
|
||||
DSL and SQL surfaces — using format-flexible storage that needs no
|
||||
migration.
|
||||
|
||||
### D1 — Matching policy: the full PK, in order
|
||||
|
||||
A compound-PK FK references **all** columns of the parent's
|
||||
primary key, in PK declaration order, matched 1:1 to the child's
|
||||
column list (same length). Referencing a *subset* of a compound PK
|
||||
is **out of scope**: SQL/SQLite require FK parent columns to form a
|
||||
PK or UNIQUE key, and a strict subset of a compound PK is not
|
||||
itself unique unless separately constrained. Teaching-clean rule:
|
||||
*a foreign key to a compound key names every column of that key.*
|
||||
|
||||
A length mismatch (child supplies N columns, parent PK has M ≠ N)
|
||||
is a friendly error naming both counts.
|
||||
|
||||
### D2 — Type compatibility: per pair, positional
|
||||
|
||||
Each child column's type must satisfy
|
||||
`parent_pk_col.fk_target_type() == child_col` for the
|
||||
corresponding pair (the existing ADR-0011 rule, applied
|
||||
element-wise in order). `check_fk_type_compat` generalises to walk
|
||||
the pairs and report the **first** offending pair with the same
|
||||
wording it uses today.
|
||||
|
||||
### D3 — DSL syntax: parenthesized column lists
|
||||
|
||||
`add 1:n relationship [as <name>]
|
||||
from <P>.(<a>, <b>) to <C>.(<x>, <y>)
|
||||
[on delete …] [on update …] [--create-fk]`
|
||||
|
||||
The single-column form `from <P>.<col> to <C>.<col>` is unchanged
|
||||
(no parens) — back-compatible and the common case. The
|
||||
parenthesized list is the multi-column form. Both sides must use
|
||||
the same arity (enforced as a D1 length check). Parentheses mirror
|
||||
the existing compound-PK *declaration* syntax (`with pk a(int),
|
||||
b(int)` uses parens around the per-column type; the FK list uses
|
||||
parens around the column names) and the SQL `FOREIGN KEY (…)`
|
||||
shape, so the surface stays internally consistent.
|
||||
|
||||
### D4 — SQL syntax: extend the existing lists
|
||||
|
||||
`FOREIGN KEY (<x>, <y>) REFERENCES <P> (<a>, <b>)` — the grammar's
|
||||
child and parent column slots become comma-separated **lists**
|
||||
(today capped at one). Inline `<col> <type> REFERENCES <P>(<a>,
|
||||
<b>)` stays single-child-column (one inline column can't match a
|
||||
2-column key) — a compound FK uses the table-level form. Bare
|
||||
table-level `FOREIGN KEY (x, y) REFERENCES <P>` (no parent
|
||||
columns) **auto-expands to the parent's full PK** when the arities
|
||||
match; bare inline `<col> REFERENCES <P>` on a compound-PK parent
|
||||
keeps today's friendly refusal, with the message pointing at the
|
||||
table-level multi-column form.
|
||||
|
||||
### D5 — Storage: uniform column lists, matching the house style
|
||||
|
||||
Both stores hold an **ordered column list**, uniformly (a
|
||||
one-element list for the single-column case), following the
|
||||
convention `project.yaml` already uses for `primary_key` and index
|
||||
`columns`.
|
||||
|
||||
- **`project.yaml`**: `RawEndpoint` becomes `{ table, columns:
|
||||
Vec<String> }` and writes `columns: [a, b]` (single-column →
|
||||
`columns: [id]`), exactly parallel to `primary_key: [id]`. No
|
||||
scalar `column:` form, no dual-shape reader.
|
||||
- **Metadata** (`__rdbms_playground_relationships`): no
|
||||
`CREATE TABLE` change (the `TEXT` columns and
|
||||
`PRIMARY KEY (child_table, child_column)` are untouched).
|
||||
`parent_column` / `child_column` store the list **comma-joined**
|
||||
in the same text cell (`a,b`; a single column is just its bare
|
||||
name). *As-built note:* the ADR first said "JSON array"; the
|
||||
implementation uses a comma delimiter, which is safe because
|
||||
column identifiers are `[A-Za-z0-9_]+` (no commas — `parser.rs`)
|
||||
and simpler (no `serde_json` dependency). This is an internal
|
||||
encoding detail below fork F-B — the user-visible `project.yaml`
|
||||
is still the `columns: [a, b]` list.
|
||||
The actual enforced FK lives on the rebuilt child table's DDL
|
||||
(`FOREIGN KEY (a, b) REFERENCES P(x, y)`), emitted by
|
||||
`schema_to_ddl`, exactly as the single-column FK is today via the
|
||||
rebuild-table primitive (ADR-0013) — one relationship, one undo
|
||||
step.
|
||||
|
||||
### D6 — In-memory model: `Vec<String>` column lists
|
||||
|
||||
`Command::AddRelationship`, `SqlForeignKey`, `RelationshipSchema`,
|
||||
the internal `ReadForeignKey`, and `RelationshipEnd` (display) all
|
||||
carry `parent_columns: Vec<String>` / `child_columns: Vec<String>`
|
||||
(or `Option<Vec<String>>` for the bare-SQL parent case). A
|
||||
one-element vec is the single-column case; nothing about the
|
||||
single-column UX changes.
|
||||
|
||||
## Genuine forks (escalated for sign-off)
|
||||
|
||||
These are decisions, not facts. Recommendations are marked; the
|
||||
user confirms before this ADR moves to Accepted.
|
||||
|
||||
- **F-A — matching policy.** Full PK only (D1, *recommended*) vs.
|
||||
allow a subset (needs a separate UNIQUE key; larger, less
|
||||
teaching-clean).
|
||||
- **F-B — storage encoding.** Uniform column lists in the existing
|
||||
house style — `columns: [a, b]` in yaml (like `primary_key`),
|
||||
JSON-array in the unchanged metadata `TEXT` columns; no
|
||||
back-compat, no migration (D5, *recommended*) vs. a normalized
|
||||
relationship-columns child table (more "correct" but a schema
|
||||
change with joins on read, no learner-visible payoff). Premise:
|
||||
no existing projects to preserve (confirmed).
|
||||
- **F-C — DSL multi-column syntax.** `from P.(a, b) to C.(x, y)`
|
||||
parenthesized (D3, *recommended*) vs. a repeated-dotted form
|
||||
(`from P.a, P.b to C.x, C.y`, more ambiguous to parse and read).
|
||||
- **F-D — bare table-level SQL FK auto-expansion.** Auto-expand
|
||||
`FOREIGN KEY (x,y) REFERENCES P` to P's full PK when arities
|
||||
match (D4, *recommended*) vs. always require explicit parent
|
||||
columns.
|
||||
|
||||
## Implementation sketch (change sites)
|
||||
|
||||
Grouped; each lands behind tests. No migration step.
|
||||
|
||||
1. **AST** — `AddRelationship` + `SqlForeignKey` column fields →
|
||||
`Vec<String>` / `Option<Vec<String>>` (`command.rs`).
|
||||
2. **Grammar** — DSL endpoint column slot → optional
|
||||
parenthesized list (`ddl.rs`); SQL child/parent column slots →
|
||||
comma lists (`sql_create_table.rs`). Builders collect lists.
|
||||
3. **Metadata** — `insert_relationship_metadata` /
|
||||
`read_all_relationships` encode/decode bare-or-JSON
|
||||
(`db.rs`); no `CREATE TABLE` change.
|
||||
4. **Persistence** — `RelationshipSchema` → `Vec<String>`;
|
||||
`RawEndpoint` becomes `{ table, columns: Vec<String> }`, written
|
||||
`columns: [a, b]` like `primary_key`
|
||||
(`persistence/mod.rs`, `persistence/yaml.rs`).
|
||||
5. **Executor** — `do_add_relationship` /
|
||||
`resolve_create_table_fks` / `do_alter_add_foreign_key` walk
|
||||
column lists; `schema_to_ddl` emits multi-column `FOREIGN KEY
|
||||
(…) REFERENCES P(…)`; `check_fk_type_compat` loops pairs;
|
||||
bare-reference paths auto-expand to the full PK (D4) or refuse
|
||||
with the improved message; the default relationship-name
|
||||
generator (`db.rs:6850`) joins the column lists; `--create-fk`
|
||||
creates one child column per parent PK column (`db.rs`).
|
||||
6. **Display** — `RelationshipEnd` → column lists; `describe`
|
||||
renders `(a, b) → (x, y)` symmetrically (outbound + inbound,
|
||||
ADR-0013) (`db.rs`, `output_render.rs`).
|
||||
7. **Teaching echo (ADR-0038)** — `render_add_relationship` and
|
||||
`render_add_relationship_create_fk` (`echo.rs`) go multi-column:
|
||||
the FK line emits `FOREIGN KEY (a, b) REFERENCES P (x, y)`, and
|
||||
`--create-fk` emits **one `ADD COLUMN` line per newly-created
|
||||
child column** (each typed to the matching parent PK column's
|
||||
`fk_target_type`) before the FK line. Copy-paste contract
|
||||
(ADR-0038) holds: every echoed line is runnable advanced SQL.
|
||||
8. **Tests** — parse (DSL + SQL: single-col still works; multi
|
||||
parses; arity mismatch errors; empty `()` rejected; inline
|
||||
`col REFERENCES P(a,b)` rejected with the table-level pointer);
|
||||
worker round-trip (declare a 2-col FK, rebuild, the FK is
|
||||
**enforced** — an insert violating it is refused; per-pair
|
||||
type-mismatch refused; bare-FK **auto-expand** to the parent PK;
|
||||
`--create-fk` creates both child columns); persistence
|
||||
round-trip (a single-col relationship writes `columns: [id]` and
|
||||
reads back; a 2-col writes `columns: [a, b]` and reads back;
|
||||
full save→rebuild reconstructs the FK); **undo** (add a 2-col
|
||||
relationship, undo, it is gone — one step); display
|
||||
(`describe` shows `(a, b) → (x, y)` both directions).
|
||||
|
||||
## Implementation-readiness notes (DA pass, 2026-06-09)
|
||||
|
||||
Verified against the code before build; folded in so the plan is
|
||||
complete.
|
||||
|
||||
- **SQLite precondition holds.** A FK's parent columns must be a
|
||||
PK or a UNIQUE-indexed set. A SQLite `PRIMARY KEY (a, b)` creates
|
||||
the requisite unique index, so `FOREIGN KEY (x, y) REFERENCES
|
||||
P(a, b)` is valid against a compound PK with no extra index.
|
||||
STRICT tables do not change FK rules. (F-A's "full PK" therefore
|
||||
always targets a valid key; a subset would not be unique — the
|
||||
reason F-A excludes it.)
|
||||
- **Explicit parent columns must be exactly the PK set.** Under
|
||||
F-A, `REFERENCES P(<cols>)` is accepted iff `<cols>` is the
|
||||
parent's PK column **set**; any ordering is accepted and maps
|
||||
positionally to the child list (SQLite matches the set to the
|
||||
unique index; the child↔parent pairing is positional). A
|
||||
non-PK, partial, or super-set list is refused with a friendly
|
||||
message naming the parent's actual PK (subset/UNIQUE targets are
|
||||
OOS).
|
||||
- **Arity + emptiness.** Child and parent lists must be equal,
|
||||
non-zero length; a mismatch reports both counts
|
||||
("N child column(s) but M in `P`'s key"). An empty `()` list is
|
||||
a parse error. Inline single-column `col REFERENCES P(a, b)` is
|
||||
refused (one inline column can't satisfy a 2-column key) with a
|
||||
pointer to the table-level `FOREIGN KEY (…)` form (D4).
|
||||
- **DSL `from P.(a)` (single in parens)** is accepted — equivalent
|
||||
to bare `from P.a` — so the parenthesized form is uniform across
|
||||
arities; the bare form stays the idiomatic single-column
|
||||
spelling.
|
||||
- **`--create-fk` is per-column.** When child columns are missing,
|
||||
one is created per parent PK column, each typed to that parent
|
||||
column's `fk_target_type` (ADR-0011) — generalising today's
|
||||
single-column behaviour; the echo mirrors this (sketch step 7).
|
||||
- **Metadata identity unchanged.** `PRIMARY KEY (child_table,
|
||||
child_column)` still holds with the JSON-array string as the
|
||||
key — so a child column **set** still participates in at most one
|
||||
relationship (pre-existing behaviour, now per-set). Distinct
|
||||
sets on the same child table are distinct keys.
|
||||
- **Auto-name generation** (`db.rs:6850`, the `[as <name>]`-less
|
||||
default) is single-column today
|
||||
(`{parent_table}_{parent_column}_to_{child_table}_{child_column}`)
|
||||
— it must join the column lists (e.g.
|
||||
`Orders_a_b_to_Customers_x_y`). A found change site the first
|
||||
sketch missed; added to the executor step.
|
||||
- **Undo / batch unchanged.** One `add 1:n relationship` is one
|
||||
rebuild = one undo step (ADR-0013/0006), independent of arity.
|
||||
|
||||
## Consequences
|
||||
|
||||
- T3 closes; a learner can model a real composite-key relationship
|
||||
end to end.
|
||||
- No migration, and the on-disk representation gets *more*
|
||||
consistent: the relationship endpoint joins the `primary_key:
|
||||
[...]` / index `columns: [...]` list convention. The in-app
|
||||
single-column UX is untouched (one-element vecs).
|
||||
- Accepted trade-off (user, 2026-06-09): a `project.yaml` written
|
||||
before this change that contains relationships will not load
|
||||
under the new format. There is no installed base to preserve, so
|
||||
this is a clean cutover, not data loss.
|
||||
- The relationship model becomes list-based throughout, which is
|
||||
the natural foundation if subset/UNIQUE-targeted FKs are ever
|
||||
wanted (explicitly OOS here).
|
||||
- A modest, broad refactor (the `Vec` field change ripples through
|
||||
the 6 layers) — methodical, not deep; locked by tests at each
|
||||
layer.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Subset/non-PK FK targets (referencing a UNIQUE key that isn't
|
||||
the PK) — possible later on this list-based foundation.
|
||||
- Any change to single-column behaviour, the rebuild-table
|
||||
primitive, or the undo model (one relationship = one undo step
|
||||
stands).
|
||||
- A `project.yaml` version bump or F3 migrator (not needed —
|
||||
no installed base to migrate; clean cutover per D5).
|
||||
+7
-2
@@ -1,9 +1,14 @@
|
||||
# ADR-0042: Public website and documentation site
|
||||
# ADR-0044: Public website and documentation site
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (2026-06-04). Implementation plan:
|
||||
[`docs/plans/20260604-adr-0042-website.md`](../plans/20260604-adr-0042-website.md).
|
||||
[`docs/plans/20260604-adr-0044-website.md`](../plans/20260604-adr-0044-website.md).
|
||||
|
||||
> Renumbered from ADR-0042 to ADR-0044 when the `website` branch merged
|
||||
> `main` (2026-06-09): `main` had independently used 0042 for the H1a
|
||||
> parse-error ADR and 0043 for compound-PK FK references. Content is
|
||||
> unchanged from the original draft.
|
||||
|
||||
## Context
|
||||
|
||||
+6
-4
@@ -6,7 +6,7 @@ This directory contains the project's ADRs, recorded per
|
||||
## Index
|
||||
|
||||
- [ADR-0000 — Record architecture decisions](0000-record-architecture-decisions.md)
|
||||
- [ADR-0001 — Language and TUI framework](0001-language-and-tui-framework.md)
|
||||
- [ADR-0001 — Language and TUI framework](0001-language-and-tui-framework.md) — **Amendment 1 (2026-06-09)**: after the GitHub→Gitea migration (`git.lazyeval.net`), the prebuilt-binary distribution channel named in the Decision ("GitHub releases") is reopened as an undecided choice, to be settled by a future distribution ADR; package-manager channels unaffected
|
||||
- [ADR-0002 — Database engine](0002-database-engine.md)
|
||||
- [ADR-0003 — Input modes and command dispatch](0003-input-modes-and-command-dispatch.md) — the persistent `Simple`/`Advanced` mode and the `:` one-shot escape. The **startup mode is no longer always `simple`**: it is restored from the project's stored mode and overridable with `--mode` (see **ADR-0015 Amendment 1**, issue #14). The app-command registry gains **`copy`** (ADR-0041, issue #11)
|
||||
- [ADR-0004 — Project file format](0004-project-file-format.md)
|
||||
@@ -25,8 +25,8 @@ This directory contains the project's ADRs, recorded per
|
||||
- [ADR-0017 — Column type-change compatibility](0017-column-type-change-compatibility.md)
|
||||
- [ADR-0018 — Auto-fill contracts for `serial` and `shortid` columns](0018-auto-fill-contracts-for-serial-and-shortid.md)
|
||||
- [ADR-0019 — Friendly error layer (H1) and i18n message catalog](0019-friendly-error-layer-and-i18n.md)
|
||||
- [ADR-0020 — Tokenization layer for the DSL parser](0020-tokenization-layer-for-the-dsl-parser.md)
|
||||
- [ADR-0021 — Parser-as-source-of-truth for H1a (per-command usage in parse errors)](0021-parser-as-source-of-truth-for-h1a.md)
|
||||
- [ADR-0020 — Tokenization layer for the DSL parser](0020-tokenization-layer-for-the-dsl-parser.md) — **Superseded by ADR-0024 (never implemented).** Specified a `chumsky`-over-tokens architecture (separate lexer, `define_keywords!`, `&[Token]` grammar). ADR-0024 adopted a scannerless hand-rolled walker and removed `chumsky` entirely; the lexer/keyword/token model here does not exist. Kept as institutional memory of the path not taken.
|
||||
- [ADR-0021 — Parser-as-source-of-truth for H1a (per-command usage in parse errors)](0021-parser-as-source-of-truth-for-h1a.md) — **Mechanism superseded by ADR-0024; H1a scope continued in ADR-0042.** The *intent* (show the command's grammar at the point of error) shipped — `usage_ids` on each `CommandNode`, the `parse.usage.*` templates, and the `available_commands` fallback all exist — but via grammar nodes, not the `chumsky` `UsageEntry` registry / `parse.token.*` keys described here (which were never built).
|
||||
- [ADR-0022 — Ambient typing assistance: colour, hint panel, completion (I3 + I4)](0022-ambient-typing-assistance.md) — **Amendment 1 supersedes §12's simple-mode-only carve-out**: the unified mode-aware walker (ADR-0030/0031/0032) now speaks SQL, so advanced-mode ambient assistance is re-enabled. `ambient_hint_in_mode` + `hint_resolution_at_input_in_mode` + `expected_for_hint_snapshot` thread `Mode`; `render_hint_panel` calls ambient for all modes (no more advanced-mode `None`); the one-shot `:` sigil is stripped before the ambient walk. Fixes a live bug where advanced-mode SQL hinting/completion-preview were dead despite Phase 2 marking them green (validated at the engine layer, not the UI). Simple-mode gating, highlighting, and the §13 performance posture are unchanged; covered by an app-level render test plus ambient-layer regression locks; **Amendment 2 reverses the handoff-14 keywords-first candidate ordering** — schema identifiers (table/column/relationship names) now sort *before* keywords so a name the user would have to look up stays visible in the single-row, window-scrolled candidate line (keywords are learned over time; the `tok_identifier`/`tok_keyword` colour split marks the boundary); shipped with a `walk_repeated` fix that surfaces a list item's trailing optionals at a clean boundary (`order by Name ` → `asc`/`desc`, `select Name ` → `as`, `create table … Code(text) ` → `not`/`unique`/`default`/`check`; the `,` separator deliberately not surfaced); records a deferred two-line hint box for growing lists; **Amendment 3 makes the ambient-hint fallback rung schema-aware** — Amendment 1's bottom-rung `parse_command_in_mode` was schemaless while every earlier rung was not, so between-values insert hints pointed at `)` (type-blind close) instead of `,` and wrong-arity closed tuples read "submit with Enter" for an input the schema-aware parse rejects (issue #2); now uses `parse_command_with_schema_in_mode`, no extra walk, with the friendly arity diagnostic still winning at its higher rung; **Amendment 4 gives column types a dedicated highlight class** — both `Node::Ident.highlight_override` *and* the `Word.highlight_override` field were dead (driver destructured the former to `_`, `walk_word` hardcoded `Keyword`); now both wired through, with a new `HighlightClass::Type` + eighth `Theme` field `tok_type` (a pink/deep-magenta distinct from both keyword purple and identifier teal) so types no longer render identically to identifiers (issue #8); the three `IdentSource::Types` slots opt in via `Some(Type)` (advanced-mode single-word SQL aliases — `float`, `varchar`, … per ADR-0035 §3 — ride along for free), and the two-word `double precision` alias opts in via the new `Word::type_keyword` constructor so it matches its synonyms; **Amendment 5 lets the hint panel grow for long prose hints** — a fixed one-row panel clipped long field-value/usage hints past the first line (issue #12); `resolve_hint_lines` now pre-wraps prose and `render_right_column` sizes the panel to the line count (1 row default, up to `MAX_HINT_ROWS`=3, reclaimed when short) with a `clamp_wrapped` ellipsis backstop; the candidate list still scrolls horizontally on one row (Amendment 2's deferred two-line candidate box stays deferred); also shortens the 299-char `parse.usage.sql_create_table` synopsis to a terse one-liner (full grammar remains in `help.ddl.sql_create_table`); **Amendment 6 adds a curated SQL function-name list** (`src/dsl/sql_functions.rs`, `KNOWN_SQL_FUNCTIONS` — aggregates + common + broader scalars; `cast` deliberately excluded as its `CAST(x AS type)` syntax isn't a plain-call shape) as the single source of truth shared by two consumers at the `sql_expr_ident` slot (ADR-0031 §1): **issue #15** offers the functions as Tab candidates under a new `CandidateKind::Function` + ninth `Theme` colour `tok_function` (a blue distinct from keyword/identifier/type, parallel to Amendment 4's `tok_type`) so a learner discovers `sum`/`upper`/…; **issue #16** restores the typing-time column-typo flag the issue-#6 fix had dropped wholesale at this slot — `invalid_ident_at_cursor` now bails only when the partial prefix-matches a known function, else falls through to the schema-column check, so `select Agx` warns again at typing time while `select sum` does not (the issue-#6 lockdown tests + the submit-time `unknown_column` diagnostic path are untouched, and the no-validation-allowlist posture stands); see ADR-0031's status note for the grammar-side anchor
|
||||
- [ADR-0023 — Unified declarative grammar tree](0023-unified-grammar-tree.md) — direction (superseded for execution detail by ADR-0024)
|
||||
- [ADR-0024 — Unified grammar tree: execution plan](0024-unified-grammar-tree-execution-plan.md) — **Accepted**, the executable spec — implemented (Phases A–F; Phase F shipped "minimal", `parser.rs` retained as the router — see the ADR's Phase F implementation note)
|
||||
@@ -47,4 +47,6 @@ This directory contains the project's ADRs, recorded per
|
||||
- [ADR-0039 — EXPLAIN over advanced-mode SQL queries](0039-explain-over-advanced-sql.md) — **Accepted** (2026-05-27), **implemented 2026-05-30 (issue #7)**, **supersedes ADR-0030 §13 OOS-2**. Lets `explain` wrap the advanced SQL commands (`Select`/`SqlInsert`/`SqlUpdate`/`SqlDelete`, plus `with`/CTE which builds a `Select`) in addition to the DSL `ShowData`/`Update`/`Delete` it already covers (ADR-0028), running `EXPLAIN QUERY PLAN` over the validated SQL text through the existing ADR-0028 span-styled plan tree (advanced mode only; DSL `explain` unchanged in both modes). Implemented via a second `Advanced` `explain` CommandNode (`EXPLAIN_SQL`) registered under the shared `explain` entry word — reusing the established `insert`/`update`/`delete` shared-word dispatch (`decide`: SQL-first / DSL-fallback), so `explain show data …` and DSL-only `--all-rows` still reach the DSL node; rejected a `DynamicSubgrammar` mode-gate (its resolution cache key omits `mode`). `build_explain_sql` slices the inner SQL off the source (excludes `explain`) and reuses the existing SQL builders; `do_explain_plan` runs the carried text verbatim, no params. Advanced `explain update`/`delete` now route through SQL (identical plan, full SQL syntax); DSL-explain tests pinned to simple mode. Reframed OOS-2 as a *deferred* exclusion (per ADR-0000's out-of-scope discipline), not a rejection. OOS (deferred): EXPLAIN of DDL (no query plan exists)
|
||||
- [ADR-0040 — A per-command completion marker (✓/✗) replaces the `[ok]` summary line](0040-completion-marker-replaces-ok-summary.md) — **Accepted 2026-05-30 (issue #9)**, amends ADR-0014 / ADR-0028 / ADR-0019 output conventions, builds on ADR-0037's mode-tagged echo. An audit of the whole command surface found the `[ok] <verb> <subject>` summary line duplicates the echo line above it (verb+subject) everywhere; its only unique contribution is the success-vs-error signal (and `explain select` even rendered `[ok] explain` with an empty subject post-ADR-0039). Decision: drop the `[ok]` line and the symmetric `"…" failed:` prefix; the echo line gains a trailing inline **✓** (green, success) / **✗** (red, failure) — `running:` becomes a pending state that resolves to `<input> ✓/✗` on completion (status set via the existing `rfind(Echo)` lookup). Content (row counts, structure, data, plan tree, teaching echo) unchanged. Scoped to the DSL/data/SQL family that has the redundant echo+`[ok]` pair; app-command `[ok]` lines (`rebuild`/`export`/`now editing`) are payload-bearing, have no echo to mark, and stay as-is. `ok.summary` retired; `dsl.failed` reduced to the rendered reason. Broad but mechanical snapshot churn. OOS: app-command `[ok]` lines, the `[WRN]` validity indicator, and the tag colours (issue #10)
|
||||
- [ADR-0041 — Copy the output panel to the system clipboard](0041-copy-output-to-clipboard.md) — **Accepted 2026-06-02 (issue #11)**, amends ADR-0003's app-command registry (adds **`copy`** / `copy all` / `copy last`). The friction it removes: filing a bug report meant terminal-selecting the output panel and fighting wrapping/borders. New **app-level command** (sigil-free, both modes): `copy` / `copy all` copy the whole panel; `copy last` copies from the most recent echo line to the end. **Mechanism — OSC 52 *and* native (`arboard`), always both**, because OSC 52 acceptance is undetectable (no terminal ack), so a true "fall back when unsupported" can't be built: emit the OSC 52 escape (no new dep — `base64`+`crossterm`; works over SSH; tmux-passthrough-wrapped via `$TMUX`), then a best-effort native write whose failure is ignored (headless host — OSC 52 carried it); the two carry identical content. **Format — plain text verbatim as rendered** (tags, `✓`/`✗`, box-drawing) joined by `\n`, without viewport padding/wrapping; a drift-lock test pins `OutputLine::plain_text` to `render_output_line`. `arboard` added **`--no-default-features`** (drops the `image` crate; X11-only on Linux — `wayland-data-control` deliberately omitted as it ~doubles the dep tree and OSC 52 covers native-Wayland). Security: write-only, scans clean for arboard's tree (cargo audit / osv-scanner / grype), 1Password-maintained, minimal surface. OOS: Markdown export, selection/range, a keybinding, OSC 52 read, `screen` passthrough
|
||||
- [ADR-0042 — Public website and documentation site](0042-public-website-and-documentation-site.md) — **Accepted 2026-06-04**. The first public website: a marketing landing page plus the **canonical** user docs. Stack **Astro 6 + Starlight + Tailwind v4** (chosen over SvelteKit + Tailwind for a docs-heavy + marketing site; interactive bits as Astro islands). Showcase demos are **asciinema** `.cast` recordings (scripted-input driver for paced, re-recordable sessions — *not* `history.log` replay), reused inline in docs. The **in-page WASM playground is deferred** (OOS: deferred) behind a stable `Demo` seam, with the portable-core (`dsl`/`app`/`ui`, in-memory `rusqlite` via `ffi-sqlite-wasm-rs`) vs native-edge (Tokio/worker-thread/`crossterm`/persistence/backup-API) boundary recorded for a future ADR + iteration plan. Portable **static build** (Vercel target, but host-agnostic); **no CI yet**; **monorepo** (`website/`). Docs cover the **full supported feature set** with "planned" callouts for the unshipped minority; two wording rules bind user-facing copy — **no engine name** (continues ADR-0002) and **no "DSL"** ("simple mode" / "advanced mode"). Install docs cover **prebuilt binaries + package managers** (D1–D3 track the release tooling). Plan: `docs/plans/20260604-adr-0042-website.md`
|
||||
- [ADR-0042 — H1a parse-error pedagogy in the grammar-tree era](0042-h1a-parse-error-pedagogy-grammar-tree.md) — **Accepted 2026-06-03.** Continues **H1a** from ADR-0021 against the ADR-0024 grammar tree (ADR-0021's chumsky mechanism is dead). Records the **baseline already shipped** — per-command `usage:` block (38 `parse.usage.*` templates), available-commands fallback, structural "after `…`, expected …" wording, source-derived ident slot labels ("table name"/"column name"), curated `parse.custom.*` near-miss messages, and the ADR-0027/0033/0036 schema-aware `[ERR]` diagnostics — so H1a is *substantially* delivered at the intent level. Defines the remaining work as **(1)** a verified per-command **near-miss matrix** (`tests/typing_surface/` + `tests/it/parse_error_pedagogy.rs`) as the definition of done, test-first; **(2)** **friendlier literal expectation labels** — optional prose glosses on `Word`/`Punct`/`Flag` positions that *add* role context while always keeping the exact literal visible (e.g. "a filter clause: `where …` or `--all-rows`"); **(3)** **advanced-mode SQL** near-miss parity (RETURNING scope, CTE-arity positioning, `CROSS JOIN … ON`, INSERT…SELECT count) — **in scope**, kept distinct from ADR-0019 §OOS-2 which covers advanced-SQL *engine*-error sanitisation, a different layer. Catalog/anchor-phrase discipline (ADR-0019) preserved; no public API change. OOS: I3/I4, spell-correction, multi-error reporting, verbosity-gating the usage block
|
||||
- [ADR-0043 — Compound-primary-key foreign-key references (T3)](0043-compound-pk-foreign-key-references.md) — **Accepted + implemented 2026-06-09** (all four forks confirmed at the recommended option: full-PK matching, house-style uniform lists, parenthesized DSL syntax, bare-SQL-FK auto-expansion). Closes `requirements.md` **T3** `[x]` — the relationship model went list-based across six layers (single-column preserved, no migration), DSL `from P.(a,b) to C.(x,y)` + SQL `FOREIGN KEY (a,b) REFERENCES P(x,y)` parse/execute/enforce, 12 tests in `tests/it/compound_fk.rs`. Closes the open leg of `requirements.md` **T3**: a foreign key that *references* a parent's compound primary key. A 2026-06-09 audit found single-column FK woven through ~15–20 sites (metadata table, `RelationshipSchema`, `project.yaml` `RawEndpoint`, both grammar surfaces, executor FK-DDL emission, per-column type-compat, display) — earns an ADR, not an inline build. **Decision:** reference the parent's **full** compound PK, matched **positionally** to an equal-length child column list, per-pair `fk_target_type` compat (ADR-0011, element-wise); DSL `from <P>.(a, b) to <C>.(x, y)` (single form unchanged), SQL `FOREIGN KEY (x, y) REFERENCES P(a, b)` (extend the existing one-cap lists; bare table-level FK auto-expands to the parent PK when arities match). **Storage — no migration (back-compat not required, user-confirmed 2026-06-09; no installed base):** the relationship endpoint joins the list convention `project.yaml` *already* uses — `columns: [a, b]` like `primary_key: [id]` and index `columns: [...]` (the endpoint was the lone scalar `column:` holdout); the metadata `TEXT` columns are unchanged and store the list **comma-joined** (`a,b`; the bare name for single — safe because identifiers are `[A-Za-z0-9_]+`). No F3 migrator, no version bump; accepted trade-off is that a pre-change `project.yaml` with relationships won't load (clean cutover). In-memory model goes list-based (`Vec<String>`) through all six layers; the enforced FK is the rebuilt child-table DDL (`FOREIGN KEY (a,b) REFERENCES P(x,y)`), one relationship = one undo step (ADR-0013). Genuine forks escalated: matching policy (full-PK vs subset), storage (house-style uniform lists vs normalized table), DSL syntax (parenthesized vs repeated-dotted), bare-SQL-FK auto-expansion. OOS: subset/non-PK (UNIQUE-targeted) FK references; any single-column behaviour change
|
||||
- [ADR-0044 — Public website and documentation site](0044-public-website-and-documentation-site.md) — **Accepted 2026-06-04** (originally drafted as ADR-0042 on the `website` branch; renumbered on merge to avoid colliding with the H1a ADR-0042). The first public website: a marketing landing page plus the **canonical** user docs. Stack **Astro 6 + Starlight + Tailwind v4** (chosen over SvelteKit + Tailwind for a docs-heavy + marketing site; interactive bits as Astro islands). Showcase demos are **asciinema** `.cast` recordings (scripted-input driver for paced, re-recordable sessions — *not* `history.log` replay), reused inline in docs. The **in-page WASM playground is deferred** (OOS: deferred) behind a stable `Demo` seam, with the portable-core (`dsl`/`app`/`ui`, in-memory `rusqlite` via `ffi-sqlite-wasm-rs`) vs native-edge (Tokio/worker-thread/`crossterm`/persistence/backup-API) boundary recorded for a future ADR + iteration plan. Portable **static build** (Vercel target, but host-agnostic); **no CI yet**; **monorepo** (`website/`). Docs cover the **full supported feature set** with "planned" callouts for the unshipped minority; two wording rules bind user-facing copy — **no engine name** (continues ADR-0002) and **no "DSL"** ("simple mode" / "advanced mode"). Install docs cover **prebuilt binaries + package managers** (D1–D3 track the release tooling). Plan: `docs/plans/20260604-adr-0044-website.md`
|
||||
|
||||
Reference in New Issue
Block a user