docs: session handoff 60 — Gitea migration cleanup + V1 relationship visualization (ADR-0044)
This commit is contained in:
claude@clouddev1
@@ -0,0 +1,211 @@
|
|||||||
|
# Session handoff — 2026-06-10 (60)
|
||||||
|
|
||||||
|
Sixtieth handover. Continues from handoff-59 (tracking reconciliation
|
||||||
|
+ V5/H3/V5a sweep + T3 compound-PK FK). This session did **three**
|
||||||
|
things: (1) verified the **Claude Code 2.1.170** upgrade is healthy;
|
||||||
|
(2) finished the **GitHub→Gitea migration cleanup** and added `tea`
|
||||||
|
issue-tracking conventions; (3) the big one — **completed requirement
|
||||||
|
V1, relationship visualization**, designed in **ADR-0044** and
|
||||||
|
implemented end-to-end with two `/runda` passes.
|
||||||
|
|
||||||
|
## §1. State at handoff
|
||||||
|
|
||||||
|
**Branch:** `main`. **HEAD `0a34303`.** 5 commits this session
|
||||||
|
(`b17148b` → `0a34303`); push is the user's step.
|
||||||
|
|
||||||
|
**Tests: 2207 passing / 0 failing / 1 ignored** (lib 1586, it 429,
|
||||||
|
typing_surface_matrix 192; the 1 ignored is the long-standing
|
||||||
|
doc-test). **Clippy clean** (nursery, all targets). +14 over the
|
||||||
|
handoff-59 baseline of 2193.
|
||||||
|
|
||||||
|
This session's commits:
|
||||||
|
```
|
||||||
|
0a34303 feat: compound-FK bus routing + complete V1 relationship visualization (ADR-0044)
|
||||||
|
a0ee323 feat: show table renders relationships as compact diagrams (ADR-0044)
|
||||||
|
cad90ec feat: show relationship <name> renders a styled two-table diagram (ADR-0044)
|
||||||
|
bb02dfb docs: ADR-0044 relationship visualization (V1); accepted
|
||||||
|
b17148b docs: scrub GitHub-specifics after Gitea migration; add tea issue conventions
|
||||||
|
```
|
||||||
|
|
||||||
|
## §2. Repo migration: GitHub → Gitea (commit `b17148b`)
|
||||||
|
|
||||||
|
The repo moved off GitHub to a self-hosted **Gitea** at
|
||||||
|
`git.lazyeval.net` (`oli/rdbms-playground`). `tea` auto-detects this
|
||||||
|
repo correctly off the remote **even though the machine's default
|
||||||
|
`tea` login is a different host** (`git.oliversturm.com`) — verified.
|
||||||
|
|
||||||
|
- **Durable GitHub-specifics scrubbed:** `Cargo.toml` `repository`
|
||||||
|
URL; `requirements.md` backlog note ("now tracked as Gitea
|
||||||
|
issues"); **ADR-0001 Amendment 1** reopens the prebuilt-binary
|
||||||
|
distribution channel (was "GitHub releases") as an undecided choice
|
||||||
|
for a future distribution ADR (the Decision text was *not*
|
||||||
|
rewritten, per supersede-don't-rewrite).
|
||||||
|
- **Left as historical:** all `docs/handoff/*.md` (append-only log).
|
||||||
|
- **`CLAUDE.md` gained** an *Issue tracking* working-style bullet +
|
||||||
|
an *Issue tracking — Gitea via `tea`* section (adapted from another
|
||||||
|
project; repo coordinates corrected, `tea` gotchas kept). **Working
|
||||||
|
method now: file bugs/enhancements as Gitea issues, cross-reference
|
||||||
|
in commits/handoffs; `requirements.md` + ADRs remain the source of
|
||||||
|
truth for scope/decisions; a change to a decided area still earns an
|
||||||
|
ADR.** No heavyweight planning workflow (we're near completion of
|
||||||
|
the initial requirements).
|
||||||
|
- No open Gitea issues; the 18-issue campaign backlog (#1–#18) is all
|
||||||
|
closed. V1 lives in `requirements.md`, not an issue.
|
||||||
|
|
||||||
|
## §3. V1 — relationship visualization (the big one)
|
||||||
|
|
||||||
|
**ADR-0044** (`docs/adr/0044-relationship-visualization.md`, Accepted
|
||||||
|
2026-06-09, **implemented 2026-06-10**). Resolves **ADR-0016 OOS-1**
|
||||||
|
and closes `requirements.md` **V1** (`[x]`). The
|
||||||
|
relationship-as-line-art half that had been "repeatedly pushed away"
|
||||||
|
now renders as **Style-A two-table connector diagrams**.
|
||||||
|
|
||||||
|
**Design forks (all user-chosen):**
|
||||||
|
- **Style A** (two structure boxes + connector) over a compact key
|
||||||
|
card or crow's-foot ER.
|
||||||
|
- **Reach = "relationship-relevant"** (over global / show-only):
|
||||||
|
diagrams where the relationship is the *subject* —
|
||||||
|
`show relationship <name>`, `show table <T>`, and
|
||||||
|
`add`/`drop relationship` echoes; incidental DDL echoes (add column,
|
||||||
|
drop index, change column, plain create table) keep the prose
|
||||||
|
`References:` / `Referenced by:` form.
|
||||||
|
- **`show table` layout:** focal structure box, then a
|
||||||
|
**Relationships** section of **stacked compact** per-relationship
|
||||||
|
diagrams (over a focal-centred subgraph — no crossing lines, scales
|
||||||
|
via scroll, two-boxes-wide fits any terminal).
|
||||||
|
|
||||||
|
**Visual conventions:** child (FK holder) on the **left**, parent
|
||||||
|
(referenced) on the **right**, arrow → (child references parent),
|
||||||
|
**`n` … `1`** cardinality, referential actions beneath, and a
|
||||||
|
**bold title row + rule** on every box so a table name can't read as
|
||||||
|
a column. Compound FKs route a shared **bus** (each endpoint stub
|
||||||
|
merges into a vertical channel that splits to the paired endpoints)
|
||||||
|
plus an explicit `(a, b) ▶ P.(x, y)` **pairing line**.
|
||||||
|
Self-referential FKs draw two same-named boxes. **Width-aware**:
|
||||||
|
side-by-side when it fits, else a **vertical stack** fallback.
|
||||||
|
|
||||||
|
**Three implementation increments:**
|
||||||
|
- `cad90ec` — `show relationship <name>` full diagram (both tables as
|
||||||
|
full structure boxes).
|
||||||
|
- `a0ee323` — `show table` compact stacked diagrams + the
|
||||||
|
`Diagram|Prose` render mode.
|
||||||
|
- `0a34303` — compound-FK bus routing + pairing line, self-referential
|
||||||
|
diagrams, V1 → `[x]`.
|
||||||
|
|
||||||
|
**Two `/runda` passes.** The design pass (pre-build) **caught an
|
||||||
|
inverted-architecture assumption** carried in from a code survey
|
||||||
|
(rendering is App-side, not worker-side; width was claimed "already
|
||||||
|
tracked" but wasn't; `show relationship` built prose in the worker).
|
||||||
|
The implementation pass confirmed ADR-compliance, UTF-8/byte-range
|
||||||
|
safety, and edge-case routing, and added a compound-from-data glue
|
||||||
|
test. The §3 **last-resort helper line was considered and rejected**
|
||||||
|
(vertical fallback + ratatui truncation cover all realistic cases).
|
||||||
|
|
||||||
|
## §4. Key implementation facts (read before touching the renderer)
|
||||||
|
|
||||||
|
- **Rendering is App-side.** `output_render.rs` helpers
|
||||||
|
(`render_structure`, `render_data_table`, and the new diagram
|
||||||
|
functions) are called from **`app.rs`**, never `db.rs`. The worker
|
||||||
|
returns structured data (`TableDescription`); the App formats it.
|
||||||
|
*(An Explore survey got this backwards — verify architecture claims
|
||||||
|
against the code, not a summary.)*
|
||||||
|
- **The diagram renderer** lives in `output_render.rs` under the
|
||||||
|
`// ── Relationship visualization (ADR-0044)` banner: a styled `Seg`
|
||||||
|
engine (text + `OutputSpan` runs that compose by concatenation with
|
||||||
|
offset-shifting); `render_box` (full or compact box with a title
|
||||||
|
row); `gutter_seg` + `junction` (the bus connector — routes **all**
|
||||||
|
endpoint pairs, reduces exactly to the single-column jog);
|
||||||
|
`compose_side_by_side` / `compose_vertical`;
|
||||||
|
`render_relationship_layout` (width dispatch + pairing line);
|
||||||
|
`render_relationship_diagram` (the `show relationship` entry, builds
|
||||||
|
full `DiagramTable`s from `RelationshipDiagramData`);
|
||||||
|
`render_structure_with_diagrams` (the `show table` entry: focal box
|
||||||
|
+ compact diagrams; `render_structure` was refactored into section
|
||||||
|
helpers — `structure_box_lines` / `relationship_prose_lines` /
|
||||||
|
`index_lines` / `constraint_lines` — with **byte-identical** prose
|
||||||
|
output so the old snapshots held).
|
||||||
|
- **`show relationship` worker path:** `db.rs`
|
||||||
|
`RelationshipDiagramData` (rel + both endpoint `TableDescription`s)
|
||||||
|
+ `Database::show_relationship` + `do_show_relationship`; runtime
|
||||||
|
`CommandOutcome::ShowRelationship` (boxed — two `TableDescription`s
|
||||||
|
dwarf the other variants) reroutes a named relationship before the
|
||||||
|
prose `show_list` fallback; event `DslShowRelationshipSucceeded`;
|
||||||
|
app `handle_dsl_show_relationship_success`.
|
||||||
|
- **The Diagram/Prose split** is in `handle_dsl_success`: it renders
|
||||||
|
diagrams for `ShowTable | AddRelationship | DropRelationship`, prose
|
||||||
|
otherwise.
|
||||||
|
- **Width:** new `App::last_output_width` (default `80`), set from
|
||||||
|
`ui.rs` `render_output_panel` next to `note_output_viewport`.
|
||||||
|
Snapshot at command time — **no live reflow** (that's V4).
|
||||||
|
- **Styling:** four new `OutputStyleClass` variants
|
||||||
|
(`DiagramTableName` / `DiagramKey` / `DiagramCardinality` /
|
||||||
|
`DiagramConnector`), mapped in `ui.rs::output_span_style` to
|
||||||
|
**existing** theme colours (no new `Theme` fields). `Seg` only ever
|
||||||
|
pushes whole strings/chars, so styled-run byte ranges are always
|
||||||
|
valid UTF-8 boundaries (exercised live by the `add relationship`
|
||||||
|
`rendered_text` test through `ui.rs`'s `text[start..end]` slice).
|
||||||
|
- **`do_show_one`'s relationship prose branch is now dead-for-users**
|
||||||
|
(the reroute supersedes it) but **retained** — reachable via the
|
||||||
|
`Database::show_list` worker API, covered by a worker test, and a
|
||||||
|
candidate text fallback for a future non-visual display option (cf.
|
||||||
|
ADR-0044 **OOS-7** relationship-display setting). Documented in
|
||||||
|
`db.rs`.
|
||||||
|
- **Two bugs the tests caught** (both in compact boxes, which the
|
||||||
|
single-relationship full-box tests didn't exercise): an eager
|
||||||
|
`widths[1]` index panic (`then_some` → `then`), and body-cell
|
||||||
|
padding under title-widening (pass the widened `widths[0]`, not the
|
||||||
|
pre-widening `label_w`).
|
||||||
|
|
||||||
|
## §5. Remaining open landscape
|
||||||
|
|
||||||
|
**Still `[/]` partial / `[~]` / larger (unchanged from handoff-59):**
|
||||||
|
- **V2 / S3** multi-result tabs — output-model redesign.
|
||||||
|
- **V3** whole-DB ER export; **V4** scrollable journal + Markdown
|
||||||
|
(the home for diagram live-reflow, OOS-1 here).
|
||||||
|
- **A1** app-commands — blocked on `seed` (SD1) + `hint` (H2).
|
||||||
|
- **DOC1** reference docs; **X1** logging density.
|
||||||
|
|
||||||
|
**`[ ]` not started:** H2 `hint`, SD1 `seed`, C4 m:n, B3
|
||||||
|
query-timeout, I1 multi-line, I1b readline, I5 cancellation, **TT5
|
||||||
|
CI** (now Gitea Actions, ties into ADR-0001's reopened distribution
|
||||||
|
question), TT4 PTY (spec-only), D1–D3 distribution, NFR-1…7.
|
||||||
|
|
||||||
|
**ADR-0044 OOS for later:** OOS-7 user-configurable
|
||||||
|
relationship-display setting (always-prose / always-diagram /
|
||||||
|
auto-by-width); compound display polish if needed.
|
||||||
|
|
||||||
|
## §6. Next job — candidates
|
||||||
|
|
||||||
|
No forced next step. By readiness:
|
||||||
|
1. **X1 logging** — mechanical, no ADR; brings instrumentation to the
|
||||||
|
`CLAUDE.md` "log liberally" bar (~25 `tracing` sites today).
|
||||||
|
2. **TT5 CI** — test infra solid (2207 green); no pipeline. Now
|
||||||
|
**Gitea Actions / Woodpecker**, not GitHub Actions — a fresh
|
||||||
|
decision tied to today's migration + ADR-0001's distribution
|
||||||
|
question.
|
||||||
|
3. **T3 residuals** (ADR-0043 §4) — two messaging-only polish items
|
||||||
|
(inline-FK arity error wording; compound-FK-violation friendly
|
||||||
|
error names only the first pair).
|
||||||
|
4. **V2/S3 multi-result tabs** or **V4 journal** — larger,
|
||||||
|
design-first (own ADR).
|
||||||
|
|
||||||
|
## §7. How to take over
|
||||||
|
|
||||||
|
1. Read handoffs 58 → 59 → 60, then `CLAUDE.md` (now with the
|
||||||
|
*Issue tracking — Gitea via `tea`* section), `docs/requirements.md`
|
||||||
|
(V1 now `[x]`), `docs/adr/README.md`.
|
||||||
|
2. **For relationship diagrams: read ADR-0044**, then the
|
||||||
|
`// ── Relationship visualization` block in `src/output_render.rs`
|
||||||
|
(§4 above maps the functions).
|
||||||
|
3. **Gitea/`tea`:** plain `tea issues` works here (auto-detects
|
||||||
|
`git.lazyeval.net`); the gotchas section in `CLAUDE.md` matters
|
||||||
|
(stdin-hang → `< /dev/null`; multiline bodies via temp file; the
|
||||||
|
display blind-spot for milestones/comments).
|
||||||
|
4. Codebase on `main` at `0a34303`, clean, 5 commits unpushed.
|
||||||
|
5. Process pins that paid off this session: **verify architecture
|
||||||
|
claims against the code, not a survey** (the §3 inversion);
|
||||||
|
**`/runda` after design AND after implementation** (both found real
|
||||||
|
things); **tests on the *compact* path caught bugs the full-box
|
||||||
|
path missed** — exercise every variant; **escalate genuine forks**
|
||||||
|
(every V1 design choice was the user's). Commits user-confirmed,
|
||||||
|
append-only, no AI attribution.
|
||||||
Reference in New Issue
Block a user