feat: implement metadata catalog database management

docs/adr/0001-postgres-metadata-catalog.md

@@ -2,10 +2,12 @@
 
 ThothII userà un Metadata Catalog PostgreSQL interno per conservare, per ogni workspace, la
 struttura fisica acquisita interrogando il relativo database e i metadati semantici generati con
-l'AI. Ogni workspace avrà un solo Workspace Database; identità e lista dei workspace resteranno
-autorevoli in `thoth-workspaces.yaml`, mentre il catalogo ne conserverà soltanto il riferimento
-stabile. `schema/annotations.yaml` verrà sostituito come input del core in uno step successivo;
-l'interfaccia e il lifecycle amministrativi resteranno separati dal workflow NL→SQL.
+l'AI. Ogni Workspace Database conserverà un `workspace_id` obbligatorio e univoco: questo realizza
+l'associazione uno-a-uno senza introdurre nel catalogo una tabella Workspace o una foreign key SQL.
+Identità e lista dei workspace resteranno autorevoli in `thoth-workspaces.yaml`; il servizio
+validerà il riferimento contro quel catalogo. `schema/annotations.yaml` verrà sostituito come input
+del core in uno step successivo; l'interfaccia e il lifecycle amministrativi resteranno separati dal
+workflow NL→SQL.
 
 ## Considered Options
 
@@ -18,4 +20,7 @@ l'interfaccia e il lifecycle amministrativi resteranno separati dal workflow NL
 
 PSD importerà le annotations esistenti; gli altri workspace genereranno i metadati da zero. Il
 cutover futuro dovrà sostituire consapevolmente i consumatori delle annotations e verificarne
-l'equivalenza semantica. Le sessioni di test esistenti non sono un vincolo di migrazione.
+l'equivalenza semantica. PostgreSQL può garantire che uno stesso `workspace_id` non sia assegnato a
+due database, ma l'esistenza del workspace e la gestione di rename o rimozioni restano responsabilità
+del confine applicativo con il catalogo YAML. Le sessioni di test esistenti non sono un vincolo di
+migrazione.

docs/adr/0002-workspace-database-secret-references.md

@@ -0,0 +1,19 @@
+# Riferimenti al secret store per i Workspace Database
+
+Il Metadata Catalog non conserverà credenziali o chiavi dei Workspace Database. Riuserà il secret
+store cifrato già posseduto da ThothII e conserverà soltanto riferimenti ai requisiti segreti del
+workspace, evitando un secondo vault e impedendo che API, esportazioni o log espongano i valori.
+
+## Considered Options
+
+- Copiare i campi testuali del modello ThothAI avrebbe semplificato il CRUD, ma avrebbe conservato
+  password e passphrase in chiaro.
+- Introdurre subito un secondo vault avrebbe separato il catalogo dal runtime workspace, ma avrebbe
+  duplicato cifratura, rotazione, autorizzazioni e procedure operative senza un'esigenza distinta.
+
+## Consequences
+
+Il catalogo e il runtime condividono l'identità dei requisiti segreti, mentre permessi e API del
+catalogo restano separati. Sostituzione e cancellazione di un Workspace Database dovranno definire
+esplicitamente il lifecycle dei relativi riferimenti senza includere i valori nelle transazioni del
+catalogo PostgreSQL.

docs/adr/0003-installation-local-database-bindings.md

@@ -0,0 +1,26 @@
+# Binding di database specifiche dell'installazione
+
+Il Metadata Catalog separa il Workspace Database logico dalla Database Binding che lo rende
+raggiungibile in una specifica installazione. Esiste un solo Workspace Database per `workspace_id`
+e una sola binding attiva nel catalogo di ciascuna installazione; per esempio PSD usa REST in locale
+e PostgreSQL diretto sul server senza diventare due database distinti.
+
+Nel modello finale il catalogo è autorevole per engine, nome fisico, schema, capability e binding,
+mentre `thoth-workspaces.yaml` conserva l'identità del workspace. Gli attuali campi DWH dei
+descriptor sono una sorgente di bootstrap da importare e confrontare durante un cutover esplicito,
+non una seconda fonte di verità permanente.
+
+## Considered Options
+
+- Conservare un record database per ogni trasporto avrebbe duplicato identità, struttura e
+  metadati dello stesso DWH fra locale e server.
+- Conservare permanentemente i dati DWH sia nello YAML sia nel catalogo avrebbe introdotto
+  conflitti non risolvibili deterministicamente.
+- Rendere globali le binding avrebbe mescolato endpoint e credenziali che appartengono a
+  installazioni con topologie e confini di sicurezza differenti.
+
+## Consequences
+
+La lista amministrativa unisce workspace YAML, database configurati e record orphaned. Il cutover
+deve importare e confrontare la configurazione esistente prima di rimuoverla dai descriptor; il
+runtime non deve osservare simultaneamente due autorità discordanti.

