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.
2.7 KiB
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.