Handoff doc for end of 2026-05-09 (#6)
Documents this session's work and the recommended next move:
## Session totals
- 11 commits since handoff-5
- 534 → 610 tests passing (+76)
- Release binary 7.2 → 7.8 MB
## What landed
- All four non-CI items from handoff-5's Independent Work
list: B2 (int→bool tests), B1 (help update), A2 (engine-
vocabulary audit), A3 (replay command)
- ADR-0019 fully implemented end-to-end:
- Friendly-error layer + i18n catalog (~170 entries
across 16 categories)
- §6 runtime row-pinpoint enrichment with
schema-resolved facts
- §9 migration sweep — every user-visible literal in
src/ now flows through the catalog (caught a ui.rs
gap during the post-sweep manual sanity check, folded
it in as sweep 3/3)
## Recommended next move
Parser-as-source-of-truth ADR + H1a implementation. The
friendly-error layer made engine errors much better;
parse-error wording is now the visibly-weakest user
surface. User explicitly surfaced the gap during manual
testing this session ("typing `create` should illustrate
the expectation"). Bounded scope, high pedagogical value,
unblocks I3/I4 in passing.
A1 (CI workflow) noted as the easy alternative for a
quick win first.
## Sharp edges captured
- New i18n workflow: catalog + keys.rs + t!() at every
use site, validator catches drift
- TranslateContext is owned (no lifetime); App combines
runtime FailureContext with verbosity
- Anchor phrases load-bearing per ADR-0019 §10
- `running: ` prefix coupled to caret-padding math
- main.rs initialises catalog before args parsing
- Several alignment-coupled strings deliberately left out
of the catalog (echo prefix tags, mode labels)
This commit is contained in:
claude@clouddev1
@@ -0,0 +1,592 @@
|
||||
# Session handoff — 2026-05-09 (6)
|
||||
|
||||
Sixth handover. The previous session (handoff-5) shipped
|
||||
ADR-0017, ADR-0018, the parser tiny-win, and the cleanup
|
||||
queue. This session worked through every item on
|
||||
handoff-5's "Independent work" list (B2, B1, A2, A3 — A1
|
||||
deferred at user request), then designed and **fully
|
||||
implemented ADR-0019** (friendly error layer + i18n
|
||||
catalog), including the schema-aware row-pinpoint enrichment
|
||||
and the catalog migration sweep. The next agent picks up a
|
||||
clean baseline with only one substantial recommended next
|
||||
move.
|
||||
|
||||
## State at handoff
|
||||
|
||||
**Branch:** `main`. Working tree clean. **1 commit ahead of
|
||||
`origin/main`** (just the latest §9 sweep — earlier commits
|
||||
were pushed between turns). Push remains the user's call.
|
||||
|
||||
Commits since handoff-5:
|
||||
|
||||
```
|
||||
a6fd26d ADR-0019 §9 sweep (3/3): ui.rs prose strings (caught in
|
||||
manual sanity)
|
||||
720511e ADR-0019 §9 sweep (2/2): help blocks + modals + system notes
|
||||
aff528a ADR-0019 §9 sweep (1/2): replay/client_side/ok/mode/
|
||||
messages/project/parse
|
||||
431645a ADR-0019 §6: runtime enrichment + row pinpointing
|
||||
eac7e5b ADR-0019 implementation: friendly error layer + i18n catalog
|
||||
d4801ea ADR-0019: pluralisation is a translator concern, not
|
||||
deferred work
|
||||
2a8618c ADR-0019: friendly error layer (H1) and i18n message catalog
|
||||
c4ee264 replay: new `replay <path>` command (A3, U4)
|
||||
b8102dc tests: ADR-0002 engine-vocabulary audit (A2)
|
||||
3dbaedc help: surface ADR-0017/0018 auto-fill semantics (B1)
|
||||
0d7a7bc db: end-to-end tests for change_column int -> bool (B2)
|
||||
```
|
||||
|
||||
**Tests:** **610 passing, 0 failing, 1 ignored** (up from
|
||||
534 at handoff-5's baseline; +76 over this session).
|
||||
The ignored test is unchanged from handoff-5 — not new
|
||||
debt. Per-phase counts:
|
||||
|
||||
- B2 (int→bool tests): +2 (534 → 536)
|
||||
- B1 (help text test): +1 (536 → 537)
|
||||
- A2 (engine-vocabulary audit): +4 (537 → 541)
|
||||
- A3 (replay command): +20 (541 → 561)
|
||||
- ADR-0019 H1 implementation: +39 (561 → 600)
|
||||
- §6 runtime enrichment: +8 integration tests + 2 fixups
|
||||
(600 → 610)
|
||||
- §9 migration sweep: 0 net (pure refactor)
|
||||
|
||||
**Clippy:** clean with `nursery` lints enabled.
|
||||
|
||||
**Release build:** ~7.8 MB single binary (up ~600 KB from
|
||||
handoff-5's 7.2 MB; the increase is the friendly module +
|
||||
serde_yml + the embedded en-US catalog).
|
||||
|
||||
## What's implemented (delta vs. handoff-5)
|
||||
|
||||
### Independent work from handoff-5 §"Independent work"
|
||||
|
||||
All four non-CI items shipped:
|
||||
|
||||
- **B2** — End-to-end tests for `change column int → bool`
|
||||
(the `(Int, Bool)` matrix entry at the db.rs level, not
|
||||
just the per-cell unit tests).
|
||||
- **B1** — In-app `help` updated to surface ADR-0017's flag
|
||||
semantics and ADR-0018's auto-fill behaviour. New
|
||||
regression test pins the wording so future help-text
|
||||
edits can't silently drop the pedagogical lines.
|
||||
- **A2** — ADR-0002 engine-vocabulary audit confirmed the
|
||||
codebase is already clean (no `SQLite` / `STRICT` /
|
||||
`PRAGMA` / `rusqlite` in user-reachable strings).
|
||||
`tests/engine_vocabulary_audit.rs` pins this so a
|
||||
regression fails loudly.
|
||||
- **A3** — New `replay <path>` DSL command. Parser
|
||||
grammar, `Action::Replay`, runtime `run_replay`,
|
||||
per-line failure reporting, file-relative-to-project
|
||||
resolution, nested-replay refusal, history.log
|
||||
invariant (sub-commands persisted but the replay
|
||||
invocation itself is not). 9 integration tests.
|
||||
|
||||
**A1 (CI workflow) remains open** — explicitly postponed
|
||||
at the start of this session.
|
||||
|
||||
### ADR-0019 (friendly error layer + i18n) — **fully implemented**
|
||||
|
||||
The session's biggest piece. Started as a deferred handoff-5
|
||||
"pending work" item; now the entire ADR is shipped, including
|
||||
the originally-deferred §6 (row pinpointing) and §9
|
||||
(migration sweep).
|
||||
|
||||
What the ADR provides:
|
||||
|
||||
- **Single chokepoint for user-visible message wording.**
|
||||
Every literal that reaches the user goes through the i18n
|
||||
catalog (`src/friendly/strings/en-US.yaml`) via the
|
||||
`t!()` macro. ~170 entries across 16 categories
|
||||
(`error.*`, `client_side.*`, `replay.*`, `ok.*`,
|
||||
`mode.*`, `messages.*`, `project.*`, `parse.*`,
|
||||
`help.*`, `dsl.*`, `advanced_mode.*`, `fatal.*`,
|
||||
`modal.*`, `save.*`, `status.*`, `panel.*`,
|
||||
`shortcut.*`).
|
||||
|
||||
- **`friendly` module** owns the structured translator:
|
||||
- `format.rs` — catalog loader (YAML embedded via
|
||||
`include_str!` + `serde_yml`), `{name}` substitution
|
||||
rejecting format specifiers per ADR-0019 §8.4.
|
||||
- `keys.rs` — the canonical
|
||||
`KEYS_AND_PLACEHOLDERS` list every translation site
|
||||
references; a unit test validates every key exists,
|
||||
placeholders match, no specifiers, no engine
|
||||
vocabulary, no orphan YAML entries.
|
||||
- `error.rs` — `FriendlyError { headline, hint,
|
||||
diagnostic_table }` payload + renderer composing the
|
||||
three blocks per ADR-0019 §7.
|
||||
- `translate.rs` — `translate(&DbError, &TranslateContext)
|
||||
→ FriendlyError` classifies UNIQUE / FK / NOT NULL /
|
||||
CHECK / type-mismatch / not_found / already_exists /
|
||||
generic / invalid_value with operation-tailored
|
||||
wording per §4. Verbose vs short via the `Verbosity`
|
||||
enum.
|
||||
|
||||
- **Runtime-side row pinpoint + schema enrichment**
|
||||
(ADR-0019 §6). When an INSERT/UPDATE/DELETE fails, the
|
||||
runtime calls `enrich_dsl_failure(database, command,
|
||||
error)` which:
|
||||
- Parses the engine message to identify the
|
||||
table/column.
|
||||
- For UNIQUE: looks up the user's attempted value from
|
||||
the Command (with schema-aware fallback for
|
||||
natural-order multi-value INSERT — including the
|
||||
serial/shortid auto-skip rule), pinpoints the
|
||||
existing conflicting row(s) via
|
||||
`Database::find_rows_matching` and renders as a
|
||||
`DiagnosticTable`.
|
||||
- For FK INSERT/UPDATE: outbound relationship lookup
|
||||
resolves `parent_table`, `parent_column`, and the
|
||||
attempted `value`.
|
||||
- For FK DELETE: inbound relationship lookup resolves
|
||||
`child_table`.
|
||||
- For NOT NULL: table+column resolution; no value or
|
||||
pinpoint (the value is null by definition).
|
||||
|
||||
- **`messages (short|verbose)` app-level command**.
|
||||
In-session state on `App::messages_verbosity`, threaded
|
||||
through `TranslateContext`. Default `verbose`
|
||||
(pedagogical headline + hint + optional diagnostic
|
||||
table). `short` drops the hint. Persistence waits on a
|
||||
future settings ADR.
|
||||
|
||||
- **`AppEvent::DslFailed`** carries
|
||||
`(command, error: DbError, facts: FailureContext)` so
|
||||
the App can defer rendering and apply its current
|
||||
verbosity at display time.
|
||||
|
||||
- **Catalog validator** (`tests::keys_validate_against_catalog`)
|
||||
enforces six invariants at build time: every key
|
||||
declared, every placeholder used and declared, no
|
||||
format specifiers, no forbidden engine vocabulary, no
|
||||
orphan YAML entries.
|
||||
|
||||
- **`main.rs`** parses the catalog at the very top so a
|
||||
corrupted build artefact fails loudly there rather than
|
||||
at the first `t!()` call deep inside the event loop.
|
||||
|
||||
What the ADR explicitly leaves out (still bounded to
|
||||
future ADRs):
|
||||
|
||||
- Advanced-mode SQL error sanitisation (waits on Q1).
|
||||
- Settings persistence for `messages` (future settings
|
||||
ADR).
|
||||
- Plural-form rules per locale (intentionally not a
|
||||
goal — see ADR §8.5 amendment).
|
||||
- Runtime locale selection (§8.2).
|
||||
- Locale-aware value formatting (rejected, not deferred —
|
||||
§8.7).
|
||||
- Constraint-management surface for CHECK (C3 territory;
|
||||
the catalog has CHECK wording ready as a placeholder).
|
||||
- Echo prefix tags + mode labels in `ui.rs` — left as
|
||||
literals because they're width-coupled to the
|
||||
alignment math; documented in commit `a6fd26d`.
|
||||
|
||||
### Anchor phrases preserved (ADR-0019 §10)
|
||||
|
||||
The catalog's anchor-phrase commitments held throughout:
|
||||
"no such table", "no such column", "no such relationship",
|
||||
"already exists", "already has the value", "cannot be
|
||||
converted", "discard information", "referenced by",
|
||||
"[client-side]". Existing tests asserting on these
|
||||
substrings still pass without rewording.
|
||||
|
||||
## Recommended next move
|
||||
|
||||
### Parser-as-source-of-truth ADR + H1a implementation
|
||||
|
||||
**This is the strongest recommendation.** Rationale:
|
||||
|
||||
- It's the natural follow-on from H1. The friendly-error
|
||||
layer dramatically improved engine-error wording; the
|
||||
parser-error wording is now the visibly-weakest user
|
||||
surface.
|
||||
- A concrete user gap surfaced during manual testing in
|
||||
this session: typing `create` produces
|
||||
`after `create`, expected `table`` — informative about
|
||||
the next missing token but not about the grammar of the
|
||||
command. The user explicitly asked "can we illustrate
|
||||
the expectation?" and we agreed it was a separate piece
|
||||
of work that needs its own ADR.
|
||||
- The handoff-5 pending list named it as the
|
||||
"load-bearing piece" because it unblocks H1a (syntax
|
||||
help in parse errors), I3 (tab completion), I4 (syntax
|
||||
highlighting), and on-the-fly error squiggles in one
|
||||
go.
|
||||
- The chumsky `keyword_ci` structural-error rework is
|
||||
the specific technical piece — today `keyword_ci` emits
|
||||
`Rich::custom` errors that don't aggregate across
|
||||
`choice` alternatives, so we get "expected `table`"
|
||||
instead of "expected `data` or `table`". Fixing that
|
||||
unlocks the rest.
|
||||
|
||||
Suggested ADR scope:
|
||||
|
||||
- What structured information chumsky already gives us
|
||||
(expected sets, span-tagged AST, partial parses on
|
||||
failure) and what we currently throw away.
|
||||
- `keyword_ci` rework so `choice` alternatives aggregate
|
||||
(the load-bearing change).
|
||||
- Per-command grammar templates surfaced in the error
|
||||
("`create table` expects: `<name> with pk
|
||||
[<col>:<type>...]`" rather than a single missing-token
|
||||
pointer).
|
||||
- Thinking ahead: how the same parse-output feeds tab
|
||||
completion (next valid token at cursor position) and
|
||||
syntax highlighting (token classification from the
|
||||
AST).
|
||||
- Catalog migration: parse-error wording joins
|
||||
`parse.*` once the grammar templates are in place.
|
||||
The current `parse.error` / `parse.caret` /
|
||||
`parse.empty` keys cover the wrapper; the per-command
|
||||
templates would land as new keys (`parse.usage.create`
|
||||
etc.).
|
||||
|
||||
Estimated: ADR design 200-400 lines; implementation
|
||||
probably 300-500 lines plus tests. Comparable in scope
|
||||
to ADR-0017's reception path.
|
||||
|
||||
## Other open work, in suggested priority order
|
||||
|
||||
### Easy alternative if you want a quick win first: A1 (CI workflow)
|
||||
|
||||
Single GitHub Actions YAML at `.github/workflows/ci.yml`.
|
||||
Cross-platform Linux / macOS / Windows; `cargo test` +
|
||||
`cargo clippy --all-targets -- -D warnings`. Locks in the
|
||||
610-test green baseline. Standard Rust CI template adapted
|
||||
to nursery-clippy. 1-2 hours. Detailed plan in handoff-5
|
||||
§A1, unchanged.
|
||||
|
||||
### Larger pending pieces
|
||||
|
||||
**Query DSL ADR + implementation.** Biggest remaining
|
||||
design piece. Earlier discussions landed on extending
|
||||
`show data` into a SELECT-style command with WHERE /
|
||||
projection / order; expose generated SQL as a pedagogical
|
||||
hook; bundle C5a's complex WHERE into one coherent
|
||||
feature. Then QA1 (EXPLAIN QUERY PLAN) becomes
|
||||
meaningful.
|
||||
|
||||
**Constraint management surface (C3).** UNIQUE / CHECK /
|
||||
NOT NULL DDL operations. The friendly-error layer has
|
||||
CHECK wording ready; the missing piece is the DDL surface
|
||||
itself. Probably 400-600 lines + tests.
|
||||
|
||||
**V-series UX projects** (handoff-5 §"Bigger UX
|
||||
projects"):
|
||||
- V4 — session log + Markdown export.
|
||||
- V1/V2 — relationship rendering (the "two structures +
|
||||
arrow" view).
|
||||
- V3 — ER diagram export.
|
||||
|
||||
### Smaller items still on the table
|
||||
|
||||
- I1 — multi-line input (Enter inserts newline,
|
||||
Ctrl-Enter submits).
|
||||
- I1b — readline shortcuts (Ctrl-A/E, Ctrl-W/K/U).
|
||||
- I3 — tab completion (depends on parser-as-source-of-
|
||||
truth).
|
||||
- I4 — syntax highlighting (depends on
|
||||
parser-as-source-of-truth).
|
||||
- C4 — m:n convenience (auto-junction-table). Rebuild
|
||||
primitive is solid so this should be straightforward.
|
||||
|
||||
### Tracked but explicitly bounded to other ADRs
|
||||
|
||||
- Q1 (SQL handling in advanced mode) — waits on Q4 (SQL
|
||||
subset ADR).
|
||||
- U-series undo/snapshot (replay landed this session as
|
||||
A3; undo + snapshot are independent and need their own
|
||||
pass).
|
||||
- Settings persistence — feeds the deferred
|
||||
`messages` persistence among other things.
|
||||
|
||||
## Sharp edges and subtleties (delta vs. handoff-5)
|
||||
|
||||
Carried-over edges still apply (sync `update`, worker
|
||||
thread, metadata transactions, rebuild-table primitive,
|
||||
modal infrastructure, project-switch lock dance, `[temp]`
|
||||
cleanup guards, persistence ordering, `DataResult` carries
|
||||
`column_types`, `output_render` is the only place tabular
|
||||
output should originate, `Type::Serial` no longer implies
|
||||
PK, `add column` returns `AddColumnResult`,
|
||||
`ChangeColumnTypeResult.client_side` field shape, non-PK
|
||||
serial INSERT auto-fill via `MAX(col)+1`, schema_to_ddl
|
||||
inline UNIQUE for non-PK, `read_schema` reads UNIQUE via
|
||||
`pragma_index_list`, structured parse-error rendering).
|
||||
New ones this session:
|
||||
|
||||
- **Every user-visible string flows through the catalog.**
|
||||
When adding a new error / hint / modal label / shortcut,
|
||||
the workflow is: add the entry to
|
||||
`src/friendly/strings/en-US.yaml`, add the
|
||||
`(key, &[placeholders])` tuple to
|
||||
`src/friendly/keys.rs::KEYS_AND_PLACEHOLDERS`, then call
|
||||
`crate::t!("category.key", placeholder = value)` at the
|
||||
use site. The validator unit test fails the build if
|
||||
any of those three steps are missed.
|
||||
|
||||
- **The translator's input is `TranslateContext` (owned
|
||||
Strings).** It used to be borrowed; the move to owned
|
||||
strings landed when runtime enrichment took over the
|
||||
schema-resolved facts. App's `build_translate_context`
|
||||
combines runtime-supplied `FailureContext` with the
|
||||
Command's operation derivation and the App's verbosity.
|
||||
|
||||
- **Anchor phrases are load-bearing.** ADR-0019 §10 lists
|
||||
9 substrings the catalog commits to keeping stable. Many
|
||||
existing tests assert on these. When migrating a
|
||||
category to new wording, preserve the anchor or
|
||||
consciously update the catalog comment block.
|
||||
|
||||
- **The `running: ` prefix is hard-coded against the
|
||||
caret-padding math.** `app.rs` derives the caret
|
||||
position from `prefix.chars().count() = 9`. The
|
||||
`dsl.running` catalog template **must** start with
|
||||
"running: " for caret rendering to align. Documented
|
||||
inline.
|
||||
|
||||
- **`main.rs` initialises the catalog before args
|
||||
parsing** so the args-error path can use `help_text()`.
|
||||
A corrupted catalog (impossible in practice since it's
|
||||
`include_str!`'d and validated) would panic before the
|
||||
args error surfaces. Acceptable for a teaching tool.
|
||||
|
||||
- **`AppEvent::DslFailed` carries structured payload, not
|
||||
a pre-rendered string.** Tests that synthesise this
|
||||
event (in `tests/walking_skeleton.rs` and `app::tests`)
|
||||
must construct a `DbError` and a `FailureContext` (use
|
||||
`::default()` if you don't care about enrichment).
|
||||
|
||||
- **`Database::find_rows_matching(table, column, value,
|
||||
limit)`** is the public hook for row-pinpoint queries.
|
||||
The runtime uses it for UNIQUE conflict diagnostics. If
|
||||
a future feature wants similar row-finding (e.g. FK
|
||||
parent-side pinpoint, which is structurally plumbed but
|
||||
not yet populated — see runtime.rs's
|
||||
`enrich_fk_violation`'s "FK pinpoint not implemented in
|
||||
v1" comment), reuse this method.
|
||||
|
||||
- **`Database::read_relationships(table)` returns
|
||||
`(outbound, inbound)`.** The lifted version of the
|
||||
previously-private `read_relationships_outbound/inbound`
|
||||
pair.
|
||||
|
||||
## ADR index (read these before touching the related areas)
|
||||
|
||||
```
|
||||
0000 Record architecture decisions (process)
|
||||
0001 Language and TUI framework (Rust + Ratatui)
|
||||
0002 Database engine
|
||||
— User-facing posture (engine-vocabulary audit
|
||||
regression-tested via tests/engine_vocabulary_audit.rs)
|
||||
0003 Input modes and command dispatch
|
||||
0004 Project file format
|
||||
— amended by 0015
|
||||
0005 Column type vocabulary
|
||||
— definition of `serial` generalised by ADR-0018
|
||||
0006 Undo snapshots and replay log
|
||||
— replay command landed this session (ADR-0019 §9
|
||||
migration sweep covered its message wording too)
|
||||
0007 Sharing and export
|
||||
— amended by 0015 amendment 1
|
||||
0008 Testing approach
|
||||
0009 DSL command syntax conventions
|
||||
0010 Database access via worker thread
|
||||
— ADR-0019 §6 enrichment uses the worker via two new
|
||||
public methods (read_relationships, find_rows_matching)
|
||||
0011 FK column type compatibility
|
||||
0012 Internal metadata for user-facing column types
|
||||
0013 Relationships, naming, and rebuild-table strategy
|
||||
0014 Data operations, value literals, and auto-show
|
||||
0015 Project storage runtime
|
||||
— ColumnSchema gained `unique: bool` for ADR-0018
|
||||
0016 Pretty table rendering for data and structure views
|
||||
— ADR-0019 §7 reuses `render_diagnostic_table` for
|
||||
the friendly-error pinpoint output
|
||||
0017 Column type-change compatibility
|
||||
0018 Auto-fill contracts for serial and shortid columns
|
||||
0019 Friendly error layer (H1) and i18n message catalog
|
||||
— IMPLEMENTED (this session). Catalog covers ~170
|
||||
entries across 16 categories. Runtime enrichment
|
||||
per §6, migration sweep per §9 both done.
|
||||
```
|
||||
|
||||
## Repository layout (delta vs. handoff-5)
|
||||
|
||||
```
|
||||
src/
|
||||
friendly/ — new module (ADR-0019)
|
||||
mod.rs — public API, t!() macro
|
||||
format.rs — catalog loader, substitution
|
||||
keys.rs — KEYS_AND_PLACEHOLDERS + validator
|
||||
error.rs — FriendlyError + DiagnosticTable + render
|
||||
translate.rs — DbError → FriendlyError classification
|
||||
strings/
|
||||
en-US.yaml — the catalog body (~170 entries)
|
||||
action.rs — Action::Replay
|
||||
app.rs — messages command + verbosity field;
|
||||
build_translate_context;
|
||||
attempted-value extraction (later
|
||||
moved to runtime); note_ok_summary
|
||||
helper; modal/help/system notes all
|
||||
go through t!()
|
||||
cli.rs — HELP_TEXT const replaced with
|
||||
pub fn help_text() that reads catalog
|
||||
db.rs — Request::ReadRelationships +
|
||||
Request::FindRowsMatching;
|
||||
read_relationships /
|
||||
find_rows_matching public methods;
|
||||
RelationshipsReply type alias;
|
||||
friendly_message body delegates to
|
||||
translator; friendly_change_column_engine_error
|
||||
+ enrich_fk_message removed;
|
||||
fk_violation_message_lists_outbound_relationships
|
||||
test rewritten as
|
||||
fk_violation_returns_engine_classified_constraint_error
|
||||
dsl/
|
||||
command.rs — Command::Replay variant
|
||||
parser.rs — replay rule + path_literal terminal
|
||||
event.rs — DslFailed { command, error, facts }
|
||||
+ Replay events
|
||||
main.rs — catalog init at top; help_text() use
|
||||
runtime.rs — Action::Replay handler;
|
||||
spawn_replay + run_replay (pub for
|
||||
integration tests);
|
||||
enrich_dsl_failure (pub) + helpers;
|
||||
resolve_replay_path
|
||||
ui.rs — modal/status/panel/shortcut strings
|
||||
routed through t!() (left echo prefix
|
||||
tags + mode labels alone — alignment-
|
||||
coupled, documented)
|
||||
docs/
|
||||
adr/
|
||||
0019-friendly-error-layer-and-i18n.md
|
||||
— new (this session)
|
||||
README.md — indexed
|
||||
handoff/
|
||||
20260509-handoff-6.md — this file
|
||||
tests/
|
||||
engine_vocabulary_audit.rs — new in this session (A2)
|
||||
friendly_enrichment.rs — 8 integration tests for ADR-0019 §6
|
||||
replay_command.rs — 9 integration tests for A3 (U4)
|
||||
```
|
||||
|
||||
## How to take over
|
||||
|
||||
1. Read this file.
|
||||
2. Read `CLAUDE.md` for the working-style rules.
|
||||
3. Read `docs/requirements.md` for the granular progress
|
||||
table.
|
||||
4. **If picking up the recommended next move (parser-as-
|
||||
source-of-truth ADR)**: read `docs/adr/0019-*` to see
|
||||
how ADR-0019 framed catalog wording, since parse errors
|
||||
join the catalog under `parse.*`. The current keys are
|
||||
`parse.error`, `parse.caret`, `parse.empty` — the new
|
||||
work would add `parse.usage.<command>` and friends.
|
||||
Read `src/dsl/parser.rs` for the chumsky scaffolding
|
||||
and `src/app.rs::dispatch_dsl` for the source-line +
|
||||
caret rendering. The `keyword_ci` rework is the
|
||||
technical core.
|
||||
5. **If picking up A1 (CI)**: handoff-5 §A1 has a
|
||||
complete plan. Nothing new to add.
|
||||
6. **If picking up Query DSL or another bigger piece**:
|
||||
start with an ADR draft. Don't implement without one —
|
||||
those touch enough code to warrant the discipline.
|
||||
7. Run `cargo test` to confirm the 610-test green
|
||||
baseline.
|
||||
8. Run `cargo clippy --all-targets` to confirm
|
||||
clippy-clean.
|
||||
9. Run `cargo run --release` and try the smoke test in
|
||||
the next section.
|
||||
|
||||
### End-to-end smoke test (current state)
|
||||
|
||||
Demonstrates ADR-0019's friendly-error wording with row
|
||||
pinpointing. Replaces handoff-5's recipe (which is now
|
||||
stale — every error path renders through the catalog and
|
||||
shows pinpointed rows where applicable).
|
||||
|
||||
```
|
||||
$ rm -rf /tmp/handoff6-smoke
|
||||
$ rdbms-playground --data-dir /tmp/handoff6-smoke
|
||||
|
||||
# Inside the app:
|
||||
help -- in-app help (now from catalog)
|
||||
messages -- shows current verbosity
|
||||
(verbose by default)
|
||||
|
||||
# Setup:
|
||||
create table Customers with pk id:int
|
||||
add column Customers: Name (text)
|
||||
insert into Customers (1, 'Alice')
|
||||
insert into Customers (2, 'Bob')
|
||||
|
||||
create table Orders with pk id:serial
|
||||
add column Orders: CustId (int)
|
||||
add column Orders: Total (real)
|
||||
add 1:n relationship from Customers.id to Orders.CustId
|
||||
insert into Orders (CustId, Total) values (1, 9.99)
|
||||
|
||||
# UNIQUE INSERT — original report case from this session:
|
||||
insert into Customers (1, 'Carol')
|
||||
-- emits:
|
||||
-- "insert into Customers" failed:
|
||||
-- `Customers.id` already has the value `1`.
|
||||
-- The `id` column on `Customers` is unique —
|
||||
-- pick a different value, or update the existing
|
||||
-- row instead.
|
||||
-- + bordered table showing Alice's row.
|
||||
|
||||
# UNIQUE UPDATE — operation-tailored hint:
|
||||
update Customers set id=1 where Name='Bob'
|
||||
-- "your update would create a duplicate"
|
||||
-- (different from the INSERT wording)
|
||||
|
||||
# FK INSERT (child-side) — was broken pre-§6, now resolves
|
||||
# parent_table/parent_column/value via outbound-FK lookup:
|
||||
insert into Orders (CustId, Total) values (999, 5.50)
|
||||
-- "no parent row in `Customers` has `id` = `999`"
|
||||
-- + hint about inserting a matching parent.
|
||||
|
||||
# FK DELETE (parent-side) — child_table from inbound-FK lookup:
|
||||
delete from Customers where id=1
|
||||
-- "`Customers` rows are referenced by `Orders`"
|
||||
|
||||
# Compare verbosity:
|
||||
messages short
|
||||
insert into Customers (1, 'Carol') -- headline only, no hint, but
|
||||
pinpoint table still shows
|
||||
messages verbose
|
||||
insert into Customers (1, 'Carol') -- full headline + hint + pinpoint
|
||||
|
||||
# Replay (A3 from earlier in session):
|
||||
# Save a few commands to a file then replay:
|
||||
save -- prompts for project name
|
||||
# Or use `replay history.log` to re-run the entire session.
|
||||
replay history.log
|
||||
|
||||
# Anchor phrases:
|
||||
show data Ghost -- "no such table: `Ghost`"
|
||||
(anchor: "no such table")
|
||||
|
||||
quit
|
||||
```
|
||||
|
||||
### Manual spot-checks worth running
|
||||
|
||||
- `--help` produces the CLI banner from the catalog (no
|
||||
literal const anymore).
|
||||
- `mode advanced` then any input produces the
|
||||
not-implemented placeholder ("advanced mode SQL not
|
||||
implemented yet — echo: …").
|
||||
- `messages` toggles verbosity in-session; not persisted
|
||||
across restarts (waits on settings ADR).
|
||||
- Switch to a non-existent project path → see "path `…`
|
||||
does not exist" via `project.load_path_missing`.
|
||||
- Trigger a parse error (e.g. `create`) → see the caret
|
||||
pointer aligned under the offending character + the
|
||||
structural "after `create`, expected `table`" message
|
||||
(still chumsky-derived; the parser-as-source-of-truth
|
||||
ADR addresses this). This is the recommended-next-move
|
||||
hook.
|
||||
Reference in New Issue
Block a user