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