feat: complete catalog-driven preprocessing

2026-09-06 17:49:35 +02:00
parent 8707ae1d46
commit cffa60772e
141 changed files with 5898 additions and 3015 deletions
@@ -76,6 +76,10 @@ import { CatalogLogicalRelationshipService } from "./catalog/logical-relationshi
 import { catalogLogicalRelationshipRoutes } from "./routes/catalog-logical-relationships.js";
 import { EffectiveRelationshipSnapshotProvider } from "./catalog/effective-relationship-snapshot.js";
 import { loadRuntimeModelCatalog, type RuntimeModelCatalog } from "./models/runtime-model-catalog.js";
+import { createProductionWorkspacePreprocessingService } from "./workspace-maintenance.js";
+import type { WorkspacePreprocessingService } from "./workspaces/preprocessing-service.js";
+import { PreprocessingStateStore } from "./workspaces/preprocessing-state.js";
+import { workspacePreprocessingRoutes } from "./routes/workspace-preprocessing.js";

 export interface BuildAppDeps {
  thtRunner?: ThtRunner;
@@ -89,6 +93,7 @@ export interface BuildAppDeps {
  workspaceDiagnoser?: WorkspaceDiagnoser;
  workspaceDatabaseTester?: WorkspaceDatabaseTester;
  workspaceSecretStore?: WorkspaceSecretStore;
+  workspacePreprocessingService?: Pick<WorkspacePreprocessingService, "run" | "clear">;
  catalogRepository?: CatalogRepository;
  catalogService?: CatalogService;
  catalogPostgresAccess?: CatalogPostgresAccess;
@@ -156,6 +161,8 @@ export function buildApp(config: AppConfig, deps?: BuildAppDeps): FastifyInstanc
  app.register(cookie);
  app.register(rateLimit, { global: false });

+  const workspaceRegistry = deps?.workspaceRegistry ?? new WorkspaceRegistry(config.workspaceRegistry);
+  const catalogRepository = deps?.catalogRepository ?? createCatalogRepository(config.catalogDatabase);
  const tht = deps?.thtRunner ?? new ThtRunner({
    thtBin: config.thtBin,
    harnessDir: config.harnessDir,
@@ -166,6 +173,7 @@ export function buildApp(config: AppConfig, deps?: BuildAppDeps): FastifyInstanc
    secretsFile: config.secretsFile,
    secretFiles: config.secretFiles,
    workspaceSecretStore,
+    catalogRepository: deps?.catalogRepository ?? (config.catalogDatabase ? catalogRepository : undefined),
    semanticRuntime: {
      internalQdrantUrl: config.internalQdrantUrl,
      internalEmbeddingUrl: config.internalEmbeddingUrl,
@@ -174,9 +182,15 @@ export function buildApp(config: AppConfig, deps?: BuildAppDeps): FastifyInstanc
      internalEmbeddingDimensions: config.internalEmbeddingDimensions,
    },
  });
+  const workspacePreprocessingService = deps?.workspacePreprocessingService
+    ?? createProductionWorkspacePreprocessingService({
+      config,
+      catalogRepository,
+      registry: workspaceRegistry,
+      workspaceSecretStore,
+      runner: tht as ThtRunner,
+    });
  const hub = deps?.hub ?? new SseHub();
-  const workspaceRegistry = deps?.workspaceRegistry ?? new WorkspaceRegistry(config.workspaceRegistry);
-  const catalogRepository = deps?.catalogRepository ?? createCatalogRepository(config.catalogDatabase);
  const catalogOperationCoordinator = deps?.catalogOperationCoordinator ?? new CatalogOperationCoordinator();
  const runtimeModelCatalog = deps?.runtimeModelCatalog ?? loadRuntimeModelCatalog(config.modelCatalogFile);
  const mgr = deps?.mgr ?? new PiProcessManager(config, {
@@ -242,14 +256,6 @@ export function buildApp(config: AppConfig, deps?: BuildAppDeps): FastifyInstanc
  const catalogTableService = deps?.catalogTableService ?? new CatalogTableService(catalogRepository);
  const catalogLogicalRelationshipService = deps?.catalogLogicalRelationshipService
    ?? new CatalogLogicalRelationshipService(catalogRepository);
-  const effectiveRelationships = deps?.effectiveRelationshipSnapshotProvider
-    ?? (config.catalogDatabase === undefined
-      ? undefined
-      : new EffectiveRelationshipSnapshotProvider(
-        catalogRepository,
-        catalogLogicalRelationshipService,
-        catalogOperationCoordinator,
-      ));
  const catalogSchemaIntrospector = deps?.catalogSchemaIntrospector ?? new ConcreteCatalogSchemaIntrospector(
    catalogPostgresAccess,
    workspaceSecretStore,
@@ -457,7 +463,7 @@ export function buildApp(config: AppConfig, deps?: BuildAppDeps): FastifyInstanc
    workspaceRuntimeSupport,
    modelCatalog: runtimeModelCatalog,
    maintenanceBarrier,
-    effectiveRelationships,
+    catalogRepository: deps?.catalogRepository ?? (config.catalogDatabase ? catalogRepository : undefined),
  });
  app.post("/internal/maintenance/activate", async (req, reply) => {
    try {
@@ -496,6 +502,16 @@ export function buildApp(config: AppConfig, deps?: BuildAppDeps): FastifyInstanc
    secretStore: workspaceSecretStore,
    testDatabaseConnection: workspaceDatabaseTester,
  });
+  workspacePreprocessingRoutes(app, {
+    repository: catalogRepository,
+    registry: workspaceRegistry,
+    service: workspacePreprocessingService,
+    inputFingerprint: tht as ThtRunner,
+    readLatestJob: (workspaceId) => new PreprocessingStateStore({
+      dataRoot: config.dataRoot ?? "/data",
+      workspaceId,
+    }).readLatestJob(),
+  });
  catalogDatabaseRoutes(app, { repository: catalogRepository, service: catalogService, operations: catalogOperationCoordinator });
  catalogTableRoutes(app, {
    repository: catalogRepository,
@@ -59,10 +59,16 @@ const completionResponseSchema = z.object({
 class InvalidModelJsonError extends Error {}
 class InvalidModelSchemaError extends Error {}
 class MissingModelTargetsError extends Error {}
+
+interface DescriptionGenerationFailureTarget {
+  id: string;
+  reference: string;
+}
+
 class DescriptionGenerationBatchError extends Error {
  constructor(
    readonly failure: unknown,
-    readonly failedTargets: readonly { id: string; label: "Catalog Column" | "Catalog Table" }[],
+    readonly failedTargets: readonly DescriptionGenerationFailureTarget[],
  ) {
    super("description generation batch failed");
  }
@@ -138,7 +144,7 @@ type ParsedOutcome = z.infer<typeof outcomeSchema>;

 interface DescriptionGenerationPlan {
  columnTargets: SelectedColumnTarget[];
-  tableIds: string[];
+  tableTargets: Array<{ id: string; name: string }>;
 }

 interface DescriptionGenerationCounters {
@@ -164,10 +170,17 @@ function persistedCounters(counters: DescriptionGenerationCounters) {
  };
 }

-function failureTarget(target: SelectedTarget) {
+function targetReference(target: SelectedTarget): string {
  return target.kind === "column"
-    ? { id: target.column.id, label: "Catalog Column" as const }
-    : { id: target.table.id, label: "Catalog Table" as const };
+    ? `Column ${JSON.stringify(`${target.table.name}.${target.column.name}`)}`
+    : `Table ${JSON.stringify(target.table.name)}`;
+}
+
+function failureTarget(target: SelectedTarget): DescriptionGenerationFailureTarget {
+  return {
+    id: target.kind === "column" ? target.column.id : target.table.id,
+    reference: targetReference(target),
+  };
 }

 const NON_GENERATABLE_DESCRIPTION: Record<DescriptionGenerationRun["language"], string> = {
@@ -681,7 +694,7 @@ function safeFailure(error: unknown): string {
 function batchFailureEvent(error: DescriptionGenerationBatchError): string {
  const summary = safeFailure(error);
  return error.failedTargets.length > 0
-    ? `${summary} Affected ${error.failedTargets[0]!.label} target${error.failedTargets.length === 1 ? "" : "s"}: ${error.failedTargets.map((target) => target.id).join(", ")}.`
+    ? `${summary} Affected target${error.failedTargets.length === 1 ? "" : "s"}: ${error.failedTargets.map((target) => target.reference).join(", ")}.`
    : summary;
 }

@@ -794,7 +807,7 @@ export class DescriptionGenerationWorker {
          scope === "selected_columns" ? "column" : "table",
        );
      }
-      const total = plan.columnTargets.length + plan.tableIds.length;
+      const total = plan.columnTargets.length + plan.tableTargets.length;
      if (total === 0 && (scope === "all" || scope === "missing")) {
        throw new DescriptionGenerationNoEligibleTargetsError(scope);
      }
@@ -934,12 +947,18 @@ export class DescriptionGenerationWorker {
    };
    await this.processTargets(run, database, plan.columnTargets, model, counters, signal);
    throwIfCancelled(signal);
-    if (plan.tableIds.length > 0) {
-      const tableTargets = await this.resolveTableTargets(run.databaseId, plan.tableIds);
+    if (plan.tableTargets.length > 0) {
+      const tableTargets = await this.resolveTableTargets(
+        run.databaseId,
+        plan.tableTargets.map((target) => target.id),
+      );
      if (!tableTargets) {
        throw new DescriptionGenerationBatchError(
          new Error("selected tables changed during generation"),
-          plan.tableIds.map((id) => ({ id, label: "Catalog Table" })),
+          plan.tableTargets.map((target) => ({
+            id: target.id,
+            reference: `Table ${JSON.stringify(target.name)}`,
+          })),
        );
      }
      await this.processTargets(run, database, tableTargets, model, counters, signal);
@@ -1093,8 +1112,8 @@ export class DescriptionGenerationWorker {
          run.id,
          "info",
          outcome.outcome === "generated"
-            ? `Generated description for ${target.kind === "column" ? "Catalog Column" : "Catalog Table"} ${targetId}.`
-            : `Stored non-generatable result for ${target.kind === "column" ? "Catalog Column" : "Catalog Table"} ${targetId}.`,
+            ? `Generated description for ${targetReference(target)}.`
+            : `Stored non-generatable result for ${targetReference(target)}.`,
        );
      }
    }
@@ -1188,16 +1207,22 @@ export class DescriptionGenerationWorker {
      }
      return {
        columnTargets,
-        tableIds: tables
+        tableTargets: tables
          .filter((table) => scope === "all" || !table.generatedDescription?.trim())
-          .map((table) => table.id),
+          .map((table) => ({ id: table.id, name: table.name })),
      };
    }
    if (scope === "selected_tables") {
      const tableById = new Map(tables.map((table) => [table.id, table]));
      const selected = targetIds.map((tableId) => tableById.get(tableId));
      if (selected.some((table) => table === undefined)) return undefined;
-      return { columnTargets: [], tableIds: [...targetIds] };
+      return {
+        columnTargets: [],
+        tableTargets: (selected as CatalogTable[]).map((table) => ({
+          id: table.id,
+          name: table.name,
+        })),
+      };
    }

    const byId = new Map<string, SelectedColumnTarget>();
@@ -1209,7 +1234,7 @@ export class DescriptionGenerationWorker {
    const targets = targetIds.map((columnId) => byId.get(columnId));
    return targets.some((target) => target === undefined)
      ? undefined
-      : { columnTargets: targets as SelectedColumnTarget[], tableIds: [] };
+      : { columnTargets: targets as SelectedColumnTarget[], tableTargets: [] };
  }

  private async resolveTableTargets(
@@ -18,6 +18,8 @@ import {
  type CatalogLogicalRelationshipCandidate,
  type CatalogLogicalRelationshipContext,
  type CatalogPhysicalRelationship,
+  type CatalogPreprocessingStartResult,
+  type CatalogPreprocessingClearResult,
  type CatalogSchemaDiff,
  type CatalogSyncCounts,
  type CatalogSyncEvent,
@@ -72,6 +74,77 @@ export class MemoryCatalogRepository implements CatalogRepository {
    const value = [...this.records.values()].find((record) => record.workspaceId === workspaceId);
    return value ? clone(value) : undefined;
  }
+  async beginPreprocessing(
+    workspaceId: string,
+    inputFingerprint: string,
+  ): Promise<CatalogPreprocessingStartResult> {
+    const database = [...this.records.values()].find((record) => record.workspaceId === workspaceId);
+    if (!database) return { kind: "not_found" };
+    if (database.preprocessingStatus === "running") return { kind: "already_running" };
+    if (database.schemaSyncedVersion !== database.version) return { kind: "schema_stale" };
+    const catalogBusy = [...this.syncRuns.values()].some((run) =>
+      run.databaseId === database.id
+      && ["queued", "running", "awaiting_confirmation", "applying"].includes(run.state))
+      || [...this.descriptionGenerationRuns.values()].some((run) =>
+        run.databaseId === database.id && ["queued", "running"].includes(run.status))
+      || [...this.sensitivityAnalysisRuns.values()].some((run) =>
+        run.databaseId === database.id && ["queued", "running"].includes(run.status));
+    if (catalogBusy) return { kind: "catalog_busy" };
+    const now = new Date().toISOString();
+    const updated: WorkspaceDatabase = {
+      ...database,
+      preprocessingStatus: "running",
+      preprocessingInputFingerprint: inputFingerprint,
+      preprocessedMetadataRevision: undefined,
+      preprocessingStartedAt: now,
+      preprocessingFinishedAt: undefined,
+      preprocessingErrorCode: undefined,
+      updatedAt: now,
+    };
+    this.records.set(database.id, updated);
+    return { kind: "started", database: clone(updated) };
+  }
+  async finishPreprocessing(
+    workspaceId: string,
+    metadataContentRevision: number,
+    inputFingerprint: string,
+    outcome: { status: "succeeded" } | { status: "failed"; errorCode: string },
+  ): Promise<WorkspaceDatabase | undefined> {
+    const database = [...this.records.values()].find((record) => record.workspaceId === workspaceId);
+    if (!database
+      || database.preprocessingStatus !== "running"
+      || database.metadataContentRevision !== metadataContentRevision
+      || database.preprocessingInputFingerprint !== inputFingerprint) return undefined;
+    const updated: WorkspaceDatabase = {
+      ...database,
+      preprocessingStatus: outcome.status,
+      preprocessedMetadataRevision: outcome.status === "succeeded"
+        ? metadataContentRevision
+        : undefined,
+      preprocessingFinishedAt: new Date().toISOString(),
+      preprocessingErrorCode: outcome.status === "failed" ? outcome.errorCode : undefined,
+    };
+    this.records.set(database.id, updated);
+    return clone(updated);
+  }
+  async clearPreprocessing(workspaceId: string): Promise<CatalogPreprocessingClearResult> {
+    const database = [...this.records.values()].find((record) => record.workspaceId === workspaceId);
+    if (!database) return { kind: "not_found" };
+    if (database.preprocessingStatus === "running") return { kind: "already_running" };
+    const now = new Date().toISOString();
+    const updated: WorkspaceDatabase = {
+      ...database,
+      preprocessingStatus: "failed",
+      preprocessingInputFingerprint: undefined,
+      preprocessedMetadataRevision: undefined,
+      preprocessingStartedAt: undefined,
+      preprocessingFinishedAt: now,
+      preprocessingErrorCode: "derived_data_cleared",
+      updatedAt: now,
+    };
+    this.records.set(database.id, updated);
+    return { kind: "cleared", database: clone(updated) };
+  }
  async getCatalogMetrics(databaseId?: string): Promise<CatalogMetrics | undefined> {
    if (databaseId !== undefined && !this.records.has(databaseId)) return undefined;

@@ -114,6 +187,8 @@ export class MemoryCatalogRepository implements CatalogRepository {
      createdAt: now,
      updatedAt: now,
      connectionStatus: "untested",
+      metadataContentRevision: 0,
+      preprocessingStatus: "failed",
    };
    this.records.set(record.id, record);
    return clone(record);
@@ -286,12 +361,24 @@ export class MemoryCatalogRepository implements CatalogRepository {
      return undefined;
    }
    const now = new Date().toISOString();
-    if (target === "database_columns") {
-      const targets = [...this.columns.values()].filter((column) => (
+    if (target === "database" || target === "database_columns") {
+      const tableTargets = target === "database"
+        ? [...this.tables.values()].filter((table) => table.databaseId === databaseId)
+        : [];
+      const columnTargets = [...this.columns.values()].filter((column) => (
        this.tables.get(column.tableId)?.databaseId === databaseId
      ));
-      const copied = targets.filter((column) => Boolean(column.generatedDescription?.trim()));
-      for (const column of copied) {
+      const copiedTables = tableTargets.filter((table) => Boolean(table.generatedDescription?.trim()));
+      const copiedColumns = columnTargets.filter((column) => Boolean(column.generatedDescription?.trim()));
+      for (const table of copiedTables) {
+        this.tables.set(table.id, {
+          ...table,
+          description: table.generatedDescription,
+          version: table.version + 1,
+          updatedAt: now,
+        });
+      }
+      for (const column of copiedColumns) {
        this.columns.set(column.id, {
          ...column,
          description: column.generatedDescription,
@@ -299,7 +386,8 @@ export class MemoryCatalogRepository implements CatalogRepository {
          updatedAt: now,
        });
      }
-      return { copied: copied.length, skipped: targets.length - copied.length };
+      const copied = copiedTables.length + copiedColumns.length;
+      return { copied, skipped: tableTargets.length + columnTargets.length - copied };
    }
    if (selectedTargetIds.length === 0) return undefined;
    if (target === "tables") {
@@ -0,0 +1,144 @@
+import type {
+  CatalogColumn,
+  CatalogLogicalRelationship,
+  CatalogPhysicalRelationship,
+  CatalogRepository,
+  CatalogTable,
+} from "./types.js";
+
+export type CatalogDescriptionSource = "curated" | "generated" | "source_comment";
+
+export interface CatalogMetadataSnapshotColumn {
+  id: string;
+  name: string;
+  ordinalPosition: number;
+  dataType: string;
+  isNullable: boolean;
+  defaultExpression: string | null;
+  primaryKeyPosition: number | null;
+  sensitive: boolean;
+  description: string | null;
+  descriptionSource: CatalogDescriptionSource | null;
+}
+
+export interface CatalogMetadataSnapshotTable {
+  id: string;
+  name: string;
+  description: string | null;
+  descriptionSource: CatalogDescriptionSource | null;
+  columns: CatalogMetadataSnapshotColumn[];
+}
+
+export interface CatalogMetadataSnapshotRelationship {
+  id: string;
+  origin: "physical" | "generated" | "manual";
+  sourceTable: string;
+  sourceColumns: string[];
+  targetTable: string;
+  targetColumns: string[];
+}
+
+export interface CatalogMetadataSnapshot {
+  schemaVersion: 1;
+  workspaceId: string;
+  databaseId: string;
+  databaseName: string;
+  schemaName: string;
+  metadataContentRevision: number;
+  tables: CatalogMetadataSnapshotTable[];
+  relationships: CatalogMetadataSnapshotRelationship[];
+}
+
+function effectiveDescription(value: {
+  description: string | null;
+  generatedDescription: string | null;
+  sourceComment: string | null;
+}): { description: string | null; descriptionSource: CatalogDescriptionSource | null } {
+  if (value.description?.trim()) {
+    return { description: value.description.trim(), descriptionSource: "curated" };
+  }
+  if (value.generatedDescription?.trim()) {
+    return { description: value.generatedDescription.trim(), descriptionSource: "generated" };
+  }
+  if (value.sourceComment?.trim()) {
+    return { description: value.sourceComment.trim(), descriptionSource: "source_comment" };
+  }
+  return { description: null, descriptionSource: null };
+}
+
+function snapshotColumn(column: CatalogColumn): CatalogMetadataSnapshotColumn {
+  return {
+    id: column.id,
+    name: column.name,
+    ordinalPosition: column.ordinalPosition,
+    dataType: column.dataType,
+    isNullable: column.isNullable,
+    defaultExpression: column.defaultExpression,
+    primaryKeyPosition: column.primaryKeyPosition,
+    sensitive: column.sensitive,
+    ...effectiveDescription(column),
+  };
+}
+
+function snapshotRelationship(
+  relationship: CatalogPhysicalRelationship | CatalogLogicalRelationship,
+): CatalogMetadataSnapshotRelationship {
+  const columns = [...relationship.columns].sort((left, right) => left.position - right.position);
+  return {
+    id: relationship.id,
+    origin: relationship.origin,
+    sourceTable: relationship.sourceTableName,
+    sourceColumns: columns.map((column) => column.sourceColumnName),
+    targetTable: relationship.targetTableName,
+    targetColumns: columns.map((column) => column.targetColumnName),
+  };
+}
+
+export async function buildCatalogMetadataSnapshot(
+  repository: CatalogRepository,
+  workspaceId: string,
+  expectedMetadataContentRevision: number,
+): Promise<CatalogMetadataSnapshot> {
+  const database = await repository.getByWorkspace(workspaceId);
+  if (!database || database.preprocessingStatus !== "running") {
+    throw new Error("catalog preprocessing lease is not active");
+  }
+  if (database.metadataContentRevision !== expectedMetadataContentRevision) {
+    throw new Error("catalog metadata revision changed");
+  }
+
+  const catalogTables = await repository.listTables(database.id);
+  const tables: CatalogMetadataSnapshotTable[] = [];
+  for (const table of [...catalogTables].sort((left, right) => left.name.localeCompare(right.name))) {
+    const columns = await repository.listColumns(database.id, table.id);
+    tables.push({
+      id: table.id,
+      name: table.name,
+      ...effectiveDescription(table),
+      columns: columns
+        .sort((left, right) => left.ordinalPosition - right.ordinalPosition || left.name.localeCompare(right.name))
+        .map(snapshotColumn),
+    });
+  }
+
+  const physical = await repository.listRelationships(database.id);
+  const logical = (await repository.listLogicalRelationships(database.id))
+    .filter((relationship) => relationship.status === "active");
+  const relationships = [...physical, ...logical]
+    .map(snapshotRelationship)
+    .sort((left, right) =>
+      left.sourceTable.localeCompare(right.sourceTable)
+      || left.targetTable.localeCompare(right.targetTable)
+      || left.id.localeCompare(right.id));
+
+  return {
+    schemaVersion: 1,
+    workspaceId,
+    databaseId: database.id,
+    databaseName: database.databaseName,
+    schemaName: database.schema,
+    metadataContentRevision: expectedMetadataContentRevision,
+    tables,
+    relationships,
+  };
+}
@@ -15,6 +15,7 @@ import * as aiTokenUsageMigration from "./migrations/009_ai_token_usage.js";
 import * as canonicalModelIdsMigration from "./migrations/010_canonical_model_ids.js";
 import * as localSensitivityAnalysisMigration from "./migrations/011_local_sensitivity_analysis.js";
 import * as sensitivityReasonMigration from "./migrations/012_sensitivity_reason.js";
+import * as catalogPreprocessingStateMigration from "./migrations/013_catalog_preprocessing_state.js";

 const connectionString = process.env.THT_CATALOG_MIGRATOR_DATABASE_URL;
 const host = process.env.THT_CATALOG_DB_HOST;
@@ -52,6 +53,7 @@ const provider: MigrationProvider = {
      "010_canonical_model_ids": canonicalModelIdsMigration,
      "011_local_sensitivity_analysis": localSensitivityAnalysisMigration,
      "012_sensitivity_reason": sensitivityReasonMigration,
+      "013_catalog_preprocessing_state": catalogPreprocessingStateMigration,
    };
  },
 };
@@ -0,0 +1,212 @@
+import { type Kysely, sql } from "kysely";
+import type { CatalogDatabase } from "../repository.js";
+
+export async function up(db: Kysely<CatalogDatabase>): Promise<void> {
+  await db.schema.alterTable("workspace_databases")
+    .addColumn("metadata_content_revision", "bigint", (column) => column.notNull().defaultTo(0))
+    .addColumn("preprocessing_status", "text", (column) => column.notNull().defaultTo("failed"))
+    .addColumn("preprocessing_input_fingerprint", "text")
+    .addColumn("preprocessed_metadata_revision", "bigint")
+    .addColumn("preprocessing_started_at", "timestamptz")
+    .addColumn("preprocessing_finished_at", "timestamptz")
+    .addColumn("preprocessing_error_code", "text")
+    .execute();
+  await sql`
+    alter table workspace_databases
+    add constraint workspace_databases_preprocessing_status_check
+    check (preprocessing_status in ('running', 'succeeded', 'failed'))
+  `.execute(db);
+
+  await sql`
+    create function catalog_metadata_write_guard()
+    returns trigger
+    language plpgsql
+    as $$
+    declare
+      resolved_database_id uuid;
+      current_status text;
+      relation_id uuid;
+      table_id uuid;
+    begin
+      if tg_table_name = 'catalog_tables' then
+        resolved_database_id := coalesce(new.database_id, old.database_id);
+      elsif tg_table_name = 'catalog_columns' then
+        table_id := coalesce(new.table_id, old.table_id);
+        select database_id into resolved_database_id from catalog_tables where id = table_id;
+      elsif tg_table_name = 'catalog_relationships' then
+        resolved_database_id := coalesce(new.database_id, old.database_id);
+      elsif tg_table_name = 'catalog_relationship_columns' then
+        relation_id := coalesce(new.relationship_id, old.relationship_id);
+        select database_id into resolved_database_id from catalog_relationships where id = relation_id;
+      elsif tg_table_name = 'catalog_logical_relationships' then
+        resolved_database_id := coalesce(new.database_id, old.database_id);
+      elsif tg_table_name = 'database_bindings' then
+        if tg_op = 'UPDATE' and not (
+          new.transport is distinct from old.transport
+          or new.host is distinct from old.host
+          or new.port is distinct from old.port
+          or new.username is distinct from old.username
+          or new.base_url is distinct from old.base_url
+          or new.rest_path is distinct from old.rest_path
+          or new.rest_auth is distinct from old.rest_auth
+          or new.tls_servername is distinct from old.tls_servername
+          or new.ssh_host is distinct from old.ssh_host
+          or new.ssh_port is distinct from old.ssh_port
+          or new.ssh_username is distinct from old.ssh_username
+          or new.ssh_target_host is distinct from old.ssh_target_host
+          or new.ssh_target_port is distinct from old.ssh_target_port
+        ) then
+          return new;
+        end if;
+        resolved_database_id := coalesce(new.database_id, old.database_id);
+      end if;
+      if resolved_database_id is null then
+        if tg_op = 'DELETE' then return old; else return new; end if;
+      end if;
+
+      select preprocessing_status into current_status
+      from workspace_databases
+      where id = resolved_database_id
+      for update;
+
+      if current_status = 'running' then
+        raise exception 'catalog preprocessing is running'
+          using errcode = '55000';
+      end if;
+
+      update workspace_databases
+      set metadata_content_revision = metadata_content_revision + 1,
+          preprocessing_status = 'failed',
+          preprocessing_finished_at = now(),
+          preprocessing_error_code = 'catalog_changed',
+          updated_at = now()
+      where id = resolved_database_id;
+      if tg_op = 'DELETE' then return old; else return new; end if;
+    end;
+    $$
+  `.execute(db);
+
+  for (const table of [
+    "catalog_tables",
+    "catalog_columns",
+    "catalog_relationships",
+    "catalog_relationship_columns",
+    "catalog_logical_relationships",
+    "database_bindings",
+  ]) {
+    await sql.raw(`
+      create trigger ${table}_metadata_write_guard
+      before insert or update or delete on ${table}
+      for each row execute function catalog_metadata_write_guard()
+    `).execute(db);
+  }
+
+  await sql`
+    create function catalog_database_configuration_guard()
+    returns trigger
+    language plpgsql
+    as $$
+    begin
+      if new.workspace_id is distinct from old.workspace_id
+        or new.engine is distinct from old.engine
+        or new.database_name is distinct from old.database_name
+        or new.schema_name is distinct from old.schema_name then
+        if old.preprocessing_status = 'running' then
+          raise exception 'catalog preprocessing is running'
+            using errcode = '55000';
+        end if;
+        new.metadata_content_revision := old.metadata_content_revision + 1;
+        new.preprocessing_status := 'failed';
+        new.preprocessing_finished_at := now();
+        new.preprocessing_error_code := 'catalog_changed';
+      end if;
+      return new;
+    end;
+    $$
+  `.execute(db);
+  await sql`
+    create trigger workspace_databases_configuration_guard
+    before update of workspace_id, engine, database_name, schema_name on workspace_databases
+    for each row execute function catalog_database_configuration_guard()
+  `.execute(db);
+
+  await sql`
+    create function catalog_operation_start_guard()
+    returns trigger
+    language plpgsql
+    as $$
+    declare
+      current_status text;
+      starting boolean;
+    begin
+      if tg_table_name = 'catalog_sync_runs' then
+        starting := new.state in ('queued', 'running', 'awaiting_confirmation', 'applying');
+      else
+        starting := new.status in ('queued', 'running');
+      end if;
+      if not starting then
+        return new;
+      end if;
+
+      select preprocessing_status into current_status
+      from workspace_databases
+      where id = new.database_id
+      for update;
+      if current_status = 'running' then
+        raise exception 'catalog preprocessing is running'
+          using errcode = '55000';
+      end if;
+      return new;
+    end;
+    $$
+  `.execute(db);
+
+  for (const table of [
+    "catalog_sync_runs",
+    "description_generation_runs",
+    "sensitive_data_suggestion_runs",
+  ]) {
+    await sql.raw(`
+      create trigger ${table}_operation_start_guard
+      before insert or update on ${table}
+      for each row execute function catalog_operation_start_guard()
+    `).execute(db);
+  }
+}
+
+export async function down(db: Kysely<CatalogDatabase>): Promise<void> {
+  for (const table of [
+    "catalog_sync_runs",
+    "description_generation_runs",
+    "sensitive_data_suggestion_runs",
+  ]) {
+    await sql.raw(`drop trigger if exists ${table}_operation_start_guard on ${table}`).execute(db);
+  }
+  await sql`drop function if exists catalog_operation_start_guard()`.execute(db);
+  await sql`drop trigger if exists workspace_databases_configuration_guard on workspace_databases`.execute(db);
+  await sql`drop function if exists catalog_database_configuration_guard()`.execute(db);
+  for (const table of [
+    "catalog_tables",
+    "catalog_columns",
+    "catalog_relationships",
+    "catalog_relationship_columns",
+    "catalog_logical_relationships",
+    "database_bindings",
+  ]) {
+    await sql.raw(`drop trigger if exists ${table}_metadata_write_guard on ${table}`).execute(db);
+  }
+  await sql`drop function if exists catalog_metadata_write_guard()`.execute(db);
+  await db.schema.alterTable("workspace_databases")
+    .dropConstraint("workspace_databases_preprocessing_status_check").execute();
+  for (const column of [
+    "preprocessing_error_code",
+    "preprocessing_finished_at",
+    "preprocessing_started_at",
+    "preprocessed_metadata_revision",
+    "preprocessing_input_fingerprint",
+    "preprocessing_status",
+    "metadata_content_revision",
+  ]) {
+    await sql.raw(`alter table workspace_databases drop column ${column}`).execute(db);
+  }
+}
@@ -27,6 +27,8 @@ import {
  type CatalogLogicalRelationshipCandidate,
  type CatalogLogicalRelationshipContext,
  type CatalogPhysicalRelationship,
+  type CatalogPreprocessingStartResult,
+  type CatalogPreprocessingClearResult,
  type CatalogSchemaDiff,
  type CatalogSyncCounts,
  type CatalogSyncEvent,
@@ -54,6 +56,11 @@ import {
 } from "./types.js";

 type Timestamp = ColumnType<Date, Date | string | undefined, Date | string>;
+type NullableTimestamp = ColumnType<
+  Date | null,
+  Date | string | null | undefined,
+  Date | string | null
+>;

 interface WorkspaceDatabaseTable {
  id: string;
@@ -66,6 +73,13 @@ interface WorkspaceDatabaseTable {
  updatedAt: Timestamp;
  schemaSyncedVersion: number | null;
  schemaSyncedAt: Timestamp | null;
+  metadataContentRevision: Generated<number>;
+  preprocessingStatus: Generated<WorkspaceDatabase["preprocessingStatus"]>;
+  preprocessingInputFingerprint: Generated<string | null>;
+  preprocessedMetadataRevision: Generated<number | null>;
+  preprocessingStartedAt: NullableTimestamp;
+  preprocessingFinishedAt: NullableTimestamp;
+  preprocessingErrorCode: Generated<string | null>;
 }

 interface DatabaseBindingTable {
@@ -325,6 +339,19 @@ function serialize(row: JoinedRow): WorkspaceDatabase {
    lastErrorMessage: present(row.lastErrorMessage),
    schemaSyncedVersion: present(row.schemaSyncedVersion),
    schemaSyncedAt: row.schemaSyncedAt == null ? undefined : new Date(row.schemaSyncedAt).toISOString(),
+    metadataContentRevision: Number(row.metadataContentRevision),
+    preprocessingStatus: row.preprocessingStatus,
+    preprocessingInputFingerprint: present(row.preprocessingInputFingerprint),
+    preprocessedMetadataRevision: row.preprocessedMetadataRevision == null
+      ? undefined
+      : Number(row.preprocessedMetadataRevision),
+    preprocessingStartedAt: row.preprocessingStartedAt == null
+      ? undefined
+      : new Date(row.preprocessingStartedAt).toISOString(),
+    preprocessingFinishedAt: row.preprocessingFinishedAt == null
+      ? undefined
+      : new Date(row.preprocessingFinishedAt).toISOString(),
+    preprocessingErrorCode: present(row.preprocessingErrorCode),
  };
 }

@@ -477,6 +504,98 @@ export class KyselyCatalogRepository implements CatalogRepository {
    return id ? await this.get(id.id) : undefined;
  }

+  async beginPreprocessing(
+    workspaceId: string,
+    inputFingerprint: string,
+  ): Promise<CatalogPreprocessingStartResult> {
+    return await this.db.transaction().execute(async (trx) => {
+      const database = await trx.selectFrom("workspaceDatabases")
+        .selectAll()
+        .where("workspaceId", "=", workspaceId)
+        .forUpdate()
+        .executeTakeFirst();
+      if (!database) return { kind: "not_found" };
+      if (database.preprocessingStatus === "running") return { kind: "already_running" };
+      if (database.schemaSyncedVersion !== database.version) return { kind: "schema_stale" };
+
+      const activeSync = await trx.selectFrom("catalogSyncRuns")
+        .select("id")
+        .where("databaseId", "=", database.id)
+        .where("state", "in", ["queued", "running", "awaiting_confirmation", "applying"])
+        .executeTakeFirst();
+      const activeDescriptions = await trx.selectFrom("descriptionGenerationRuns")
+        .select("id")
+        .where("databaseId", "=", database.id)
+        .where("status", "in", ["queued", "running"])
+        .executeTakeFirst();
+      const activeSensitivity = await trx.selectFrom("sensitiveDataSuggestionRuns")
+        .select("id")
+        .where("databaseId", "=", database.id)
+        .where("status", "=", "running")
+        .executeTakeFirst();
+      if (activeSync || activeDescriptions || activeSensitivity) return { kind: "catalog_busy" };
+
+      await trx.updateTable("workspaceDatabases")
+        .set({
+          preprocessingStatus: "running",
+          preprocessingInputFingerprint: inputFingerprint,
+          preprocessedMetadataRevision: null,
+          preprocessingStartedAt: sql`now()`,
+          preprocessingFinishedAt: null,
+          preprocessingErrorCode: null,
+          updatedAt: sql`now()`,
+        })
+        .where("id", "=", database.id)
+        .execute();
+      return { kind: "started", database: (await selectOne(trx, database.id))! };
+    });
+  }
+
+  async finishPreprocessing(
+    workspaceId: string,
+    metadataContentRevision: number,
+    inputFingerprint: string,
+    outcome: { status: "succeeded" } | { status: "failed"; errorCode: string },
+  ): Promise<WorkspaceDatabase | undefined> {
+    const result = await this.db.updateTable("workspaceDatabases")
+      .set({
+        preprocessingStatus: outcome.status,
+        preprocessedMetadataRevision: outcome.status === "succeeded" ? metadataContentRevision : null,
+        preprocessingFinishedAt: sql`now()`,
+        preprocessingErrorCode: outcome.status === "failed" ? outcome.errorCode : null,
+        updatedAt: sql`now()`,
+      })
+      .where("workspaceId", "=", workspaceId)
+      .where("preprocessingStatus", "=", "running")
+      .where("metadataContentRevision", "=", metadataContentRevision)
+      .where("preprocessingInputFingerprint", "=", inputFingerprint)
+      .returning("id")
+      .executeTakeFirst();
+    return result ? await this.get(result.id) : undefined;
+  }
+
+  async clearPreprocessing(workspaceId: string): Promise<CatalogPreprocessingClearResult> {
+    return await this.db.transaction().execute(async (trx) => {
+      const database = await trx.selectFrom("workspaceDatabases")
+        .select(["id", "preprocessingStatus"])
+        .where("workspaceId", "=", workspaceId)
+        .forUpdate()
+        .executeTakeFirst();
+      if (!database) return { kind: "not_found" };
+      if (database.preprocessingStatus === "running") return { kind: "already_running" };
+      await trx.updateTable("workspaceDatabases").set({
+        preprocessingStatus: "failed",
+        preprocessingInputFingerprint: null,
+        preprocessedMetadataRevision: null,
+        preprocessingStartedAt: null,
+        preprocessingFinishedAt: sql`now()`,
+        preprocessingErrorCode: "derived_data_cleared",
+        updatedAt: sql`now()`,
+      }).where("id", "=", database.id).execute();
+      return { kind: "cleared", database: (await selectOne(trx, database.id))! };
+    });
+  }
+
  async getCatalogMetrics(databaseId?: string): Promise<CatalogMetrics | undefined> {
    const result = await sql<CatalogMetricsRow>`
      WITH requested_database AS (
@@ -763,7 +882,9 @@ export class KyselyCatalogRepository implements CatalogRepository {
    targetIds: readonly string[],
  ): Promise<CatalogDescriptionConsolidationCounts | undefined> {
    const selectedTargetIds = [...new Set(targetIds)];
-    if (target !== "database_columns" && selectedTargetIds.length === 0) return undefined;
+    if (target !== "database" && target !== "database_columns" && selectedTargetIds.length === 0) {
+      return undefined;
+    }
    return await this.db.transaction().execute(async (trx) => {
      const database = await trx.selectFrom("workspaceDatabases").select("id")
        .where("id", "=", databaseId).forUpdate().executeTakeFirst();
@@ -793,8 +914,23 @@ export class KyselyCatalogRepository implements CatalogRepository {
        };
      }

-      const tableRows = await trx.selectFrom("catalogTables").select("id")
-        .where("databaseId", "=", databaseId).execute();
+      const tableRows = await trx.selectFrom("catalogTables").select(["id", "generatedDescription"])
+        .where("databaseId", "=", databaseId)
+        .orderBy("id")
+        .forUpdate()
+        .execute();
+      const copiedTableIds = target === "database"
+        ? tableRows
+          .filter((row) => Boolean(row.generatedDescription?.trim()))
+          .map((row) => row.id)
+        : [];
+      if (copiedTableIds.length > 0) {
+        await trx.updateTable("catalogTables").set({
+          description: sql`generated_description`,
+          version: sql`version + 1`,
+          updatedAt: sql`now()`,
+        }).where("id", "in", copiedTableIds).execute();
+      }
      const rows = tableRows.length === 0 ? [] : await trx.selectFrom("catalogColumns")
        .select(["id", "generatedDescription"])
        .where("tableId", "in", tableRows.map((table) => table.id))
@@ -812,7 +948,7 @@ export class KyselyCatalogRepository implements CatalogRepository {
          version: sql`version + 1`,
          updatedAt: sql`now()`,
        });
-        update = target === "database_columns"
+        update = target === "database" || target === "database_columns"
          ? update
            .where("tableId", "in", tableRows.map((table) => table.id))
            .where(sql<boolean>`nullif(btrim(generated_description), '') is not null`)
@@ -820,8 +956,9 @@ export class KyselyCatalogRepository implements CatalogRepository {
        await update.execute();
      }
      return {
-        copied: copiedIds.length,
-        skipped: rows.length - copiedIds.length,
+        copied: copiedTableIds.length + copiedIds.length,
+        skipped: (target === "database" ? tableRows.length : 0) - copiedTableIds.length
+          + rows.length - copiedIds.length,
      };
    });
  }
@@ -1835,6 +1972,9 @@ export class UnavailableCatalogRepository implements CatalogRepository {
  async list(): Promise<WorkspaceDatabase[]> { return this.fail(); }
  async get(): Promise<WorkspaceDatabase | undefined> { return this.fail(); }
  async getByWorkspace(): Promise<WorkspaceDatabase | undefined> { return this.fail(); }
+  async beginPreprocessing(): Promise<CatalogPreprocessingStartResult> { return this.fail(); }
+  async finishPreprocessing(): Promise<WorkspaceDatabase | undefined> { return this.fail(); }
+  async clearPreprocessing(): Promise<CatalogPreprocessingClearResult> { return this.fail(); }
  async getCatalogMetrics(): Promise<CatalogMetrics | undefined> { return this.fail(); }
  async create(): Promise<WorkspaceDatabase> { return this.fail(); }
  async update(): Promise<WorkspaceDatabase | undefined> { return this.fail(); }
@@ -0,0 +1,140 @@
+import { dirname } from "node:path";
+
+import { resolveRuntimeBindings, type RuntimeBindings } from "../workspaces/bindings.js";
+import { buildInstallationContract, type InstallationSuffix } from "../workspaces/contracts.js";
+import {
+  discoverWorkspaceSecretRequirements,
+} from "../workspaces/secret-requirements.js";
+import type {
+  WorkspaceSecretMaterialization,
+  WorkspaceSecretStore,
+} from "../workspaces/secret-store.js";
+import {
+  validateWorkspaceDescriptor,
+  type WorkspaceDescriptor,
+} from "../workspaces/schema.js";
+import { CATALOG_SECRET_IDS } from "./secrets.js";
+import type { WorkspaceDatabase } from "./types.js";
+
+export interface CatalogRuntimeBindingLease {
+  workspace: WorkspaceDescriptor;
+  bindings: RuntimeBindings;
+  release(): void;
+}
+
+const CATALOG_SECRET_BY_SUFFIX: Readonly<Partial<Record<InstallationSuffix, string>>> = {
+  PASSWORD_FILE: CATALOG_SECRET_IDS.password,
+  API_KEY_FILE: CATALOG_SECRET_IDS.apiKey,
+  TLS_CA_FILE: CATALOG_SECRET_IDS.tlsCa,
+  SSH_PRIVATE_KEY_FILE: CATALOG_SECRET_IDS.sshPrivateKey,
+  SSH_KNOWN_HOSTS_FILE: CATALOG_SECRET_IDS.sshKnownHosts,
+};
+
+function runtimeWorkspace(
+  workspace: WorkspaceDescriptor,
+  database: WorkspaceDatabase,
+): WorkspaceDescriptor {
+  if (workspace.workspace.id !== database.workspaceId) {
+    throw new Error("Catalog database binding does not belong to the workspace");
+  }
+  const { dwh: _legacyDwh, diagnostics: _legacyDiagnostics, ...descriptor } = workspace;
+  const binding = database.binding;
+  return validateWorkspaceDescriptor({
+    ...descriptor,
+    dwh: {
+      engine: "postgres",
+      database: database.databaseName,
+      schema: database.schema,
+      ...(binding.port === undefined ? {} : { port: binding.port }),
+      supported_transports: [binding.transport],
+    },
+    ...(binding.transport === "rest_api" ? {
+      diagnostics: {
+        dwh_rest: {
+          method: "GET",
+          path: binding.restPath ?? "/health",
+          auth: binding.restAuth ?? "bearer",
+          response: { database: "database", schema: "schema" },
+        },
+      },
+    } : {}),
+  });
+}
+
+function setIfDefined(
+  environment: NodeJS.ProcessEnv,
+  name: string | undefined,
+  value: string | number | undefined,
+): void {
+  if (name !== undefined && value !== undefined && value !== "") environment[name] = String(value);
+}
+
+/**
+ * Project one PostgreSQL Catalog row into the legacy-shaped configuration consumed by the
+ * Python runtime. The authored workspace remains database-free; this object exists only for
+ * the lifetime of a backend-owned runtime lease.
+ */
+export function resolveCatalogRuntimeBinding(options: {
+  workspace: WorkspaceDescriptor;
+  database: WorkspaceDatabase;
+  environment: NodeJS.ProcessEnv;
+  secretRoots: readonly string[];
+  secretStore: WorkspaceSecretStore;
+}): CatalogRuntimeBindingLease {
+  const workspace = runtimeWorkspace(options.workspace, options.database);
+  const evidenceRequirements = discoverWorkspaceSecretRequirements(
+    options.workspace,
+    options.environment,
+  ).filter(({ connector }) => connector === "evidence");
+  const catalogSecretIds = Object.values(CATALOG_SECRET_IDS);
+  let materialization: WorkspaceSecretMaterialization | undefined;
+  try {
+    materialization = options.secretStore.materialize(
+      options.database.workspaceId,
+      [...catalogSecretIds, ...evidenceRequirements.map(({ id }) => id)],
+    );
+    const environment: NodeJS.ProcessEnv = { ...options.environment };
+    const roots = new Set(options.secretRoots);
+    for (const path of materialization.files.values()) roots.add(dirname(path));
+
+    const variables = buildInstallationContract(workspace).variables;
+    const variable = (role: "DWH" | "EVIDENCE", suffix: InstallationSuffix) => (
+      variables.find((candidate) => candidate.role === role && candidate.suffix === suffix)?.name
+    );
+    const binding = options.database.binding;
+    setIfDefined(environment, variable("DWH", "TRANSPORT"), binding.transport);
+    setIfDefined(environment, variable("DWH", "HOST"), binding.host);
+    setIfDefined(environment, variable("DWH", "PORT"), binding.port);
+    setIfDefined(environment, variable("DWH", "BASE_URL"), binding.baseUrl);
+    setIfDefined(environment, variable("DWH", "USER"), binding.username);
+    setIfDefined(environment, variable("DWH", "SSH_HOST"), binding.sshHost);
+    setIfDefined(environment, variable("DWH", "SSH_PORT"), binding.sshPort);
+    setIfDefined(environment, variable("DWH", "SSH_USER"), binding.sshUsername);
+    setIfDefined(environment, variable("DWH", "SSH_TARGET_HOST"), binding.sshTargetHost);
+    setIfDefined(environment, variable("DWH", "SSH_TARGET_PORT"), binding.sshTargetPort);
+    for (const [suffix, secretId] of Object.entries(CATALOG_SECRET_BY_SUFFIX) as Array<[
+      InstallationSuffix,
+      string,
+    ]>) {
+      setIfDefined(environment, variable("DWH", suffix), materialization.files.get(secretId));
+    }
+    for (const requirement of evidenceRequirements) {
+      setIfDefined(environment, requirement.variable, materialization.files.get(requirement.id));
+    }
+
+    const bindings = resolveRuntimeBindings(workspace, environment, [...roots]);
+    let released = false;
+    return {
+      workspace,
+      bindings,
+      release: () => {
+        if (released) return;
+        released = true;
+        materialization?.release();
+      },
+    };
+  } catch (error) {
+    materialization?.release();
+    throw error;
+  }
+}
@@ -1,5 +1,3 @@
-import { buildInstallationContract } from "../workspaces/contracts.js";
-import { resolveBinding } from "../workspaces/bindings.js";
 import type { WorkspaceRegistry } from "../workspaces/registry.js";
 import type { WorkspaceDescriptor } from "../workspaces/schema.js";
 import { discoverWorkspaceSecretRequirements } from "../workspaces/secret-requirements.js";
@@ -45,60 +43,33 @@ export interface CatalogListItem extends Omit<WorkspaceDatabase, "id"> {
  secrets: Record<CatalogSecretName, boolean>;
 }

-function bindingValue(workspace: WorkspaceDescriptor, values: Record<string, string>, suffix: string) {
-  const variable = buildInstallationContract(workspace).variables.find((entry) => (
-    entry.role === "DWH" && entry.suffix === suffix
-  ));
-  return variable ? values[variable.name] : undefined;
-}
-
-function numeric(value: string | undefined): number | undefined {
-  if (!value) return undefined;
-  const parsed = Number(value);
-  return Number.isInteger(parsed) && parsed >= 1 && parsed <= 65_535 ? parsed : undefined;
-}
-
-function yamlBinding(workspace: WorkspaceDescriptor, secretRoots: readonly string[]): DatabaseBinding {
-  const effective = resolveBinding(workspace, "DWH", process.env, secretRoots);
-  const value = (suffix: string) => bindingValue(workspace, effective.values, suffix);
-  return {
-    transport: effective.transport,
-    host: value("HOST"),
-    port: numeric(value("PORT")) ?? workspace.dwh.port,
-    username: value("USER"),
-    baseUrl: value("BASE_URL"),
-    restPath: workspace.diagnostics?.dwh_rest?.path ?? "/health",
-    restAuth: workspace.diagnostics?.dwh_rest?.auth ?? "bearer",
-    tlsServername: value("TLS_SERVERNAME"),
-    sshHost: value("SSH_HOST"),
-    sshPort: numeric(value("SSH_PORT")),
-    sshUsername: value("SSH_USER"),
-    sshTargetHost: value("SSH_TARGET_HOST"),
-    sshTargetPort: numeric(value("SSH_TARGET_PORT")),
-  };
-}
-
 function secretState(store: WorkspaceSecretStore, workspaceId: string): Record<CatalogSecretName, boolean> {
  return Object.fromEntries(Object.entries(CATALOG_SECRET_IDS).map(([name, id]) => (
    [name, store.has(workspaceId, id)]
  ))) as Record<CatalogSecretName, boolean>;
 }

-function workspaceRuntimeState(
+function databaseRuntimeState(
  store: WorkspaceSecretStore,
-  workspace: WorkspaceDescriptor,
-  secretRoots: readonly string[],
+  database: WorkspaceDatabase,
 ): NonNullable<CatalogListItem["runtimeBinding"]> {
-  const requirements = discoverWorkspaceSecretRequirements(workspace, process.env);
-  const secretVariables = new Set(requirements.map(({ variable }) => variable));
-  const effective = resolveBinding(workspace, "DWH", process.env, secretRoots);
-  const configurationRequired = requirements.some(({ id, required }) => (
-    required && !store.has(workspace.workspace.id, id)
-  )) || effective.missing.some((variable) => !secretVariables.has(variable));
+  const { binding, workspaceId } = database;
+  const configured = (id: string) => store.has(workspaceId, id);
+  const connectionComplete = binding.transport === "postgres_direct"
+    ? Boolean(binding.host && binding.port && binding.username && configured(CATALOG_SECRET_IDS.password))
+    : binding.transport === "rest_api"
+      ? Boolean(binding.baseUrl && (binding.restAuth === "none" || configured(CATALOG_SECRET_IDS.apiKey)))
+      : Boolean(
+        binding.username && binding.sshHost && binding.sshPort && binding.sshUsername
+        && binding.sshTargetHost && binding.sshTargetPort
+        && configured(CATALOG_SECRET_IDS.password)
+        && configured(CATALOG_SECRET_IDS.sshPrivateKey)
+        && configured(CATALOG_SECRET_IDS.sshKnownHosts),
+      );
  return {
-    transport: effective.transport,
-    configurationState: configurationRequired ? "configuration_required" : "ready",
-    sessionTransportSupported: effective.transport !== "ssh_tunnel",
+    transport: binding.transport,
+    configurationState: connectionComplete ? "ready" : "configuration_required",
+    sessionTransportSupported: binding.transport !== "ssh_tunnel",
  };
 }

@@ -145,17 +116,18 @@ export class CatalogService {
    const active = await Promise.all(workspaces.map(async (entry) => {
      const database = byWorkspace.get(entry.id);
      const { workspace } = await this.registry.readPinned(entry.id, entry.revision.commit);
-      const runtimeDatabaseBinding = yamlBinding(workspace, this.secretRoots);
      const base = database ?? {
        workspaceId: entry.id,
        engine: "postgres" as const,
-        databaseName: workspace.dwh.database,
-        schema: workspace.dwh.schema,
+        databaseName: "",
+        schema: "",
        version: 0,
        createdAt: "",
        updatedAt: "",
-        binding: runtimeDatabaseBinding,
+        binding: { transport: "postgres_direct" as const },
        connectionStatus: "untested" as const,
+        metadataContentRevision: 0,
+        preprocessingStatus: "failed" as const,
      };
      return {
        ...base,
@@ -167,7 +139,7 @@ export class CatalogService {
          blob: entry.revision.blob,
        },
        workspaceEvidence: workspaceEvidenceState(this.secretStore, workspace),
-        runtimeBinding: workspaceRuntimeState(this.secretStore, workspace, this.secretRoots),
+        runtimeBinding: database ? databaseRuntimeState(this.secretStore, database) : null,
        configured: database !== undefined,
        secrets: secretState(this.secretStore, entry.id),
      };
@@ -195,13 +167,13 @@ export class CatalogService {
  }

  async normalizeInput(input: DatabaseConfigurationInput): Promise<DatabaseConfigurationInput> {
-    const workspace = await this.ensureWorkspace(input.workspaceId);
+    await this.ensureWorkspace(input.workspaceId);
    if (input.binding.transport !== "rest_api") return input;
    return {
      ...input,
      binding: {
        ...input.binding,
-        restPath: workspace.diagnostics?.dwh_rest?.path ?? "/health",
+        restPath: input.binding.restPath ?? "/health",
      },
    };
  }
@@ -2,6 +2,7 @@ export const DATABASE_TRANSPORTS = ["postgres_direct", "rest_api", "ssh_tunnel"]
 export type DatabaseTransport = (typeof DATABASE_TRANSPORTS)[number];

 export type ConnectionStatus = "untested" | "reachable" | "failed";
+export type CatalogPreprocessingStatus = "running" | "succeeded" | "failed";

 export interface DatabaseBinding {
  transport: DatabaseTransport;
@@ -36,8 +37,23 @@ export interface WorkspaceDatabase {
  lastErrorMessage?: string;
  schemaSyncedVersion?: number;
  schemaSyncedAt?: string;
+  metadataContentRevision: number;
+  preprocessingStatus: CatalogPreprocessingStatus;
+  preprocessingInputFingerprint?: string;
+  preprocessedMetadataRevision?: number;
+  preprocessingStartedAt?: string;
+  preprocessingFinishedAt?: string;
+  preprocessingErrorCode?: string;
 }

+export type CatalogPreprocessingStartResult =
+  | { kind: "started"; database: WorkspaceDatabase }
+  | { kind: "not_found" | "schema_stale" | "catalog_busy" | "already_running" };
+
+export type CatalogPreprocessingClearResult =
+  | { kind: "cleared"; database: WorkspaceDatabase }
+  | { kind: "not_found" | "already_running" };
+
 export interface CatalogMetrics {
  scope: "global" | "database";
  databaseId: string | null;
@@ -196,7 +212,7 @@ export interface CatalogLogicalRelationshipCandidate {

 export type CatalogDatabaseMetadataDeleteTarget = "tables" | "relationships";
 export type CatalogTableMetadataDeleteTarget = "columns" | "relationships";
-export type CatalogDescriptionTarget = "tables" | "columns" | "database_columns";
+export type CatalogDescriptionTarget = "tables" | "columns" | "database" | "database_columns";

 export interface CatalogMetadataDeleteCounts {
  tables: number;
@@ -433,6 +449,17 @@ export interface CatalogRepository {
  list(): Promise<WorkspaceDatabase[]>;
  get(id: string): Promise<WorkspaceDatabase | undefined>;
  getByWorkspace(workspaceId: string): Promise<WorkspaceDatabase | undefined>;
+  beginPreprocessing(
+    workspaceId: string,
+    inputFingerprint: string,
+  ): Promise<CatalogPreprocessingStartResult>;
+  finishPreprocessing(
+    workspaceId: string,
+    metadataContentRevision: number,
+    inputFingerprint: string,
+    outcome: { status: "succeeded" } | { status: "failed"; errorCode: string },
+  ): Promise<WorkspaceDatabase | undefined>;
+  clearPreprocessing(workspaceId: string): Promise<CatalogPreprocessingClearResult>;
  getCatalogMetrics(databaseId?: string): Promise<CatalogMetrics | undefined>;
  create(input: DatabaseConfigurationInput): Promise<WorkspaceDatabase>;
  update(id: string, expectedVersion: number, input: DatabaseConfigurationInput): Promise<WorkspaceDatabase | undefined>;
@@ -14,7 +14,7 @@ const consolidationSchema = z.discriminatedUnion("target", [
    target: z.enum(["tables", "columns"]),
    targetIds: z.array(idSchema).min(1).max(10_000),
  }).strict(),
-  z.object({ target: z.literal("database_columns") }).strict(),
+  z.object({ target: z.enum(["database", "database_columns"]) }).strict(),
 ]);

 function manage(request: FastifyRequest, reply: FastifyReply) {
@@ -11,8 +11,8 @@ import type { WorkspaceRegistry } from "../workspaces/registry.js";
 import { validateOperationalWorkspace, type WorkspaceDescriptor } from "../workspaces/schema.js";
 import type { MaintenanceBarrier } from "../runtime/maintenance-gate.js";
 import { hasPermission, isPrincipalContext, requirePermission } from "../auth/authorization.js";
-import type { EffectiveRelationshipSnapshotProvider } from "../catalog/effective-relationship-snapshot.js";
 import { splitCanonicalModelId, type RuntimeModelCatalog } from "../models/runtime-model-catalog.js";
+import type { CatalogRepository } from "../catalog/types.js";

 const BOOTSTRAP_FAILURE_MESSAGE =
  "Session startup failed. Check configuration and connectivity, then Resume the session.";
@@ -42,12 +42,40 @@ export function sessionRoutes(
    /** Fail-closed installation/runtime transport capability check. */
    workspaceRuntimeSupport: (workspace: WorkspaceDescriptor) => boolean;
    maintenanceBarrier: MaintenanceBarrier;
-    /** Optional only for narrow route-test stubs and installations without a Catalog database. */
-    effectiveRelationships?: EffectiveRelationshipSnapshotProvider;
    modelCatalog: RuntimeModelCatalog;
+    /** PostgreSQL authority for mandatory preprocessing admission. */
+    catalogRepository?: CatalogRepository;
  },
 ) {
  const lifecycleTails = new Map<string, Promise<void>>();
+
+  const preprocessingIsCurrent = async (
+    workspaceId: string,
+    inputFingerprint?: string,
+  ): Promise<boolean> => {
+    if (!d.catalogRepository) return true;
+    const database = await d.catalogRepository.getByWorkspace(workspaceId);
+    return database !== undefined
+      && database.preprocessingStatus === "succeeded"
+      && database.preprocessedMetadataRevision === database.metadataContentRevision
+      && (inputFingerprint === undefined
+        || database.preprocessingInputFingerprint === inputFingerprint);
+  };
+
+  const catalogTransportSupportsSessionRuntime = async (workspaceId: string): Promise<boolean> => {
+    if (!d.catalogRepository) return true;
+    const database = await d.catalogRepository.getByWorkspace(workspaceId);
+    return database === undefined || database.binding.transport !== "ssh_tunnel";
+  };
+
+  const currentInputFingerprint = async (
+    runner: any,
+    workspaceConfigPath: string,
+  ): Promise<string | undefined> => (
+    typeof runner.workspaceInputFingerprint === "function"
+      ? await runner.workspaceInputFingerprint(workspaceConfigPath)
+      : undefined
+  );
  const boundRuntimes = new Map<
    string,
    ReturnType<PiProcessManager["createFor"]>
@@ -92,16 +120,13 @@ export function sessionRoutes(
  const optionsWithRuntimeConfig = async (
    runner: any,
    workspaceConfigPath: string | undefined,
-    workspaceId: string | undefined,
+    _workspaceId: string | undefined,
    options: any,
  ) => {
    if (!workspaceConfigPath || typeof runner.acquireWorkspaceRuntime !== "function") return options;
-    const effectiveRelationships = workspaceId && d.effectiveRelationships
-      ? await d.effectiveRelationships.render(workspaceId)
-      : undefined;
    return {
      ...options,
-      runtimeConfig: runner.acquireWorkspaceRuntime(workspaceConfigPath, effectiveRelationships),
+      runtimeConfig: await runner.acquireWorkspaceRuntime(workspaceConfigPath),
    };
  };

@@ -379,6 +404,19 @@ export function sessionRoutes(
          workspaceId = resolved.revision.id;
          workspaceRevision = resolved.revision.commit;
          workspaceDescriptor = resolved.workspace;
+          if (!await catalogTransportSupportsSessionRuntime(workspaceId)) {
+            return reply.code(409).send({
+              error: "This workspace transport is not available to runtime sessions.",
+              code: "workspace_not_activatable",
+            });
+          }
+          const fingerprint = await currentInputFingerprint(runner, workspaceConfigPath);
+          if (!await preprocessingIsCurrent(workspaceId, fingerprint)) {
+            return reply.code(409).send({
+              error: "Run workspace preprocessing before starting the core.",
+              code: "preprocessing_required",
+            });
+          }
        } catch {
          return reply.code(409).send({
            error: WORKSPACE_REVISION_UNAVAILABLE_MESSAGE,
@@ -615,6 +653,23 @@ export function sessionRoutes(
        workspaceDescriptor = resolved.workspace;
      }
      catch { return unavailableWorkspaceReply(reply); }
+      if (d.catalogRepository && saved.workspace_id
+        && !await catalogTransportSupportsSessionRuntime(saved.workspace_id)) {
+        return reply.code(409).send({
+          error: "This workspace transport is not available to runtime sessions.",
+          code: "workspace_not_activatable",
+        });
+      }
+      const fingerprint = d.catalogRepository
+        ? await currentInputFingerprint(runner, workspaceConfigPath)
+        : undefined;
+      if (d.catalogRepository
+        && (!saved.workspace_id || !await preprocessingIsCurrent(saved.workspace_id, fingerprint))) {
+        return reply.code(409).send({
+          error: "Run workspace preprocessing before starting the core.",
+          code: "preprocessing_required",
+        });
+      }
      try { settings = await d.getSettings(principal); } catch { return storageFailure(reply); }
      // This check belongs inside the per-session lock: a preceding cold Resume may have
      // installed a running runtime while this request was waiting.
@@ -0,0 +1,402 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+import { isPrincipalContext, requirePermission } from "../auth/authorization.js";
+import {
+  CatalogUnavailableError,
+  type CatalogRepository,
+  type WorkspaceDatabase,
+} from "../catalog/types.js";
+import type { ThtRunner } from "../tht/tht-runner.js";
+import type { WorkspacePreprocessingService } from "../workspaces/preprocessing-service.js";
+import type { PreprocessingJobState } from "../workspaces/preprocessing-state.js";
+import type { WorkspaceRegistry } from "../workspaces/registry.js";
+
+const workspaceIdSchema = z.string().regex(/^[a-z][a-z0-9-]{2,62}$/);
+const ACTIVE_SYNC_STATES = new Set(["queued", "running", "awaiting_confirmation", "applying"]);
+
+export type WorkspacePreprocessingUiState =
+  | "ready"
+  | "required"
+  | "running"
+  | "blocked"
+  | "failed";
+
+export interface WorkspacePreprocessingStatus {
+  schemaVersion: 1;
+  workspaceId: string;
+  state: WorkspacePreprocessingUiState;
+  actionable: boolean;
+  clearable: boolean;
+  detail: string;
+  reason?: string;
+  nextStep?: string;
+  metadataRevision?: number;
+  preprocessedMetadataRevision?: number;
+  startedAt?: string;
+  finishedAt?: string;
+  progress?: {
+    stage: "catalog_snapshot" | "schema_index" | "evidence" | "finalizing";
+    step: number;
+    totalSteps: 4;
+  };
+  lastFailure?: {
+    stage: string;
+    errorCode: string;
+    finishedAt: string;
+  };
+}
+
+export interface WorkspacePreprocessingRouteDeps {
+  repository: CatalogRepository;
+  registry: WorkspaceRegistry;
+  service: Pick<WorkspacePreprocessingService, "run" | "clear">;
+  inputFingerprint?: Pick<ThtRunner, "workspaceInputFingerprint">;
+  readLatestJob?: (workspaceId: string) => PreprocessingJobState | undefined;
+}
+
+const PROGRESS_DETAILS = {
+  catalog_snapshot: "Preparing the PostgreSQL Catalog snapshot.",
+  schema_index: "Building schema vectors and LSH indexes.",
+  evidence: "Indexing Evidence.",
+  finalizing: "Publishing the completed preprocessing state.",
+} as const;
+
+function runningProgress(
+  workspaceId: string,
+  deps: WorkspacePreprocessingRouteDeps,
+): NonNullable<WorkspacePreprocessingStatus["progress"]> {
+  let job: PreprocessingJobState | undefined;
+  try {
+    job = deps.readLatestJob?.(workspaceId);
+  } catch {
+    // Progress is supplemental. A damaged or temporarily unavailable checkpoint must not hide
+    // the authoritative running state held by PostgreSQL.
+  }
+  const completed = new Set(job?.status === "active" ? job.completedStages : []);
+  if (completed.has("evidence")) return { stage: "finalizing", step: 4, totalSteps: 4 };
+  if (completed.has("schema_index")) return { stage: "evidence", step: 3, totalSteps: 4 };
+  if (completed.has("catalog_snapshot")) return { stage: "schema_index", step: 2, totalSteps: 4 };
+  return { stage: "catalog_snapshot", step: 1, totalSteps: 4 };
+}
+
+function base(
+  workspaceId: string,
+  state: WorkspacePreprocessingUiState,
+  detail: string,
+  database?: WorkspaceDatabase,
+): WorkspacePreprocessingStatus {
+  return {
+    schemaVersion: 1,
+    workspaceId,
+    state,
+    actionable: state === "ready" || state === "required" || state === "failed",
+    clearable: Boolean(
+      database
+      && state !== "running"
+      && database.preprocessingErrorCode !== "derived_data_cleared"
+    ),
+    detail,
+    ...(database ? {
+      metadataRevision: database.metadataContentRevision,
+      ...(database.preprocessedMetadataRevision === undefined
+        ? {}
+        : { preprocessedMetadataRevision: database.preprocessedMetadataRevision }),
+      ...(database.preprocessingStartedAt ? { startedAt: database.preprocessingStartedAt } : {}),
+      ...(database.preprocessingFinishedAt ? { finishedAt: database.preprocessingFinishedAt } : {}),
+    } : {}),
+  };
+}
+
+function blocked(
+  workspaceId: string,
+  detail: string,
+  reason: string,
+  nextStep: string,
+  database?: WorkspaceDatabase,
+): WorkspacePreprocessingStatus {
+  return { ...base(workspaceId, "blocked", detail, database), reason, nextStep };
+}
+
+function failureDiagnostic(errorCode: string): {
+  stage: string;
+  detail: string;
+  reason: string;
+  nextStep: string;
+} {
+  switch (errorCode) {
+    case "catalog_snapshot_failed":
+      return {
+        stage: "catalog_snapshot",
+        detail: "The Catalog snapshot could not be prepared.",
+        reason: "PostgreSQL Catalog metadata could not be read into a consistent preprocessing snapshot.",
+        nextStep: "Check Catalog availability, then retry preprocessing.",
+      };
+    case "schema_index_failed":
+      return {
+        stage: "schema_index",
+        detail: "The schema index could not be rebuilt.",
+        reason: "The schema indexing worker stopped before the Catalog snapshot was published to Qdrant.",
+        nextStep: "Open Last run details below, check the core service log for this error code, then retry.",
+      };
+    case "evidence_preprocessing_failed":
+      return {
+        stage: "evidence",
+        detail: "Evidence preprocessing did not complete.",
+        reason: "The Evidence indexing worker stopped before it finished publishing the current workspace data.",
+        nextStep: "Open Last run details below, check the core service log for this error code, then retry.",
+      };
+    case "semantic_index_incompatible":
+      return {
+        stage: "semantic_preflight",
+        detail: "The semantic index configuration is incompatible.",
+        reason: "Qdrant rejected the collection configuration for the active embedding model.",
+        nextStep: "Check embedding dimensions and Qdrant collection settings, then retry.",
+      };
+    case "egress_policy_refused":
+      return {
+        stage: "evidence",
+        detail: "The Evidence source was refused by policy.",
+        reason: "The configured Evidence endpoint is not allowed by the installation egress policy.",
+        nextStep: "Correct the Evidence source or its allowlist configuration, then retry.",
+      };
+    case "workspace_not_activatable":
+      return {
+        stage: "runtime_preflight",
+        detail: "The workspace runtime could not be prepared.",
+        reason: "The active workspace or one of its required runtime bindings is not usable.",
+        nextStep: "Check Workspace management and Database management, then retry.",
+      };
+    default:
+      return {
+        stage: "preprocessing",
+        detail: "Preprocessing did not complete.",
+        reason: "The preprocessing worker stopped before the current Catalog revision was published.",
+        nextStep: "Open Last run details below, check the core service log for this error code, then retry.",
+      };
+  }
+}
+
+export async function readWorkspacePreprocessingStatus(
+  workspaceId: string,
+  deps: WorkspacePreprocessingRouteDeps,
+): Promise<WorkspacePreprocessingStatus> {
+  const database = await deps.repository.getByWorkspace(workspaceId);
+  if (!database) {
+    return blocked(
+      workspaceId,
+      "Database configuration is required.",
+      "This workspace has no database configuration in the PostgreSQL Catalog.",
+      "Open Database management and configure the workspace database.",
+    );
+  }
+
+  if (database.preprocessingStatus === "running") {
+    const progress = runningProgress(workspaceId, deps);
+    return {
+      ...base(workspaceId, "running", PROGRESS_DETAILS[progress.stage], database),
+      progress,
+    };
+  }
+  if (database.binding.transport === "ssh_tunnel") {
+    return blocked(
+      workspaceId,
+      "The database transport is not supported by the core runtime.",
+      "The current database binding uses an SSH tunnel, which cannot be used by a ThothII session.",
+      "Open Database management and select a supported runtime transport.",
+      database,
+    );
+  }
+  if (database.schemaSyncedVersion !== database.version) {
+    return blocked(
+      workspaceId,
+      "Catalog synchronization is required.",
+      `Database configuration v${database.version} is newer than the latest Catalog synchronization${database.schemaSyncedVersion === undefined ? "." : ` v${database.schemaSyncedVersion}.`}`,
+      "Open Database management and run Synchronize schema.",
+      database,
+    );
+  }
+
+  const [syncRuns, activeDescriptionRun, sensitivityRuns] = await Promise.all([
+    deps.repository.listSyncRuns(database.id, 10),
+    deps.repository.getActiveDescriptionGenerationRun(),
+    deps.repository.listSensitivityAnalysisRuns(50),
+  ]);
+  if (syncRuns.some((run) => ACTIVE_SYNC_STATES.has(run.state))) {
+    return blocked(
+      workspaceId,
+      "Catalog synchronization is in progress.",
+      "The Catalog is being synchronized and its metadata revision is not stable yet.",
+      "Wait for schema synchronization to finish, then run preprocessing.",
+      database,
+    );
+  }
+  if (activeDescriptionRun?.databaseId === database.id
+    && ["queued", "running"].includes(activeDescriptionRun.status)) {
+    return blocked(
+      workspaceId,
+      "Description generation is in progress.",
+      "Catalog descriptions are still being generated for this database.",
+      "Wait for description generation to finish, then run preprocessing.",
+      database,
+    );
+  }
+  if (sensitivityRuns.some((run) => run.databaseId === database.id && run.status === "running")) {
+    return blocked(
+      workspaceId,
+      "Sensitivity analysis is in progress.",
+      "Catalog sensitivity metadata is still being analyzed for this database.",
+      "Wait for sensitivity analysis to finish, then run preprocessing.",
+      database,
+    );
+  }
+
+  let inputFingerprint: string | undefined;
+  try {
+    const record = await deps.registry.read(workspaceId);
+    if (deps.inputFingerprint) {
+      inputFingerprint = await deps.inputFingerprint.workspaceInputFingerprint(
+        record.revision.snapshotPath,
+      );
+    }
+  } catch {
+    return blocked(
+      workspaceId,
+      "The workspace runtime configuration is unavailable.",
+      "The active workspace revision or one of its required database secrets could not be resolved.",
+      "Check Workspace management and Database management before running preprocessing.",
+      database,
+    );
+  }
+
+  const current = database.preprocessingStatus === "succeeded"
+    && database.preprocessedMetadataRevision === database.metadataContentRevision
+    && (inputFingerprint === undefined
+      || database.preprocessingInputFingerprint === inputFingerprint);
+  if (current) {
+    return base(
+      workspaceId,
+      "ready",
+      `Catalog revision ${database.metadataContentRevision} is indexed.`,
+      database,
+    );
+  }
+
+  if (database.preprocessingErrorCode === "derived_data_cleared") {
+    return base(
+      workspaceId,
+      "required",
+      "Reference vectors and LSH are empty. Memory is preserved.",
+      database,
+    );
+  }
+
+  if (database.preprocessingStatus === "failed"
+    && database.preprocessingErrorCode
+    && database.preprocessingErrorCode !== "catalog_changed"
+    && database.preprocessingErrorCode !== "derived_data_cleared"
+    && database.preprocessingFinishedAt) {
+    const diagnostic = failureDiagnostic(database.preprocessingErrorCode);
+    return {
+      ...base(workspaceId, "failed", diagnostic.detail, database),
+      reason: diagnostic.reason,
+      nextStep: diagnostic.nextStep,
+      lastFailure: {
+        stage: diagnostic.stage,
+        errorCode: database.preprocessingErrorCode,
+        finishedAt: database.preprocessingFinishedAt,
+      },
+    };
+  }
+
+  return base(
+    workspaceId,
+    "required",
+    `Catalog revision ${database.metadataContentRevision} is not indexed.`,
+    database,
+  );
+}
+
+function safeError(reply: FastifyReply, error: unknown) {
+  if (error instanceof CatalogUnavailableError) {
+    return reply.code(503).send({
+      code: "catalog_unavailable",
+      message: "Database catalog is unavailable.",
+    });
+  }
+  if (error instanceof z.ZodError) {
+    return reply.code(400).send({
+      code: "preprocessing_request_invalid",
+      message: "Preprocessing request is invalid.",
+    });
+  }
+  return reply.code(500).send({
+    code: "preprocessing_run_failed",
+    message: "Preprocessing status could not be resolved.",
+  });
+}
+
+function workspaceIdFrom(request: FastifyRequest): string {
+  return workspaceIdSchema.parse((request.params as { workspaceId?: unknown }).workspaceId);
+}
+
+export function workspacePreprocessingRoutes(
+  app: FastifyInstance,
+  deps: WorkspacePreprocessingRouteDeps,
+): void {
+  app.get("/workspaces/:workspaceId/preprocessing", async (request, reply) => {
+    if (!isPrincipalContext(requirePermission(request, reply, "session.use"))) return reply;
+    try {
+      return await readWorkspacePreprocessingStatus(workspaceIdFrom(request), deps);
+    } catch (error) {
+      return safeError(reply, error);
+    }
+  });
+
+  app.post("/workspaces/:workspaceId/preprocessing", async (request, reply) => {
+    if (!isPrincipalContext(requirePermission(request, reply, "database.manage"))) return reply;
+    try {
+      const workspaceId = workspaceIdFrom(request);
+      const before = await readWorkspacePreprocessingStatus(workspaceId, deps);
+      if (!before.actionable) {
+        return reply.code(409).send({ ...before, code: "preprocessing_blocked" });
+      }
+
+      const result = await deps.service.run({ workspaceId });
+      const after = await readWorkspacePreprocessingStatus(workspaceId, deps);
+      if (after.state === "ready") return after;
+      if (after.state === "failed") {
+        return reply.code(422).send({ ...after, code: "preprocessing_run_failed" });
+      }
+      if (after.state === "blocked" || after.state === "running") {
+        return reply.code(409).send({ ...after, code: "preprocessing_blocked" });
+      }
+      return reply.code(500).send({
+        code: "preprocessing_run_failed",
+        message: `Preprocessing ended with ${result.code}.`,
+      });
+    } catch (error) {
+      return safeError(reply, error);
+    }
+  });
+
+  app.delete("/workspaces/:workspaceId/preprocessing", async (request, reply) => {
+    if (!isPrincipalContext(requirePermission(request, reply, "database.manage"))) return reply;
+    try {
+      const workspaceId = workspaceIdFrom(request);
+      const before = await readWorkspacePreprocessingStatus(workspaceId, deps);
+      if (!before.clearable) {
+        return reply.code(409).send({ ...before, code: "preprocessing_clear_blocked" });
+      }
+      const result = await deps.service.clear({ workspaceId });
+      if (result.status !== "succeeded") {
+        return reply.code(result.code === "preprocessing_conflict" ? 409 : 500).send({
+          code: result.code,
+          message: "Preprocessing data could not be cleared.",
+        });
+      }
+      return await readWorkspacePreprocessingStatus(workspaceId, deps);
+    } catch (error) {
+      return safeError(reply, error);
+    }
+  });
+}
@@ -5,7 +5,7 @@ import {
  openSync, readFileSync, readSync, realpathSync, statSync, unlinkSync, writeFileSync,
 } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { parseAllDocuments } from "yaml";
+import { parse, parseAllDocuments } from "yaml";
 import { clearPrincipalEnvironment, principalEnvironment, type PrincipalContext } from "../auth/principal.js";
 import { secretValue, type SecretBundleConfig } from "../config/secret-bundle.js";
 import { renderWorkspaceRuntimeFromSnapshotPath } from "../workspaces/runtime-config-lease.js";
@@ -22,6 +22,9 @@ import {
 } from "../workspaces/schema.js";
 import { reconcileCollection, type CollectionMode } from "../workspaces/qdrant-collection.js";
 import type { WorkspaceSecretStore } from "../workspaces/secret-store.js";
+import type { CatalogRepository } from "../catalog/types.js";
+import { preprocessingInputFingerprint } from "../workspaces/effective-config.js";
+import { workspaceVectorCollections } from "../workspaces/vector-collections.js";

 export interface ThtConfig extends SecretBundleConfig {
  thtBin: string;
@@ -35,12 +38,14 @@ export interface ThtConfig extends SecretBundleConfig {
  /** "self_heal" for session admission (create missing collections/indexes), default "require_existing". */
  qdrantCollectionMode?: "self_heal" | "require_existing";
  workspaceSecretStore?: WorkspaceSecretStore;
+  catalogRepository?: CatalogRepository;
 }

 export interface RuntimeConfigLease {
  path: string;
  workspaceId: string;
  workspaceRevision: string;
+  inputFingerprint: string;
  release(): void;
 }

@@ -79,6 +84,7 @@ export type SemanticReadinessCode = "workspace_not_activatable" | "semantic_inde
 export interface QdrantEnsureResult {
  ok: boolean;
  code?: SemanticReadinessCode;
+  state?: "ready" | "created" | "repaired" | "upgraded";
 }

 const REQUIRED_QDRANT_PAYLOAD_INDEXES = [
@@ -213,37 +219,31 @@ export class ThtRunner {
  }

  /** Render one immutable canonical registry revision into a backend-owned harness config. */
-  acquireWorkspaceRuntime(
-    workspaceConfigPath: string,
-    effectiveRelationships?: string,
-  ): RuntimeConfigLease {
-    const effectiveRelationshipsPath = effectiveRelationships === undefined
+  async acquireWorkspaceRuntime(workspaceConfigPath: string): Promise<RuntimeConfigLease> {
+    const identity = this.assertWorkspaceSnapshot(workspaceConfigPath);
+    const catalogDatabase = this.cfg.catalogRepository === undefined
      ? undefined
-      : this.createRuntimeSnapshot(effectiveRelationships);
-    let rendered: ReturnType<typeof renderWorkspaceRuntimeFromSnapshotPath>;
-    try {
-      rendered = renderWorkspaceRuntimeFromSnapshotPath({
-        snapshotPath: workspaceConfigPath,
-        harnessDir: this.cfg.harnessDir,
-        configPath: this.cfg.configPath,
-        dataRoot: this.cfg.dataRoot ?? (() => {
-          throw new Error("registry workspace runtime requires an absolute data root");
-        })(),
-        secretRoots: this.cfg.secretRoots ?? [],
-        semanticRuntime: this.cfg.semanticRuntime ?? DEFAULT_SEMANTIC_RUNTIME,
-        workspaceSecretStore: this.cfg.workspaceSecretStore,
-        effectiveRelationshipsPath,
-      });
-    } catch (error) {
-      if (effectiveRelationshipsPath) this.cleanupRuntimeSnapshot(effectiveRelationshipsPath);
-      throw error;
+      : await this.cfg.catalogRepository.getByWorkspace(identity.workspaceId);
+    if (this.cfg.catalogRepository !== undefined && !catalogDatabase) {
+      throw new Error("workspace database is not configured in the Catalog");
    }
+    const rendered = renderWorkspaceRuntimeFromSnapshotPath({
+      snapshotPath: workspaceConfigPath,
+      harnessDir: this.cfg.harnessDir,
+      configPath: this.cfg.configPath,
+      dataRoot: this.cfg.dataRoot ?? (() => {
+        throw new Error("registry workspace runtime requires an absolute data root");
+      })(),
+      secretRoots: this.cfg.secretRoots ?? [],
+      semanticRuntime: this.cfg.semanticRuntime ?? DEFAULT_SEMANTIC_RUNTIME,
+      workspaceSecretStore: this.cfg.workspaceSecretStore,
+      catalogDatabase,
+    });
    let path: string;
    try {
      path = this.createRuntimeSnapshot(rendered.renderedConfig);
    } catch (error) {
      rendered.releaseSecrets();
-      if (effectiveRelationshipsPath) this.cleanupRuntimeSnapshot(effectiveRelationshipsPath);
      throw error;
    }
    let released = false;
@@ -251,16 +251,29 @@ export class ThtRunner {
      path,
      workspaceId: rendered.workspaceId,
      workspaceRevision: rendered.workspaceRevision,
+      inputFingerprint: preprocessingInputFingerprint(
+        rendered.workspaceId,
+        rendered.workspaceRevision,
+        parse(rendered.renderedConfig),
+      ),
      release: () => {
        if (released) return;
        released = true;
        this.cleanupRuntimeSnapshot(path);
-        if (effectiveRelationshipsPath) this.cleanupRuntimeSnapshot(effectiveRelationshipsPath);
        rendered.releaseSecrets();
      },
    };
  }

+  async workspaceInputFingerprint(workspaceConfigPath: string): Promise<string> {
+    const lease = await this.acquireWorkspaceRuntime(workspaceConfigPath);
+    try {
+      return lease.inputFingerprint;
+    } finally {
+      lease.release();
+    }
+  }
+
  private runtimeSnapshotDirectory(): string {
    if (!this.cfg.runtimeSnapshotRoot) throw new Error("runtime snapshot root is not configured");
    if (!isAbsolute(this.cfg.runtimeSnapshotRoot)) throw new Error("runtime snapshot root must be absolute");
@@ -392,13 +405,9 @@ export class ThtRunner {
      workspaceConfigPath && isAbsolute(workspaceConfigPath)
      && !this.runtimeSnapshots.has(workspaceConfigPath)
    ) {
-      let runtime: RuntimeConfigLease;
-      try {
-        runtime = this.acquireWorkspaceRuntime(workspaceConfigPath);
-      } catch (error) {
-        return Promise.reject(error);
-      }
-      return this.run(args, runtime.path, timeoutMs).finally(runtime.release);
+      return this.acquireWorkspaceRuntime(workspaceConfigPath).then((runtime) => (
+        this.run(args, runtime.path, timeoutMs).finally(runtime.release)
+      ));
    }
    return new Promise((resolve) => {
      const env: NodeJS.ProcessEnv = { ...process.env };
@@ -598,24 +607,26 @@ export class ThtRunner {
    } catch {
      return { ok: false, code: "workspace_not_activatable" };
    }
-    const collection = {
-      collection: descriptor.workspace.id,
-      dimensions: this.cfg.semanticRuntime.internalEmbeddingDimensions,
-      distance: "cosine" as const,
-    };
+    const collections = workspaceVectorCollections(descriptor.workspace.id);
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), Math.max(1, timeoutSec) * 1000);
    try {
-      const checked = await reconcileCollection({
-        baseUrl: this.cfg.semanticRuntime.internalQdrantUrl,
-        collection: collection.collection,
-        dimensions: collection.dimensions,
-        distance: collection.distance,
-        mode,
-        request: this.cfg.qdrantRequest ?? fetch,
-        signal: controller.signal,
-      });
-      return checked;
+      const checked = await Promise.all(Object.entries(collections).map(async ([purpose, collection]) =>
+        await reconcileCollection({
+          baseUrl: this.cfg.semanticRuntime.internalQdrantUrl,
+          collection,
+          dimensions: this.cfg.semanticRuntime.internalEmbeddingDimensions,
+          distance: "cosine",
+          mode: mode === "evidence_maintenance" && purpose === "memory" ? "self_heal" : mode,
+          request: this.cfg.qdrantRequest ?? fetch,
+          signal: controller.signal,
+        })));
+      if (!checked.every((result) => result.ok)) {
+        return { ok: false, code: "semantic_index_incompatible" };
+      }
+      const state = (["upgraded", "repaired", "created", "ready"] as const)
+        .find((candidate) => checked.some((result) => result.state === candidate));
+      return { ok: true, ...(state ? { state } : {}) };
    } catch {
      return { ok: false, code: "workspace_not_activatable" };
    } finally {
@@ -1,15 +1,14 @@
 import { spawn } from "node:child_process";
 import { closeSync, constants as fsConstants, openSync } from "node:fs";
-import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { parse } from "yaml";
-import { loadConfig } from "./config.js";
+import { loadConfig, type AppConfig } from "./config.js";
 import { ThtRunner } from "./tht/tht-runner.js";
 import { WorkspaceRegistry } from "./workspaces/registry.js";
 import { publishDeterministicRuntimeConfigLease, renderActiveWorkspaceRuntime } from "./workspaces/runtime-config-lease.js";
 import { WorkspaceSecretStore } from "./workspaces/secret-store.js";
 import { WorkspacePreprocessingService, type WorkspaceOperationResult } from "./workspaces/preprocessing-service.js";
-import type { SessionInventoryRow } from "./workspaces/preprocessing-state.js";
+import { createCatalogRepository } from "./catalog/repository.js";
+import type { CatalogRepository } from "./catalog/types.js";

 export interface WorkspaceMaintenanceIo {
  stdin: string;
@@ -19,7 +18,7 @@ export interface WorkspaceMaintenanceIo {
  writeStderr(value: string): void;
 }

-type Command = "inspect" | "preprocess-dwh" | "schema-suggest-fks" | "schema-check" | "schema-accept" | "index-schema" | "preprocess-evidence" | "preprocess-run" | "vector-inspect" | "vector-rebuild";
+type Command = "inspect" | "preprocess-run" | "preprocess-clear";

 function failureResult(
  operation: string,
@@ -64,15 +63,8 @@ function parseRequest(command: string, stdin: string): Record<string, unknown> {
  }
  const allowedByCommand: Record<string, readonly string[]> = {
    inspect: ["schemaVersion", "workspaceId"],
-    "preprocess-dwh": ["schemaVersion", "workspaceId", "resumeRunId"],
-    "schema-suggest-fks": ["schemaVersion", "workspaceId", "fromSql", "assume", "resumeRunId"],
-    "schema-check": ["schemaVersion", "workspaceId", "annotationsYaml", "reviewedCandidatesDigest"],
-    "schema-accept": ["schemaVersion", "workspaceId", "runId", "yes"],
-    "index-schema": ["schemaVersion", "workspaceId", "resumeRunId"],
-    "preprocess-evidence": ["schemaVersion", "workspaceId", "dryRun", "resumeRunId"],
-    "preprocess-run": ["schemaVersion", "workspaceId", "resumeRunId"],
-    "vector-inspect": ["schemaVersion", "workspaceId"],
-    "vector-rebuild": ["schemaVersion", "workspaceId", "collection", "confirm", "destroy"],
+    "preprocess-run": ["schemaVersion", "workspaceId"],
+    "preprocess-clear": ["schemaVersion", "workspaceId"],
  };
  const allowed = allowedByCommand[command];
  if (!allowed) throw new Error("unknown command");
@@ -91,55 +83,12 @@ async function dispatch(command: Command, service: WorkspacePreprocessingService
  switch (command) {
    case "inspect":
      return await service.inspect({ workspaceId: request.workspaceId as string });
-    case "preprocess-dwh":
-      return await service.preprocessDwh({
-        workspaceId: request.workspaceId as string,
-        resumeRunId: request.resumeRunId as string | undefined,
-      });
-    case "schema-suggest-fks":
-      return await service.suggestFks({
-        workspaceId: request.workspaceId as string,
-        fromSql: request.fromSql as any,
-        assume: request.assume as any,
-        resumeRunId: request.resumeRunId as string | undefined,
-      });
-    case "schema-check":
-      return await service.checkSchema({
-        workspaceId: request.workspaceId as string,
-        annotationsYaml: request.annotationsYaml as string | undefined,
-        reviewedCandidatesDigest: request.reviewedCandidatesDigest as string | undefined,
-      });
-    case "schema-accept":
-      return await service.acceptSchema({
-        workspaceId: request.workspaceId as string,
-        runId: request.runId as string,
-        yes: request.yes === true,
-      });
-    case "index-schema":
-      return await service.indexSchema({
-        workspaceId: request.workspaceId as string,
-        resumeRunId: request.resumeRunId as string | undefined,
-      });
-    case "preprocess-evidence":
-      return await service.preprocessEvidence({
-        workspaceId: request.workspaceId as string,
-        dryRun: request.dryRun as boolean | undefined,
-        resumeRunId: request.resumeRunId as string | undefined,
-      });
    case "preprocess-run":
      return await service.run({
        workspaceId: request.workspaceId as string,
-        resumeRunId: request.resumeRunId as string | undefined,
-      });
-    case "vector-inspect":
-      return await service.vectorInspect({ workspaceId: request.workspaceId as string });
-    case "vector-rebuild":
-      return await service.vectorRebuild({
-        workspaceId: request.workspaceId as string,
-        collection: request.collection as string | undefined,
-        confirm: request.confirm as string | undefined,
-        destroy: request.destroy === true,
      });
+    case "preprocess-clear":
+      return await service.clear({ workspaceId: request.workspaceId as string });
  }
 }

@@ -178,48 +127,31 @@ export async function runWorkspaceMaintenanceCli(
      || message === "unexpected request field"
      || message === "invalid workspace id";
    return command in {
-      inspect: true, "preprocess-dwh": true, "schema-suggest-fks": true, "schema-check": true,
-      "schema-accept": true,
-      "index-schema": true, "preprocess-evidence": true, "preprocess-run": true,
+      inspect: true, "preprocess-run": true, "preprocess-clear": true,
    } ? (requestError ? 2 : 1) : 2;
  }
 }

-async function readSessionInventory(dataRoot: string, workspaceId: string): Promise<readonly SessionInventoryRow[]> {
-  const directory = join(dataRoot, "sessions", workspaceId, "sessions");
-  try {
-    const entries = await readdir(directory, { withFileTypes: true });
-    const rows: SessionInventoryRow[] = [];
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
-      try {
-        const source = await readFile(join(directory, entry.name, "session_manifest.yaml"), "utf8");
-        const manifest = parse(source) as Record<string, unknown>;
-        rows.push({
-          id: entry.name,
-          status: typeof manifest.status === "string" ? manifest.status : "open",
-          archived: manifest.archived === true,
-          workspaceRevision: typeof manifest.workspace_revision === "string" ? manifest.workspace_revision : null,
-        });
-      } catch {
-        // fail closed at mutation time by ignoring unreadable manifests from the resumable scan
-      }
-    }
-    return rows;
-  } catch {
-    return [];
-  }
+export interface ProductionWorkspacePreprocessingDeps {
+  config?: AppConfig;
+  catalogRepository?: CatalogRepository;
+  registry?: WorkspaceRegistry;
+  workspaceSecretStore?: WorkspaceSecretStore;
+  runner?: ThtRunner;
 }

-function createProductionService(): WorkspacePreprocessingService {
-  const config = loadConfig(process.env, { surface: "workspace-maintenance" });
-  const registry = new WorkspaceRegistry(config.workspaceRegistry);
-  const workspaceSecretStore = new WorkspaceSecretStore({
+export function createProductionWorkspacePreprocessingService(
+  deps: ProductionWorkspacePreprocessingDeps = {},
+): WorkspacePreprocessingService {
+  const config = deps.config ?? loadConfig(process.env, { surface: "workspace-maintenance" });
+  const catalogRepository = deps.catalogRepository ?? createCatalogRepository(config.catalogDatabase);
+  const registry = deps.registry ?? new WorkspaceRegistry(config.workspaceRegistry);
+  const workspaceSecretStore = deps.workspaceSecretStore ?? new WorkspaceSecretStore({
    root: config.workspaceSecretStoreRoot,
    runtimeRoot: config.workspaceSecretRuntimeRoot,
    installationId: config.workspaceRegistry.installationId,
  });
-  const runner = new ThtRunner({
+  const runner = deps.runner ?? new ThtRunner({
    thtBin: config.thtBin,
    harnessDir: config.harnessDir,
    configPath: process.env.THT_CONFIG ?? "config/tht.yaml",
@@ -232,16 +164,19 @@ function createProductionService(): WorkspacePreprocessingService {
    semanticRuntime: {
      internalQdrantUrl: config.internalQdrantUrl,
      internalEmbeddingUrl: config.internalEmbeddingUrl,
+      internalEmbeddingId: config.internalEmbeddingId,
      internalEmbeddingModel: config.internalEmbeddingModel,
      internalEmbeddingDimensions: config.internalEmbeddingDimensions,
    },
  });
  return new WorkspacePreprocessingService({
    dataRoot: config.dataRoot ?? "/data",
-    embeddingDimensions: config.internalEmbeddingDimensions,
    httpPrivateHostAllowlist: (process.env.THT_EVIDENCE_PRIVATE_HOST_ALLOWLIST ?? "")
      .split(",").map((value) => value.trim()).filter((value) => value.length > 0),
+    catalogRepository,
    acquireActiveRuntime: async (workspaceId) => {
+      const catalogDatabase = await catalogRepository.getByWorkspace(workspaceId);
+      if (!catalogDatabase) throw new Error("workspace database is not configured in the Catalog");
      const active = await renderActiveWorkspaceRuntime({
        workspaceId,
        registry,
@@ -251,6 +186,7 @@ function createProductionService(): WorkspacePreprocessingService {
        dataRoot: config.dataRoot ?? "/data",
        secretRoots: config.workspaceRegistry.secretRoots,
        workspaceSecretStore,
+        catalogDatabase,
        semanticRuntime: {
          internalQdrantUrl: config.internalQdrantUrl,
          internalEmbeddingUrl: config.internalEmbeddingUrl,
@@ -258,38 +194,55 @@ function createProductionService(): WorkspacePreprocessingService {
          internalEmbeddingDimensions: config.internalEmbeddingDimensions,
        },
      });
-      const configLease = await publishDeterministicRuntimeConfigLease({
-        workspaceId,
-        registry,
-        registryConfig: config.workspaceRegistry,
-        harnessDir: config.harnessDir,
-        configPath: process.env.THT_CONFIG ?? "config/tht.yaml",
-        dataRoot: config.dataRoot ?? "/data",
-        secretRoots: config.workspaceRegistry.secretRoots,
-        semanticRuntime: {
-          internalQdrantUrl: config.internalQdrantUrl,
-          internalEmbeddingUrl: config.internalEmbeddingUrl,
-          internalEmbeddingModel: config.internalEmbeddingModel,
-          internalEmbeddingDimensions: config.internalEmbeddingDimensions,
-        },
-        workspaceSecretStore,
-      });
-      return {
-        workspace: active.workspace,
-        workspaceId: active.workspaceId,
-        workspaceRevision: active.workspaceRevision,
-        descriptorBlob: active.descriptorBlob,
-        catalogBlob: active.catalogBlob,
-        configLease,
-      };
+      try {
+        const configLease = await publishDeterministicRuntimeConfigLease({
+          workspaceId,
+          registry,
+          registryConfig: config.workspaceRegistry,
+          harnessDir: config.harnessDir,
+          configPath: process.env.THT_CONFIG ?? "config/tht.yaml",
+          dataRoot: config.dataRoot ?? "/data",
+          secretRoots: config.workspaceRegistry.secretRoots,
+          semanticRuntime: {
+            internalQdrantUrl: config.internalQdrantUrl,
+            internalEmbeddingUrl: config.internalEmbeddingUrl,
+            internalEmbeddingModel: config.internalEmbeddingModel,
+            internalEmbeddingDimensions: config.internalEmbeddingDimensions,
+          },
+          workspaceSecretStore,
+          catalogDatabase,
+        });
+        return {
+          workspace: active.workspace,
+          workspaceId: active.workspaceId,
+          workspaceRevision: active.workspaceRevision,
+          descriptorBlob: active.descriptorBlob,
+          catalogBlob: active.catalogBlob,
+          configLease,
+        };
+      } finally {
+        active.releaseSecrets();
+      }
    },
    runChild: async ({ argv, configPath }) => {
      const configFd = openSync(configPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
      try {
        return await new Promise((resolve) => {
+          const childEnvironment = { ...process.env };
+          for (const name of [
+            "THT_CATALOG_DATABASE_URL",
+            "THT_CATALOG_DB_HOST",
+            "THT_CATALOG_DB_PORT",
+            "THT_CATALOG_DB_NAME",
+            "THT_CATALOG_RUNTIME_USER",
+            "THT_CATALOG_RUNTIME_PASSWORD_FILE",
+            "THT_CATALOG_MIGRATOR_DATABASE_URL",
+            "THT_CATALOG_MIGRATOR_USER",
+            "THT_CATALOG_MIGRATOR_PASSWORD_FILE",
+          ]) delete childEnvironment[name];
          const child = spawn(config.thtBin, argv, {
            cwd: config.harnessDir,
-            env: { ...process.env, ...(config.dataRoot ? { THT_DATA_ROOT: config.dataRoot } : {}) },
+            env: { ...childEnvironment, ...(config.dataRoot ? { THT_DATA_ROOT: config.dataRoot } : {}) },
            stdio: ["ignore", "pipe", "pipe", configFd],
          });
          let stdout = "";
@@ -303,9 +256,8 @@ function createProductionService(): WorkspacePreprocessingService {
        closeSync(configFd);
      }
    },
-    listSessions: async (workspaceId) => await readSessionInventory(config.dataRoot ?? "/data", workspaceId),
    semanticPreflight: async (workspace) => {
-      const result = await runner.qdrantEnsure(workspace, 30);
+      const result = await runner.qdrantEnsure(workspace, 30, "self_heal");
      return result.ok ? { ok: true as const } : { ok: false as const, code: result.code ?? "workspace_not_activatable" };
    },
    evidencePreflight: async (workspace) => {
@@ -330,7 +282,11 @@ if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).
    writeStdout: (value) => { stdout.push(value); },
    writeStderr: (value) => { stderr.push(value); },
  };
-  const exitCode = await runWorkspaceMaintenanceCli(process.argv, createProductionService(), io);
+  const exitCode = await runWorkspaceMaintenanceCli(
+    process.argv,
+    createProductionWorkspacePreprocessingService(),
+    io,
+  );
  process.stdout.write(stdout.join(""));
  if (stderr.length > 0) process.stderr.write(stderr.join("").slice(0, 64 * 1024));
  process.exit(exitCode);
@@ -90,6 +90,7 @@ export function resolveBinding(
 ): ResolvedBinding {
  requireSupportedDescriptor(workspace);
  const descriptor = validateWorkspaceDescriptor(workspace);
+  if (!descriptor.dwh) throw new Error("workspace database is not bound in the descriptor");
  const contract = buildInstallationContract(descriptor);
  const variables = contract.variables.filter((variable) => variable.role === role);
  const transportVariable = variables.find((variable) => variable.suffix === "TRANSPORT");
@@ -165,7 +166,9 @@ export function resolveRuntimeBindings(
  const descriptor = validateWorkspaceDescriptor(workspace);

  return {
-    dwh: resolveBinding(descriptor, "DWH", env, secretRoots),
+    dwh: descriptor.dwh
+      ? resolveBinding(descriptor, "DWH", env, secretRoots)
+      : { transport: "postgres_direct", values: {}, missing: [] },
    evidence: resolveEvidenceBinding(descriptor, env, secretRoots),
  };
 }
@@ -155,7 +155,9 @@ export function buildInstallationContract(workspace: WorkspaceDescriptor): Insta
    workspaceId: descriptor.workspace.id,
    namespace,
    variables: [
-      ...connectorVariables(namespace, descriptor.dwh.supported_transports),
+      ...(descriptor.dwh
+        ? connectorVariables(namespace, descriptor.dwh.supported_transports)
+        : []),
      ...evidenceVariables(namespace, descriptor),
    ],
  };
@@ -12,6 +12,7 @@ import {
 import type { WorkspaceErrorCode } from "./types.js";
 import type { SemanticRuntimeConfig } from "./runtime-renderer.js";
 import type { AuthDiagnostics } from "../auth/diagnostics.js";
+import { workspaceVectorCollections } from "./vector-collections.js";

 export interface Diagnostic {
  level: "error" | "warning" | "info";
@@ -447,6 +448,9 @@ async function diagnoseValidatedWorkspace(

  let activatable = true;
  if (!skipDwh) {
+    if (!descriptor.dwh) {
+      return { activatable: false, diagnostics: [diagnosticError("binding_missing", "dwh")] };
+    }
    const dwhTimeout = boundedTimeout(descriptor.dwh.timeout_ms, timeoutMs);
    const dwhValues = bindings.dwh.values;
    const dwhField = (suffix: string) => bindingName(descriptor, suffix);
@@ -514,20 +518,18 @@ async function diagnoseValidatedWorkspace(
  }

  try {
-    const vector = await withTimeout(timeoutMs, (signal) => adapters.inspectQdrant({
-      baseUrl: semanticRuntime.internalQdrantUrl,
-      collection: descriptor.workspace.id,
-      timeoutMs,
-      signal,
-    }));
-    const expected = {
-      collection: descriptor.workspace.id,
-      dimensions: semanticRuntime.internalEmbeddingDimensions,
-      distance: "cosine",
-    };
-    if (vector.collection !== expected.collection
-      || vector.dimensions !== expected.dimensions
-      || vector.distance !== expected.distance) {
+    const expectedCollections = Object.values(workspaceVectorCollections(descriptor.workspace.id));
+    const vectors = await Promise.all(expectedCollections.map(async (collection) =>
+      await withTimeout(timeoutMs, (signal) => adapters.inspectQdrant({
+        baseUrl: semanticRuntime.internalQdrantUrl,
+        collection,
+        timeoutMs,
+        signal,
+      }))));
+    if (vectors.some((vector, index) =>
+      vector.collection !== expectedCollections[index]
+      || vector.dimensions !== semanticRuntime.internalEmbeddingDimensions
+      || vector.distance !== "cosine")) {
      diagnostics.push(diagnosticError("semantic_index_incompatible"));
      activatable = false;
    }
@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { normalize } from "node:path";

 export interface CanonicalEffectiveConfig {
-  schemaVersion: 2;
+  schemaVersion: 3;
  dwh: CanonicalDwhConfig;
  vector: CanonicalVectorConfig;
  embedding: CanonicalEmbeddingConfig;
@@ -21,7 +21,10 @@ export interface CanonicalDwhConfig {
 }

 export interface CanonicalVectorConfig {
-  collection: string;
+  collections: {
+    reference: string;
+    memory: string;
+  };
  dimensions: number;
  distance: string;
 }
@@ -120,7 +123,10 @@ function buildVectorConfig(rendered: Record<string, unknown>): CanonicalVectorCo
  if (!vector) {
    throw new TypeError("effective config is missing vector resources");
  }
-  const collection = requireString(vector, "collection");
+  const collections = asRecord(vector.collections);
+  if (!collections) {
+    throw new TypeError("effective config is missing vector collections");
+  }
  const semanticIndex = asRecord(rendered.semantic_index);
  const vectorStore = semanticIndex ? asRecord(semanticIndex.vector_store) : undefined;
  const dimensions = vectorStore
@@ -129,7 +135,14 @@ function buildVectorConfig(rendered: Record<string, unknown>): CanonicalVectorCo
  const distance = vectorStore
    ? requireString(vectorStore, "distance")
    : (optionalString(vector, "distance") ?? "cosine");
-  return { collection, dimensions, distance };
+  return {
+    collections: {
+      reference: requireString(collections, "reference"),
+      memory: requireString(collections, "memory"),
+    },
+    dimensions,
+    distance,
+  };
 }

 function buildEmbeddingConfig(rendered: Record<string, unknown>): CanonicalEmbeddingConfig {
@@ -169,7 +182,7 @@ export function buildCanonicalEffectiveConfig(renderedConfig: unknown): Canonica
    throw new TypeError("effective config requires a rendered configuration object");
  }
  return {
-    schemaVersion: 2,
+    schemaVersion: 3,
    dwh: buildDwhConfig(rendered),
    vector: buildVectorConfig(rendered),
    embedding: buildEmbeddingConfig(rendered),
@@ -220,3 +233,20 @@ export function configFingerprint(renderedConfig: unknown): string {
 export function inputFingerprint(workspaceId: string, renderedConfig: unknown): string {
  return sha256(effectiveConfigIdentity(workspaceId, renderedConfig));
 }
+
+/**
+ * Fingerprint every non-Catalog input consumed by complete preprocessing. The immutable Git
+ * revision covers the workspace descriptor and its revision-pinned Evidence tree; the effective
+ * configuration identity covers the Catalog-derived DWH binding and semantic runtime contract.
+ */
+export function preprocessingInputFingerprint(
+  workspaceId: string,
+  workspaceRevision: string,
+  renderedConfig: unknown,
+): string {
+  return sha256(JSON.stringify({
+    workspaceId,
+    workspaceRevision,
+    effectiveConfigIdentity: effectiveConfigIdentity(workspaceId, renderedConfig),
+  }));
+}
@@ -171,6 +171,14 @@ export async function continueEvidencePreprocessing(
  const policy = evidencePolicy(request.evidence, request.httpPrivateHostAllowlist);
  if (policy) return { ...policy, ...jobResult(request.job) };
  if (!request.job.completedStages.includes("evidence")) {
+    const preflight = await deps.evidencePreflight();
+    if (!preflight.ok) {
+      return {
+        status: "failed",
+        code: preflight.code,
+        ...jobResult(request.job),
+      };
+    }
    return await runEvidenceStage(request, deps);
  }
  return { status: "unchanged", code: "ok", ...jobResult(request.job) };
@@ -1,22 +1,19 @@
-import { createHash, randomBytes } from "node:crypto";
-import { readdirSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { renameSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import {
  continueEvidencePreprocessing,
-  preprocessEvidence as runEvidencePreprocessing,
  type EvidencePreprocessingDependencies,
  type EvidencePreprocessingOutcome,
 } from "./evidence/preprocessing.js";
 import type { WorkspaceDescriptor } from "./schema.js";
 import {
  PreprocessingStateStore,
-  type FkReviewRecord,
  type PreprocessingJobState,
-  type SessionInventoryRow,
 } from "./preprocessing-state.js";
 import type { DeterministicRuntimeConfigLease } from "./runtime-config-lease.js";
-import { readAnnotationsSync } from "./annotations-sync.js";
-import { reconcileCollection } from "./qdrant-collection.js";
+import { buildCatalogMetadataSnapshot } from "../catalog/metadata-snapshot.js";
+import type { CatalogRepository } from "../catalog/types.js";

 export interface WorkspaceOperationResult {
  schemaVersion: 1;
@@ -27,7 +24,7 @@ export interface WorkspaceOperationResult {
    | "preprocessing_resume_mismatch" | "manual_review_required"
    | "evidence_materialization_required" | "effective_config_mismatch"
    | "semantic_index_incompatible" | "annotation_invalid"
-    | "egress_policy_refused";
+    | "egress_policy_refused" | "catalog_not_ready" | "preprocessing_clear_failed";
  workspaceId: string;
  workspaceRevision: string;
  descriptorBlob: string;
@@ -69,7 +66,6 @@ export interface WorkspacePreprocessingServiceDeps {
  dataRoot: string;
  acquireActiveRuntime(workspaceId: string): Promise<ActiveRuntime>;
  runChild(request: ChildProcessRequest): Promise<ChildProcessResult>;
-  listSessions(workspaceId: string): Promise<readonly SessionInventoryRow[]>;
  semanticPreflight(workspace: WorkspaceDescriptor): Promise<
    { ok: true } | { ok: false; code: "workspace_not_activatable" | "semantic_index_incompatible" }
  >;
@@ -77,7 +73,7 @@ export interface WorkspacePreprocessingServiceDeps {
    { ok: true } | { ok: false; code: "workspace_not_activatable" | "semantic_index_incompatible" }
  >;
  httpPrivateHostAllowlist?: readonly string[];
-  embeddingDimensions?: number;
+  catalogRepository?: CatalogRepository;
 }

 interface RunScope {
@@ -86,10 +82,6 @@ interface RunScope {
  job: PreprocessingJobState;
 }

-function digest(value: string | Buffer): string {
-  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
-}
-
 function baseResult(
  runtime: ActiveRuntime,
  operation: string,
@@ -116,41 +108,6 @@ function baseResult(
 export class WorkspacePreprocessingService {
  constructor(private readonly deps: WorkspacePreprocessingServiceDeps) {}

-
-  async vectorInspect(options: { workspaceId: string }): Promise<WorkspaceOperationResult> {
-    const runtime = await this.deps.acquireActiveRuntime(options.workspaceId);
-    const collection = runtime.workspace.workspace.id;
-    const res = await fetch(`${runtime.configLease.semanticQdrantUrl}/collections/${encodeURIComponent(collection)}`, { method: "GET" });
-    if (!res.ok) return baseResult(runtime, "vector inspect", "failed", "semantic_index_incompatible", { warnings: ["collection unavailable"] });
-    const body = await res.json() as any;
-    const info = body?.result;
-    const vectors = info?.config?.params?.vectors;
-    return baseResult(runtime, "vector inspect", "succeeded", "ok", {
-      counts: { dimensions: vectors?.size ?? 0 },
-      warnings: [`collection=${collection} distance=${vectors?.distance ?? "unknown"}`],
-    });
-  }
-
-  async vectorRebuild(options: { workspaceId: string; collection?: string; confirm?: string; destroy?: boolean }): Promise<WorkspaceOperationResult> {
-    const runtime = await this.deps.acquireActiveRuntime(options.workspaceId);
-    const collection = runtime.workspace.workspace.id;
-    if (options.collection !== collection || options.confirm !== collection || options.destroy !== true) {
-      return baseResult(runtime, "vector rebuild", "failed", "semantic_index_incompatible", { warnings: ["rebuild requires exact confirmation and --destroy"] });
-    }
-    const q = `${runtime.configLease.semanticQdrantUrl}/collections/${encodeURIComponent(collection)}`;
-    const del = await fetch(q, { method: "DELETE" });
-    if (!del.ok && del.status !== 404) return baseResult(runtime, "vector rebuild", "failed", "semantic_index_incompatible", { warnings: ["collection delete failed"] });
-    // Recreate the complete contract (dimensions + distance + the 8 required keyword indexes).
-    const recreated = await reconcileCollection({
-      baseUrl: runtime.configLease.semanticQdrantUrl,
-      collection,
-      dimensions: this.deps.embeddingDimensions ?? 1024,
-      distance: "cosine",
-      mode: "self_heal",
-    });
-    if (!recreated.ok) return baseResult(runtime, "vector rebuild", "failed", "semantic_index_incompatible", { warnings: ["collection recreate failed"] });
-    return baseResult(runtime, "vector rebuild", "succeeded", "ok", { warnings: [`recreated collection=${collection}`] });
-  }
  async inspect(options: { workspaceId: string }): Promise<WorkspaceOperationResult> {
    try {
      const runtime = await this.deps.acquireActiveRuntime(options.workspaceId);
@@ -175,227 +132,151 @@ export class WorkspacePreprocessingService {
    }
  }

-  async preprocessDwh(options: { workspaceId: string; resumeRunId?: string }): Promise<WorkspaceOperationResult> {
-    const scope = await this.startRun(options.workspaceId, "preprocess dwh", options.resumeRunId);
-    if (scope.job.completedStages.includes("dwh")) {
-      return baseResult(scope.runtime, "preprocess dwh", "unchanged", "ok", {
-        runId: scope.job.runId,
-        childRuns: scope.job.childRuns,
-        completedStages: [...scope.job.completedStages],
-      });
+  async run(options: { workspaceId: string }): Promise<WorkspaceOperationResult> {
+    if (!this.deps.catalogRepository) {
+      const runtime = await this.deps.acquireActiveRuntime(options.workspaceId);
+      return baseResult(runtime, "preprocess run", "failed", "catalog_not_ready");
    }
-    const payload = await this.runJsonStage(scope.runtime, [
-      "preprocess", "dwh", "--steps", "introspect,lsh",
-      ...(scope.job.childRuns.dwh ? ["--resume", scope.job.childRuns.dwh] : []),
-      "--json", "-c", "/dev/fd/3",
-    ]);
-    const childRun = this.requireRunId(payload.run_id);
-    scope.job.childRuns.dwh = childRun;
-    if (!scope.job.completedStages.includes("dwh")) scope.job.completedStages.push("dwh");
-    this.state(scope.runtime.workspaceId).writeJob(scope.job);
-    return baseResult(scope.runtime, "preprocess dwh", "succeeded", "ok", {
-      runId: scope.job.runId,
-      childRuns: { ...scope.job.childRuns },
-      completedStages: [...scope.job.completedStages],
-    });
+    return await this.runFromCatalog(options);
  }

-  async suggestFks(options: {
-    workspaceId: string;
-    fromSql?: ReadonlyArray<{ name: string; sql: string }>;
-    assume?: readonly string[];
-    resumeRunId?: string;
-  }): Promise<WorkspaceOperationResult> {
-    const scope = await this.startRun(options.workspaceId, "schema suggest-fks", options.resumeRunId);
-    return await this.runSuggestStage(scope, options.fromSql ?? [], options.assume ?? []);
-  }
-
-  async checkSchema(options: {
-    workspaceId: string;
-    annotationsYaml?: string;
-    reviewedCandidatesDigest?: string;
-  }): Promise<WorkspaceOperationResult> {
+  async clear(options: { workspaceId: string }): Promise<WorkspaceOperationResult> {
    const runtime = await this.deps.acquireActiveRuntime(options.workspaceId);
-    const state = this.state(runtime.workspaceId);
-    if ((options.annotationsYaml === undefined) !== (options.reviewedCandidatesDigest === undefined)) {
-      return baseResult(runtime, "schema check", "failed", "annotation_invalid");
+    const repository = this.deps.catalogRepository;
+    if (!repository) return baseResult(runtime, "preprocess clear", "failed", "catalog_not_ready");
+    const cleared = await repository.clearPreprocessing(runtime.workspaceId);
+    if (cleared.kind !== "cleared") {
+      return baseResult(
+        runtime,
+        "preprocess clear",
+        "failed",
+        cleared.kind === "already_running" ? "preprocessing_conflict" : "catalog_not_ready",
+      );
    }
-    if (options.reviewedCandidatesDigest === undefined) {
-      const payload = await this.runJsonStage(runtime, ["schema", "check", "--json", "-c", "/dev/fd/3"]);
-      return baseResult(runtime, "schema check", Number(payload.orphan_count ?? 0) === 0 ? "succeeded" : "failed", Number(payload.orphan_count ?? 0) === 0 ? "ok" : "annotation_invalid");
-    }
-    const reviewedCandidatesDigest = options.reviewedCandidatesDigest;
-    const runId = this.findRunIdByCandidateDigest(state, reviewedCandidatesDigest);
-    if (!runId) return baseResult(runtime, "schema check", "failed", "annotation_invalid");
-    const request = await this.withStagedInputs(runtime.workspaceId, [
-      { flag: "--annotations", name: "annotations.yaml", contents: options.annotationsYaml! },
-    ], async (argv) => await this.runJsonStage(runtime, [
-      "schema", "check", ...argv,
-      "--reviewed-candidates", reviewedCandidatesDigest,
-      "--json", "-c", "/dev/fd/3",
-    ]));
-    if (request.reviewed_candidates_digest !== reviewedCandidatesDigest || typeof request.annotations_digest !== "string") {
-      return baseResult(runtime, "schema check", "failed", "annotation_invalid", { runId });
-    }
-    // P5 supersedes the host-file FK review: schema check is read-only validation and never
-    // records a review. Only `schema accept` records a human review for the curated Git blob.
-    return baseResult(runtime, "schema check", "succeeded", "ok", { runId });
-  }
-
-  async acceptSchema(options: { workspaceId: string; runId: string; yes?: boolean }): Promise<WorkspaceOperationResult> {
-    const runtime = await this.deps.acquireActiveRuntime(options.workspaceId);
-    const state = this.state(runtime.workspaceId);
-    if (options.yes !== true) {
-      return baseResult(runtime, "schema accept", "failed", "annotation_invalid", {
-        runId: options.runId,
-        warnings: ["accept requires --yes"],
-      });
-    }
-    if (!/^[0-9a-f]{32}$/.test(options.runId)) {
-      return baseResult(runtime, "schema accept", "failed", "annotation_invalid");
-    }
-    const candidate = state.readFkCandidates(options.runId);
-    if (candidate === undefined) {
-      return baseResult(runtime, "schema accept", "failed", "annotation_invalid", {
-        runId: options.runId,
-        warnings: ["candidate run is unavailable"],
-      });
-    }
-    const synced = readAnnotationsSync(this.deps.dataRoot, runtime.workspaceId, runtime.workspaceRevision);
-    if (synced === undefined || synced.contents.toString("utf8").trim() === "") {
-      return baseResult(runtime, "schema accept", "failed", "annotation_invalid", {
-        runId: options.runId,
-        warnings: ["curated annotations are not synchronized"],
-      });
-    }
-    // The harness parser validates the curated blob against the physical schema; the recorded
-    // candidate digest must round-trip and the blob digest must match the synced destination.
-    const payload = await this.runJsonStage(runtime, [
-      "schema", "check", "--reviewed-candidates", candidate.digest, "--json", "-c", "/dev/fd/3",
-    ]);
-    if (payload.annotations_digest !== synced.contentDigest
-      || payload.reviewed_candidates_digest !== candidate.digest
-      || Number(payload.orphan_count ?? 0) !== 0) {
-      return baseResult(runtime, "schema accept", "failed", "annotation_invalid", { runId: options.runId });
-    }
-    const review = state.writeFkReview(options.runId, {
-      reviewedCandidatesDigest: candidate.digest,
-      annotationsDigest: synced.contentDigest,
-      workspaceRevision: runtime.workspaceRevision,
-      blobId: synced.blobId,
+    const result = await this.deps.runChild({
+      argv: ["preprocess", "clear", "--json", "-c", "/dev/fd/3"],
+      configPath: runtime.configLease.path,
    });
-    const job = state.readJob(options.runId);
-    job.reviewDigest = review.digest;
-    if (!job.completedStages.includes("fk_review")) job.completedStages.push("fk_review");
-    state.writeJob(job);
-    return baseResult(runtime, "schema accept", "succeeded", "ok", {
-      runId: options.runId,
-      completedStages: [...job.completedStages],
-      artifactIdentities: [
-        { kind: "fk_review", digest: review.digest },
-        { kind: "annotations", digest: synced.contentDigest },
-      ],
+    if (result.exitCode !== 0) {
+      return baseResult(runtime, "preprocess clear", "failed", "preprocessing_clear_failed");
+    }
+    const payload = JSON.parse(result.stdout) as Record<string, unknown>;
+    return baseResult(runtime, "preprocess clear", "succeeded", "ok", {
+      counts: this.numberRecord(payload.counts),
    });
  }

-  async indexSchema(options: { workspaceId: string; resumeRunId?: string }): Promise<WorkspaceOperationResult> {
-    const scope = await this.startRun(options.workspaceId, "index-schema", options.resumeRunId);
-    const semantic = await this.deps.semanticPreflight(scope.runtime.workspace);
-    if (!semantic.ok) return baseResult(scope.runtime, "index-schema", "failed", semantic.code, { runId: scope.job.runId });
-    if (scope.job.completedStages.includes("schema_index")) {
-      return baseResult(scope.runtime, "index-schema", "unchanged", "ok", {
-        runId: scope.job.runId,
-        completedStages: [...scope.job.completedStages],
-      });
+  private async runFromCatalog(options: { workspaceId: string }): Promise<WorkspaceOperationResult> {
+    const scope = await this.startRun(options.workspaceId);
+    const repository = this.deps.catalogRepository!;
+    const fingerprint = scope.runtime.configLease.inputFingerprint;
+    const started = await repository.beginPreprocessing(scope.runtime.workspaceId, fingerprint);
+    if (started.kind !== "started") {
+      scope.job.status = "failed";
+      scope.state.writeJob(scope.job);
+      return baseResult(
+        scope.runtime,
+        "preprocess run",
+        "failed",
+        started.kind === "already_running" ? "preprocessing_conflict" : "catalog_not_ready",
+        { warnings: [`catalog=${started.kind}`] },
+      );
    }
-    const payload = await this.runJsonStage(scope.runtime, ["vector", "index-schema", "--json", "-c", "/dev/fd/3"]);
-    const counts = this.numberRecord(payload.counts);
-    scope.job.completedStages.push("schema_index");
-    this.state(scope.runtime.workspaceId).writeJob(scope.job);
-    return baseResult(scope.runtime, "index-schema", "succeeded", "ok", {
-      runId: scope.job.runId,
-      completedStages: [...scope.job.completedStages],
-      counts,
-    });
-  }

-  async preprocessEvidence(options: { workspaceId: string; dryRun?: boolean; resumeRunId?: string }): Promise<WorkspaceOperationResult> {
-    const scope = await this.startRun(options.workspaceId, "preprocess evidence", options.resumeRunId);
-    const outcome = await runEvidencePreprocessing(
-      {
-        evidence: scope.runtime.workspace.evidence,
-        job: scope.job,
-        dryRun: options.dryRun,
-        httpPrivateHostAllowlist: this.deps.httpPrivateHostAllowlist,
-      },
-      this.evidenceDependencies(scope),
-    );
-    return this.evidenceResult(scope, "preprocess evidence", outcome);
-  }
-
-  async run(options: { workspaceId: string; resumeRunId?: string }): Promise<WorkspaceOperationResult> {
-    const scope = await this.startRun(options.workspaceId, "preprocess run", options.resumeRunId);
-    if (!scope.job.completedStages.includes("dwh")) {
-      const payload = await this.runJsonStage(scope.runtime, [
-        "preprocess", "dwh", "--steps", "introspect,lsh",
-        ...(scope.job.childRuns.dwh ? ["--resume", scope.job.childRuns.dwh] : []),
-        "--json", "-c", "/dev/fd/3",
-      ]);
-      scope.job.childRuns.dwh = this.requireRunId(payload.run_id);
-      scope.job.completedStages.push("dwh");
-      this.state(scope.runtime.workspaceId).writeJob(scope.job);
-    }
-    if (!scope.job.completedStages.includes("fk_suggest")) {
-      const suggest = await this.runSuggestStage(scope, [], []);
-      if (suggest.code === "manual_review_required") return suggest;
-    }
-    const candidate = this.state(scope.runtime.workspaceId).readFkCandidates(scope.job.runId);
-    if (candidate && !scope.job.completedStages.includes("fk_review")) {
-      // P5: continuation requires a review accepted for this candidate whose accepted blob digest
-      // equals the current revision's synced annotations. A revision change (or a missing curated
-      // blob) therefore records a new review checkpoint instead of silently reusing the old one.
-      const accepted = this.findAcceptedReviewForDigest(scope.runtime.workspaceId, candidate.digest);
-      const currentDigest = this.currentAnnotationsDigest(scope.runtime);
-      if (accepted === undefined || currentDigest === undefined || accepted.annotationsDigest !== currentDigest) {
-        return baseResult(scope.runtime, "preprocess run", "blocked", "manual_review_required", {
-          runId: scope.job.runId,
-          childRuns: { ...scope.job.childRuns },
-          completedStages: [...scope.job.completedStages],
-          artifactIdentities: [{ kind: "fk_candidates", digest: candidate.digest }],
-        });
+    const revision = started.database.metadataContentRevision;
+    let finished = false;
+    let failureCode = "catalog_snapshot_failed";
+    try {
+      const snapshot = await buildCatalogMetadataSnapshot(
+        repository,
+        scope.runtime.workspaceId,
+        revision,
+      );
+      const snapshotPath = this.publishCatalogSnapshot(
+        scope.runtime.workspaceId,
+        JSON.stringify(snapshot),
+      );
+      this.completeStages(scope, "catalog_snapshot");
+      const semantic = await this.deps.semanticPreflight(scope.runtime.workspace);
+      if (!semantic.ok) {
+        await repository.finishPreprocessing(
+          scope.runtime.workspaceId,
+          revision,
+          fingerprint,
+          { status: "failed", errorCode: semantic.code },
+        );
+        scope.job.status = "failed";
+        scope.state.writeJob(scope.job);
+        finished = true;
+        return baseResult(scope.runtime, "preprocess run", "failed", semantic.code);
      }
-      scope.job.reviewDigest = accepted.reviewedCandidatesDigest;
-      scope.job.completedStages.push("fk_review");
-      this.state(scope.runtime.workspaceId).writeJob(scope.job);
+
+      failureCode = "schema_index_failed";
+      const payload = await this.runJsonStage(scope.runtime, [
+        "preprocess",
+        "catalog",
+        "--catalog-metadata",
+        snapshotPath,
+        "--json",
+        "-c",
+        "/dev/fd/3",
+      ]);
+      this.completeStages(scope, "catalog_metadata", "lsh", "schema_index");
+      failureCode = "evidence_preprocessing_failed";
+      const outcome = await continueEvidencePreprocessing(
+        {
+          evidence: scope.runtime.workspace.evidence,
+          job: scope.job,
+          httpPrivateHostAllowlist: this.deps.httpPrivateHostAllowlist,
+          priorCounts: this.numberRecord(payload.counts),
+        },
+        this.evidenceDependencies(scope),
+      );
+      if (!["succeeded", "unchanged"].includes(outcome.status)) {
+        await repository.finishPreprocessing(
+          scope.runtime.workspaceId,
+          revision,
+          fingerprint,
+          { status: "failed", errorCode: outcome.code },
+        );
+        scope.job.status = "failed";
+        scope.state.writeJob(scope.job);
+        finished = true;
+        return this.evidenceResult(scope, outcome);
+      }
+      // Evidence has been published. The only remaining operation is the atomic Catalog commit.
+      this.completeStages(scope, "evidence");
+      const completed = await repository.finishPreprocessing(
+        scope.runtime.workspaceId,
+        revision,
+        fingerprint,
+        { status: "succeeded" },
+      );
+      if (!completed) throw new Error("catalog preprocessing completion lost its lease");
+      scope.job.status = "succeeded";
+      scope.state.writeJob(scope.job);
+      finished = true;
+      return this.evidenceResult(scope, outcome);
+    } catch (error) {
+      if (!finished) {
+        await repository.finishPreprocessing(
+          scope.runtime.workspaceId,
+          revision,
+          fingerprint,
+          { status: "failed", errorCode: failureCode },
+        );
+      }
+      scope.job.status = "failed";
+      scope.state.writeJob(scope.job);
+      throw error;
    }
-    const semantic = await this.deps.semanticPreflight(scope.runtime.workspace);
-    if (!semantic.ok) return baseResult(scope.runtime, "preprocess run", "failed", semantic.code, { runId: scope.job.runId });
-    let schemaCounts: Record<string, number> | undefined;
-    if (!scope.job.completedStages.includes("schema_index")) {
-      const payload = await this.runJsonStage(scope.runtime, ["vector", "index-schema", "--json", "-c", "/dev/fd/3"]);
-      scope.job.completedStages.push("schema_index");
-      this.state(scope.runtime.workspaceId).writeJob(scope.job);
-      schemaCounts = this.numberRecord(payload.counts);
-    }
-    const outcome = await continueEvidencePreprocessing(
-      {
-        evidence: scope.runtime.workspace.evidence,
-        job: scope.job,
-        httpPrivateHostAllowlist: this.deps.httpPrivateHostAllowlist,
-        priorCounts: schemaCounts,
-      },
-      this.evidenceDependencies(scope),
-    );
-    return this.evidenceResult(scope, "preprocess run", outcome);
  }

-  private async startRun(workspaceId: string, operation: string, resumeRunId?: string): Promise<RunScope> {
+  private async startRun(workspaceId: string): Promise<RunScope> {
    const runtime = await this.deps.acquireActiveRuntime(workspaceId);
    const state = this.state(runtime.workspaceId);
-    await state.assertSessionInventoryCompatible(runtime.workspaceRevision, await this.deps.listSessions(runtime.workspaceId));
    const job = await state.beginJob({
-      operation,
-      runId: resumeRunId,
+      operation: "preprocess run",
      workspaceRevision: runtime.workspaceRevision,
      descriptorBlob: runtime.descriptorBlob,
      catalogBlob: runtime.catalogBlob,
@@ -411,6 +292,28 @@ export class WorkspacePreprocessingService {
    return new PreprocessingStateStore({ dataRoot: this.deps.dataRoot, workspaceId });
  }

+  private completeStages(scope: RunScope, ...stages: string[]): void {
+    for (const stage of stages) {
+      if (!scope.job.completedStages.includes(stage)) scope.job.completedStages.push(stage);
+    }
+    scope.state.writeJob(scope.job);
+  }
+
+  private publishCatalogSnapshot(workspaceId: string, contents: string): string {
+    const root = join(this.deps.dataRoot, "sessions", workspaceId, "preprocessing");
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const target = join(root, "catalog-metadata.json");
+    const staging = join(root, `.catalog-metadata-${randomBytes(6).toString("hex")}.json`);
+    try {
+      writeFileSync(staging, contents, { encoding: "utf8", flag: "wx", mode: 0o600 });
+      renameSync(staging, target);
+      return target;
+    } catch (error) {
+      rmSync(staging, { force: true });
+      throw error;
+    }
+  }
+
  private evidenceDependencies(scope: RunScope): EvidencePreprocessingDependencies {
    return {
      runStage: async (argv) => await this.runJsonStage(scope.runtime, argv),
@@ -423,50 +326,10 @@ export class WorkspacePreprocessingService {

  private evidenceResult(
    scope: RunScope,
-    operation: "preprocess evidence" | "preprocess run",
    outcome: EvidencePreprocessingOutcome,
  ): WorkspaceOperationResult {
    const { status, code, ...extra } = outcome;
-    return baseResult(scope.runtime, operation, status, code, extra);
-  }
-
-  private async runSuggestStage(
-    scope: RunScope,
-    fromSql: ReadonlyArray<{ name: string; sql: string }>,
-    assume: readonly string[],
-  ): Promise<WorkspaceOperationResult> {
-    const payload = await this.withStagedInputs(scope.runtime.workspaceId, fromSql.map((entry) => ({
-      flag: "--from-sql",
-      name: entry.name,
-      contents: entry.sql,
-    })), async (stagedArgv) => await this.runJsonStage(scope.runtime, [
-      "schema", "suggest-fks", ...stagedArgv,
-      ...assume.flatMap((value) => ["--assume", value]),
-      "--json", "-c", "/dev/fd/3",
-    ]));
-    const candidateCount = Number(payload.candidate_count ?? 0);
-    const candidateYaml = typeof payload.candidate_yaml === "string" ? payload.candidate_yaml : "";
-    let artifactIdentities: Array<{ kind: string; digest: string }> | undefined;
-    if (candidateCount > 0) {
-      const persisted = this.state(scope.runtime.workspaceId).writeFkCandidates(scope.job.runId, candidateYaml);
-      scope.job.candidateDigest = persisted.digest;
-      artifactIdentities = [{ kind: "fk_candidates", digest: persisted.digest }];
-    }
-    if (!scope.job.completedStages.includes("fk_suggest")) scope.job.completedStages.push("fk_suggest");
-    this.state(scope.runtime.workspaceId).writeJob(scope.job);
-    const resultExtra = {
-      runId: scope.job.runId,
-      completedStages: [...scope.job.completedStages],
-      ...(artifactIdentities ? { artifactIdentities } : {}),
-      ...(candidateYaml.length > 0 ? { suggestedFksYaml: candidateYaml } : {}),
-    };
-    if (candidateCount > 0) {
-      return baseResult(scope.runtime, scope.job.operation === "preprocess run" ? "preprocess run" : "schema suggest-fks", "blocked", "manual_review_required", {
-        ...resultExtra,
-        childRuns: { ...scope.job.childRuns },
-      });
-    }
-    return baseResult(scope.runtime, scope.job.operation === "preprocess run" ? "preprocess run" : "schema suggest-fks", "succeeded", "ok", resultExtra);
+    return baseResult(scope.runtime, "preprocess run", status, code, extra);
  }

  private async runJsonStage(runtime: ActiveRuntime, argv: string[]): Promise<Record<string, unknown>> {
@@ -485,54 +348,5 @@ export class WorkspacePreprocessingService {
    return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, nested]) => [key, Number(nested)]));
  }

-  private async withStagedInputs<T>(
-    workspaceId: string,
-    inputs: ReadonlyArray<{ flag: string; name: string; contents: string }>,
-    fn: (argv: string[]) => Promise<T>,
-  ): Promise<T> {
-    if (inputs.length === 0) return await fn([]);
-    const root = join(this.deps.dataRoot, "sessions", workspaceId, "preprocessing", `.stage-${randomBytes(6).toString("hex")}`);
-    mkdirSync(root, { recursive: true, mode: 0o700 });
-    const argv: string[] = [];
-    const paths: string[] = [];
-    try {
-      for (const input of inputs) {
-        const path = join(root, input.name);
-        writeFileSync(path, input.contents, { encoding: "utf8", flag: "wx", mode: 0o600 });
-        paths.push(path);
-        argv.push(input.flag, path);
-      }
-      return await fn(argv);
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  }
-
-  private currentAnnotationsDigest(runtime: ActiveRuntime): string | undefined {
-    return readAnnotationsSync(this.deps.dataRoot, runtime.workspaceId, runtime.workspaceRevision)?.contentDigest;
-  }
-
-  private findAcceptedReviewForDigest(
-    workspaceId: string,
-    digestValue: string,
-  ): FkReviewRecord | undefined {
-    const state = this.state(workspaceId);
-    for (const entry of readdirSync(state.fkReviewsDirectory(), { withFileTypes: true })) {
-      if (!entry.isFile() || entry.isSymbolicLink() || !/^[0-9a-f]{32}\.json$/.test(entry.name)) continue;
-      const runId = entry.name.slice(0, -".json".length);
-      const review = state.readFkReview(runId);
-      if (review && review.reviewedCandidatesDigest === digestValue) return review;
-    }
-    return undefined;
-  }
-
-  private findRunIdByCandidateDigest(state: PreprocessingStateStore, digestValue: string): string | undefined {
-    for (const entry of readdirSync(state.fkCandidatesDirectory(), { withFileTypes: true })) {
-      if (!entry.isFile() || entry.isSymbolicLink() || !/^[0-9a-f]{32}\.yaml$/.test(entry.name)) continue;
-      const runId = entry.name.slice(0, -".yaml".length);
-      if (state.readFkCandidates(runId)?.digest === digestValue) return runId;
-    }
-    return undefined;
-  }

 }
@@ -198,6 +198,7 @@ export class PreprocessingStateStore {
  runtimeConfigDirectory(): string { return join(this.root, "runtime-config"); }
  runtimeConfigManifestDirectory(): string { return join(this.root, "runtime-config-manifests"); }
  jobsDirectory(): string { return join(this.root, "jobs"); }
+  latestJobPath(): string { return join(this.root, "latest-job.json"); }
  fkCandidatesDirectory(): string { return join(this.root, "fk-candidates"); }
  fkReviewsDirectory(): string { return join(this.root, "fk-reviews"); }
  jobPath(runId: string): string { return join(this.jobsDirectory(), `${validateRunId(runId)}.json`); }
@@ -289,7 +290,7 @@ export class PreprocessingStateStore {
          "Workspace preprocessing resume no longer matches the pinned revision",
        );
      }
-      return existing;
+      return this.writeJob(existing);
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
        if (error instanceof PreprocessingStateError) throw error;
@@ -318,19 +319,30 @@ export class PreprocessingStateStore {
      childRuns: {},
      status: "active",
    };
-    writeAtomicFile(path, `${JSON.stringify(job)}
-`, 0o600);
-    return job;
+    return this.writeJob(job);
  }

  readJob(runId: string): PreprocessingJobState {
    return decodeJob(JSON.parse(readTrustedFile(this.jobPath(runId))));
  }

+  readLatestJob(): PreprocessingJobState | undefined {
+    try {
+      return decodeJob(JSON.parse(readTrustedFile(this.latestJobPath())));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw error;
+    }
+  }
+
  writeJob(job: PreprocessingJobState): PreprocessingJobState {
    this.ensureLayout();
-    writeAtomicFile(this.jobPath(job.runId), `${JSON.stringify(job)}
-`, 0o600);
+    const contents = `${JSON.stringify(job)}
+`;
+    writeAtomicFile(this.jobPath(job.runId), contents, 0o600);
+    // This fixed pointer is the sole status surface for operators. Per-run files remain an
+    // internal resume mechanism and are never exposed as history.
+    writeAtomicFile(this.latestJobPath(), contents, 0o600);
    return job;
  }

@@ -23,7 +23,7 @@ import {
  canonicalEffectiveConfigJson,
  configFingerprint,
  effectiveConfigIdentity,
-  inputFingerprint,
+  preprocessingInputFingerprint,
  type CanonicalEffectiveConfig,
 } from "./effective-config.js";
 import { resolveRuntimeBindings, type RuntimeBindings } from "./bindings.js";
@@ -41,6 +41,8 @@ import {
 } from "./runtime-renderer.js";
 import { parseWorkspaceYaml, validateOperationalWorkspace, type WorkspaceDescriptor } from "./schema.js";
 import type { WorkspaceRegistryConfig } from "./types.js";
+import { resolveCatalogRuntimeBinding } from "../catalog/runtime-binding.js";
+import type { WorkspaceDatabase } from "../catalog/types.js";

 export interface RuntimeConfigLease {
  path: string;
@@ -246,8 +248,6 @@ function readSnapshotWorkspace(snapshotPath: string): {
 function runtimePaths(
  dataRoot: string,
  workspaceId: string,
-  workspaceRevision?: string,
-  effectiveRelationshipsPath?: string,
 ): RuntimePaths {
  if (!isAbsolute(dataRoot)) throw new Error("registry workspace runtime requires an absolute data root");
  const root = join(dataRoot, "sessions", workspaceId);
@@ -256,12 +256,7 @@ function runtimePaths(
    artifacts: join(root, "artifacts"),
    indexes: join(root, "indexes"),
    memory: join(root, "memory"),
-    ...(workspaceRevision === undefined
-      ? {}
-      : { annotations_root: join(dataRoot, "sessions", workspaceId, "revisions", workspaceRevision, "artifacts") }),
-    ...(effectiveRelationshipsPath === undefined
-      ? {}
-      : { effective_relationships: effectiveRelationshipsPath }),
+    catalog_metadata_snapshot: join(root, "preprocessing", "catalog-metadata.json"),
  };
 }

@@ -309,19 +304,32 @@ function renderWorkspaceRuntimeFromWorkspace(options: {
  dataRoot: string;
  secretRoots: readonly string[];
  semanticRuntime: SemanticRuntimeConfig;
-  effectiveRelationshipsPath?: string;
  workspaceSecretStore?: WorkspaceSecretStore;
+  catalogDatabase?: WorkspaceDatabase;
 }): RenderedWorkspaceRuntime {
-  const secretLease = options.workspaceSecretStore === undefined
+  if (options.catalogDatabase && !options.workspaceSecretStore) {
+    throw new Error("Catalog runtime binding requires the workspace secret store");
+  }
+  const catalogLease = options.catalogDatabase === undefined
+    ? undefined
+    : resolveCatalogRuntimeBinding({
+      workspace: options.workspace,
+      database: options.catalogDatabase,
+      environment: process.env,
+      secretRoots: options.secretRoots,
+      secretStore: options.workspaceSecretStore!,
+    });
+  const runtimeWorkspace = catalogLease?.workspace ?? options.workspace;
+  const secretLease = catalogLease !== undefined || options.workspaceSecretStore === undefined
    ? undefined
    : resolveRuntimeBindingsWithWorkspaceSecrets(
-      options.workspace,
+      runtimeWorkspace,
      process.env,
      options.secretRoots,
      options.workspaceSecretStore,
    );
-  const bindings = secretLease?.bindings
-    ?? resolveRuntimeBindings(options.workspace, process.env, options.secretRoots);
+  const bindings = catalogLease?.bindings ?? secretLease?.bindings
+    ?? resolveRuntimeBindings(runtimeWorkspace, process.env, options.secretRoots);
  const overlay = installationOverlay(options.harnessDir, options.configPath);
  const context: RuntimeRenderContext = {
    workspaceId: options.workspaceId,
@@ -334,32 +342,26 @@ function renderWorkspaceRuntimeFromWorkspace(options: {
      workspaceId: options.workspaceId,
      workspaceRevision: options.workspaceRevision,
      revisionContentRoot: options.revisionContentRoot,
-      runtimePaths: runtimePaths(
-        options.dataRoot,
-        options.workspaceId,
-        options.workspaceRevision,
-        options.effectiveRelationshipsPath,
-      ),
+      runtimePaths: runtimePaths(options.dataRoot, options.workspaceId),
      installationOverlay: overlay,
      bindings,
      bindingDigest: stableBindingDigest(bindings),
      semanticQdrantUrl: options.semanticRuntime.internalQdrantUrl,
-      releaseSecrets: () => secretLease?.release(),
+      releaseSecrets: () => {
+        catalogLease?.release();
+        secretLease?.release();
+      },
      renderedConfig: renderRuntimeConfig(
-        options.workspace,
+        runtimeWorkspace,
        bindings,
-        runtimePaths(
-          options.dataRoot,
-          options.workspaceId,
-          options.workspaceRevision,
-          options.effectiveRelationshipsPath,
-        ),
+        runtimePaths(options.dataRoot, options.workspaceId),
        context,
        overlay,
        options.semanticRuntime,
      ),
    };
  } catch (error) {
+    catalogLease?.release();
    secretLease?.release();
    throw error;
  }
@@ -372,8 +374,8 @@ export function renderWorkspaceRuntimeFromSnapshotPath(options: {
  dataRoot: string;
  secretRoots: readonly string[];
  semanticRuntime: SemanticRuntimeConfig;
-  effectiveRelationshipsPath?: string;
  workspaceSecretStore?: WorkspaceSecretStore;
+  catalogDatabase?: WorkspaceDatabase;
 }): RenderedWorkspaceRuntime {
  const snapshot = readSnapshotWorkspace(options.snapshotPath);
  return renderWorkspaceRuntimeFromWorkspace({
@@ -386,8 +388,8 @@ export function renderWorkspaceRuntimeFromSnapshotPath(options: {
    dataRoot: options.dataRoot,
    secretRoots: options.secretRoots,
    semanticRuntime: options.semanticRuntime,
-    effectiveRelationshipsPath: options.effectiveRelationshipsPath,
    workspaceSecretStore: options.workspaceSecretStore,
+    catalogDatabase: options.catalogDatabase,
  });
 }

@@ -401,6 +403,7 @@ export async function renderActiveWorkspaceRuntime(options: {
  secretRoots: readonly string[];
  semanticRuntime: SemanticRuntimeConfig;
  workspaceSecretStore?: WorkspaceSecretStore;
+  catalogDatabase?: WorkspaceDatabase;
 }): Promise<ActiveRenderedWorkspaceRuntime> {
  // The persisted active state may reference host-side snapshot paths (written by another
  // process or installation). Read the active state directly and resolve the immutable snapshot
@@ -431,6 +434,7 @@ export async function renderActiveWorkspaceRuntime(options: {
    secretRoots: options.secretRoots,
    semanticRuntime: options.semanticRuntime,
    workspaceSecretStore: options.workspaceSecretStore,
+    catalogDatabase: options.catalogDatabase,
  });
  return {
    ...rendered,
@@ -480,6 +484,7 @@ export async function publishDeterministicRuntimeConfigLease(options: {
  secretRoots: readonly string[];
  semanticRuntime: SemanticRuntimeConfig;
  workspaceSecretStore?: WorkspaceSecretStore;
+  catalogDatabase?: WorkspaceDatabase;
 }): Promise<DeterministicRuntimeConfigLease> {
  const rendered = await renderActiveWorkspaceRuntime(options);
  const publishedConfig = applyCollectionLifecycle(rendered.renderedConfig, "require_existing");
@@ -487,7 +492,11 @@ export async function publishDeterministicRuntimeConfigLease(options: {
  const effectiveConfig = buildCanonicalEffectiveConfig(renderedConfigObject);
  const effectiveConfigIdentityValue = effectiveConfigIdentity(rendered.workspaceId, renderedConfigObject);
  const configFingerprintValue = configFingerprint(renderedConfigObject);
-  const inputFingerprintValue = inputFingerprint(rendered.workspaceId, renderedConfigObject);
+  const inputFingerprintValue = preprocessingInputFingerprint(
+    rendered.workspaceId,
+    rendered.workspaceRevision,
+    renderedConfigObject,
+  );
  const identitySuffix = inputFingerprintValue.slice(7, 23);

  const preprocessingRoot = ensureTrustedDirectory(join(
@@ -3,6 +3,7 @@ import { stringify } from "yaml";
 import { buildInstallationContract } from "./contracts.js";
 import { validateWorkspaceDescriptor, type WorkspaceDescriptor } from "./schema.js";
 import type { ResolvedBinding, ResolvedEvidenceBinding, RuntimeBindings } from "./bindings.js";
+import { workspaceVectorCollections } from "./vector-collections.js";
 export type { RuntimeBindings } from "./bindings.js";

 export interface RuntimePaths {
@@ -10,10 +11,8 @@ export interface RuntimePaths {
  artifacts: string;
  indexes: string;
  memory: string;
-  /** Revision-qualified root for curated FK annotations (P5); optional for legacy callers. */
-  annotations_root?: string;
-  /** Immutable Catalog projection used as the exclusive runtime relationship source. */
-  effective_relationships?: string;
+  /** Current backend-produced projection of the PostgreSQL Metadata Catalog. */
+  catalog_metadata_snapshot?: string;
 }

 export interface RuntimeIdentity {
@@ -224,6 +223,7 @@ export function renderRuntimeConfig(
 ): string {
  requireSupportedDescriptor(workspace);
  const descriptor = validateWorkspaceDescriptor(workspace);
+  if (!descriptor.dwh) throw new Error("runtime configuration requires a Catalog database binding");
  const contract = buildInstallationContract(descriptor);
  const name = (role: "DWH" | "EVIDENCE", suffix: string) => {
    const variable = contract.variables.find((entry) => entry.role === role && entry.suffix === suffix);
@@ -243,6 +243,7 @@ export function renderRuntimeConfig(
  }

  const dwhIdentity = { database: descriptor.dwh.database, schema: descriptor.dwh.schema };
+  const vectorCollections = workspaceVectorCollections(descriptor.workspace.id);
  const database = bindings.dwh.transport === "postgres_direct"
    ? { ...directConnection(bindings.dwh, {
      host: name("DWH", "HOST"),
@@ -268,7 +269,7 @@ export function renderRuntimeConfig(
    semantic_index: {
      vector_store: {
        engine: "qdrant",
-        collection: descriptor.workspace.id,
+        collections: vectorCollections,
        dimensions: semanticRuntime.internalEmbeddingDimensions,
        distance: "cosine",
      },
@@ -284,7 +285,7 @@ export function renderRuntimeConfig(
      vector: {
        engine: "qdrant",
        base_url: semanticRuntime.internalQdrantUrl,
-        collection: descriptor.workspace.id,
+        collections: vectorCollections,
      },
      embeddings: {
        provider: "ollama_internal",
@@ -53,7 +53,8 @@ interface WorkspaceDwh {

 interface WorkspaceBase {
  workspace: WorkspaceMetadata;
-  dwh: WorkspaceDwh;
+  /** Legacy connection block; current descriptors bind their database through PostgreSQL. */
+  dwh?: WorkspaceDwh;
  diagnostics?: Pick<CanonicalDiagnostics, "dwh_rest">;
 }

@@ -328,7 +329,9 @@ function unique<T>(values: readonly T[], context: z.RefinementCtx, path: Propert
 }

 function workspaceInvariants(workspace: any, context: z.RefinementCtx): void {
-  unique(workspace.dwh.supported_transports, context, ["dwh", "supported_transports"]);
+  if (workspace.dwh) {
+    unique(workspace.dwh.supported_transports, context, ["dwh", "supported_transports"]);
+  }

  if (workspace.evidence?.source.type === "filesystem") {
    const expected = `${workspace.workspace.id}/evidence`;
@@ -341,7 +344,8 @@ function workspaceInvariants(workspace: any, context: z.RefinementCtx): void {
    }
  }

-  if (workspace.diagnostics?.dwh_rest && !workspace.dwh.supported_transports.includes("rest_api")) {
+  if (workspace.diagnostics?.dwh_rest
+    && !workspace.dwh?.supported_transports.includes("rest_api")) {
    context.addIssue({
      code: "custom",
      path: ["diagnostics", "dwh_rest"],
@@ -351,7 +355,7 @@ function workspaceInvariants(workspace: any, context: z.RefinementCtx): void {
 }

 const WorkspaceV4Schema = z.object({
-  dwh: dwhSchema,
+  dwh: dwhSchema.optional(),
  evidence: workspaceEvidenceSchema.optional(),
  diagnostics: z.object({
    dwh_rest: dwhRestDiagnostic.optional(),
@@ -363,7 +367,7 @@ const WorkspaceV4Schema = z.object({
 }).strict().superRefine(workspaceInvariants);
 const WorkspaceDescriptorSchema = WorkspaceV4Schema;

-export function parseWorkspaceYaml(source: string): WorkspaceDescriptor {
+function parseWorkspaceDocument(source: string): unknown {
  const documents = parseAllDocuments(source, { uniqueKeys: true });
  if (documents.length !== 1) throw new Error("Workspace YAML must contain exactly one document");
  const document = documents[0];
@@ -371,10 +375,30 @@ export function parseWorkspaceYaml(source: string): WorkspaceDescriptor {
    throw new Error(`Invalid workspace YAML: ${[...document.errors, ...document.warnings]
      .map((error) => error.message).join("; ")}`);
  }
-  return validateWorkspaceDescriptor(document.toJSON());
+  return document.toJSON();
 }

-/** Deterministically removes the two installation-owned v3 blocks without altering workspace data. */
+export function parseWorkspaceYaml(source: string): WorkspaceDescriptor {
+  const value = parseWorkspaceDocument(source);
+  assertAuthoredWorkspaceIsDatabaseFree(value);
+  return validateWorkspaceDescriptor(value);
+}
+
+/** Parses an ephemeral, generated core runtime descriptor that may contain a Catalog binding. */
+export function parseRuntimeWorkspaceYaml(source: string): WorkspaceDescriptor {
+  return validateWorkspaceDescriptor(parseWorkspaceDocument(source));
+}
+
+function assertAuthoredWorkspaceIsDatabaseFree(workspace: unknown): void {
+  if (workspace !== null && typeof workspace === "object"
+    && ("dwh" in workspace || "diagnostics" in workspace)) {
+    throw new Error(
+      "Workspace YAML must not contain database configuration; use the PostgreSQL Metadata Catalog",
+    );
+  }
+}
+
+/** Build a database-free v4 descriptor; legacy database/configuration fields are not carried over. */
 export function migrateWorkspaceV3Yaml(source: string): string {
  const documents = parseAllDocuments(source, { uniqueKeys: true });
  if (documents.length !== 1) throw new Error("Workspace YAML must contain exactly one document");
@@ -388,6 +412,8 @@ export function migrateWorkspaceV3Yaml(source: string): string {
    throw new Error("Workspace migration requires schema version 3");
  }
  metadata.schema_version = 4;
+  delete value.dwh;
+  delete value.diagnostics;
  delete value.semantic_index;
  delete value.llm_policy;
  return serializeWorkspaceYaml(validateWorkspaceDescriptor(value));
@@ -423,6 +449,7 @@ export function resolveDiagnosticUrl(baseUrl: string, path: string): URL {

 export function serializeWorkspaceYaml(workspace: CanonicalWorkspace): string {
  const canonical = validateOperationalWorkspace(workspace);
+  assertAuthoredWorkspaceIsDatabaseFree(canonical);
  return stringify(canonical, { lineWidth: 0, sortMapEntries: true });
 }

@@ -101,7 +101,8 @@ function selectedTransport(
  descriptor: WorkspaceDescriptor,
  variables: readonly InstallationVariable[],
  env: NodeJS.ProcessEnv,
-): DwhTransport {
+): DwhTransport | undefined {
+  if (!descriptor.dwh) return undefined;
  const transportVariable = variables.find(({ role, suffix }) => role === "DWH" && suffix === "TRANSPORT");
  const value = transportVariable === undefined ? undefined : env[transportVariable.name];
  return isTransport(value) && descriptor.dwh.supported_transports.includes(value)
@@ -136,11 +137,14 @@ export function discoverWorkspaceSecretRequirements(
  const variables = buildInstallationContract(descriptor).variables;
  const transport = selectedTransport(descriptor, variables, env);
  const restHasNoAuthentication = transport === "rest_api" && descriptor.diagnostics?.dwh_rest?.auth === "none";
-  const requiredDwh = new Set(restHasNoAuthentication ? [] : REQUIRED_DWH_SECRETS[transport]);
+  const requiredDwh = new Set(
+    transport === undefined || restHasNoAuthentication ? [] : REQUIRED_DWH_SECRETS[transport],
+  );

  const requirements: WorkspaceSecretRequirement[] = [];
  for (const variable of variables) {
    if (variable.role === "DWH") {
+      if (transport === undefined) continue;
      if (variable.transports !== undefined && !variable.transports.includes(transport)) continue;
      const requirement = requirementFor(variable, requiredDwh.has(variable.suffix));
      if (requirement !== undefined && requirement.required) requirements.push(requirement);
@@ -0,0 +1,20 @@
+export interface WorkspaceVectorCollections {
+  reference: string;
+  memory: string;
+}
+
+/**
+ * Physical Qdrant namespaces owned by one workspace.
+ *
+ * Reference data is replaceable preprocessing output. Memory is durable runtime
+ * state and deliberately has a separate lifecycle.
+ */
+export function workspaceVectorCollections(workspaceId: string): WorkspaceVectorCollections {
+  if (!/^[a-z][a-z0-9-]{2,62}$/.test(workspaceId)) {
+    throw new Error("workspace id is invalid");
+  }
+  return {
+    reference: `${workspaceId}-reference`,
+    memory: `${workspaceId}-memory`,
+  };
+}