Merge branch 'main' into website
This commit is contained in:
claude@clouddev1
@@ -70,3 +70,65 @@ True UUIDs are intentionally **not** in the type set.
|
||||
- Learners who later need a true UUID column will find that the
|
||||
app does not provide one; this is a deliberate trade-off in
|
||||
favour of TUI legibility.
|
||||
|
||||
## Amendment 1 — display rounding of coerced doubles (2026-06-12)
|
||||
|
||||
Issue #32. The Decision keeps `decimal` exact by storing it as
|
||||
TEXT, noting that "numeric ops require casts" — the engine has no
|
||||
native decimal/BCD type (SQLite's storage classes are only NULL /
|
||||
INTEGER / REAL / TEXT / BLOB; `NUMERIC` is an affinity, not a
|
||||
type). What the original wording did not anticipate is that the
|
||||
engine performs that cast **implicitly**: `sum(price * qty)` over
|
||||
TEXT decimals coerces to an IEEE-754 double with no explicit cast,
|
||||
and the computed result carries no playground type (ADR-0030 §6),
|
||||
so it rendered with the double's full noise —
|
||||
`298.59999999999997` for `298.60`. For a teaching tool that is a
|
||||
confusing, off-topic lesson about float representation.
|
||||
|
||||
### Decision
|
||||
|
||||
**Round floating-point values to 15 significant figures for
|
||||
display only.** A double carries ~15–17 significant decimal digits
|
||||
and the noise lives in the last one or two; rounding to 15 then
|
||||
taking the shortest round-tripping form of the rounded value
|
||||
collapses `298.59999999999997` → `298.6` and
|
||||
`0.30000000000000004` → `0.3`. A clean value rounds to itself, so
|
||||
the result is never longer than before; non-finite values pass
|
||||
through. Implemented as `format_real_display` in `db.rs`.
|
||||
|
||||
The rounding is wired into **exactly one place — `format_cell`,
|
||||
the result-set / `show data` cell formatter** — because that is
|
||||
the only surface where the IEEE-754 noise actually appears: noise
|
||||
arises from *arithmetic/aggregation*, whose results flow through
|
||||
`format_cell`. Every other `f64`-to-string path deliberately keeps
|
||||
full precision, and the distinction is **semantic, not cosmetic**:
|
||||
|
||||
- **Persistence stays exact.** The CSV encoder
|
||||
(`persistence::csv_io::format_real`) keeps the shortest
|
||||
round-tripping form so a stored `real` survives save/load
|
||||
byte-for-byte — rounding there would corrupt data.
|
||||
- **Uniqueness dry-runs key on exact values.** `render_value`
|
||||
(the diagnostic/echo formatter) is reused as a *canonical
|
||||
identity key* by `dry_run_unique` (ADR-0029 §5) and
|
||||
`check_uniqueness_collisions` (ADR-0017 §4.3): they group rows
|
||||
by this string to predict the duplicates the engine would
|
||||
reject. Rounding there would merge two distinct doubles into one
|
||||
key and report a collision the engine — which compares exact
|
||||
values — would not. So `render_value` keeps `format!("{r}")`.
|
||||
(It also never displays a *computed* value, so it has no noise
|
||||
to trim.)
|
||||
- **FK-key matching and EXPLAIN-SQL literals keep full
|
||||
precision** — neither is a data-cell display.
|
||||
|
||||
Within `format_cell` the rounding applies to **all** REAL cells
|
||||
(stored `real` columns and computed results alike), for one
|
||||
consistent rule; the lost digits are at the double's precision
|
||||
limit, not real information, and a stored `real` typed by the user
|
||||
is itself noise-free so its display is unchanged in practice. Raw
|
||||
`decimal` columns are unaffected — they are TEXT and render
|
||||
verbatim, trailing zeros and all (`100.10`). Exact decimal
|
||||
*arithmetic* (a SQLite extension exposing
|
||||
`decimal_mul`/`decimal_sum`) was considered and rejected: it would
|
||||
require rewriting the user's standard-SQL operators into function
|
||||
calls, defeating both the "validated SQL runs verbatim" model and
|
||||
the goal of teaching ordinary SQL.
|
||||
|
||||
@@ -213,6 +213,14 @@ working copy.
|
||||
|
||||
### 6. Persistence ordering
|
||||
|
||||
> **Amended by ADR-0052 (2026-06-13, issue #30):** `history.log` is no
|
||||
> longer written inside the worker transaction. It is a *journal* of typed
|
||||
> commands, not state, so success journaling moved to the dispatch layer
|
||||
> (next to the already-top-level failure journaling); `commit-db-last` now
|
||||
> governs the three **state** targets only (db + `project.yaml` +
|
||||
> `data/*.csv`), which still commit atomically in the worker. The journal
|
||||
> write is best-effort (amends ADR-0040).
|
||||
|
||||
A successful user command produces effects in four targets:
|
||||
the SQLite database, `project.yaml`, the relevant
|
||||
`data/<table>.csv` file(s), and `history.log`. INV-2 from the
|
||||
|
||||
@@ -197,6 +197,16 @@ Referenced by:
|
||||
The relationship sections retain today's plain-text format
|
||||
to leave room for the future relationship-rendering ADR.
|
||||
|
||||
> **Superseded.** ADR-0044 replaced this prose block with compact
|
||||
> diagrams on relationship-subject surfaces (`show table`,
|
||||
> `add`/`drop relationship`). **ADR-0050 (2026-06-12, issue #28)** then
|
||||
> removed the relationship block entirely from incidental-DDL structure
|
||||
> echoes (`create table`, `add`/`drop`/`rename`/`change column`,
|
||||
> `add`/`drop index`) — those render structure only — and **deleted the
|
||||
> prose renderer**. The `References:` / `Referenced by:` format above is
|
||||
> retained here as documentation/provenance should the OOS-7
|
||||
> always-prose display setting ever be built.
|
||||
|
||||
### 6. Theme integration
|
||||
|
||||
Theme colors apply to the box-drawing characters via the
|
||||
|
||||
@@ -772,6 +772,58 @@ invalid_ident_does_not_fire_for_column_prefix_at_sql_expr_slot}`;
|
||||
`theme::function_colour_is_distinct_from_keyword_identifier_and_type`.
|
||||
See ADR-0031's status note for the grammar-side anchor.
|
||||
|
||||
## Amendment 7 — optional positional args reach the hint panel (2026-06-12)
|
||||
|
||||
Issue #26. At `seed <table> ▮` the hint panel showed only the
|
||||
`set` / `--seed` continuation chips and never mentioned the
|
||||
**optional row count** — even though a count (`seed users 50`) is
|
||||
the most common next move. The count is a bare positional
|
||||
`NumberLit` with no keyword/candidate text, so the candidate ladder
|
||||
can't surface it; and `seed <table>` is already a *complete*
|
||||
command, so the hint resolver short-circuits (empty expected set).
|
||||
|
||||
The existing `IntroProse` `HintMode` (ADR-0024 §HintMode-per-node;
|
||||
issue #4's CREATE-TABLE element hint) is the right tool — it shows
|
||||
prose that *introduces* a position whose first-class move has no
|
||||
candidate, with the keyword alternatives folded into the prose and
|
||||
Tab still cycling them. But it did not reach this position: a
|
||||
`Node::Hinted`'s mode lives in `pending_hint_mode`, which the very
|
||||
next match clears — including the **empty** match of a skipped
|
||||
`Optional`. The CREATE-TABLE element survives only because it sits
|
||||
in a *required* `Repeated(min:1)`; an optional positional followed
|
||||
by more optionals (the seed count) is cleared before the resolver
|
||||
reads it.
|
||||
|
||||
### Mechanism
|
||||
|
||||
A small, general carry: when `walk_optional` skips its inner (the
|
||||
inner didn't engage), it stashes any `IntroProse` key the inner
|
||||
left in `pending_hint_mode` into a new `WalkContext` field,
|
||||
`surviving_intro_hint: Option<(key, position)>`, **before** the
|
||||
empty match clears `pending_hint_mode`. The trailing optionals,
|
||||
which are not `IntroProse`, don't overwrite it. The hint snapshot
|
||||
keeps the key **only when `position == cursor`** (the slice end),
|
||||
so it shows while the cursor sits at the count slot but not once a
|
||||
later clause (`set …`) consumes input past it, nor once the count
|
||||
itself is supplied. The resolver returns that `IntroProse` even for
|
||||
an otherwise-complete command (ahead of the empty-expected
|
||||
short-circuit).
|
||||
|
||||
The seed grammar wraps the count in
|
||||
`Hinted { IntroProse("hint.seed_count"), NumberLit }`; the prose
|
||||
names the count (with its default 20) plus the `.column`
|
||||
column-fill form and the `set` / `--seed` keywords (user-chosen
|
||||
scope: mention every option). Only `IntroProse` is carried —
|
||||
`ProseOnly` / `ForceProse` mark *active* slots and reach the
|
||||
resolver through the normal path, unchanged. The CREATE-TABLE
|
||||
element (in a `Repeated`, not an `Optional`) is untouched.
|
||||
|
||||
This is a refinement of ADR-0024 §HintMode-per-node and a sibling
|
||||
of issue #4; no `AmbientHint` / renderer change. Covered by
|
||||
`input_render::{seed_count_is_advertised_at_the_optional_position,
|
||||
seed_count_hint_does_not_leak_once_the_count_or_a_clause_is_given,
|
||||
seed_count_hint_also_fires_after_a_column_fill_target}`.
|
||||
|
||||
## Out of scope
|
||||
|
||||
Deliberately deferred to keep this ADR shippable as a single
|
||||
|
||||
@@ -1480,6 +1480,76 @@ accumulators), the per-keystroke re-walk (ADR-0027's
|
||||
debounced cadence), and the ORDER BY no-fixup-needed
|
||||
clarification.
|
||||
|
||||
## Amendment 3 — bare table aliases in expression slots (2026-06-12)
|
||||
|
||||
Issue #31. A bare in-scope table alias typed where the grammar
|
||||
expects a column — `… GROUP BY o`, with `o` aliasing
|
||||
`FROM Orders o` — was a blind spot in two surfaces:
|
||||
|
||||
- **Completion (§10).** §10.5 narrows columns *past* a
|
||||
`qualifier .`, but the bare-ident slot before the dot offered
|
||||
only columns and function names, never the aliases themselves.
|
||||
A learner mid-typing `o` toward `o.<column>` got no Tab help.
|
||||
- **Diagnostics (§11.2).** §11.2 added `projection_alias_misplaced`
|
||||
for a *projection* alias used in a forbidden clause, but a bare
|
||||
*table* alias fell through to the generic `unknown_column`
|
||||
bare-reference check (§11.2's `matched.len() == 0` arm), which
|
||||
reported `no such column \`o\` on table \`Orders, …\`` — calling
|
||||
an in-scope alias an unknown column.
|
||||
|
||||
### What changes
|
||||
|
||||
1. **Completion offers in-scope FROM qualifiers at a bare
|
||||
`sql_expr_ident` slot** (one not already past a `qualifier .`).
|
||||
Each binding contributes its *qualifier* — the alias if it has
|
||||
one, else the table name (an aliased source must be referenced
|
||||
by its alias). Folded into the existing `IdentSource::Columns`
|
||||
candidate list so it sorts / dedups / colours uniformly. When
|
||||
the partial *exactly* matches an in-scope qualifier the alias
|
||||
source steps aside: discoverability is already served, and
|
||||
suppressing sibling aliases lets the diagnostic below surface
|
||||
(rather than being hidden by the `typing_over_diag` path).
|
||||
|
||||
2. **A bare ident matching an in-scope qualifier now emits a
|
||||
targeted diagnostic** instead of `unknown_column`, checked in
|
||||
the `matched.len() == 0` arm *after* the projection-alias check
|
||||
(so an ORDER-BY projection-alias reference still wins). It is a
|
||||
drop-in replacement at the same span and `Error` severity — only
|
||||
the message text changes — so the validity verdict, token
|
||||
overlay, and hint-panel paths behave exactly as they did for
|
||||
`unknown_column`:
|
||||
- `diagnostic.alias_used_as_column` — `` `o` is a table alias —
|
||||
write `o.<column>` to reference one of its columns `` (the
|
||||
binding has an alias), or
|
||||
- `diagnostic.table_used_as_column` — same shape, "is a table"
|
||||
(an un-aliased table source).
|
||||
|
||||
Two guards keep the qualified-form advice correct (both covered
|
||||
by regression tests):
|
||||
- **SQL only.** The branch fires only for `role ==
|
||||
"sql_expr_ident"`. The DSL `Expr` (role `expr_column`) reaches
|
||||
the same arm but has no `table.column` syntax, so a DSL bare
|
||||
table-name ref keeps the generic `unknown_column` — advising
|
||||
the qualified form there would be wrong.
|
||||
- **Effective-qualifier match.** It matches the binding's
|
||||
*effective qualifier* — the alias if present, else the table
|
||||
name — not the table name independently. An aliased source
|
||||
must be referenced by its alias (`FROM a x … GROUP BY a` is
|
||||
invalid SQL), so the shadowed real name `a` falls through to
|
||||
`unknown_column` rather than being advised as `a.<column>`.
|
||||
This mirrors the completion side's qualifier rule exactly.
|
||||
|
||||
A genuine unknown column (matching no alias, table, or column)
|
||||
still reports `unknown_column` verbatim.
|
||||
|
||||
The message tail is deliberately clause-neutral ("to reference
|
||||
one of its columns") rather than GROUP-BY-specific, because the
|
||||
bare-reference arm fires across the projection, `WHERE`,
|
||||
`GROUP BY`, and `HAVING`.
|
||||
|
||||
This is an additive refinement of §10 and §11.2; no grammar node
|
||||
changes.
|
||||
|
||||
## See also
|
||||
|
||||
- ADR-0005 — the ten-type vocabulary §10 resolves back to.
|
||||
|
||||
@@ -2,7 +2,13 @@
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
Accepted. **Amended by ADR-0052 (2026-06-13, issue #30):** the status
|
||||
field gains an optional `:adv` mode suffix (`ok:adv` / `err:adv`) — the
|
||||
"non-breaking future extension" this ADR reserved — and **success
|
||||
journaling moves out of the worker to the dispatch layer**
|
||||
(`spawn_dsl_dispatch` / `run_replay` / app-command sites), next to the
|
||||
failure path, where the submission mode is in scope. `status_is_ok` keys
|
||||
off the base token, so `ok:adv` replays like `ok`.
|
||||
|
||||
## Context
|
||||
|
||||
|
||||
@@ -5,7 +5,11 @@
|
||||
**Accepted** — 2026-05-30 (issue #9). Amends the output conventions of
|
||||
ADR-0014 (data operations), ADR-0028 (query plans / `explain`), and
|
||||
ADR-0019 (failure rendering); builds on ADR-0037's mode-tagged echo
|
||||
line.
|
||||
line. **Amended by ADR-0052 (2026-06-13, issue #30):** a `history.log`
|
||||
*journal*-write failure on a **successful** command is no longer fatal —
|
||||
journaling moved to the dispatch layer (after the db commit), so it is
|
||||
best-effort (logged + ignored), consistent with the failure-journal path.
|
||||
State-write failures (yaml/csv/db) remain fatal.
|
||||
|
||||
## Context
|
||||
|
||||
|
||||
@@ -103,6 +103,10 @@ Prose-retained surfaces (**unchanged** from ADR-0016 §5):
|
||||
`add`/`drop index` — keep the terse `References:` /
|
||||
`Referenced by:` prose. A simple `add column` on a heavily-related
|
||||
table should not print a wall of diagrams.
|
||||
*(**Superseded 2026-06-12 by ADR-0050** (issue #28): these incidental
|
||||
DDL echoes now render **structure only** — no relationship block at
|
||||
all, neither prose nor diagram. The prose renderer was deleted. The
|
||||
diagram surfaces below are unchanged.)*
|
||||
|
||||
So this **partially supersedes ADR-0016 §5**: the prose block is
|
||||
replaced by diagrams on the relationship-subject surfaces and
|
||||
|
||||
@@ -525,7 +525,9 @@ All tiers green, zero skips; clippy clean (nursery).
|
||||
submits over a multi-logical-line buffer. DA3/DA4 keep a single
|
||||
logical line; this remains a separate, deferred feature.
|
||||
- **Readline shortcuts (I1b)** — Ctrl-A/E/W/K/U stay reserved-deferred;
|
||||
not touched here.
|
||||
not touched here. *(Superseded 2026-06-12: I1b is now in scope and
|
||||
decided by **ADR-0049** — Esc-clear + Ctrl-A/E/W/K/U in the input
|
||||
field, issue #29.)*
|
||||
- **Cross-session sidebar persistence** — visibility is session-only
|
||||
(DB1); persisting it would amend ADR-0015.
|
||||
- **The output panel as a third navigation focus target** — navigation
|
||||
@@ -554,3 +556,27 @@ All tiers green, zero skips; clippy clean (nursery).
|
||||
and is accepted: 90 is the screencast width, real terminals sit well
|
||||
to one side of it, and `Ctrl-O` peek covers the in-between case. The
|
||||
`90` threshold is a tunable constant.
|
||||
|
||||
## Amendment 1 — focus accent is a colour, not bold (2026-06-12)
|
||||
|
||||
Issue #25. DC3's "accent border" on the focused sidebar panel was
|
||||
first implemented as bright `theme.fg` **plus `Modifier::BOLD`** on
|
||||
the box-drawing border. Bold box-drawing glyphs render as broken /
|
||||
gapped line-art in the asciinema player used for the website casts
|
||||
(vertical strokes don't connect to the corner glyphs) and are
|
||||
fragile in some terminals.
|
||||
|
||||
**`panel_border_style` now marks focus with a non-bold accent
|
||||
colour — `theme.mode_simple` (blue) — and never `Modifier::BOLD` on
|
||||
a border.** The unfocused border stays muted `theme.border`. This
|
||||
makes the ADR's "accent border (lazygit convention)" wording
|
||||
literal — it is now a true accent hue rather than bold bright-fg —
|
||||
and is what renders cleanly in casts. Bold remains fine on *text*
|
||||
spans (titles, key hints); the constraint is specifically that
|
||||
box-drawing borders carry no bold attribute.
|
||||
|
||||
Note: this is a pure style change. The Tier-2 snapshots are
|
||||
text-only (`render_to_string` captures cell symbols, not styles),
|
||||
so none needed re-accepting; the Tier-1 `panel_border_style`
|
||||
assertion was updated and a render-level test now checks the actual
|
||||
border cells carry the accent colour and no bold.
|
||||
|
||||
@@ -317,6 +317,8 @@ with the implementation):
|
||||
| `url`/`website`/`homepage` · `color`/`colour` | URL / hex colour | text |
|
||||
| `price`/`amount`/`cost`/`salary`/`balance`/`total` | currency-range number | numeric |
|
||||
| `age` · `quantity`/`qty`/`stock`/`count` | 18–80 · small int | numeric |
|
||||
| `year`/`*_year`/`published`/`founded` (Amendment 1) | bounded year (birth window for `birth`/`born`/`dob`, else 1950–2025) | int |
|
||||
| `priority`/`prio` · `severity` · `rating`/`stars` (Amendment 1) | built-in `PickFrom` value set | text/int |
|
||||
| `date`/`*_date` | date, recent ~3 yr window | date |
|
||||
| `dob`/`birthday` | date, adult window (18–80 yr ago) | date |
|
||||
| `timestamp`/`datetime` · `created_at`/`updated_at`/`*_at` | datetime, recent window (`updated_at` ≥ `created_at`) | datetime |
|
||||
@@ -675,3 +677,66 @@ the regression floor.
|
||||
derive-`IN`-else-friendly-fail tier.
|
||||
- **`set`-driven NULL / per-column report / recursive parent seed:**
|
||||
deferred — see Out of scope.
|
||||
|
||||
## Amendment 1 — year-as-int + conventional choice sets (2026-06-12)
|
||||
|
||||
Two SD2-style refinements to the D7 catalogue, surfaced while writing
|
||||
the website `seed` docs. Both are additive name rules; no change to D8
|
||||
(type fallback), the executor, or the grammar.
|
||||
|
||||
### Issue #33 — year-like `int` columns
|
||||
|
||||
A column such as `published` or `birth_year` was just an `int`, so it
|
||||
fell through to the unbounded type-based `int` path (D8) and produced
|
||||
nonsense like `9419` or `1426` — implausible as years, undercutting the
|
||||
"realistic data" pedagogy. Added an **`int`-gated** year rule, placed
|
||||
*after* the quantity rule (so `year_count` stays a count):
|
||||
|
||||
- `year` / `*_year` / `published` / `founded` → **`YearRecent`**, a
|
||||
bounded window of **1950–2025** (75 years relative to the fixed
|
||||
`REF_YEAR`, wide enough for published books / founding years /
|
||||
release years; matches the issue's own `between 1950 and 2020`
|
||||
workaround).
|
||||
- the same with a `birth` / `born` / `dob` token (e.g. `birth_year`) →
|
||||
**`YearBirth`**, mirroring the existing `dob → DateAdult` adult birth
|
||||
window as years (**1945–2007**).
|
||||
|
||||
Both emit a plain `int`. `published` / `founded` are included
|
||||
(user-confirmed): an `int` so named is almost always a year (a flag
|
||||
would be `is_published`). The generators are **not** added to the D9
|
||||
named-generator vocabulary — explicit control stays with `set <col>
|
||||
between <lo> and <hi>`.
|
||||
|
||||
### Issue #34 — built-in value sets for conventional choice names
|
||||
|
||||
D12 deliberately does not guess values for enum-ish names. For a few,
|
||||
though, there is a near-canonical small set that reads far better than
|
||||
lorem text. Added a **type-gated `PickFrom`** lookup (reusing the
|
||||
existing generator — no new machinery), placed ahead of the enum-ish
|
||||
fallthrough:
|
||||
|
||||
| Name (tokens) | text | int |
|
||||
|---|---|---|
|
||||
| `priority` / `prio` | `low`/`medium`/`high` | `1`/`2`/`3` |
|
||||
| `severity` | `low`/`medium`/`high`/`critical` | `1`/`2`/`3`/`4` |
|
||||
| `rating` / `stars` | — | `1`–`5` |
|
||||
|
||||
A user-declared `IN`-CHECK (D17) still wins — it is resolved before the
|
||||
heuristics. Any name that gains a set is **removed from the enum-ish
|
||||
advisory trigger** (`priority` left `ENUM_TOKENS`); since the advisory
|
||||
(D13) only fires on `Generator::Generic`, a `PickFrom` name is excluded
|
||||
either way, but the removal keeps `is_enum_ish` semantically "names seed
|
||||
still can't guess".
|
||||
|
||||
**`status` is deliberately excluded** (user-confirmed on the issue): its
|
||||
real values are too domain-specific (`active/inactive`,
|
||||
`open/closed/pending`, `draft/published`, …), so it keeps the D12
|
||||
"don't guess" stance — generic text + the advisory pointing at `set
|
||||
status in (…)`. `state` stays its US-state-name generator (D7);
|
||||
`type`/`kind`/`category`/`stage`/`gender` and `size`/`tier`/`plan` were
|
||||
considered and left to the advisory.
|
||||
|
||||
**Website follow-up** (tracked on the `website` branch, not here): the
|
||||
`seed` cast exercises a `tickets` table with `priority`; it should be
|
||||
re-recorded so the table tightens once `priority` collapses to a short
|
||||
value — likely subsumed by the pre-publication cast sweep.
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
# ADR-0049: Input-field readline keymap — Esc-clear + Ctrl-A/E/W/K/U (I1b)
|
||||
|
||||
## Status
|
||||
|
||||
**Accepted + implemented 2026-06-12 (issue #29).** Closes Gitea **#29**
|
||||
("Command input keystroke support") and the deferred **I1b** readline
|
||||
requirement in `requirements.md`. Every fork below was escalated to the
|
||||
user and user-chosen before any code was written; implemented test-first
|
||||
(22 new Tier-1 tests in `src/app.rs`, all green; clippy nursery clean).
|
||||
|
||||
This ADR **amends ADR-0046**, which explicitly listed "readline
|
||||
shortcuts (I1b)" in its out-of-scope set: that item is now in scope and
|
||||
decided here. It is orthogonal to ADR-0003's input-*mode* model (simple
|
||||
vs advanced, the `:` sigil) — these are editing keys within the input
|
||||
field, not mode or sigil changes — and it extends the single-line cursor
|
||||
editing already shipped under requirement **I1a** (Left/Right/Home/End/
|
||||
Backspace/Delete, `app.rs`).
|
||||
|
||||
## Context
|
||||
|
||||
The input field already supported in-line cursor editing (I1a): Left/
|
||||
Right by char (UTF-8 aware), Home/End to the extremes, Backspace/Delete.
|
||||
Two gaps remained, raised in issue #29:
|
||||
|
||||
1. No way to **clear a partly-typed command** in one keystroke — a user
|
||||
who started typing the wrong thing had to hold Backspace.
|
||||
2. No **readline cursor/kill shortcuts** (Ctrl-A/Ctrl-E and friends) for
|
||||
keyboards without Home/End and for muscle-memory in a command-driven
|
||||
workflow. This is requirement I1b, deferred by ADR-0046.
|
||||
|
||||
`Esc` was free in the input field except that a *live Tab-completion
|
||||
memo* consumes it first (to undo the completion in one keystroke,
|
||||
ADR-0022). Ctrl-A/E/W/K/U were unbound. The existing chords are Ctrl-C
|
||||
(quit), Ctrl-O (nav focus cycle, ADR-0046), and Ctrl-`]` (demo caption
|
||||
toggle, ADR-0047) — none collide with a/e/w/k/u.
|
||||
|
||||
## Decision
|
||||
|
||||
Bind the following in the input field (non-modal, non-navigation,
|
||||
both input modes), in `App::handle_key`:
|
||||
|
||||
| Key | Action |
|
||||
|-----------|---------------------------------------------------|
|
||||
| `Esc` | Clear the input (empty buffer, cursor→0, scroll→0)|
|
||||
| `Ctrl-A` | Cursor to line start (alias of Home) |
|
||||
| `Ctrl-E` | Cursor to line end (alias of End) |
|
||||
| `Ctrl-W` | Delete the word before the cursor |
|
||||
| `Ctrl-K` | Kill from the cursor to end of line |
|
||||
| `Ctrl-U` | Kill from start of line to the cursor |
|
||||
|
||||
Behavioural rules:
|
||||
|
||||
- **Esc precedence.** A live completion memo still wins: the first Esc
|
||||
undoes the completion (ADR-0022), and Esc only *clears* when no memo
|
||||
is alive. This is a natural progression — Esc once to back out the
|
||||
completion, Esc again to clear.
|
||||
- **Esc does not clear while navigating the sidebar.** When a sidebar
|
||||
panel is focused (Ctrl-O, ADR-0046 DC3), `handle_key` routes every
|
||||
key to the navigation handler *before* the input-field keymap, where
|
||||
Esc exits navigation mode (`nav_exit`). Entering nav mode never
|
||||
touched the input buffer, so Esc-to-close-the-panel returns focus to
|
||||
the input with the partly-typed command intact — it cannot reach the
|
||||
clear binding. Locked by a regression test.
|
||||
- **Single Esc clears** (user-chosen over double-Esc). Discoverable and
|
||||
fast; the trade-off (an accidental Esc wipes an unsubmitted line) was
|
||||
accepted. A submitted line is always recoverable from history; only
|
||||
*unsubmitted* draft text is lost.
|
||||
- **Cursor-only keys don't touch history navigation.** Ctrl-A/Ctrl-E,
|
||||
like Home/End, move the cursor without ending history recall.
|
||||
- **Buffer-mutating keys end history navigation.** Esc-clear and
|
||||
Ctrl-W/K/U call `cancel_history_navigation` (the cleared/edited line
|
||||
*is* the new draft), matching Backspace/Delete.
|
||||
- **Ctrl-W is readline-style and UTF-8 safe.** It eats any run of
|
||||
trailing whitespace, then the preceding run of non-whitespace; word
|
||||
boundaries are found on char boundaries so multi-byte words delete
|
||||
cleanly. It only ever deletes back to the cursor (a mid-line Ctrl-W
|
||||
leaves the suffix intact).
|
||||
|
||||
Helpers added: `clear_input`, `delete_prev_word`, `kill_to_end`,
|
||||
`kill_to_start` (`src/app.rs`), mirroring the existing `cursor_left` /
|
||||
`delete_before_cursor` style.
|
||||
|
||||
## Forks (all user-chosen)
|
||||
|
||||
- **Esc semantics:** single-Esc-clears, *not* double-Esc — discoverable
|
||||
over accident-proof.
|
||||
- **Scope:** the *full* I1b set (Esc-clear + Ctrl-A/E/W/K/U), not just
|
||||
the issue's literal Ctrl-A/E + Esc — closes the whole I1b requirement
|
||||
in one pass rather than leaving Ctrl-W/K/U for a follow-up.
|
||||
- **Documentation:** a new ADR (this one), recording the input-field
|
||||
keymap convention and amending ADR-0046's OOS list — over folding it
|
||||
into ADR-0046 or shipping it I1a-style with no ADR.
|
||||
|
||||
## Consequences
|
||||
|
||||
- I1b is complete; `requirements.md` I1b moves to `[x]`.
|
||||
- The new keys are **not yet advertised on screen.** Surfacing per-focus
|
||||
keybindings in the bottom status line is issue #27's domain (a
|
||||
separate, in-design UX change); this ADR makes the keys *work*, #27
|
||||
will make them *discoverable*.
|
||||
- **Demo-mode badges** (ADR-0047) are *not* extended to the new Ctrl-
|
||||
chords here. Esc already badges as `[ESC]`; Ctrl-A/E/W/K/U are
|
||||
glyph-less and would be invisible in an asciinema cast. Whether to add
|
||||
`[CTRL-A]`…`[CTRL-U]` badges is left to ADR-0047's scope and flagged
|
||||
as a follow-up — it is a cast-polish concern, not a #29 requirement.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- On-screen keybinding hints for the input field (issue #27).
|
||||
- Demo badges for the new chords (ADR-0047 follow-up; flagged above).
|
||||
- Multi-line input (I1) and its Ctrl-Enter submit — unrelated, still
|
||||
deferred.
|
||||
- Word-wise *cursor motion* (Alt-B/Alt-F) and transpose/yank — not
|
||||
requested; not part of I1b.
|
||||
@@ -0,0 +1,119 @@
|
||||
# ADR-0050: Incidental-DDL confirmations omit relationship info (structure-only)
|
||||
|
||||
## Status
|
||||
|
||||
**Accepted + implemented 2026-06-12 (issue #28).** Closes Gitea **#28**.
|
||||
Both forks below were escalated to the user and user-chosen before any
|
||||
code was written; implemented test-first. **Supersedes** the
|
||||
incidental-DDL clause of **ADR-0044 §1** and the part of **ADR-0016 §5**
|
||||
that placed a relationship block under every structure echo. The
|
||||
diagram behaviour ADR-0044 introduced for relationship-subject surfaces
|
||||
is unchanged.
|
||||
|
||||
## Context
|
||||
|
||||
ADR-0016 §5 rendered a structure box followed by a plain-text
|
||||
`References:` / `Referenced by:` relationship block under **every**
|
||||
structure echo. ADR-0044 §1 split that by surface:
|
||||
|
||||
- **Relationship-subject surfaces** — `show table <T>`,
|
||||
`add 1:n relationship`, `drop relationship`, `show relationship <name>`
|
||||
— render relationships as compact **diagrams** (the user asked for, or
|
||||
acted on, a relationship).
|
||||
- **Incidental DDL auto-shows** — `create table`, `add`/`drop`/`rename`/
|
||||
`change column`, `add`/`drop index` — kept the terse **prose** block,
|
||||
with the rationale *"a simple `add column` on a heavily-related table
|
||||
should not print a wall of diagrams."*
|
||||
|
||||
Issue #28 reconsiders the deeper question ADR-0044 did not ask: should
|
||||
an incidental-DDL confirmation show relationship information **at all**?
|
||||
Owner preference: **no.** A confirmation echo should focus on the change
|
||||
just made — the new / updated structure — not re-print the table's
|
||||
relationships, which the user did not touch. The terse prose was the
|
||||
lesser of "prose vs diagram", but the right answer for these surfaces is
|
||||
**neither**.
|
||||
|
||||
## Decision
|
||||
|
||||
**Incidental-DDL confirmation echoes render the structure only** — the
|
||||
table-name header, the column / type / constraints box, the `Indexes:`
|
||||
section, and the constraint section — with **no relationship section**
|
||||
(neither prose nor diagram).
|
||||
|
||||
- **Scope: all incidental DDL** (user-chosen, over "just `add column`"):
|
||||
`create table`, `add column`, `drop column`, `rename column`,
|
||||
`change column`, `add index`, `drop index`. The rule is uniform — a
|
||||
structural edit confirms structure, never relationships. (For a
|
||||
freshly `create`d table the relationship section was empty anyway; the
|
||||
rule still applies for consistency of the mental model.)
|
||||
- **Relationship-subject surfaces are unchanged.** `show table`,
|
||||
`add`/`drop relationship`, and `show relationship <name>` still render
|
||||
diagrams. Relationships appear **only** when the user asks for them
|
||||
(`show table` / `show relationship`) or acts on one
|
||||
(`add`/`drop relationship`).
|
||||
- **No information is lost.** Anything dropped from an incidental echo is
|
||||
one `show table <T>` away.
|
||||
|
||||
### Mechanism
|
||||
|
||||
The `handle_dsl_success` routing (`app.rs`) is **unchanged**: it still
|
||||
sends relationship-subject commands to the diagram renderer and
|
||||
everything else to `render_structure`. The change is entirely inside
|
||||
`render_structure` (`output_render.rs`): it no longer appends the
|
||||
relationship block — `render_structure` = structure box + indexes +
|
||||
constraints. All of `render_structure`'s callers are incidental DDL
|
||||
(verified), so this single edit covers the whole scope with no
|
||||
per-command branching.
|
||||
|
||||
### Prose renderer disposition
|
||||
|
||||
The orphaned prose renderer (`relationship_prose_lines`, and its
|
||||
sole helper `cols_disp`) is **deleted** (user-chosen, over retaining it
|
||||
dormant). After this change no shipped surface renders the prose form,
|
||||
so keeping it would be dead code. The prose format remains documented in
|
||||
**ADR-0016 §5** and in git history; if ADR-0044's OOS-7 user-configurable
|
||||
"always-prose" display setting is ever built, it re-introduces the ~30
|
||||
lines from that provenance.
|
||||
|
||||
## Forks (all user-chosen)
|
||||
|
||||
- **Scope:** *all incidental DDL*, not just `add column` — the owner's
|
||||
rationale ("confirm the change, not untouched relationships") applies
|
||||
uniformly, gives a clean mental model, and is the simpler edit (remove
|
||||
one call vs a per-command flag).
|
||||
- **Prose renderer:** *delete* it — no dead code — over retaining a
|
||||
public, tested-but-uncalled renderer for the speculative OOS-7 setting.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Incidental confirmations are shorter and on-topic; a heavily-related
|
||||
table no longer prints a relationship wall after `add column`.
|
||||
- One relationship renderer (prose) leaves the codebase; the diagram
|
||||
renderer (ADR-0044) is the only relationship render path that ships.
|
||||
- `requirements.md` is unaffected (this is an ADR-tracked refinement of a
|
||||
decided area, like ADR-0044 itself); the change is cross-referenced
|
||||
from the commit + this ADR.
|
||||
|
||||
## Tests
|
||||
|
||||
- **Unit (`output_render.rs`):** the prose-asserting test
|
||||
`render_structure_with_relationships` (+ its snapshot) is removed; a
|
||||
new test asserts `render_structure` on a description **carrying** both
|
||||
inbound and outbound relationships emits the structure box but **no**
|
||||
`References:` / `Referenced by:` lines. The box/index/constraint tests
|
||||
are unaffected (their descriptions have no relationships).
|
||||
- **Integration (`walking_skeleton.rs`):** the misnamed
|
||||
`add_relationship_flow_shows_inbound_section_on_parent` (which sends an
|
||||
`AddColumn` and asserted the inbound prose) is inverted + renamed to
|
||||
assert the add-column confirmation shows the structure but **omits**
|
||||
the relationship prose.
|
||||
- **Unchanged:** the diagram tests (`show_list.rs` `show table`,
|
||||
`walking_skeleton.rs` `add relationship`) still pass — they already
|
||||
assert prose is absent and diagrams are present.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- The diagram form and its per-surface defaults (ADR-0044) — unchanged.
|
||||
- The OOS-7 user-configurable display setting (always-prose / -diagram /
|
||||
auto-by-width) — still a future follow-up; this ADR removes the prose
|
||||
*renderer*, not the *idea* of a prose mode.
|
||||
@@ -0,0 +1,147 @@
|
||||
# ADR-0051: Bottom keybinding strip — context- and state-aware
|
||||
|
||||
## Status
|
||||
|
||||
**Accepted 2026-06-13 (issue #27).** Closes Gitea **#27**. All forks
|
||||
below were escalated to the user and user-chosen before any code was
|
||||
written; to be implemented test-first. Builds on ADR-0046 (nav focus),
|
||||
ADR-0003 (input modes), ADR-0049 (the #29 readline keys this strip now
|
||||
advertises), and ADR-0022 (the Tab-completion memo).
|
||||
|
||||
## Context
|
||||
|
||||
The bottom status line (`render_status_bar`, `ui.rs`) mixed keystrokes
|
||||
with typed-command words: `Enter submit · : advanced once · mode
|
||||
advanced switch · Ctrl-C quit`. That is redundant — the hint panel
|
||||
already teaches `help` and `Enter` when the input is empty — and it is
|
||||
static apart from a three-way mode branch, so it never reflects what the
|
||||
user can actually do *right now* (navigating the sidebar, cycling a
|
||||
completion, browsing history, editing a line).
|
||||
|
||||
Issue #27: repurpose the line as a **keybindings-only** strip that is
|
||||
**context-sensitive to nav focus** and **state-aware of the current
|
||||
transient interaction**, and move mode discovery into the empty-input
|
||||
hint.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. The strip is keybindings-only and state-selected
|
||||
|
||||
A single pure function `status_bar_bindings(app) -> Vec<Binding>`
|
||||
computes the strip from app state; `render_status_bar` is a thin
|
||||
renderer over it (so the binding sets are unit-testable without a
|
||||
Frame). `history_cursor` is private to `App`, so a small
|
||||
`pub fn is_browsing_history(&self) -> bool` accessor exposes the
|
||||
history-navigation predicate; `mode` / `nav_focus` / `last_completion`
|
||||
are already `pub` and `effective_mode()` is a `pub` method. The state is
|
||||
chosen by **priority — first match wins**:
|
||||
|
||||
| Priority | State (predicate) | Strip |
|
||||
|---|---|---|
|
||||
| 1 | **Sidebar focus** (`nav_focus` in a sidebar) | `Ctrl-O next pane · ↑↓/PgUp/PgDn scroll · Esc input` |
|
||||
| 2 | **Completion memo live** (`last_completion.is_some()`) | `Tab/Shift-Tab cycle · Esc cancel · Enter run` |
|
||||
| 3 | **History navigation** (`history_cursor.is_some()`) | `↑↓ browse · Esc clear · Enter run` |
|
||||
| 4 | **Editing** (Input focus, input non-empty) | `Esc clear · Ctrl-A/E home/end · Ctrl-W del word · Enter run` |
|
||||
| 5 | **Default** (Input focus, input empty) | `Ctrl-O sidebar · Tab complete · ↑ history · Enter run` |
|
||||
|
||||
Priority order matters: a completion memo or history navigation is a
|
||||
non-empty-input situation, so states 2 and 3 must precede state 4. The
|
||||
sidebar overlay occludes the input entirely (ADR-0046), so state 1 wins
|
||||
outright.
|
||||
|
||||
### 2. Mode discovery moves off the strip, into the empty-input hint
|
||||
|
||||
The typed-command advertisements (`mode advanced` / `mode simple`
|
||||
switch, the `:` one-shot) leave the strip — they are not keystrokes.
|
||||
Mode discovery moves to the **empty-input hint** (`resolve_hint_lines`'s
|
||||
`(None, None)` arm), in **simple mode only**:
|
||||
|
||||
- **Simple:** `… · \`mode advanced\` for SQL`
|
||||
- **Advanced (persistent):** no pointer.
|
||||
|
||||
The pointer omits the verb "type" — the surrounding prompt already
|
||||
implies it (we don't say "type `help`" either). Advanced mode shows
|
||||
**no** pointer (user decision, post-trial): a user who switched into
|
||||
advanced mode knows how they got there, and `help` covers the way back —
|
||||
a "switch back" pointer only reads naturally in the moment right after
|
||||
switching, so it earns its space poorly.
|
||||
|
||||
The one-shot advanced state's old `Backspace cancel one-shot` label is
|
||||
**subsumed** by the editing state (the input is non-empty in one-shot;
|
||||
Esc-clear and Backspace both cancel it). No behaviour is lost — only the
|
||||
dedicated label.
|
||||
|
||||
### 3. Width: no drop machinery; a budget test instead
|
||||
|
||||
The longest strip (state 4, editing) is ≈ **65 display columns**, which
|
||||
fits every supported width (90-col screencasts, 80-col terminals) with
|
||||
margin — so the priority-drop / abbreviation machinery considered would
|
||||
never trigger and is not built (user-confirmed). Ratatui's existing
|
||||
**clip-at-edge** is the trivial fallback for pathologically narrow
|
||||
(< 65-col) terminals. Instead, a **width-budget unit test** pins the
|
||||
longest rendered strip within an 80-col budget, keeping the strip lean
|
||||
*by construction* — a future over-long strip fails the test rather than
|
||||
silently clipping in a cast.
|
||||
|
||||
## Forks (all user-chosen)
|
||||
|
||||
- **Editing state — yes:** when the input has text, surface the #29
|
||||
readline keys (Esc-clear, Ctrl-A/E, Ctrl-W); the strip stays lean
|
||||
(nav/complete/history) when empty. (vs not advertising the #29 keys.)
|
||||
- **`Ctrl-C quit` — omitted** from the strip (vs always shown): quit is
|
||||
a near-universal convention; omitting it keeps the strips lean and
|
||||
matches the issue's sketch.
|
||||
- **Width — budget test, no drop logic** (vs graceful priority-drop /
|
||||
abbreviation): the strips fit at supported widths, so the machinery
|
||||
would be dead weight (user's own observation).
|
||||
|
||||
## Consequences
|
||||
|
||||
- The strip now teaches the keys for the *current* situation; learners
|
||||
see `Tab/Shift-Tab cycle` exactly while cycling, the editing keys
|
||||
exactly while editing, etc.
|
||||
- The #29 readline keys (ADR-0049) gain their on-screen advertisement,
|
||||
closing that ADR's deferred item.
|
||||
- 15 existing full-panel insta snapshots churn (the bottom line — and,
|
||||
on empty-input views, the hint pointer — changes in every one,
|
||||
including the rebuild-confirm modal view, whose modal box is itself
|
||||
unchanged); each diff was reviewed, not blind-accepted.
|
||||
- `requirements.md` is unaffected (an ADR-tracked UI refinement); the
|
||||
change is cross-referenced from the commit + this ADR.
|
||||
|
||||
## Tests
|
||||
|
||||
- **Tier-1 (`ui.rs` unit):** `status_bar_bindings` returns the expected
|
||||
key set for each of the five states (sidebar, completion-live,
|
||||
history-nav, editing, default) — the completion/history states driven
|
||||
through real key events (`update`) so the predicate transitions are
|
||||
exercised, the others by setting `App` fields; plus the width-budget
|
||||
assertion across states. (Per-state coverage is these unit tests, not
|
||||
snapshots — a one-line strip is asserted more precisely by its exact
|
||||
key list than by a full-panel snapshot.)
|
||||
- **Tier-1:** the empty-input hint appends the correct mode pointer in
|
||||
Simple vs Advanced, and does **not** append it when an ambient hint is
|
||||
showing (non-empty input).
|
||||
- **Tier-3 (`walking_skeleton`):** the old `status_bar_lists_quit_and_
|
||||
submit_in_all_modes` (which asserted the pre-ADR strip) is rewritten +
|
||||
renamed to assert the keystroke-only, state-aware strip end-to-end
|
||||
through the real render path (default → editing transition).
|
||||
- **Tier-2 (insta):** the 15 full-panel snapshots re-accepted (each diff
|
||||
reviewed — strip line and/or hint pointer only).
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Modal-aware strip.** While a modal is open (load picker, rebuild /
|
||||
undo confirm) it owns the keyboard and carries its own in-box key
|
||||
hints; the bottom strip under a modal computes from input state
|
||||
exactly as it does today (modals render *over* the status bar). This
|
||||
issue does not redesign the modal case — pre-existing behaviour,
|
||||
unchanged and not worsened.
|
||||
- A persistent/togglable help overlay listing *all* keys (the strip is a
|
||||
contextual subset, not a cheatsheet).
|
||||
- Per-key colour theming beyond the existing key/label/separator styles.
|
||||
- Localisation of the new label strings beyond adding catalog entries.
|
||||
- The remaining I1b kill keys' (Ctrl-K/Ctrl-U) advertisement — the
|
||||
editing strip shows the highest-value subset (Esc/Ctrl-A/E/Ctrl-W) to
|
||||
stay within the width budget; Ctrl-K/U remain unadvertised muscle
|
||||
memory.
|
||||
@@ -0,0 +1,250 @@
|
||||
# ADR-0052: Mode-tagged history for cross-mode recall
|
||||
|
||||
## Status
|
||||
|
||||
**Accepted + implemented 2026-06-13 (issue #30).** Closes Gitea **#30** —
|
||||
both the feature ("reuse advanced history commands in simple mode by
|
||||
prepending `:`") and the bug reported in its comment (the `:` one-shot
|
||||
prefix lost across sessions). All forks user-chosen before any code.
|
||||
**Amends ADR-0034** (journal status field gains a `:adv` tag; *journaling
|
||||
moves from the worker to the dispatch layer*), **ADR-0015 §5/§6**
|
||||
(history.log leaves the worker transaction — `commit-db-last` now scopes
|
||||
yaml/csv/db only), and **ADR-0040** (a success-path journal-write failure
|
||||
is best-effort, no longer fatal); references ADR-0003 (the `:` one-shot
|
||||
sigil). Plan: `docs/plans/20260613-issue-30-top-of-chain-journaling.md`
|
||||
(pre-build `/runda`, then a second `/runda` that drove the journaling
|
||||
relocation + the app-command exclusion). **2471 tests pass / 0 fail / 0
|
||||
skip (1 ignored), clippy clean.**
|
||||
|
||||
> **Why journaling moved (the key architectural turn).** The first draft
|
||||
> kept journaling in the worker and threaded the mode down to it (~30-site
|
||||
> plumbing). On review the user asked the right question: why is the
|
||||
> journal written deep in the worker at all, when the failure path already
|
||||
> journals at the top of the chain where command + mode + outcome are all
|
||||
> in scope? It shouldn't — `history.log` is a *journal of typed commands*,
|
||||
> not *state*. So success journaling moved up next to the failure path
|
||||
> (`spawn_dsl_dispatch` / `run_replay` / the app-command sites), the
|
||||
> mode-plumbing dilemma dissolved, and the worker's `finalize_persistence`
|
||||
> now writes only the state sources (yaml/csv). Consequence: the journal
|
||||
> write is best-effort (the command is already committed), consistent with
|
||||
> the failure path — see §5.
|
||||
|
||||
## Context
|
||||
|
||||
The input-history ring and `history.log` carry **no mode information**,
|
||||
which causes two coupled problems:
|
||||
|
||||
1. **Feature gap.** A command typed in advanced mode (`select * from T`)
|
||||
is stored bare. Recalled in simple mode it is not valid DSL → it just
|
||||
errors. There is no way to know it was an advanced (SQL) command and
|
||||
offer it back in a runnable form.
|
||||
|
||||
2. **Bug (issue #30 comment).** A `:`-one-shot advanced command in simple
|
||||
mode recalls correctly **in-session** (the in-memory ring stores the
|
||||
raw `:select 1`), but after quit+resume it comes back **without** the
|
||||
`:` and is unusable. Root cause: the ring stores the raw input
|
||||
(`:select 1`), but the worker journals the **stripped** `effective_input`
|
||||
(`select 1`) — submission strips the `:` before dispatch (ADR-0003) —
|
||||
so the on-disk `source` never carried the `:`, and hydration loses it.
|
||||
|
||||
Both reduce to: **history does not record the submission mode**, and the
|
||||
in-memory and on-disk representations disagree about the `:`.
|
||||
|
||||
## Decision
|
||||
|
||||
Record the **submission mode** per history entry, keep the on-disk
|
||||
`source` **canonical** (stripped — replay is unaffected), and have
|
||||
**recall reconstruct the runnable line** for the current mode.
|
||||
|
||||
### 1. In-memory ring stores the `:`-prefixed runnable form
|
||||
|
||||
`App.history` stays `Vec<String>` — no type change, so the public ring,
|
||||
the `ProjectSwitched` payload, and `seed_history` are untouched. An
|
||||
**advanced** entry is stored in its **simple-mode runnable form**, the
|
||||
`: `-prefixed string (e.g. `: select * from T`); a **simple** entry is
|
||||
stored bare. This is exactly what the in-session one-shot ring already
|
||||
does (`:select 1` recalls as typed) — generalised to *persistent*-advanced
|
||||
commands too, and made reconstructable on hydration. Because a simple
|
||||
DSL command can never begin with `:` (the sole sigil, ADR-0003), a
|
||||
leading `:` unambiguously marks an advanced entry.
|
||||
|
||||
`submit` builds the stored line from the submission: advanced →
|
||||
`": " + effective_input` (the `: ` matches the auto-space the typed
|
||||
one-shot inserts), simple → `effective_input`. This is computed **after**
|
||||
`effective_input` (today `push_history` runs on the raw `trimmed` before
|
||||
stripping; the reorder also drops a bare `:`, which never executed). The
|
||||
draft (`history_draft`) stays a plain `String`. `push_history` itself is
|
||||
unchanged — it still takes one `&str`.
|
||||
|
||||
### 2. Recall strips the `:` for advanced mode
|
||||
|
||||
`history_back` / `history_forward` set `self.input` from the stored
|
||||
string, then strip a leading `:` **iff the current persistent mode is
|
||||
Advanced**:
|
||||
|
||||
```
|
||||
if self.mode == Mode::Advanced && stored.starts_with(':') { stored[1..].trim_start() } else { stored }
|
||||
```
|
||||
|
||||
So an advanced entry recalls as `: select * from T` in **simple** mode
|
||||
(runs via the one-shot escape — the feature, and the cross-session bug
|
||||
fix) and bare `select * from T` in **advanced** mode (runs as SQL). A
|
||||
simple entry recalls bare in either mode (simple DSL already runs in
|
||||
advanced mode — issue #30). In-session and cross-session paths share the
|
||||
same stored form, so they finally agree.
|
||||
|
||||
### 3. On-disk: a mode tag in the status field
|
||||
|
||||
The record stays three pipe-separated fields `<ts>|<status>|<source>`
|
||||
(so `source` remains the last, pipe-tolerant, canonical field — replay
|
||||
reads it unchanged). The **status token** gains an optional `:adv`
|
||||
suffix:
|
||||
|
||||
| Submission | Success | Failure |
|
||||
|---|---|---|
|
||||
| Simple | `ok` | `err` |
|
||||
| Advanced (persistent or one-shot) | `ok:adv` | `err:adv` |
|
||||
|
||||
ADR-0034 §1 already reserved the status field for "additional values …
|
||||
a non-breaking future extension"; this is that extension. The status
|
||||
parser splits the token on `:`: the base (`ok`/`err`) gives replayability
|
||||
(`status_is_ok` ⇔ base == `ok`), the `adv` suffix gives the mode — so an
|
||||
unknown future token degrades to "not ok, simple" rather than mis-parsing.
|
||||
|
||||
### Journaling location: the dispatch layer, not the worker
|
||||
|
||||
Both tags are written **at the dispatch layer**, where command + mode +
|
||||
outcome are all in scope — so the mode needs no plumbing into the worker:
|
||||
|
||||
- **Success:** `spawn_dsl_dispatch`, immediately after
|
||||
`execute_command_typed` returns `Ok`, calls
|
||||
`append_history(source, submission_mode.is_advanced())` (best-effort).
|
||||
`run_replay` does the same per replayed line (tagged simple — replay is
|
||||
mode-agnostic), and the app-command sites (`perform_switch` /
|
||||
`spawn_export` / `spawn_rebuild`) journal **simple** (`advanced = false`
|
||||
— app commands run in any mode, so no `:` on recall; this also avoids a
|
||||
redundant `: undo`).
|
||||
- **Failure:** unchanged location (the App→`JournalFailure`→runtime path,
|
||||
already at the top), now carrying the mode — `JournalFailure` gains
|
||||
`advanced`, and `DslFailed` gains `submission_mode` for the
|
||||
worker-rejection sub-path (the parse-failure sub-path has it in
|
||||
`dispatch_dsl`). `Ok`/`Err` are exclusive, so success-in-spawn and
|
||||
failure-in-App-path never double-journal.
|
||||
|
||||
The worker's `finalize_persistence` and the four no-op-skip / three
|
||||
read-only sites **no longer journal** — they leave the state writes
|
||||
(yaml/csv) in the worker transaction and let the dispatch layer journal
|
||||
the `Ok` outcome.
|
||||
|
||||
### 4. Hydration reconstructs the `:`-prefixed form
|
||||
|
||||
`read_recent_sources` parses each record's status tag and, for an
|
||||
advanced record, **reconstructs** the `: `-prefixed string from the
|
||||
canonical `source` (`format!(": {source}")`); simple records pass through
|
||||
bare. It still returns `Vec<String>`, so `read_history_seed`,
|
||||
`seed_history`, and the `ProjectSwitched` payload are **unchanged**. A
|
||||
hydrated entry is therefore byte-identical to its in-session form, and
|
||||
recall behaves identically.
|
||||
|
||||
### Back-compatibility
|
||||
|
||||
Old `history.log` files have only `ok` / `err` tokens → parsed as
|
||||
`advanced = false` (simple). Their advanced commands stay un-`:`-able on
|
||||
recall — the pre-existing behaviour, not a regression; nothing migrates.
|
||||
`status_is_ok` keys off the base token, so `ok:adv` records replay
|
||||
exactly as `ok` does today (source is canonical either way).
|
||||
|
||||
### Journal write is best-effort (amends ADR-0040)
|
||||
|
||||
Because the journal is now written *after* the worker replies (i.e. after
|
||||
`tx.commit`), a journal-write failure can no longer roll the command back.
|
||||
It is **best-effort** — logged and ignored, exactly like the failure path
|
||||
already is (ADR-0034 §4) — so the two journal paths are finally
|
||||
consistent. State integrity is unchanged: yaml/csv/db still commit
|
||||
atomically in the worker (a *state*-write failure still rolls back and is
|
||||
fatal). The only property given up: on a rare journal-write failure (disk
|
||||
full) a committed command may be missing from `history.log` — not
|
||||
recallable/replayable next session, but the state is correct. User-chosen
|
||||
over keeping journaling coupled in the worker (which would have needed the
|
||||
~30-site mode plumbing). See the plan's §2 for the full trade-off.
|
||||
|
||||
## Forks (user-chosen)
|
||||
|
||||
- **Format = mode tag in the status field** (`ok:adv`/`err:adv`), over a
|
||||
new 4th field (ambiguous with unescaped pipes in old `source`s without
|
||||
a version bump) or a `:`-prefix in `source` (would make `source`
|
||||
non-canonical and force replay to strip it).
|
||||
- **Scope = unified** (bug + feature) over bug-only: one mechanism does
|
||||
both, and keeping `source` canonical for replay needs the mode tag
|
||||
regardless, so bug-only is barely smaller and leaves the main ask open.
|
||||
- **Journaling location = dispatch layer, best-effort** over keeping it
|
||||
worker-coupled-and-fatal (which needed the ~30-site mode plumbing). The
|
||||
user's architectural call (§Status).
|
||||
|
||||
## Consequences
|
||||
|
||||
- Advanced history is reusable in simple mode; the `:` one-shot survives
|
||||
resume. The in-memory and on-disk representations agree.
|
||||
- **Journaling left the worker.** `finalize_persistence` and the
|
||||
no-op-skip / read-only sites no longer journal; success is journalled at
|
||||
the dispatch layer (`spawn_dsl_dispatch` / `run_replay` / app-command
|
||||
sites). The ring stays `Vec<String>`; `seed_history` / `ProjectSwitched`
|
||||
are untouched. The vestigial worker `source` plumbing has since been
|
||||
**fully unwound** (2026-06-14 follow-up): `_source` removed from
|
||||
`finalize_persistence` / `do_rebuild_from_text`; the three read-only
|
||||
`*_request` wrappers inlined and deleted; and — because the cascade ran
|
||||
deeper than first estimated — the now-dead `source` param dropped from
|
||||
the ~30 worker handlers (leaf + composite) that only forwarded it, plus
|
||||
the `source` field removed from the `DescribeTable` / `QueryData` /
|
||||
`RunSelect` requests and the matching `DatabaseHandle` method parameters
|
||||
(the ~164 call-site churn was mostly tests). The only `source` left in
|
||||
the worker is the snapshot/undo label (`snapshot_then` /
|
||||
`stage_pre_mutation` / `begin_batch`), passed at the match-arm level.
|
||||
Purely mechanical, compiler-guided, no behaviour change.
|
||||
- **App commands recall bare.** Because they are dispatched outside the
|
||||
`ExecuteDsl`/spawn path, app commands journal **simple** (`advanced =
|
||||
false`) at their own sites, and `submit` excludes them from the ring's
|
||||
`advanced` flag (`!is_app_command`) — so `mode advanced` / `undo` recall
|
||||
bare and run fine in simple mode, with no redundant `:`.
|
||||
- **Journaling is now uniform (user-confirmed).** The spawn journals on
|
||||
`outcome.is_ok()`, so **every** successful command is recorded — closing
|
||||
a pre-existing gap where `show table` / `show data` / `select` journalled
|
||||
but `show tables`/`show relationships`/`show indexes`, `show relationship
|
||||
<name>`, and `explain` did **not** (their worker arms carried no
|
||||
`source` / no journal call). The new behaviour matches ADR-0034 §1
|
||||
("record every submitted command"); those reads are now recallable and
|
||||
are re-run harmlessly on replay (`explain` never executes; shows produce
|
||||
output, no state change). A DA finding, accepted as the more-correct
|
||||
behaviour over re-adding command-outcome gating to preserve the old
|
||||
inconsistency.
|
||||
- **Replay re-journaling.** When `replay` re-dispatches a line, the
|
||||
re-written record is tagged from how replay dispatched (mode-agnostic →
|
||||
`ok`), so a replayed advanced command may be re-journalled without
|
||||
`:adv`. Replay correctness of execution is unchanged (it already parses
|
||||
mode-agnostically); this only affects the *tag* of the re-written line.
|
||||
Noted; not addressed here (replay's own mode-fidelity is out of scope).
|
||||
|
||||
## Tests
|
||||
|
||||
- **Tier-1 (`app.rs`):** an advanced one-shot / persistent-advanced
|
||||
submission is stored `: `-prefixed; it recalls as `: …` in simple mode
|
||||
and bare in advanced mode; a simple entry recalls bare in both; a bare
|
||||
`:` is not stored; a parse-failure is still recallable; dedup/cap hold.
|
||||
- **Tier-1 (`history.rs`):** the writer emits `ok:adv`/`err:adv`;
|
||||
`read_recent_sources` reconstructs the `: `-prefix for `:adv` records
|
||||
and leaves `ok`/`err` records bare (so old logs read as simple);
|
||||
`status_is_ok` is true for `ok` and `ok:adv`.
|
||||
- **Tier-3 (`iteration6_resume_history` / it):** the headline
|
||||
**regression** — type a `:`-one-shot advanced command, journal +
|
||||
hydrate, and assert it recalls **with** `:` in simple mode (fails on
|
||||
current code); plus a persistent-advanced command round-tripping to a
|
||||
`: …` recall.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Replay re-journaling mode-fidelity (above).
|
||||
- Special-casing app commands to avoid the redundant recall `: `.
|
||||
- Distinguishing one-shot from persistent advanced on recall (both are
|
||||
simply "advanced" — the `:` is what simple mode needs either way).
|
||||
- A format version marker / pipe-escaping in `source` (unneeded — the
|
||||
status-tag approach keeps `source` last and canonical).
|
||||
@@ -0,0 +1,428 @@
|
||||
# ADR-0053: Contextual `hint` — F1 live-input keybinding + `hint` command, with a tier-3 teaching corpus (H2)
|
||||
|
||||
## Status
|
||||
|
||||
Accepted — **implemented 2026-06-15** (plan:
|
||||
`docs/plans/20260614-adr-0053-contextual-hint-H2.md`; the F1 keybinding +
|
||||
`hint` command, the `hint_ids` per-form keying + `hint_key_for_input_in_mode`,
|
||||
`last_error_hint_key` + `friendly::error_hint_class`, the `note_hint*`
|
||||
renderers, and the `hint.cmd.*`/`hint.err.*` corpus for every command form
|
||||
+ the 9 runtime error classes, with the comprehensiveness coverage test
|
||||
and the ADR-0051 strip advertising F1). Closes **A1** + requirements
|
||||
**H2**. Deferred: the pre-submit-diagnostic route + `diagnostic.*` blocks
|
||||
(#38), clause-concept hints (#37). Revised after a `/runda` review
|
||||
(2026-06-14): corrected the verbosity-default fact; re-keyed tier-3
|
||||
content off `help_id`; split the pre-submit-diagnostic and runtime-error
|
||||
paths; added a comprehensiveness coverage test. Revised again during
|
||||
Phase B implementation (2026-06-15): the first exemplar showed per-*node*
|
||||
keying is too coarse for multi-form commands (`add`/`drop`/`show`/
|
||||
`create`), so D3 now keys tier-3 content **per form** via a
|
||||
`hint_ids: &[&str]` array mirroring `usage_ids` — and **clause-concept
|
||||
hints** are recorded as a deferred extension (issue #37). During Phase C
|
||||
the **pre-submit-diagnostic route + the ~33 `diagnostic.*` blocks** were
|
||||
**deferred** (issue #38) — `Diagnostic` doesn't carry its class key, so
|
||||
the route needs a broad change for marginal value (D6). v1 therefore
|
||||
ships command-form hints + the 9 runtime error-class hints. The parallel
|
||||
question of whether the in-app `help` command should likewise distinguish
|
||||
advanced-SQL forms is tracked **separately** as Gitea issue #36.
|
||||
|
||||
Decided in conversation 2026-06-14. Closes the last open piece of **A1**
|
||||
(the canonical app-command set, ADR-0003): every app command is
|
||||
implemented except `hint`, which ADR-0003's command table listed as
|
||||
*"Request a hint for the current input (ADR pending)."* This ADR is that
|
||||
pending decision. Tracked as **H2** in `docs/requirements.md`.
|
||||
|
||||
References ADR-0003 (app-command set + the `:` escape), ADR-0019 (the
|
||||
friendly error layer / H1), ADR-0021 (per-command usage templates / H1a),
|
||||
ADR-0022 (ambient typing assistance — colour + hint panel + completion),
|
||||
ADR-0027 (input validity indicator), ADR-0046 (sidebar navigation +
|
||||
responsive input hint), ADR-0049 (input-field readline keymap), and
|
||||
ADR-0051 (context/state-aware keybinding strip).
|
||||
|
||||
## Context
|
||||
|
||||
`hint` is the only unbuilt app command. The naive reading — "show a hint" —
|
||||
hides a real subtlety, and a real cost.
|
||||
|
||||
**The subtlety: a submitted `hint` command cannot see live input.** App
|
||||
commands are submitted with Enter, which empties the input buffer. By the
|
||||
time `hint` dispatches, the partial command it was meant to help with is
|
||||
gone. So "a hint for the current input" cannot be served by a submitted
|
||||
command alone — it needs a *keybinding* that acts on the live buffer
|
||||
without submitting. ADR-0003 said "current input"; `requirements.md`
|
||||
broadened it to "current input **or the most recent error**." Both are
|
||||
wanted; they map to two different trigger surfaces.
|
||||
|
||||
**The cost: the value of `hint` is content, not plumbing.** The app
|
||||
already carries two tiers of contextual text:
|
||||
|
||||
- **Tier 1** — terse, always-on: syntax colour (ADR-0022); the error
|
||||
*headline* alone (ADR-0019, when `messages_verbosity: Short`).
|
||||
- **Tier 2** — short contextual lines: the ambient typing prose /
|
||||
`expected` set, shown live while typing (ADR-0022, catalogue
|
||||
`hint.ambient_*` / `hint.value_slot_*`); and the error `hint:` field —
|
||||
which, because `Verbosity::Verbose` is the **default**
|
||||
(`src/friendly/translate.rs:46`), is shown **by default** beneath every
|
||||
error headline (`messages short` is the opt-*out*, not `messages
|
||||
verbose` the opt-in).
|
||||
|
||||
So the verbose error hint is **already on screen by default**. If `hint`
|
||||
merely re-showed it, it would duplicate what the user can already see (and
|
||||
the ambient panel). To justify itself, `hint` must add a **tier 3**: a
|
||||
genuinely deeper, *teaching*-grade explanation — what the command/error
|
||||
means, a worked example, and the underlying relational concept. That
|
||||
corpus does not exist yet, and
|
||||
authoring it (to the standard of a teaching tool, where "pedagogy wins
|
||||
ties") is the bulk of the work.
|
||||
|
||||
The mechanism is small and reuses everything already present: the command
|
||||
REGISTRY (`src/dsl/grammar/mod.rs`), the `AppCommand` enum
|
||||
(`src/dsl/command.rs`), key dispatch (`App::handle_key`,
|
||||
`src/app.rs:1155`), the `note_help`/`note_help_topic` renderers
|
||||
(`src/app.rs:2982`/`3021`), the parser/walker expected-set
|
||||
(`ParseError.expected`, `WalkResult.tail_expected`), the friendly
|
||||
catalogue + `t!` macro + `keys.rs` validation, and the output styling
|
||||
vocabulary (`OutputStyleClass::Hint`).
|
||||
|
||||
## Decision
|
||||
|
||||
### D1 — Two surfaces, no topic argument
|
||||
|
||||
`hint` is delivered through **two complementary surfaces**:
|
||||
|
||||
1. **F1 keybinding → live input.** Pressing **F1** while typing renders a
|
||||
tier-3 hint for the command currently in the buffer, into the output
|
||||
panel, **without submitting or altering the buffer**. This is the
|
||||
primary, most-valuable path (it serves the literal "current input").
|
||||
2. **`hint` command → most recent error.** Submitting `hint` renders the
|
||||
tier-3 expansion of the most recent error. This is why the command
|
||||
exists despite the empty-buffer problem: the thing it helps with is
|
||||
the *last thing you tried*, not the now-empty buffer.
|
||||
|
||||
`hint` takes **no topic argument**. Explicit per-command reference is
|
||||
already `help <topic>` (H3); `hint` is purely *contextual*, which keeps
|
||||
the two cleanly distinct (`hint` = "help me with what I'm doing right
|
||||
now"; `help insert` = "show me the insert reference").
|
||||
|
||||
F1 is a **read-only overlay**: it never alters the input buffer, the
|
||||
cursor, or the live completion memo (ADR-0022) — it only emits a block
|
||||
into the output journal. (It must therefore be handled in `handle_key`
|
||||
*before* the "any other key clears the memo" fall-through.)
|
||||
|
||||
### D2 — Trigger matrix
|
||||
|
||||
| Trigger | Buffer / state | Result |
|
||||
|---|---|---|
|
||||
| **F1** | non-empty input | tier-3 hint for the command being typed. (No "expected next" line — the always-on tier-2 ambient panel already shows it live; tier-2 owns position-awareness.) |
|
||||
| **F1** | empty input, a recent error exists | tier-3 expansion of that error |
|
||||
| **F1** | empty input, no recent error | a short "getting started" pointer (press F1 while typing a command; `help` for the full list) |
|
||||
| **`hint`** (submitted) | a recent error exists | tier-3 expansion of that error (primary use) |
|
||||
| **`hint`** (submitted) | no recent error | the same "getting started" pointer |
|
||||
|
||||
F1 is inert behind a modal and while a sidebar panel holds navigation
|
||||
focus (consistent with the existing `handle_key` gates, ADR-0046); it is
|
||||
active in the input context in both Simple and Advanced mode.
|
||||
|
||||
**Error routes.** **Runtime errors** (the 9 `translate_error` classes)
|
||||
occur *after* submit; the **`hint` command / empty-input F1** path reads
|
||||
them via the stored `last_error_hint_key` (D5) and renders their
|
||||
`hint.err.<class>` block. (A second route for **pre-submit diagnostics**
|
||||
on the F1 live-input path was specified but is **deferred** — D6 / issue
|
||||
#38; with a diagnostic present, F1 shows the command block and tier-2
|
||||
shows the diagnostic.) **`:`-prefix handling:**
|
||||
on the simple-mode one-shot escape (`: SELECT …`), command
|
||||
identification for the F1 path strips the leading `:` first, so the
|
||||
advanced form is matched.
|
||||
|
||||
### D3 — The tier-3 content model
|
||||
|
||||
Tier-3 blocks live in the friendly catalogue under the existing `hint:`
|
||||
top-level namespace (where tier-2 ambient strings already live), in two
|
||||
new sub-namespaces:
|
||||
|
||||
- **`hint.cmd.<hint_id>`** — one per command **form**, keyed by a **new
|
||||
`hint_ids: &'static [&'static str]`** field on `CommandNode`
|
||||
(`src/dsl/grammar/mod.rs:512`), **mirroring the existing `usage_ids`**.
|
||||
The F1 live-input path resolves the current input to its form's hint key
|
||||
via `hint_key_for_input_in_mode`, which reuses the same form-word
|
||||
disambiguation as `usage_key_for_input_in_mode`.
|
||||
|
||||
**Why an array mirroring `usage_ids`, not a per-node `hint_id`**
|
||||
*(`/runda`/implementation revision, 2026-06-15)*: a single per-node key
|
||||
is too coarse. Several entry words are **one node spanning many forms** —
|
||||
`add` (column/relationship/index/constraint), `drop` (table/column/
|
||||
relationship/index), `show` (data/table/tables/relationships/indexes),
|
||||
`create` (table/index). A live-input hint for `add 1:n relationship` is
|
||||
only useful if it is *specific to relationships*, so the content must be
|
||||
**per form**, not per node. The project already solved exactly this for
|
||||
usage templates (`usage_ids` is a per-form array, disambiguated by the
|
||||
form word), so `hint_ids` mirrors it. Single-form nodes carry one entry;
|
||||
multi-form nodes carry one per form. This also covers the advanced-SQL
|
||||
forms whose `usage_ids` are empty (`SQL_INSERT/UPDATE/DELETE`,
|
||||
`EXPLAIN_SQL`) — they get their own `hint_ids` directly, independent of
|
||||
usage, with mode-correct SQL examples. (The `help`-list collapse of
|
||||
advanced-SQL forms is a separate gap — issue #36.)
|
||||
|
||||
**Deferred extension — clause-concept hints** (issue #37): per-form is
|
||||
the right granularity for tier-3 *teaching* (position-awareness within a
|
||||
form is owned by tier-2 ambient + the live `Next:` line, D4). But some
|
||||
**concepts live inside a clause**, not a form — `… on delete ⟨cascade|
|
||||
set null|restrict⟩` (referential actions), the `create table` constraint
|
||||
slots (`primary`/`unique`/`check`/`foreign`), `with pk`, `1:n`/`m:n`
|
||||
cardinality. A learner parked in such a clause may want teaching deeper
|
||||
than tier-2's candidate list but narrower than the whole-form block. v1
|
||||
does **not** build this (it would multiply content for points whose value
|
||||
we can't yet measure, and we don't expect to accumulate usage statistics
|
||||
to drive it empirically — it will be tackled as a deliberate follow-up
|
||||
job). The keying does not lock it out: a later `hint.concept.<topic>`
|
||||
namespace can be surfaced when the cursor sits in a recognized clause,
|
||||
layered on top of the per-form block.
|
||||
- **`hint.err.<class>`** — one per error/diagnostic class, keyed by the
|
||||
friendly error/diagnostic key (e.g. `hint.err.foreign_key.child_side`,
|
||||
`hint.err.type_mismatch`, `hint.err.insert_arity_mismatch`). Used by
|
||||
both error routes (D2).
|
||||
|
||||
Each tier-3 block is a **structured entry with three labelled parts**, so
|
||||
the voice stays consistent and the renderer can style them uniformly:
|
||||
|
||||
```yaml
|
||||
hint.cmd.dsl.insert:
|
||||
what: "Add one or more rows to a table."
|
||||
example: "insert into Customers values ('Ann', 'ann@x.io')"
|
||||
concept: "A row is one record; each value lines up with a column, in
|
||||
order. Columns typed `serial`/`shortid` fill themselves — leave them out."
|
||||
```
|
||||
|
||||
- **`what`** — one or two plain sentences: what this command does / what
|
||||
this error means.
|
||||
- **`example`** — a single concrete, copyable line (rendered neutral, not
|
||||
muted, so it stands out as runnable).
|
||||
- **`concept`** — the underlying relational idea, in teaching voice; the
|
||||
part that makes this tier-3 rather than tier-2.
|
||||
|
||||
`concept` is optional where there is genuinely no concept beyond the
|
||||
mechanics (e.g. `quit`); `what` + `example` are always present.
|
||||
|
||||
### D4 — Rendering
|
||||
|
||||
Both surfaces render through the `App::note_hint*` family (sibling of
|
||||
`note_help`/`note_help_topic`, `src/app.rs`) via `emit_tier3_block`,
|
||||
emitting into the `output` buffer as `OutputKind::System`: a **`Hint`
|
||||
heading** followed by aligned **`What:` / `Example:` / `Concept:`** lines
|
||||
(labels + heading from `hint.block.*`). The `concept` line is muted
|
||||
(`OutputStyleClass::Hint`); the rest are plain. The block is
|
||||
**persistent** (scrolls in the journal), unlike the transient ambient
|
||||
panel — pressing F1 is an explicit request to *keep* the deeper guidance
|
||||
on screen. Its rendered shape is locked by an `insta` snapshot
|
||||
(`hint_block_insert`). The bottom keybinding strip (ADR-0051) advertises
|
||||
F1 in the editing (leading) and default states.
|
||||
|
||||
### D5 — "Most recent (runtime) error" state
|
||||
|
||||
The **runtime-error route** (submitted `hint`, and empty-input F1) needs
|
||||
to map the last runtime error back to its `hint.err.<class>` key. Runtime
|
||||
errors today live only as rendered text in the `output` buffer. We add a
|
||||
single small piece of `App` state — **`last_error_hint_key:
|
||||
Option<String>`** — set at the `translate_error` call sites
|
||||
(`runtime.rs:2615`, `app.rs:2424`) when a friendly error is rendered,
|
||||
cleared when a later command succeeds. Absent → the "getting started"
|
||||
pointer.
|
||||
|
||||
The **pre-submit-diagnostic route** (the F1 live-input path reading the
|
||||
under-cursor diagnostic) is **deferred** — see the scope note in D6.
|
||||
|
||||
### D6 — Content scope for v1
|
||||
|
||||
v1 ships tier-3 content for the **command forms and runtime error
|
||||
classes** — comprehensive for those (the graceful tier-2 fallback below
|
||||
is a safety net, not the plan):
|
||||
|
||||
- **~37 command forms** — every distinct node in `REGISTRY` gets its own
|
||||
`hint.cmd.<hint_id>` block (app + DSL + DDL + advanced-mode SQL forms),
|
||||
each with a **mode-correct example** (the advanced-SQL forms show SQL
|
||||
syntax, their simple siblings show DSL — no sharing).
|
||||
- **9 runtime error classes** — `unique`, `foreign_key` (child/parent
|
||||
side), `not_null`, `check`, `type_mismatch`, `not_found`,
|
||||
`already_exists`, `generic`, `invalid_value` — each gets a
|
||||
`hint.err.*` block.
|
||||
|
||||
**Deferred — the ~33 `diagnostic.*` pre-submit classes and the F1
|
||||
diagnostic route** *(Phase C scope decision, 2026-06-15; issue #38)*. The
|
||||
original "comprehensive" scope included them, but implementation revealed
|
||||
`Diagnostic` (`walker/outcome.rs`) carries only its rendered `message`,
|
||||
not its class key — so a live diagnostic can't be mapped to
|
||||
`hint.err.<class>` without adding a `class` field threaded through every
|
||||
diagnostic-creation site (a broad change). Weighed against the value, it
|
||||
isn't worth it for v1: pre-submit diagnostics are already surfaced by
|
||||
tier-2 (ambient message + validity indicator, ADR-0027); F1 still shows
|
||||
the useful command block when a diagnostic is present; and many
|
||||
diagnostic classes duplicate runtime classes already covered
|
||||
(`type_mismatch`, `unknown_table`↔`not_found`, arity↔`invalid_value`).
|
||||
Deferred to issue #38, additively (the keying doesn't lock it out).
|
||||
|
||||
The full enumerated checklist is the implementation plan's tracking
|
||||
artifact (see *Content inventory*, below).
|
||||
|
||||
**Fallback (safety net):** if a tier-3 key is ever missing at runtime,
|
||||
the surface degrades to tier 2 — the ambient prose for the command path,
|
||||
or the verbose error `hint:` for the error path — never to a blank or an
|
||||
error. The `keys.rs` build-time validation keeps the corpus honest, so a
|
||||
missing key is caught in tests, not in front of a student.
|
||||
|
||||
### D7 — Authoring process: exemplars-first
|
||||
|
||||
Because the corpus is large and its *voice* is a pedagogical decision the
|
||||
maintainer owns, content is produced in two stages:
|
||||
|
||||
1. This ADR carries **2–3 worked exemplars** (below) as the canonical
|
||||
style reference. The `/runda` review of this ADR is where the voice and
|
||||
depth are approved.
|
||||
2. Once approved, the remaining blocks are authored to that template in
|
||||
**reviewable batches** (grouped by area: DDL, DML, app commands,
|
||||
error classes), not one monolithic drop.
|
||||
|
||||
### Exemplars (the style reference; shipped as the rendered format)
|
||||
|
||||
**Command (F1 live-input), `insert`** (the rendered shape, locked by the
|
||||
`hint_block_insert` snapshot — a `Hint` heading + aligned labels, no
|
||||
`Next:` line since tier-2 owns position-awareness):
|
||||
|
||||
```
|
||||
Hint
|
||||
What: Add one or more rows to a table.
|
||||
Example: insert into Customers values ('Ann', 'ann@example.io')
|
||||
Concept: A row is one record; each value lines up with a column, in
|
||||
order. Columns typed serial/shortid fill themselves — leave
|
||||
them out.
|
||||
```
|
||||
|
||||
**Error (`hint` command), foreign-key child-side violation:**
|
||||
|
||||
```
|
||||
Hint
|
||||
What: The value you gave for the child column doesn't match any
|
||||
parent row, so the foreign key has nothing to point at.
|
||||
Example: First insert the parent (insert into Customers …), then the
|
||||
child that references it.
|
||||
Concept: A foreign key is a promise that every child points at a real
|
||||
parent, so the parent must exist first. To allow orphans on
|
||||
delete instead, set the relationship's `on delete` to
|
||||
`set null` or `cascade`.
|
||||
```
|
||||
|
||||
**Command (F1 live-input), `add 1:n relationship`:**
|
||||
|
||||
```
|
||||
Hint
|
||||
What: Link two tables so a parent row can own many child rows.
|
||||
Example: add 1:n relationship from Customers.id to Orders.customer_id
|
||||
Concept: The "1:n" means one parent, many children. The child column
|
||||
holds the foreign key; `--create-fk` adds it for you if it
|
||||
doesn't exist yet.
|
||||
```
|
||||
|
||||
## Forks (all user-chosen, 2026-06-14)
|
||||
|
||||
- **Trigger model:** both a keybinding (live input) and a submitted
|
||||
command (last error), rather than command-only or keybinding-only — the
|
||||
live-input path is the most useful, but the command completes the A1
|
||||
slot and serves the error case.
|
||||
- **Keybinding = F1:** the universal help convention; the key is
|
||||
genuinely free (no `KeyCode::F(1)` binding exists today — the `"F1"`
|
||||
strings in `input_render.rs`/tests are scenario labels, not the key, and
|
||||
ADR-0022 uses no `F1` requirement label). No collision with the ADR-0049
|
||||
readline keys, `Ctrl-O` (ADR-0046), `Esc`-clear, or the reserved
|
||||
`Ctrl-C` cancel (I5). Rejected: `?` (a typeable character — fiddly
|
||||
position-dependent handling) and a Ctrl/Alt chord (less discoverable, no
|
||||
advantage).
|
||||
- **No topic argument:** contextual only; `help <topic>` already owns
|
||||
explicit reference lookup.
|
||||
- **Comprehensive content for v1:** the full inventory, not a starter
|
||||
subset.
|
||||
- **Exemplars-first authoring:** lock the voice on a few blocks, then
|
||||
mass-author to template.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **A1 closes.** With `hint` registered and built, all 15 canonical
|
||||
app-level commands exist in both modes.
|
||||
- **A third contextual tier exists.** Students get on-demand, teaching-
|
||||
grade guidance that is deeper than the always-on colour, the headline,
|
||||
the ambient one-liner, and the verbose error hint — without cluttering
|
||||
those terse defaults.
|
||||
- **One new keybinding (F1)** joins the keymap and the ADR-0051 strip.
|
||||
- **A new `hint_ids: &[&str]` field on `CommandNode`** (mirroring
|
||||
`usage_ids`) + a `hint_key_for_input_in_mode` lookup (reusing the
|
||||
`usage_key_for_input_in_mode` form-disambiguation), one new field of
|
||||
`App` state (`last_error_hint_key`), and one new renderer family
|
||||
(`note_hint*`); the `AppCommand` enum gains `Hint`, the grammar a `HINT`
|
||||
node, the REGISTRY one entry.
|
||||
- **A durable content corpus** (~37 command blocks + 10 runtime
|
||||
error-class blocks) enters the catalogue under `hint.cmd.*` /
|
||||
`hint.err.*`, validated by `keys.rs`. This is ongoing surface area: new
|
||||
commands/error classes should ship with their tier-3 hint (a checklist
|
||||
item for future feature ADRs). (Diagnostic-class blocks deferred — #38.)
|
||||
- **Testing:** Tier-1 unit tests for the trigger matrix (F1 with
|
||||
empty/non-empty input; `hint` with/without a recent error;
|
||||
`last_error_hint_key` set on the `translate_error` sites and cleared on
|
||||
success; the mode-aware form resolution; the `:` strip), the
|
||||
command-identification logic, and the tier-2 fallback; Tier-2 `insta`
|
||||
snapshots for a representative rendered hint block; Tier-3 integration
|
||||
tests for the end-to-end flows (type a partial command → F1 → block
|
||||
appears, **buffer and completion memo untouched**; run a failing
|
||||
command → `hint` → error expansion). **A comprehensiveness coverage
|
||||
test** (enforces D6): iterate the REGISTRY and assert every node with a
|
||||
`hint_ids` entry resolves to a `hint.cmd.*` block, and every runtime
|
||||
error class resolves to a `hint.err.*` block — `keys.rs` only checks
|
||||
that *referenced* keys resolve, not that every command/error *has* one,
|
||||
so this test is what makes the scope enforceable rather than
|
||||
aspirational. (Diagnostic classes are out of this scope — D6 / #38.)
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Per-topic `hint <topic>`** — OOS (rejected): `help <topic>` already
|
||||
serves explicit lookup; a topic arg would overlap it and double the
|
||||
content-authoring surface.
|
||||
- **Re-showing tier-3 inline as the always-on ambient hint** — OOS
|
||||
(rejected): the ambient panel stays terse by design (ADR-0022); tier-3
|
||||
is on-demand. Promoting it would defeat the tiering.
|
||||
- **Localised tier-3 content beyond `en-US`** — OOS (deferred): the
|
||||
catalogue is structured for i18n (ADR-0019), but additional locales
|
||||
follow the project's English-only-for-v1 stance (requirements X2).
|
||||
- **`hint` for a *successful* command's deeper teaching** (e.g. "you just
|
||||
created a table — here's what an index would add") — OOS (deferred): a
|
||||
plausible future tier-3 use, but v1 scopes the command path to errors
|
||||
and the F1 path to in-progress input.
|
||||
- **Clause-concept hints** (`… on delete ⟨action⟩`, constraint slots,
|
||||
`with pk`, cardinality) — OOS (deferred, issue #37): a
|
||||
`hint.concept.<topic>` layer surfaced when the cursor sits in a
|
||||
recognized clause, deeper than tier-2's candidate list but narrower than
|
||||
the per-form block. Per-form keying (D3) does not lock it out. To be
|
||||
tackled as a deliberate follow-up job, not gated on usage statistics.
|
||||
- **Pre-submit-diagnostic route + `diagnostic.*` tier-3 blocks** — OOS
|
||||
(deferred, issue #38): needs a class field on `Diagnostic` threaded
|
||||
through every creation site (broad change) for marginal value, since
|
||||
tier-2 already surfaces diagnostics and many duplicate runtime classes
|
||||
(D6).
|
||||
|
||||
## Content inventory (implementation tracking)
|
||||
|
||||
The implementation plan enumerates and checks off every block:
|
||||
|
||||
- **`hint.cmd.<hint_id>`** — one per distinct `REGISTRY` node (~37), each
|
||||
with its own `hint_id` and a mode-correct example: app (`save`, `save
|
||||
as`, `load`, `new`, `rebuild`, `export`, `import`, `replay`, `undo`,
|
||||
`redo`, `mode`, `messages`, `copy`, `help`, `hint`, `quit`); DDL
|
||||
(`create table`, `create m:n`, `add column`/`relationship`/`index`,
|
||||
`drop`, `rename`, `change column`); DML (`insert`, `update`, `delete`,
|
||||
`show`, `seed`, `explain`, `select`/`with`). The **7 advanced-mode SQL
|
||||
forms** (`SQL CREATE TABLE`, `ALTER TABLE`, `CREATE/DROP INDEX`, `DROP
|
||||
TABLE`, `SQL INSERT/UPDATE/DELETE`, `EXPLAIN SQL`, raw `SELECT`/`WITH`)
|
||||
each get their **own** block with SQL syntax — they do **not** reuse
|
||||
their simple sibling's (this is the `/runda` correction; the parallel
|
||||
`help`-side gap is issue #36).
|
||||
- **`hint.err.*`** — one per runtime error class (`unique`,
|
||||
`foreign_key.{child,parent}_side`, `not_null`, `check`,
|
||||
`type_mismatch`, `not_found`, `already_exists`, `generic`,
|
||||
`invalid_value`). The `diagnostic.*` pre-submit classes are **deferred**
|
||||
(D6 / issue #38).
|
||||
+10
-5
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user