biggus-dickus/docs/superpowers/specs/2026-06-05-reference-data-edit-delete-design.md

# Reference-Data Edit/Delete Lifecycle — Design

**Date:** 2026-06-05
**Status:** Approved (brainstorming) — ready for implementation planning.
**Issues:** #30 (vocabularies/terms/authorities edit+delete), #36 (field-definitions edit+delete).

## Context

The admin reference-data surface currently exposes **create + list only** for all four
entity kinds:

- Vocabularies & terms — `GET/POST /api/admin/vocabularies`,
  `GET/POST /api/admin/vocabularies/{id}/terms`
- Authorities — `GET/POST /api/admin/authorities?kind=`
- Field definitions — `GET/POST /api/admin/field-definitions`

There is no way to rename a vocabulary, correct a term's labels/URI, fix a misspelled
authority, edit a field definition's labels/group/required flag, or delete any of them.
In a cataloguing system this is a real operational gap: reference data accrues mistakes
that today can only be fixed by direct DB edits. This milestone completes the CRUD
lifecycle — backend endpoints **and** frontend UI — for all four kinds.

### The integrity constraint that shapes everything

Object flexible-field values live in a **JSONB column on `object`** (migration
`0005_object_fields.sql`: `ALTER TABLE object ADD COLUMN fields JSONB NOT NULL DEFAULT
'{}'`), keyed by field-definition `key`, with `term`/`authority` references stored as
**UUID strings inside that JSON**. There is **no foreign key** from object data to
terms/authorities/field-definitions. Consequences:

- Deleting a **term, authority, or field-definition** is *not* blocked or cascaded by
  the database — it would silently leave dangling UUIDs / orphaned keys in objects. Any
  "is it referenced?" guard must be an explicit JSONB scan we write.
- Deleting a **vocabulary** *is* already protected: `term.vocabulary_id` and
  `field_definition.vocabulary_id` are `REFERENCES vocabulary (id) ON DELETE RESTRICT`
  (migrations `0002`, `0004`). So a non-empty/bound vocabulary delete fails at the FK
  level — we catch that and surface a clean 409, rather than invent a check.
- `term_label`, `authority_label`, `field_definition_label` are all `ON DELETE CASCADE`
  from their parent, so deleting a term/authority/field-def cleans up its own labels.

### Decisions settled in brainstorming

1. **Scope:** cohesive — backend **and** frontend edit/delete for all four kinds in one
   milestone (no backend endpoints shipping without UI).
2. **Delete policy for referenced entities:** **block with 409 + count.** Never silently
   alter catalogue data. The curator must clear/reassign the referencing object fields
   first. (Cascade-scrub was rejected as too destructive / no undo.)
3. **Field-definition immutability:** `key`, `data_type`, and binding
   (`vocabulary_id`/`authority_kind`) are **immutable**; `labels`, `group_key`,
   `required` are editable.
4. **`required` toggled on:** allowed; governs validation on *future* object writes only
   — no retroactive scan or block of existing objects.
5. **Vocabulary `key` rename:** allowed (cosmetic — terms and field-definitions bind by
   vocabulary UUID, not key).
6. **Frontend affordance:** **in-place edit + `AlertDialog` delete** (Option A) — reuse
   the existing two-pane form panes and the installed AlertDialog; no new shadcn deps.
7. **Storybook:** add co-located stories for components created or meaningfully changed
   where it makes sense (forms, editable rows, dialogs) — not every trivial change.

## Backend

All endpoints are gated by `EditCatalogue` and audited: every mutation runs the
insert/update/delete **and** `audit::record(&mut *conn, &NewAuditEvent { actor, action,
entity_type, entity_id, .. })` in **one transaction**, mirroring the #21 create-audit
pattern (`AuditActor::User(auth.user.id.to_uuid())`). Audit actions: `Updated` /
`Deleted`.

### Endpoints