docs/adr/0004-fastify-kysely-metadata-catalog.md

@@ -0,0 +1,22 @@
+# Metadata Catalog nello stesso backend con Kysely
+
+Il Metadata Catalog vive nello stesso processo Fastify come modulo isolato, invece di introdurre un
+microservizio. Usa il driver `pg` già presente attraverso Kysely per query, transazioni e migrazioni
+tipizzate; route, repository, service, readiness e diagnostica restano separati dal workflow e
+l'indisponibilità del catalogo non rende indisponibili sessioni o SSE.
+
+## Considered Options
+
+- Un microservizio avrebbe conservato letteralmente il backend bridge senza database, ma avrebbe
+  aggiunto deployment, autenticazione e failure mode per un solo contesto amministrativo.
+- Usare soltanto `pg` avrebbe evitato una dipendenza, ma avrebbe richiesto infrastruttura locale per
+  transazioni, tipi delle righe, ordinamento e locking delle migrazioni.
+- Drizzle o Prisma avrebbero aggiunto schema DSL, generatori e toolchain non necessari a un servizio
+  che vuole mantenere SQL e constraint PostgreSQL espliciti.
+
+## Consequences
+
+Il backend possiede una connection pool del catalogo e la chiude con il lifecycle Fastify. Le
+migrazioni timestampate sono compilate insieme al backend ma vengono eseguite soltanto da
+`catalog:migrate`, con credenziali migrator separate dal ruolo DML usato a runtime. Il modulo resta
+dietro un'interfaccia repository per mantenere unit test e route test indipendenti da PostgreSQL.

docs/adr/0005-hard-delete-catalog-tables-during-synchronization.md

@@ -0,0 +1,27 @@
+# Hard-delete catalog tables during synchronization
+
+An explicit Table Synchronization makes the Catalog Table membership exactly match a successful
+observation of the Workspace Database: new tables are created, source metadata is refreshed, and
+absent tables plus their future column and relationship children are permanently deleted. Physical
+membership cannot be edited manually.
+
+The external scan runs without holding a catalog transaction. Its diff is applied atomically only
+while the Workspace Database version still matches the scanned binding. Failed scans change
+nothing, and a non-empty removal set must exactly match the names confirmed by the operator; a
+changed second scan therefore requires a new confirmation.
+
+## Considered Options
+
+- Soft deletion would preserve descriptions across accidental removals, but would add hidden state,
+  restore rules, and ambiguity about whether the catalog still represents the physical schema.
+- Rename detection based on similarity would preserve metadata in some cases, but could silently
+  attach curated semantics to the wrong physical table.
+- Append-only introspection, as in the legacy importer, would leave stale tables in the catalog and
+  make downstream schema linking unreliable.
+
+## Consequences
+
+A physical rename is delete plus create and loses curated metadata. The UI previews permanent
+deletions, and future Catalog Column and Relationship records must cascade with their table. The
+catalog remains an exact projection of the last accepted successful scan without tombstones or
+restore lifecycle.

docs/adr/0006-separate-physical-and-logical-relationships.md

@@ -0,0 +1,8 @@
+# Separate physical and logical relationships
+
+ThothII persists each database-declared foreign-key constraint as an immutable Catalog
+Relationship with ordered column pairs, so composite keys retain their identity and the database
+remains the authority for physical structure. Curated or AI-inferred Logical Relationships will
+use a separate future model and lifecycle rather than being mixed with physical constraints or
+denormalized into textual column fields; this keeps synchronization authoritative without
+preventing later semantic enrichment.

docs/adr/0007-durable-authoritative-schema-synchronization.md

@@ -0,0 +1,9 @@
+# Use durable runs for authoritative schema synchronization
+
+All table, column, relationship, and full-schema synchronizations run as durable background
+Catalog Sync Runs rather than separate synchronous and asynchronous implementations. Each scope
+is authoritative within its boundary, while Synchronize All observes one complete schema snapshot;
+destructive diffs require confirmation and source revalidation before an atomic, fail-closed
+catalog transaction. A persistent per-database lock, progress events, interruption handling, and
+binding-version freshness make long operations observable and prevent two processes or stale
+configuration from producing a partially trusted catalog.