Codex
076c9742c5
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.
37 lines
2.7 KiB
Markdown
37 lines
2.7 KiB
Markdown
# 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.
|