**Vocabularies / terms** (`crates/api/src/admin_vocab.rs`)
- `PATCH /api/admin/vocabularies/{id}` — rename `key` only.
- `DELETE /api/admin/vocabularies/{id}` — allowed only when the vocabulary has no terms
  and is bound by no field-definition. Enforced by the existing FK `RESTRICT`; the
  resulting `sqlx` FK error is mapped to **409** with a reason, not a 500.
- `PATCH /api/admin/vocabularies/{id}/terms/{term_id}` — edit labels + `external_uri`.
- `DELETE /api/admin/vocabularies/{id}/terms/{term_id}` — **409 + count** if any object
  references the term; otherwise delete (its `term_label` rows cascade).

**Authorities** (`crates/api/src/admin_authorities.rs`)
- `PATCH /api/admin/authorities/{id}` — edit labels + `external_uri`. `kind` is
  **immutable** (field bindings filter by kind).
- `DELETE /api/admin/authorities/{id}` — **409 + count** if referenced; otherwise delete
  (`authority_label` cascades).

**Field definitions** (`crates/api/src/` field-definition handler)
- `PATCH /api/admin/field-definitions/{key}` — edit labels, `group_key`, `required`. The
  PATCH body exposes **only** those three fields, so `key`/`data_type`/binding are
  **structurally immutable** (they cannot be sent — no runtime reject needed). Invalid
  values (empty label, empty `group_key` — both have `CHECK <> ''` constraints) return
  **422**, consistent with the create path.
- `DELETE /api/admin/field-definitions/{key}` — **409 + count** if any object stores that
  field key; otherwise delete (label cascades).

### Referenced-checks (JSONB scans)

- **Term / authority referenced:** count objects whose `fields` JSONB contains the UUID
  as a value. Use a jsonpath value-match, scoped to the field keys whose definition is
  `term`/`authority`-typed for that vocabulary/kind, to avoid false positives. Returns a
  count (and the implementation may also collect a small sample of object numbers for the
  UI message).
- **Field-definition referenced:** count objects where `fields ? '<key>'` (JSONB
  key-exists operator) — simple and indexable.

### DB layer (`crates/db/src/{vocab,authority,fields}.rs`)

New functions, each taking `actor: AuditActor` and a `&mut PgConnection` and writing its
audit entry atomically (mirroring the existing create functions):

- `vocab::rename_vocabulary`, `vocab::delete_vocabulary`, `vocab::update_term`,
  `vocab::delete_term`, `vocab::count_objects_referencing_term`
- `authority::update_authority`, `authority::delete_authority`,
  `authority::count_objects_referencing_authority`
- `fields::update_field_definition`, `fields::delete_field_definition`,
  `fields::count_objects_using_field`

`delete_vocabulary` maps the FK-restrict error to a typed "in use" error so the handler
can return 409. The three `count_*` helpers are read-only (no audit, no actor).

### API error shape

Reuse the existing typed-error conventions:
- **409 (referenced / in-use):** JSON body with the blocking count (e.g.
  `{ "code": "in_use", "count": N }`) so the UI can render "used by N objects".
- **422 (invalid value):** the existing field-error shape
  (`{ field, code }`, e.g. empty label / empty `group_key`), consistent with
  `set_fields`' `FieldErrorView` and the create path. (Immutability is enforced
  structurally by the PATCH DTO, not by a runtime 422.)
- **404:** entity not found.

OpenAPI is regenerated so `web/src/api/schema.d.ts` picks up the new endpoints and DTOs.

## Frontend

**Affordance: in-place edit + `AlertDialog` delete**, per screen layout. Deletes
everywhere use the installed `AlertDialog`, mirroring the existing `DeleteObjectDialog`.

### Per-screen

**Fields** (`web/src/fields/`, two-pane `/fields`)
- Selecting a row in the left `FieldList` turns the right pane (`FieldForm`) into an
  **edit form**: `labels` / `group_key` / `required` editable; `key` / `data_type` /
  binding shown **disabled**. A "New field" button resets the pane to create mode.
- Each list row gets a delete affordance → `AlertDialog` confirm.

