Crate twg_table_catalog 

Table catalog: resolution, registration, credential vending, and descriptive metadata. Scaffold only.

Descriptive metadata is stamped at table CREATE and at schema EVOLUTION (a new column gets its comment too — evolution is a write-path event like creation). Applied as a describe-vs-execute split: descriptions and desired properties are authored once, each catalog backend applies what it supports.

Comment authority (two sources):

• Thalweg-owned columns (metadata under the configured prefix, default _twg_; dq_results; offset store): fixed built-in descriptions, authoritative and consistent across every table Thalweg creates.
• Payload columns: descriptions flow from the ODCS contract via contract-core. No contract → no payload comment.

Table-level: table comment, plus properties/tags where supported (owner, contract URI + version, source topic) — turning the catalog into a discovery surface (“which tables are fed from topic X / use contract Y v3”).

Backend capability (degrade gracefully, never error on a missing feature):

• Unity Catalog: COMMENT ON + tags + properties
• Iceberg: table properties + column docs in schema
• Glue: column Comment fields + table Parameters

Idempotent re-sync (governance-critical):

• Thalweg marks comments it stamps as managed (twg:managed=true) and records the synced source hash (twg:comment_hash).
• Re-sync writes ONLY when the contract’s description changed vs the last synced hash — no churn on no-op deploys (keeps catalog audit logs useful and avoids UC rate limits).
• A human-edited comment on a Thalweg-managed column is detected via the managed flag; whether to respect or restore is policy, not a blind stomp.

Reading Delta tables as Iceberg via the catalog’s Iceberg REST endpoint

Only one open table format is carried (ADR-0023), but a Delta table configured to generate Iceberg metadata is readable by an Iceberg client, and the catalog exposes exactly that through a read-only Iceberg REST Catalog endpoint with credential vending — temporary scoped credentials inheriting the requesting principal’s privileges.

This is the credential-vending seam already designed here, serving a case it was not written for: resolve the table, obtain vended credentials, read the Parquet through the Iceberg reader. No Delta implementation required anywhere.

Two properties to surface rather than bury, both from the table’s own metadata: whether Iceberg reads are currently enabled, and how far the generated Iceberg metadata trails the latest table version. The second is what tells a recovery pass whether what it is about to read is current.

What is implemented today

The trait seam (TableCatalog) and the pure, network-free reconcile planner (reconcile::plan) plus their value types (types). A concrete backend (Unity Catalog, per ADR-0062) executes the plan; it is not yet built.

Re-exports

pub use reconcile::PlanStep;

pub use reconcile::ReconcileOptions;

pub use reconcile::ReconcilePlan;

pub use reconcile::Refusal;

pub use reconcile::plan;

pub use types::Access;

pub use types::ColumnSpec;

pub use types::Comment;

pub use types::CommentAuthority;

pub use types::DesiredTable;

pub use types::SinkId;

pub use types::TableRef;

pub use types::TableState;

pub use types::VendedCredentials;

Modules

reconcile

The reconcile planner: a pure function from (desired, live) table state to a ReconcilePlan — a value describing exactly what a backend must do to bring the target in line with the incoming RecordBatch schema and contract.

types

Value types shared across the catalog: table identity, desired vs live table state, column specs, comments, and credential vending.

uc

Unity Catalog backend (feature unity-catalog, ADR-0062): OAuth2 auth and describe over a transport seam. Off by default. Unity Catalog backend for crate::TableCatalog (ADR-0062).

Structs

ReconcileOutcome

The outcome of a successful TableCatalog::reconcile.

Enums

CatalogError

Errors a catalog backend can return.

Traits

TableCatalog

Table provisioning, evolution, credential vending, and sink registration.