rdbms-playground/docs/adr/0050-incidental-ddl-confirmations-omit-relationships.md

# 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.