Module table_catalog 

User-visible catalog of data tables in the workspace.

Tracks, for every user-facing table:

Field	Who populates
table_name	MCP (stub)
load_tool	MCP (stub)
load_params	MCP (stub)
loaded_at	MCP (stub)
last_refreshed_at	MCP (stub, bumped on every explicit load)
row_count	MCP (stub, refreshed opportunistically)
source_url	User / LLM via set_table_metadata
source_description	User / LLM
purpose	User / LLM
license	User / LLM
notes	User / LLM

The backing table is _table_catalog (single underscore, not _hyperdb_) so it shows up in describe and the resource catalog — the catalog is meant to be read by humans and LLMs, it isn’t internal bookkeeping. The _ prefix signals “workspace meta” without triggering crate::engine::is_internal_table’s hidden-table filter.

All operations no-op quietly when HyperMcpServer was constructed with --bare: the module never gets called in that mode, so the table is never created and the workspace file stays pristine.

Structs

CatalogEntry

One row in TABLE_CATALOG_TABLE.

MetadataFields

Partial update payload for set_metadata. None means “leave the existing value alone”; Some(String::new()) clears the field.

Constants

TABLE_CATALOG_TABLE

Backing table name. Visible in describe; users can SELECT * FROM _table_catalog directly.

Functions

delete_for

Delete the catalog row (if any) for table_name. Called when a table is dropped. Idempotent — no error if the row doesn’t exist.

ensure_exists

Idempotently create the backing table in the primary workspace. Safe to call on every engine init — if the table already exists this is a no-op. The schema here is the only one the code targets; all prose columns are nullable, so a plain NULL insert is always well-formed.

ensure_exists_in_database

Idempotently create _table_catalog inside an attached database (fully qualified as "{db_alias}"."public"."_table_catalog"), with the same schema as the primary’s catalog.

get

Fetch a single row by table_name, or Ok(None) if absent.

list

Fetch every catalog row in name-sorted order. Returns an empty Vec if the catalog table doesn’t exist (callers shouldn’t need to pre-check).

reconcile

Synchronize the catalog against the current set of user tables.

set_metadata

Partial UPDATE of prose fields for one table. Errors with ErrorCode::TableNotFound if there is no catalog row for table_name (callers can decide whether to first stub via upsert_stub or surface the error).

upsert_stub

Upsert a catalog row for table_name, carrying forward prose fields from any existing row and refreshing mechanical fields.