feat: consolidate database management work

Add catalog-owned logical relationships and runtime snapshots, extend the database-management UI and validation coverage, and document the updated operational workflow. Keep active sensitive-generation status in a tooltip and indicator, and update the layout E2E to follow the history action in its new database-scoped location.
2026-09-01 14:46:55 +02:00
parent f586152636
commit 076c9742c5
73 changed files with 6966 additions and 610 deletions
@@ -0,0 +1,36 @@
+# Use the Catalog as the logical relationship authority
+
+ThothII stores database-declared foreign keys and user-managed Logical Relationships in separate
+Catalog models, as required by ADR-0006, but exposes them through one effective relationship map.
+Physical relationships remain read-only and are refreshed from the database. Logical relationships
+are either Generated by deterministic column-name inference or Manual; inference does not call an
+AI model and does not inspect source values.
+
+A generated rebuild is additive. It preserves active and Manual relationships, never reactivates a
+logically deleted relationship, and may recreate a relationship only after permanent deletion. A
+logical deletion is therefore represented by retaining the relationship with an exclusion marker;
+a permanent deletion removes it. Inference accepts only unambiguous, type-compatible matches to a
+single-column primary key and skips all other candidates. It recognizes normalized table-qualified
+names such as `user_id -> users.id`, exact non-generic primary-key names with one owner, and the
+warehouse convention `*time_key -> dim_time.<single PK>`. A source column may participate in a
+composite primary key; bare generic names such as `id`, `key`, `code`, and `pk` are not evidence by
+themselves.
+
+An exclusion is durable while both Catalog Column endpoints exist. Explicit metadata cleanup of an
+endpoint table or column is a destructive boundary: it permanently removes every relationship and
+exclusion attached to that endpoint, invalidates the synchronized-catalog marker, and requires a
+full schema synchronization. The newly imported endpoints may then be inferred again. Preserving an
+exclusion across endpoint destruction would require a second denormalized name-based identity, which
+this design deliberately avoids.
+
+The installation-local Catalog is the sole writable authority for Logical Relationships. Git-pinned
+workspace annotations remain authoritative for descriptive metadata but their embedded foreign keys
+are legacy compatibility data. The backend materializes the active effective map as an immutable,
+deterministic runtime snapshot when a session starts or resumes. When that snapshot is present, the
+harness uses it as the exclusive relationship source and ignores relationships embedded in both the
+physical schema artifact and workspace annotations; a missing or invalid declared snapshot fails
+closed. Legacy runtimes without a snapshot retain the previous merge behavior.
+
+The snapshot is a projection, not another authored store. Its lifetime is tied to the runtime-config
+lease, physical relationships take precedence over duplicate Logical Relationships, composite-key
+column order is retained, and one Pi process observes one stable map for its complete lifetime.