**Vocabularies** (`web/src/vocab/`, two-pane `/vocabularies/:id`)
- Left `VocabularyList` rows: rename-`key` (inline edit) + delete.
- Right-pane (`VocabularyTerms`) term rows: edit (labels/URI) + delete.

**Authorities** (`web/src/authorities/`, single-pane `/authorities/:kind`)
- Each authority row: inline-expand edit (labels/URI) + delete.

### Hooks (`web/src/api/queries.ts`)

Add, mirroring `useUpdateObject`/`useDeleteObject` and invalidating the correct list
query keys: `useRenameVocabulary`, `useDeleteVocabulary`, `useUpdateTerm`,
`useDeleteTerm`, `useUpdateAuthority`, `useDeleteAuthority`, `useUpdateFieldDefinition`,
`useDeleteFieldDefinition`. The **409 (referenced)** and **422 (immutable)** responses
parse into the existing `HttpError`/`FieldRejection` style.

### Delete-blocked UX

On a 409 the `AlertDialog` **stays open** and shows the blocking reason —
`t("actions.inUse", { count })` → e.g. *"Used by 7 objects — clear those fields first"* —
instead of closing.

### i18n (`web/src/i18n/{en,sv}.json`)

New action keys under `vocab.*` / `authorities.*` / `fields.*` plus a shared `actions.*`
namespace where it makes sense: `edit`, `delete`, `rename`, `save`, `cancel`, `inUse`
(count-interpolated). **en/sv parity** required.

### Storybook

Add co-located `*.stories.tsx` for the components that gain meaningful states: the
field-definition edit form, the editable term/authority row, and the delete-confirm
dialog wrapper. (Skip trivially-changed components.)

## Testing

**Backend** (existing infra: compose Postgres on host 5442, Meili on 7700;
`#[sqlx::test]` provisions its own DB; mirror `crates/api/tests/admin_catalog.rs`):
- **db:** update/delete per entity; each `count_objects_referencing_*` returns the right
  count; delete blocked when referenced; `delete_vocabulary` FK-restrict → typed in-use
  error; an audit row (`Updated`/`Deleted`, correct actor) per mutation.
- **api:** each `PATCH`/`DELETE` — `EditCatalogue` required (401/403 without), happy path
  (200/204), **409 + count** when referenced, **422** on an invalid value (empty
  `group_key`/label), **404** when missing. (Immutables are absent from the PATCH DTO, so
  there is no "immutable changed" path to test.)
- OpenAPI regenerated.

**Frontend** (Vitest + RTL + MSW, `onUnhandledRequest: "error"`):
- Mutation hooks invalidate the correct keys; a 409 parses into the typed error.
- Per screen: edit form populates and saves; delete confirms via `AlertDialog`; a 409
  keeps the dialog open showing "used by N"; field-def edit shows key/type/binding
  disabled.
- en/sv key-parity check (existing test).
- Storybook stories for the meaningfully-changed components run green under the
  addon-vitest project.

## Acceptance criteria

1. Update + delete endpoints for vocabulary (rename), term, authority, field-definition —
   all `EditCatalogue`, all audited.
2. Referenced term/authority/field-def delete → **409 + count**; vocabulary delete →
   **409** when it has terms or is bound.
3. Field-def `key`/`data_type`/binding immutable (absent from the PATCH DTO — cannot be
   changed); `labels`/`group`/`required` editable; `required` not retroactively enforced.
4. In-place edit + `AlertDialog` delete on all three screens; a blocked delete shows
   "used by N" without closing.
5. Storybook stories added for the meaningfully-changed components.
6. en/sv parity; no `any`/`eslint-disable`/`@ts-ignore`; codename ban; bundle ≤150 KB
   gz; cargo + web typecheck/lint/test/build green; OpenAPI regenerated.

## Out of scope / follow-ups

- A "find/replace a reference across objects" bulk-reassign tool (would let a curator
  clear references blocking a delete in one action) — file if the 409 friction is felt.
- Surfacing the referencing objects as clickable links in the 409 message (v1 shows a
  count + optional sample, not a live list).
- Audit-entry coalescing for multi-step edits (#13, separate).