feat: add AI catalog description generation

backend/test/catalog-description-generation-worker.test.ts

@@ -0,0 +1,456 @@
+import { expect, test, vi } from "vitest";
+import { DescriptionGenerationWorker } from "../src/catalog/description-generation-worker.js";
+import type { DescriptionSourceSampler } from "../src/catalog/description-source-sampler.js";
+import { MemoryCatalogRepository } from "../src/catalog/memory-repository.js";
+import type { MetadataGenerationModels } from "../src/catalog/metadata-generation-models.js";
+import { ModelCompletionCancelledError } from "../src/catalog/model-completer.js";
+import type { ModelCompleter, ModelCompletionRequest } from "../src/catalog/model-completer.js";
+import { CatalogOperationCoordinator } from "../src/catalog/operation-coordinator.js";
+import type { WorkspaceRegistry } from "../src/workspaces/registry.js";
+
+test("serializes Unlock with Start so stale recovery cannot release a new reservation", async () => {
+  let lookupStarted!: () => void;
+  const started = new Promise<void>((resolve) => { lookupStarted = resolve; });
+  let releaseLookup!: () => void;
+  const gate = new Promise<void>((resolve) => { releaseLookup = resolve; });
+  const repository = {
+    getActiveDescriptionGenerationRun: vi.fn(async () => {
+      lookupStarted();
+      await gate;
+      return undefined;
+    }),
+  } as unknown as MemoryCatalogRepository;
+  const resolveModel = vi.fn();
+  const worker = new DescriptionGenerationWorker(
+    repository,
+    {} as WorkspaceRegistry,
+    {
+      catalog: () => ({ models: [], default: "" }),
+      resolve: resolveModel,
+    } as MetadataGenerationModels,
+    {} as ModelCompleter,
+    new CatalogOperationCoordinator(),
+    { sample: vi.fn(async () => []) },
+  );
+
+  const unlocking = worker.unlock();
+  await started;
+  await expect(worker.start(
+    "11111111-1111-4111-8111-111111111111",
+    "openai-mini",
+    "missing",
+    [],
+  )).rejects.toThrow("already active");
+  expect(resolveModel).not.toHaveBeenCalled();
+
+  releaseLookup();
+  await expect(unlocking).resolves.toBeUndefined();
+});
+
+test("exposes an awaitable background job and absorbs provider promise rejection", async () => {
+  const repository = new MemoryCatalogRepository();
+  const database = await repository.create({
+    workspaceId: "psd-clinical",
+    engine: "postgres",
+    databaseName: "warehouse",
+    schema: "datawarehouse",
+    binding: { transport: "postgres_direct", host: "db.internal", port: 5432, username: "reader" },
+  });
+  await repository.applySchemaSync(database.id, database.version, "all", [], {
+    schemaVersion: 1,
+    capabilities: { tables: "available", columns: "available", relationships: "available" },
+    tables: [{ name: "patients", sourceComment: null }],
+    columns: [{
+      tableName: "patients",
+      name: "birth_date",
+      ordinalPosition: 1,
+      dataType: "date",
+      isNullable: true,
+      defaultExpression: null,
+      primaryKeyPosition: null,
+      sourceComment: null,
+    }],
+    relationships: [],
+  });
+  const table = (await repository.listTables(database.id))[0]!;
+  const column = (await repository.listColumns(database.id, table.id))[0]!;
+  let rejectCompletion!: (error: Error) => void;
+  const pendingCompletion = new Promise<string>((_resolve, reject) => { rejectCompletion = reject; });
+  const completer: ModelCompleter = {
+    complete: vi.fn(async () => await pendingCompletion),
+  };
+  const models: MetadataGenerationModels = {
+    catalog: () => ({ models: [{ id: "openai-mini", label: "OpenAI Mini" }], default: "openai-mini" }),
+    resolve: () => ({
+      id: "openai-mini",
+      provider: "openai",
+      model: "gpt-4.1-mini",
+      apiKeyEnv: "OPENAI_API_KEY",
+      apiKey: "test-provider-secret",
+    }),
+  };
+  const operations = new CatalogOperationCoordinator();
+  const sourceSampler: DescriptionSourceSampler = {
+    sample: vi.fn(async () => []),
+  };
+  const worker = new DescriptionGenerationWorker(
+    repository,
+    {
+      read: vi.fn(async () => ({
+        workspace: { workspace: { language: "it" } },
+        revision: {},
+      })),
+    } as unknown as WorkspaceRegistry,
+    models,
+    completer,
+    operations,
+    sourceSampler,
+  );
+
+  const run = await worker.start(database.id, "openai-mini", "selected_columns", [column.id]);
+  let settled = false;
+  const waiting = worker.waitForRun(run.id).then(() => { settled = true; });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  expect(settled).toBe(false);
+
+  rejectCompletion(new Error("test-provider-secret private prompt raw response"));
+  await expect(waiting).resolves.toBeUndefined();
+  expect(await repository.getDescriptionGenerationRun(run.id)).toMatchObject({
+    status: "completed_with_errors",
+    failed: 1,
+    errorSummary: "Description generation completed with errors.",
+  });
+  const events = await repository.listDescriptionGenerationEvents(run.id);
+  expect(JSON.stringify(events)).not.toMatch(/test-provider-secret|private prompt|raw response/);
+
+  const release = operations.reserve(database.id);
+  release();
+
+  await expect(worker.start(
+    database.id,
+    "openai-mini",
+    "selected_columns",
+    [],
+  )).rejects.toThrow("at least one target ID is required");
+});
+
+test("marks an active run interrupted when the backend worker stops", async () => {
+  const repository = new MemoryCatalogRepository();
+  const database = await repository.create({
+    workspaceId: "psd-clinical",
+    engine: "postgres",
+    databaseName: "warehouse",
+    schema: "datawarehouse",
+    binding: { transport: "postgres_direct", host: "db.internal", port: 5432, username: "reader" },
+  });
+  await repository.applySchemaSync(database.id, database.version, "all", [], {
+    schemaVersion: 1,
+    capabilities: { tables: "available", columns: "available", relationships: "available" },
+    tables: [{ name: "patients", sourceComment: null }],
+    columns: [{
+      tableName: "patients",
+      name: "status",
+      ordinalPosition: 1,
+      dataType: "text",
+      isNullable: true,
+      defaultExpression: null,
+      primaryKeyPosition: null,
+      sourceComment: null,
+    }],
+    relationships: [],
+  });
+  const table = (await repository.listTables(database.id))[0]!;
+  const column = (await repository.listColumns(database.id, table.id))[0]!;
+  const completer: ModelCompleter = {
+    complete: vi.fn(async (request) => await new Promise<string>((_resolve, reject) => {
+      const cancel = () => reject(new ModelCompletionCancelledError());
+      if (request.signal.aborted) cancel();
+      else request.signal.addEventListener("abort", cancel, { once: true });
+    })),
+  };
+  const worker = new DescriptionGenerationWorker(
+    repository,
+    {
+      read: vi.fn(async () => ({
+        workspace: { workspace: { language: "it" } },
+        revision: {},
+      })),
+    } as unknown as WorkspaceRegistry,
+    {
+      catalog: () => ({ models: [{ id: "openai-mini", label: "OpenAI Mini" }], default: "openai-mini" }),
+      resolve: () => ({
+        id: "openai-mini",
+        provider: "openai",
+        model: "gpt-4.1-mini",
+        apiKeyEnv: "OPENAI_API_KEY",
+        apiKey: "test-provider-secret",
+      }),
+    },
+    completer,
+    new CatalogOperationCoordinator(),
+    { sample: vi.fn(async () => []) },
+  );
+
+  const run = await worker.start(database.id, "openai-mini", "selected_columns", [column.id]);
+  await vi.waitFor(() => expect(completer.complete).toHaveBeenCalledOnce());
+  await worker.stop();
+
+  expect(await repository.getDescriptionGenerationRun(run.id)).toMatchObject({
+    status: "interrupted",
+    errorSummary: "Description generation was interrupted by backend shutdown.",
+  });
+  expect(await repository.listDescriptionGenerationEvents(run.id)).toContainEqual(
+    expect.objectContaining({
+      level: "warning",
+      message: "Description generation was interrupted by backend shutdown.",
+    }),
+  );
+});
+
+test("adds only bounded transient source samples to the model request", async () => {
+  const repository = new MemoryCatalogRepository();
+  const database = await repository.create({
+    workspaceId: "psd-clinical",
+    engine: "postgres",
+    databaseName: "warehouse",
+    schema: "datawarehouse",
+    binding: { transport: "postgres_direct", host: "db.internal", port: 5432, username: "reader" },
+  });
+  await repository.applySchemaSync(database.id, database.version, "all", [], {
+    schemaVersion: 1,
+    capabilities: { tables: "available", columns: "available", relationships: "available" },
+    tables: [{ name: "patients", sourceComment: null }],
+    columns: [{
+      tableName: "patients",
+      name: "status",
+      ordinalPosition: 1,
+      dataType: "text",
+      isNullable: true,
+      defaultExpression: null,
+      primaryKeyPosition: null,
+      sourceComment: null,
+    }, {
+      tableName: "patients",
+      name: "ward",
+      ordinalPosition: 2,
+      dataType: "text",
+      isNullable: true,
+      defaultExpression: null,
+      primaryKeyPosition: null,
+      sourceComment: null,
+    }],
+    relationships: [],
+  });
+  const table = (await repository.listTables(database.id))[0]!;
+  const columns = await repository.listColumns(database.id, table.id);
+  const column = columns.find((candidate) => candidate.name === "status")!;
+  const ward = columns.find((candidate) => candidate.name === "ward")!;
+  const sampleSecret = "ONLY_IN_TRANSIENT_SAMPLE_7f29c8";
+  const sourceSampler: DescriptionSourceSampler = {
+    sample: vi.fn(async () => [{
+      targetId: column.id,
+      tableName: table.name,
+      rows: [
+        { fields: [{ name: column.name, value: sampleSecret }] },
+        { fields: [{ name: column.name, value: "row-2" }] },
+        { fields: [{ name: column.name, value: "row-3" }] },
+      ],
+      representativeValues: [{
+        column: column.name,
+        values: [sampleSecret, sampleSecret, "two", "three"],
+      }],
+    }, {
+      targetId: ward.id,
+      tableName: table.name,
+      rows: [
+        { fields: [{ name: ward.name, value: "row-4" }] },
+        { fields: [{ name: ward.name, value: "row-5" }] },
+        { fields: [{ name: ward.name, value: "row-6-must-be-omitted" }] },
+      ],
+      representativeValues: [{
+        column: ward.name,
+        values: ["ward-1", "ward-2", "ward-3-must-be-omitted"],
+      }],
+    }]),
+  };
+  const completer: ModelCompleter = {
+    complete: vi.fn(async () => JSON.stringify({
+      results: [{
+        targetId: column.id,
+        outcome: "generated",
+        description: "Stato amministrativo del paziente.",
+      }, {
+        targetId: ward.id,
+        outcome: "generated",
+        description: "Reparto associato al paziente.",
+      }],
+    })),
+  };
+  const models: MetadataGenerationModels = {
+    catalog: () => ({ models: [{ id: "openai-mini", label: "OpenAI Mini" }], default: "openai-mini" }),
+    resolve: () => ({
+      id: "openai-mini",
+      provider: "openai",
+      model: "gpt-4.1-mini",
+      apiKeyEnv: "OPENAI_API_KEY",
+      apiKey: "test-provider-secret",
+    }),
+  };
+  const worker = new DescriptionGenerationWorker(
+    repository,
+    {
+      read: vi.fn(async () => ({
+        workspace: { workspace: { language: "it" } },
+        revision: {},
+      })),
+    } as unknown as WorkspaceRegistry,
+    models,
+    completer,
+    new CatalogOperationCoordinator(),
+    sourceSampler,
+  );
+
+  const run = await worker.start(
+    database.id,
+    "openai-mini",
+    "selected_columns",
+    [column.id, ward.id],
+  );
+  await worker.waitForRun(run.id);
+
+  expect(sourceSampler.sample).toHaveBeenCalledWith(
+    expect.objectContaining({ id: database.id, binding: database.binding }),
+    [
+      { targetId: column.id, tableName: table.name, columnNames: [column.name] },
+      { targetId: ward.id, tableName: table.name, columnNames: [ward.name] },
+    ],
+    expect.any(AbortSignal),
+  );
+  const request = vi.mocked(completer.complete).mock.calls[0]![0] as ModelCompletionRequest;
+  expect(request.messages[0]?.content).toContain("untrusted");
+  const userMessage = request.messages[1]!.content;
+  const context = JSON.parse(userMessage.slice(userMessage.indexOf("\n") + 1));
+  const sampledRows = context.targets.flatMap(
+    (targetContext: { sourceSample?: { rows: unknown[] } }) => targetContext.sourceSample?.rows ?? [],
+  );
+  const representativeValues = context.targets.flatMap(
+    (targetContext: { sourceSample?: { representativeValues: Array<{ values: unknown[] }> } }) => (
+      targetContext.sourceSample?.representativeValues.flatMap((entry) => entry.values) ?? []
+    ),
+  );
+  expect(sampledRows).toHaveLength(5);
+  expect(representativeValues).toHaveLength(5);
+  expect(context.targets[0].sourceSample.rows).toHaveLength(3);
+  expect(context.targets[1].sourceSample.rows).toHaveLength(2);
+  expect(context.targets[0].sourceSample.representativeValues).toEqual([{
+    column: column.name,
+    values: [sampleSecret, "two", "three"],
+  }]);
+  expect(context.targets[1].sourceSample.representativeValues).toEqual([{
+    column: ward.name,
+    values: ["ward-1", "ward-2"],
+  }]);
+  expect(userMessage).toContain(sampleSecret);
+  expect(userMessage).not.toMatch(
+    /row-6-must-be-omitted|ward-3-must-be-omitted/,
+  );
+
+  const persisted = JSON.stringify({
+    run: await repository.getDescriptionGenerationRun(run.id),
+    events: await repository.listDescriptionGenerationEvents(run.id),
+    database: await repository.get(database.id),
+    table: await repository.getTable(database.id, table.id),
+    column: await repository.getColumn(database.id, table.id, column.id),
+    ward: await repository.getColumn(database.id, table.id, ward.id),
+  });
+  expect(persisted).not.toContain(sampleSecret);
+});
+
+test("continues metadata-only with one safe warning when source sampling is unavailable", async () => {
+  const repository = new MemoryCatalogRepository();
+  const database = await repository.create({
+    workspaceId: "psd-clinical",
+    engine: "postgres",
+    databaseName: "warehouse",
+    schema: "datawarehouse",
+    binding: {
+      transport: "rest_api",
+      baseUrl: "https://dwh.example.test",
+      restPath: "/rpc/run_query",
+      restAuth: "none",
+    },
+  });
+  await repository.applySchemaSync(database.id, database.version, "all", [], {
+    schemaVersion: 1,
+    capabilities: { tables: "available", columns: "available", relationships: "available" },
+    tables: [{ name: "patients", sourceComment: null }],
+    columns: [{
+      tableName: "patients",
+      name: "status",
+      ordinalPosition: 1,
+      dataType: "text",
+      isNullable: true,
+      defaultExpression: null,
+      primaryKeyPosition: null,
+      sourceComment: null,
+    }],
+    relationships: [],
+  });
+  const table = (await repository.listTables(database.id))[0]!;
+  const column = (await repository.listColumns(database.id, table.id))[0]!;
+  const samplingFailureSecret = "UNAVAILABLE_SAMPLE_DETAIL_48b1f1";
+  const sourceSampler: DescriptionSourceSampler = {
+    sample: vi.fn(async () => { throw new Error(samplingFailureSecret); }),
+  };
+  const completer: ModelCompleter = {
+    complete: vi.fn(async () => JSON.stringify({
+      results: [{
+        targetId: column.id,
+        outcome: "generated",
+        description: "Stato del paziente.",
+      }],
+    })),
+  };
+  const models: MetadataGenerationModels = {
+    catalog: () => ({ models: [{ id: "openai-mini", label: "OpenAI Mini" }], default: "openai-mini" }),
+    resolve: () => ({
+      id: "openai-mini",
+      provider: "openai",
+      model: "gpt-4.1-mini",
+      apiKeyEnv: "OPENAI_API_KEY",
+      apiKey: "test-provider-secret",
+    }),
+  };
+  const worker = new DescriptionGenerationWorker(
+    repository,
+    {
+      read: vi.fn(async () => ({
+        workspace: { workspace: { language: "it" } },
+        revision: {},
+      })),
+    } as unknown as WorkspaceRegistry,
+    models,
+    completer,
+    new CatalogOperationCoordinator(),
+    sourceSampler,
+  );
+
+  const run = await worker.start(database.id, "openai-mini", "selected_columns", [column.id]);
+  await worker.waitForRun(run.id);
+
+  expect(await repository.getDescriptionGenerationRun(run.id)).toMatchObject({
+    status: "completed",
+    processed: 1,
+    generated: 1,
+    failed: 0,
+  });
+  const request = vi.mocked(completer.complete).mock.calls[0]![0] as ModelCompletionRequest;
+  expect(request.messages[1]?.content).not.toMatch(/sourceSample|UNAVAILABLE_SAMPLE_DETAIL/);
+  const events = await repository.listDescriptionGenerationEvents(run.id);
+  expect(events.filter((event) => event.level === "warning")).toEqual([
+    expect.objectContaining({
+      message: "Source samples unavailable for this batch; generation continued with catalog metadata only.",
+    }),
+  ]);
+  expect(JSON.stringify(events)).not.toContain(samplingFailureSecret);
+});

backend/test/catalog-description-generation.integration.test.ts

@@ -0,0 +1,384 @@
+import { spawnSync } from "node:child_process";
+import { PostgreSqlContainer } from "@testcontainers/postgresql";
+import { CamelCasePlugin, Kysely, PostgresDialect } from "kysely";
+import { Pool } from "pg";
+import { expect, test, vi } from "vitest";
+import { buildApp } from "../src/app.js";
+import type { DescriptionSourceSampler } from "../src/catalog/description-source-sampler.js";
+import type { MetadataGenerationModels } from "../src/catalog/metadata-generation-models.js";
+import { ModelCompletionProviderError, type ModelCompleter } from "../src/catalog/model-completer.js";
+import { up as upDatabases } from "../src/catalog/migrations/001_workspace_databases.js";
+import { up as upTables } from "../src/catalog/migrations/002_catalog_tables.js";
+import { up as upSchemaSync } from "../src/catalog/migrations/003_catalog_schema_sync.js";
+import { up as upDescriptionGeneration } from "../src/catalog/migrations/005_description_generation_runs.js";
+import { KyselyCatalogRepository, type CatalogDatabase } from "../src/catalog/repository.js";
+import { loadConfig } from "../src/config.js";
+import type { WorkspaceRegistry } from "../src/workspaces/registry.js";
+
+const dockerAvailable = spawnSync("docker", ["info"], { stdio: "ignore" }).status === 0;
+
+async function terminalRun(app: ReturnType<typeof buildApp>, runId: string) {
+  for (let attempt = 0; attempt < 200; attempt += 1) {
+    const response = await app.inject({
+      method: "GET",
+      url: `/catalog/description-generation-runs/${runId}`,
+    });
+    const run = response.json();
+    if (["completed", "completed_with_errors", "cancelled", "failed", "interrupted"].includes(run.status)) {
+      return run;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  throw new Error(`Description Generation Run ${runId} did not finish`);
+}
+
+test.skipIf(!dockerAvailable)("Fastify persists Description Generation success and failure through PostgreSQL", async () => {
+  const container = await new PostgreSqlContainer("postgres:17.6-bookworm").start();
+  const db = new Kysely<CatalogDatabase>({
+    dialect: new PostgresDialect({ pool: new Pool({ connectionString: container.getConnectionUri() }) }),
+    plugins: [new CamelCasePlugin()],
+  });
+  let app: ReturnType<typeof buildApp> | undefined;
+  try {
+    await upDatabases(db);
+    await upTables(db);
+    await upSchemaSync(db);
+    await upDescriptionGeneration(db);
+    const repository = new KyselyCatalogRepository(db);
+    const database = await repository.create({
+      workspaceId: "psd-clinical",
+      engine: "postgres",
+      databaseName: "warehouse",
+      schema: "datawarehouse",
+      binding: { transport: "postgres_direct", host: "db.internal", port: 5432, username: "reader" },
+    });
+    await repository.applySchemaSync(database.id, database.version, "all", [], {
+      schemaVersion: 1,
+      capabilities: { tables: "available", columns: "available", relationships: "available" },
+      tables: [{ name: "patients", sourceComment: "Clinical patients" }],
+      columns: [
+        {
+          tableName: "patients",
+          name: "birth_date",
+          ordinalPosition: 1,
+          dataType: "date",
+          isNullable: true,
+          defaultExpression: null,
+          primaryKeyPosition: null,
+          sourceComment: "Patient date of birth",
+        },
+        {
+          tableName: "patients",
+          name: "status",
+          ordinalPosition: 2,
+          dataType: "text",
+          isNullable: true,
+          defaultExpression: null,
+          primaryKeyPosition: null,
+          sourceComment: "Patient status",
+        },
+      ],
+      relationships: [],
+    });
+    const table = (await repository.listTables(database.id))[0]!;
+    const columns = await repository.listColumns(database.id, table.id);
+    const birthDate = columns.find((column) => column.name === "birth_date")!;
+    const status = columns.find((column) => column.name === "status")!;
+    const curatedTable = (await repository.updateTableMetadata(
+      database.id,
+      table.id,
+      table.version,
+      "Elenco curato dei pazienti.",
+      null,
+    ))!;
+    const curatedStatus = (await repository.updateColumnMetadata(
+      database.id,
+      table.id,
+      status.id,
+      status.version,
+      "Stato curato del paziente.",
+      null,
+    ))!;
+    let call = 0;
+    const modelCompleter: ModelCompleter = {
+      complete: vi.fn(async () => {
+        call += 1;
+        if (call === 1) {
+          return JSON.stringify({ results: [
+            {
+              targetId: birthDate.id,
+              outcome: "generated",
+              description: "Data di nascita del paziente.",
+            },
+            { targetId: status.id, outcome: "non_generatable" },
+          ] });
+        }
+        if (call === 2) {
+          return JSON.stringify({ results: [{
+            targetId: table.id,
+            outcome: "generated",
+            description: "Elenco dei pazienti e dei loro dati clinici.",
+          }] });
+        }
+        if (call === 4) {
+          return JSON.stringify({ results: [
+            {
+              targetId: birthDate.id,
+              outcome: "generated",
+              description: "Descrizione rigenerata della data di nascita.",
+            },
+            {
+              targetId: status.id,
+              outcome: "generated",
+              description: "Descrizione rigenerata dello stato.",
+            },
+          ] });
+        }
+        if (call === 5) {
+          return JSON.stringify({ results: [{
+            targetId: table.id,
+            outcome: "generated",
+            description: "Descrizione rigenerata della tabella pazienti.",
+          }] });
+        }
+        if (call === 6) {
+          return JSON.stringify({ results: [{
+            targetId: birthDate.id,
+            outcome: "generated",
+            description: "Descrizione recuperata della data di nascita.",
+          }] });
+        }
+        throw new ModelCompletionProviderError();
+      }),
+    };
+    const models: MetadataGenerationModels = {
+      catalog: () => ({ models: [{ id: "openai-mini", label: "OpenAI Mini" }], default: "openai-mini" }),
+      resolve: () => ({
+        id: "openai-mini",
+        provider: "openai",
+        model: "gpt-4.1-mini",
+        apiKeyEnv: "OPENAI_API_KEY",
+        apiKey: "test-provider-secret",
+      }),
+    };
+    const registry = {
+      list: vi.fn(async () => []),
+      read: vi.fn(async () => ({
+        workspace: { workspace: { language: "it" } },
+        revision: {},
+      })),
+    } as unknown as WorkspaceRegistry;
+    const persistedSampleSecret = "POSTGRES_TRANSIENT_SAMPLE_6a0d7b";
+    const descriptionSourceSampler: DescriptionSourceSampler = {
+      sample: vi.fn(async (_database, targets) => targets.map((target) => ({
+        targetId: target.targetId,
+        tableName: target.tableName,
+        rows: [{
+          fields: target.columnNames.slice(0, 1).map((name) => ({
+            name,
+            value: persistedSampleSecret,
+          })),
+        }],
+        representativeValues: target.columnNames.slice(0, 1).map((column) => ({
+          column,
+          values: [persistedSampleSecret],
+        })),
+      }))),
+    };
+    app = buildApp(loadConfig({ NODE_ENV: "test", THT_HARNESS_DIR: "/missing" }), {
+      thtRunner: {} as never,
+      workspaceRegistry: registry,
+      workspaceDiagnoser: vi.fn(),
+      catalogRepository: repository,
+      metadataGenerationModels: models,
+      modelCompleter,
+      descriptionSourceSampler,
+    });
+
+    const successfulStart = await app.inject({
+      method: "POST",
+      url: `/catalog/databases/${database.id}/description-generation-runs`,
+      payload: {
+        modelId: "openai-mini",
+        scope: "selected_columns",
+        targetIds: [status.id, birthDate.id],
+      },
+    });
+    expect(successfulStart.statusCode).toBe(202);
+    expect(await terminalRun(app, successfulStart.json().id)).toMatchObject({
+      status: "completed",
+      total: 2,
+      processed: 2,
+      generated: 1,
+      nonGeneratable: 1,
+      failed: 0,
+    });
+    expect(await repository.getColumn(database.id, table.id, birthDate.id)).toMatchObject({
+      generatedDescription: "Data di nascita del paziente.",
+      version: birthDate.version + 1,
+    });
+    const generatedStatus = (await repository.getColumn(database.id, table.id, status.id))!;
+    expect(generatedStatus).toMatchObject({
+      description: "Stato curato del paziente.",
+      generatedDescription: "Non generabile",
+      version: curatedStatus.version + 1,
+    });
+
+    const tableStart = await app.inject({
+      method: "POST",
+      url: `/catalog/databases/${database.id}/description-generation-runs`,
+      payload: { modelId: "openai-mini", scope: "selected_tables", targetIds: [table.id] },
+    });
+    expect(tableStart.statusCode).toBe(202);
+    expect(await terminalRun(app, tableStart.json().id)).toMatchObject({
+      scope: "selected_tables",
+      status: "completed",
+      processed: 1,
+      generated: 1,
+      nonGeneratable: 0,
+      failed: 0,
+    });
+    expect(await repository.getTable(database.id, table.id)).toMatchObject({
+      description: "Elenco curato dei pazienti.",
+      generatedDescription: "Elenco dei pazienti e dei loro dati clinici.",
+      version: curatedTable.version + 1,
+    });
+
+    const failedStart = await app.inject({
+      method: "POST",
+      url: `/catalog/databases/${database.id}/description-generation-runs`,
+      payload: { modelId: "openai-mini", scope: "selected_columns", targetIds: [status.id] },
+    });
+    expect(failedStart.statusCode).toBe(202);
+    const failedRun = await terminalRun(app, failedStart.json().id);
+    expect(failedRun).toMatchObject({
+      status: "completed_with_errors",
+      processed: 1,
+      generated: 0,
+      failed: 1,
+      errorSummary: "Description generation completed with errors.",
+    });
+    expect(await repository.getColumn(database.id, table.id, status.id)).toMatchObject({
+      description: "Stato curato del paziente.",
+      generatedDescription: "Non generabile",
+      version: generatedStatus.version,
+    });
+    const events = await app.inject({
+      method: "GET",
+      url: `/catalog/description-generation-runs/${failedRun.id}/events-list`,
+    });
+    expect(events.statusCode).toBe(200);
+    expect(events.json().find((event: { level: string }) => event.level === "error")).toEqual(expect.objectContaining({
+      level: "error",
+      message: `The model provider request failed. Affected Catalog Column target: ${status.id}.`,
+    }));
+    expect(events.body).not.toMatch(/test-provider-secret|gpt-4\.1-mini|raw provider/i);
+
+    const allStart = await app.inject({
+      method: "POST",
+      url: `/catalog/databases/${database.id}/description-generation-runs`,
+      payload: { modelId: "openai-mini", scope: "all" },
+    });
+    expect(allStart.statusCode).toBe(202);
+    const allRun = await terminalRun(app, allStart.json().id);
+    expect(allRun).toMatchObject({
+      scope: "all",
+      status: "completed",
+      total: 3,
+      processed: 3,
+      generated: 3,
+      nonGeneratable: 0,
+      failed: 0,
+    });
+    expect(await repository.getColumn(database.id, table.id, birthDate.id)).toMatchObject({
+      generatedDescription: "Descrizione rigenerata della data di nascita.",
+    });
+    expect(await repository.getColumn(database.id, table.id, status.id)).toMatchObject({
+      generatedDescription: "Descrizione rigenerata dello stato.",
+    });
+    expect(await repository.getTable(database.id, table.id)).toMatchObject({
+      generatedDescription: "Descrizione rigenerata della tabella pazienti.",
+    });
+    const allEvents = await app.inject({
+      method: "GET",
+      url: `/catalog/description-generation-runs/${allRun.id}/events-list`,
+    });
+    expect(allEvents.json()[0]).toEqual(expect.objectContaining({
+      message: "Description generation queued (scope: all).",
+    }));
+
+    const regeneratedBirthDate = (await repository.getColumn(
+      database.id, table.id, birthDate.id,
+    ))!;
+    await repository.updateColumnMetadata(
+      database.id,
+      table.id,
+      birthDate.id,
+      regeneratedBirthDate.version,
+      regeneratedBirthDate.description,
+      "   ",
+    );
+    const missingStart = await app.inject({
+      method: "POST",
+      url: `/catalog/databases/${database.id}/description-generation-runs`,
+      payload: { modelId: "openai-mini", scope: "missing" },
+    });
+    expect(missingStart.statusCode).toBe(202);
+    expect(await terminalRun(app, missingStart.json().id)).toMatchObject({
+      scope: "missing",
+      status: "completed",
+      total: 1,
+      processed: 1,
+      generated: 1,
+      nonGeneratable: 0,
+      failed: 0,
+    });
+    expect(await repository.getColumn(database.id, table.id, birthDate.id)).toMatchObject({
+      generatedDescription: "Descrizione recuperata della data di nascita.",
+    });
+    expect(modelCompleter.complete).toHaveBeenCalledTimes(6);
+    expect(JSON.stringify(vi.mocked(modelCompleter.complete).mock.calls)).toContain(persistedSampleSecret);
+
+    const runIds = [
+      successfulStart.json().id,
+      tableStart.json().id,
+      failedStart.json().id,
+      allStart.json().id,
+      missingStart.json().id,
+    ];
+    const durableState = JSON.stringify({
+      runs: await Promise.all(runIds.map(async (runId) => (
+        await repository.getDescriptionGenerationRun(runId)
+      ))),
+      events: await Promise.all(runIds.map(async (runId) => (
+        await repository.listDescriptionGenerationEvents(runId)
+      ))),
+      database: await repository.get(database.id),
+      table: await repository.getTable(database.id, table.id),
+      columns: await repository.listColumns(database.id, table.id),
+    });
+    expect(durableState).not.toContain(persistedSampleSecret);
+    const apiResponses = await Promise.all([
+      ...runIds.flatMap((runId) => [
+        app!.inject({ method: "GET", url: `/catalog/description-generation-runs/${runId}` }),
+        app!.inject({
+          method: "GET",
+          url: `/catalog/description-generation-runs/${runId}/events-list`,
+        }),
+      ]),
+      app.inject({ method: "GET", url: `/catalog/databases/${database.id}` }),
+      app.inject({ method: "GET", url: `/catalog/databases/${database.id}/tables` }),
+      app.inject({
+        method: "GET",
+        url: `/catalog/databases/${database.id}/tables/${table.id}/columns`,
+      }),
+    ]);
+    expect(apiResponses.map((response) => response.body).join("\n")).not.toContain(
+      persistedSampleSecret,
+    );
+  } finally {
+    if (app) await app.close();
+    await db.destroy();
+    await container.stop();
+  }
+}, 60_000);

backend/test/catalog-description-source-sampler.test.ts

@@ -0,0 +1,111 @@
+import { expect, test, vi } from "vitest";
+import {
+  PostgresDescriptionSourceSampler,
+  type DescriptionSourceSamplingTarget,
+} from "../src/catalog/description-source-sampler.js";
+import type {
+  CatalogDatabaseClient,
+  CatalogPostgresAccess,
+} from "../src/catalog/postgres-access.js";
+import type { WorkspaceDatabase } from "../src/catalog/types.js";
+
+const database: WorkspaceDatabase = {
+  id: "11111111-1111-4111-8111-111111111111",
+  workspaceId: "psd-clinical",
+  engine: "postgres",
+  databaseName: "warehouse",
+  schema: 'clinical"data',
+  version: 1,
+  createdAt: "2026-08-28T08:00:00Z",
+  updatedAt: "2026-08-28T08:00:00Z",
+  connectionStatus: "reachable",
+  binding: {
+    transport: "postgres_direct",
+    host: "db.internal",
+    port: 5432,
+    username: "reader",
+  },
+};
+
+const target: DescriptionSourceSamplingTarget = {
+  targetId: "22222222-2222-4222-8222-222222222222",
+  tableName: 'patient"facts',
+  columnNames: ['status"code', "ward"],
+};
+
+test("samples at most five source rows and five distinct non-null examples in a read-only transaction", async () => {
+  const query = vi.fn(async (sql: string) => {
+    if (!sql.startsWith("SELECT")) return { rows: [] };
+    return {
+      rows: [
+        { 'status"code': "active", ward: null },
+        { 'status"code': "pending", ward: "A" },
+        { 'status"code': "closed", ward: "A" },
+        { 'status"code': "transferred", ward: "B" },
+        { 'status"code': "unknown", ward: "C" },
+        { 'status"code': "must-not-be-sampled", ward: "D" },
+      ],
+    };
+  });
+  const end = vi.fn(async () => undefined);
+  const access: CatalogPostgresAccess = {
+    connect: vi.fn(async () => ({ query, end }) as CatalogDatabaseClient),
+  };
+  const sampler = new PostgresDescriptionSourceSampler(access);
+  const controller = new AbortController();
+
+  const samples = await sampler.sample(database, [target], controller.signal);
+
+  expect(samples).toEqual([{
+    targetId: target.targetId,
+    tableName: target.tableName,
+    rows: [
+      { fields: [{ name: 'status"code', value: "active" }, { name: "ward", value: null }] },
+      { fields: [{ name: 'status"code', value: "pending" }, { name: "ward", value: "A" }] },
+      { fields: [{ name: 'status"code', value: "closed" }, { name: "ward", value: "A" }] },
+      { fields: [{ name: 'status"code', value: "transferred" }, { name: "ward", value: "B" }] },
+      { fields: [{ name: 'status"code', value: "unknown" }, { name: "ward", value: "C" }] },
+    ],
+    representativeValues: [
+      {
+        column: 'status"code',
+        values: ["active", "pending", "closed", "transferred"],
+      },
+      { column: "ward", values: ["A"] },
+    ],
+  }]);
+  expect(access.connect).toHaveBeenCalledWith(database, controller.signal);
+  expect(samples[0]!.representativeValues.flatMap((entry) => entry.values)).toHaveLength(5);
+  expect(query.mock.calls).toEqual([
+    ["BEGIN TRANSACTION READ ONLY", []],
+    [
+      'SELECT LEFT(("status""code")::text, $1) AS "status""code", LEFT(("ward")::text, $1) AS "ward" FROM "clinical""data"."patient""facts" LIMIT $2',
+      [256, 5],
+    ],
+    ["ROLLBACK", []],
+  ]);
+  expect(query.mock.calls.map(([sql]) => String(sql).split(" ")[0])).toEqual([
+    "BEGIN",
+    "SELECT",
+    "ROLLBACK",
+  ]);
+  expect(end).toHaveBeenCalledOnce();
+});
+
+test("rolls back and closes the source connection when sampling fails", async () => {
+  const query = vi.fn(async (sql: string) => {
+    if (sql.startsWith("SELECT")) throw new Error("distinctive-source-secret");
+    return { rows: [] };
+  });
+  const end = vi.fn(async () => undefined);
+  const access: CatalogPostgresAccess = {
+    connect: vi.fn(async () => ({ query, end }) as CatalogDatabaseClient),
+  };
+  const sampler = new PostgresDescriptionSourceSampler(access);
+  const controller = new AbortController();
+
+  await expect(sampler.sample(database, [target], controller.signal)).rejects.toThrow();
+
+  expect(query).toHaveBeenCalledWith("ROLLBACK", []);
+  expect(end).toHaveBeenCalledOnce();
+});

backend/test/catalog-operation-coordinator.test.ts

@@ -18,3 +18,23 @@ test("reserves duplicate database ids only once for a batch operation", async ()
   expect(await coordinator.runMany(["database-a", "database-a"], async () => "completed"))
     .toBe("completed");
 });
+
+test("stale generation recovery releases only its own reservation token", () => {
+  const coordinator = new CatalogOperationCoordinator();
+  const releaseOtherOperation = coordinator.reserve("database-a");
+
+  coordinator.releaseStale("database-a", "description_generation");
+  expect(() => coordinator.reserve("database-a")).toThrow(
+    "A database operation is already in progress",
+  );
+  releaseOtherOperation();
+
+  const releaseStaleGeneration = coordinator.reserve("database-a", "description_generation");
+  coordinator.releaseStale("database-a", "description_generation");
+  const releaseNewOperation = coordinator.reserve("database-a");
+  releaseStaleGeneration();
+  expect(() => coordinator.reserve("database-a")).toThrow(
+    "A database operation is already in progress",
+  );
+  releaseNewOperation();
+});

backend/test/catalog-postgres-access.test.ts

@@ -169,3 +169,23 @@ test("connects pg through OpenSSH, supplies askpass, and releases all secret lea
   expect(child.kill).toHaveBeenCalledWith("SIGTERM");
   expect(leasedPaths.some(existsSync)).toBe(false);
 });
+
+test("fails before creating a transport when the sampling signal is already aborted", async () => {
+  const store = secretStore();
+  store.putMany("psd-clinical", {
+    [CATALOG_SECRET_IDS.password]: "db-password",
+    [CATALOG_SECRET_IDS.sshPrivateKey]: "PRIVATE KEY\n",
+    [CATALOG_SECRET_IDS.sshKnownHosts]: "bastion.internal ssh-ed25519 AAAATEST\n",
+  });
+  const spawnSsh = vi.fn(() => fakeChild());
+  const createClient = vi.fn();
+  const access = new ConcreteCatalogPostgresAccess(store, { spawnSsh, createClient });
+  const controller = new AbortController();
+  controller.abort();
+
+  await expect(access.connect(sshDatabase(), controller.signal)).rejects.toThrow(
+    "PostgreSQL connector aborted",
+  );
+  expect(spawnSsh).not.toHaveBeenCalled();
+  expect(createClient).not.toHaveBeenCalled();
+});

backend/test/catalog-repository.integration.test.ts

@@ -9,6 +9,7 @@ import { up as upDatabases } from "../src/catalog/migrations/001_workspace_datab
 import { up as upTables } from "../src/catalog/migrations/002_catalog_tables.js";
 import { up as upSchemaSync } from "../src/catalog/migrations/003_catalog_schema_sync.js";
 import { up as upRuntimeSequencePrivileges } from "../src/catalog/migrations/004_catalog_runtime_sequence_privileges.js";
+import { up as upDescriptionGeneration } from "../src/catalog/migrations/005_description_generation_runs.js";
 
 const dockerAvailable = spawnSync("docker", ["info"], { stdio: "ignore" }).status === 0;
 
@@ -200,3 +201,285 @@ test.skipIf(!dockerAvailable)("PostgreSQL repository performs scoped metadata cl
     await container.stop();
   }
 }, 60_000);
+
+test.skipIf(!dockerAvailable)("PostgreSQL repository atomically consolidates selected table and column descriptions", async () => {
+  const container = await new PostgreSqlContainer("postgres:17.6-bookworm").start();
+  const db = new Kysely<CatalogDatabase>({
+    dialect: new PostgresDialect({ pool: new Pool({ connectionString: container.getConnectionUri() }) }),
+    plugins: [new CamelCasePlugin()],
+  });
+  try {
+    await upDatabases(db);
+    await upTables(db);
+    await upSchemaSync(db);
+    const repository = new KyselyCatalogRepository(db);
+    const database = await repository.create({
+      workspaceId: "consolidation-test",
+      engine: "postgres",
+      databaseName: "warehouse",
+      schema: "public",
+      binding: { transport: "postgres_direct", host: "db.internal", port: 5432, username: "reader" },
+    });
+    const snapshot: ObservedSchemaSnapshot = {
+      schemaVersion: 1,
+      capabilities: { tables: "available", columns: "available", relationships: "available" },
+      tables: [
+        { name: "patients", sourceComment: null },
+        { name: "visits", sourceComment: null },
+      ],
+      columns: [
+        { tableName: "visits", name: "id", ordinalPosition: 1, dataType: "bigint", isNullable: false, defaultExpression: null, primaryKeyPosition: 1, sourceComment: null },
+        { tableName: "visits", name: "patient_id", ordinalPosition: 2, dataType: "bigint", isNullable: false, defaultExpression: null, primaryKeyPosition: null, sourceComment: null },
+      ],
+      relationships: [],
+    };
+    await repository.applySchemaSync(database.id, database.version, "all", [], snapshot);
+    const tables = await repository.listTables(database.id);
+    const patients = tables.find((table) => table.name === "patients")!;
+    const visits = tables.find((table) => table.name === "visits")!;
+    await repository.updateTableMetadata(
+      database.id, patients.id, patients.version, "Old patients", "Generated patients",
+    );
+    await repository.updateTableMetadata(
+      database.id, visits.id, visits.version, "Keep visits", "   ",
+    );
+
+    expect(await repository.consolidateGeneratedDescriptions(
+      database.id, "tables", [patients.id, visits.id],
+    )).toEqual({ copied: 1, skipped: 1 });
+    expect(await repository.getTable(database.id, patients.id)).toMatchObject({
+      description: "Generated patients",
+      generatedDescription: "Generated patients",
+      version: patients.version + 2,
+    });
+    expect(await repository.getTable(database.id, visits.id)).toMatchObject({
+      description: "Keep visits",
+      generatedDescription: "   ",
+      version: visits.version + 1,
+    });
+
+    const columns = await repository.listColumns(database.id, visits.id);
+    const id = columns.find((column) => column.name === "id")!;
+    const patientId = columns.find((column) => column.name === "patient_id")!;
+    await repository.updateColumnMetadata(
+      database.id, visits.id, id.id, id.version, "Old id", "Generated id",
+    );
+    await repository.updateColumnMetadata(
+      database.id, visits.id, patientId.id, patientId.version, "Keep patient reference", null,
+    );
+
+    expect(await repository.consolidateGeneratedDescriptions(
+      database.id, "columns", [id.id, patientId.id],
+    )).toEqual({ copied: 1, skipped: 1 });
+    expect(await repository.getColumn(database.id, visits.id, id.id)).toMatchObject({
+      description: "Generated id",
+      generatedDescription: "Generated id",
+      version: id.version + 2,
+    });
+    expect(await repository.getColumn(database.id, visits.id, patientId.id)).toMatchObject({
+      description: "Keep patient reference",
+      generatedDescription: null,
+      version: patientId.version + 1,
+    });
+
+    const currentVisits = (await repository.getTable(database.id, visits.id))!;
+    await repository.updateTableMetadata(
+      database.id, visits.id, currentVisits.version, "Still curated visits", "Generated visits",
+    );
+    expect(await repository.consolidateGeneratedDescriptions(database.id, "tables", [
+      visits.id,
+      "99999999-9999-4999-8999-999999999999",
+    ])).toBeUndefined();
+    expect(await repository.getTable(database.id, visits.id)).toMatchObject({
+      description: "Still curated visits",
+      generatedDescription: "Generated visits",
+    });
+  } finally {
+    await db.destroy();
+    await container.stop();
+  }
+}, 60_000);
+
+test.skipIf(!dockerAvailable)("PostgreSQL repository persists globally exclusive Description Generation Runs and ordered events", async () => {
+  const container = await new PostgreSqlContainer("postgres:17.6-bookworm").start();
+  const db = new Kysely<CatalogDatabase>({
+    dialect: new PostgresDialect({ pool: new Pool({ connectionString: container.getConnectionUri() }) }),
+    plugins: [new CamelCasePlugin()],
+  });
+  try {
+    await upDatabases(db);
+    await upTables(db);
+    await upSchemaSync(db);
+    await upDescriptionGeneration(db);
+    const repository = new KyselyCatalogRepository(db);
+    const firstDatabase = await repository.create({
+      workspaceId: "generation-one",
+      engine: "postgres",
+      databaseName: "warehouse_one",
+      schema: "public",
+      binding: { transport: "postgres_direct", host: "one.internal", port: 5432, username: "reader" },
+    });
+    const secondDatabase = await repository.create({
+      workspaceId: "generation-two",
+      engine: "postgres",
+      databaseName: "warehouse_two",
+      schema: "public",
+      binding: { transport: "postgres_direct", host: "two.internal", port: 5432, username: "reader" },
+    });
+    await repository.applySchemaSync(firstDatabase.id, firstDatabase.version, "all", [], {
+      schemaVersion: 1,
+      capabilities: { tables: "available", columns: "available", relationships: "available" },
+      tables: [{ name: "patients", sourceComment: "Clinical patients" }],
+      columns: [{
+        tableName: "patients",
+        name: "birth_date",
+        ordinalPosition: 1,
+        dataType: "date",
+        isNullable: true,
+        defaultExpression: null,
+        primaryKeyPosition: null,
+        sourceComment: "Patient date of birth",
+      }],
+      relationships: [],
+    });
+    const table = (await repository.listTables(firstDatabase.id))[0]!;
+    const column = (await repository.listColumns(firstDatabase.id, table.id))[0]!;
+
+    const run = await repository.createDescriptionGenerationRun(
+      firstDatabase.id,
+      "selected_columns",
+      "openai-mini",
+      "it",
+      1,
+    );
+    expect(run).toMatchObject({
+      databaseId: firstDatabase.id,
+      scope: "selected_columns",
+      modelId: "openai-mini",
+      language: "it",
+      status: "queued",
+      total: 1,
+      processed: 0,
+      generated: 0,
+      nonGeneratable: 0,
+      failed: 0,
+      startedAt: null,
+      finishedAt: null,
+      errorSummary: null,
+    });
+    await expect(repository.createDescriptionGenerationRun(
+      secondDatabase.id,
+      "selected_columns",
+      "openai-mini",
+      "en",
+      1,
+    )).rejects.toThrow("A description generation run is already active");
+    await repository.updateDescriptionGenerationRun(run.id, {
+      status: "running",
+      startedAt: new Date().toISOString(),
+    });
+    await expect(repository.createDescriptionGenerationRun(
+      secondDatabase.id,
+      "selected_columns",
+      "openai-mini",
+      "en",
+      1,
+    )).rejects.toThrow("A description generation run is already active");
+
+    await repository.appendDescriptionGenerationEvent(run.id, "info", "Description generation queued.");
+    await repository.appendDescriptionGenerationEvent(run.id, "info", "Description generation started.");
+    expect(await repository.listDescriptionGenerationEvents(run.id, 1)).toEqual([
+      expect.objectContaining({
+        runId: run.id,
+        sequence: 2,
+        level: "info",
+        message: "Description generation started.",
+        createdAt: expect.any(String),
+      }),
+    ]);
+
+    const updatedColumn = await repository.updateColumnMetadata(
+      firstDatabase.id,
+      table.id,
+      column.id,
+      column.version,
+      column.description,
+      "Data di nascita del paziente.",
+    );
+    expect(updatedColumn).toMatchObject({
+      generatedDescription: "Data di nascita del paziente.",
+      version: column.version + 1,
+    });
+    expect(await repository.updateDescriptionGenerationRun(run.id, {
+      status: "completed",
+      processed: 1,
+      generated: 1,
+      startedAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+    })).toMatchObject({
+      status: "completed",
+      processed: 1,
+      generated: 1,
+    });
+
+    const next = await repository.createDescriptionGenerationRun(
+      secondDatabase.id,
+      "missing",
+      "openai-mini",
+      "en",
+      1,
+    );
+    expect(await repository.getDescriptionGenerationRun(next.id)).toMatchObject({
+      scope: "missing",
+      total: 1,
+    });
+    await repository.updateDescriptionGenerationRun(next.id, {
+      status: "running",
+      startedAt: new Date().toISOString(),
+    });
+    expect(await repository.updateDescriptionGenerationRun(next.id, {
+      status: "failed",
+      processed: 1,
+      failed: 1,
+      finishedAt: new Date().toISOString(),
+      errorSummary: "The model provider request failed.",
+    })).toMatchObject({
+      status: "failed",
+      processed: 1,
+      failed: 1,
+      errorSummary: "The model provider request failed.",
+    });
+
+    const allRun = await repository.createDescriptionGenerationRun(
+      firstDatabase.id,
+      "all",
+      "openai-mini",
+      "it",
+      2,
+    );
+    expect(await repository.getDescriptionGenerationRun(allRun.id)).toMatchObject({
+      scope: "all",
+      total: 2,
+    });
+    expect(await repository.getActiveDescriptionGenerationRun()).toMatchObject({ id: allRun.id });
+    expect((await repository.listDescriptionGenerationRuns(2)).map((candidate) => candidate.id)).toEqual([
+      allRun.id,
+      next.id,
+    ]);
+
+    expect(await repository.interruptActiveDescriptionGenerationRuns(
+      "Description generation was interrupted by backend restart.",
+    )).toEqual([
+      expect.objectContaining({
+        id: allRun.id,
+        status: "interrupted",
+        finishedAt: expect.any(String),
+        errorSummary: "Description generation was interrupted by backend restart.",
+      }),
+    ]);
+    expect(await repository.getActiveDescriptionGenerationRun()).toBeUndefined();
+  } finally {
+    await db.destroy();
+    await container.stop();
+  }
+}, 60_000);

backend/test/catalog-schema-routes.test.ts

@@ -5,6 +5,7 @@ import { afterEach, expect, test, vi } from "vitest";
 import { buildApp } from "../src/app.js";
 import { loadConfig } from "../src/config.js";
 import { MemoryCatalogRepository } from "../src/catalog/memory-repository.js";
+import { CatalogOperationCoordinator } from "../src/catalog/operation-coordinator.js";
 import type { CatalogSchemaIntrospector } from "../src/catalog/schema-introspector.js";
 import type { CatalogSyncRun, ObservedSchemaSnapshot } from "../src/catalog/types.js";
 import { WorkspaceSecretStore } from "../src/workspaces/secret-store.js";
@@ -95,7 +96,7 @@ async function waitFor(repository: MemoryCatalogRepository, runId: string, state
   throw new Error(`Run ${runId} did not reach ${state}`);
 }
 
-async function setup() {
+async function setup(env: Record<string, string> = {}) {
   const secretRoot = mkdtempSync(join(tmpdir(), "catalog-schema-secret-"));
   const runtimeRoot = mkdtempSync(join(tmpdir(), "catalog-schema-runtime-"));
   roots.push(secretRoot, runtimeRoot);
@@ -116,21 +117,23 @@ async function setup() {
     return structuredClone(observed);
   });
   const introspector: CatalogSchemaIntrospector = { scan };
+  const operations = new CatalogOperationCoordinator();
   const registry = {
     list: vi.fn(async () => [revision]),
     listCatalog: vi.fn(async () => [{ id: "psd-clinical", name: "Policlinico San Donato", configurationState: "ready", revision }]),
     read: vi.fn(async () => ({ workspace, revision })),
   } as unknown as WorkspaceRegistry;
-  const app = buildApp(loadConfig({ THT_HARNESS_DIR: "/missing", NODE_ENV: "test" }), {
+  const app = buildApp(loadConfig({ THT_HARNESS_DIR: "/missing", NODE_ENV: "test", ...env }), {
     thtRunner: {} as never,
     workspaceRegistry: registry,
     workspaceSecretStore: new WorkspaceSecretStore({ root: secretRoot, runtimeRoot, installationId: "test" }),
     catalogRepository: repository,
     catalogSchemaIntrospector: introspector,
+    catalogOperationCoordinator: operations,
     workspaceDiagnoser: vi.fn(),
   });
   return {
-    app, repository, database: (await repository.get(created.id))!, scan,
+    app, repository, database: (await repository.get(created.id))!, scan, operations,
     setObserved(next: ObservedSchemaSnapshot) { observed = next; },
   };
 }
@@ -243,6 +246,207 @@ test("keeps generated descriptions editable and preserves them across synchroniz
   expect(await repository.getColumn(database.id, patients.id, idColumn.id)).toMatchObject({ description: "Reviewed key", generatedDescription: "Generated key draft" });
 });
 
+test("consolidates non-empty generated table descriptions and reports skipped selections", async () => {
+  const { app, repository, database, scan } = await setup();
+  await seedCatalog(repository, database);
+  const tables = await repository.listTables(database.id);
+  const patients = tables.find((table) => table.name === "patients")!;
+  const visits = tables.find((table) => table.name === "visits")!;
+  await repository.updateTableMetadata(
+    database.id,
+    patients.id,
+    patients.version,
+    "Curated patients",
+    "Generated patients",
+  );
+  await repository.updateTableMetadata(
+    database.id,
+    visits.id,
+    visits.version,
+    "Keep curated visits",
+    null,
+  );
+
+  const response = await app.inject({
+    method: "POST",
+    url: `/catalog/databases/${database.id}/descriptions/consolidate`,
+    payload: { target: "tables", targetIds: [patients.id, visits.id] },
+  });
+
+  expect(response.statusCode).toBe(200);
+  expect(response.json()).toEqual({ copied: 1, skipped: 1 });
+  expect(await repository.getTable(database.id, patients.id)).toMatchObject({
+    description: "Generated patients",
+    generatedDescription: "Generated patients",
+    version: patients.version + 2,
+  });
+  expect(await repository.getTable(database.id, visits.id)).toMatchObject({
+    description: "Keep curated visits",
+    generatedDescription: null,
+    version: visits.version + 1,
+  });
+  expect(scan).not.toHaveBeenCalled();
+});
+
+test("consolidates non-empty generated column descriptions and preserves curated text for empty proposals", async () => {
+  const { app, repository, database, scan } = await setup();
+  await seedCatalog(repository, database);
+  const visits = (await repository.listTables(database.id)).find((table) => table.name === "visits")!;
+  const columns = await repository.listColumns(database.id, visits.id);
+  const id = columns.find((column) => column.name === "id")!;
+  const patientId = columns.find((column) => column.name === "patient_id")!;
+  await repository.updateColumnMetadata(
+    database.id,
+    visits.id,
+    id.id,
+    id.version,
+    "Curated visit identifier",
+    "Generated visit identifier",
+  );
+  await repository.updateColumnMetadata(
+    database.id,
+    visits.id,
+    patientId.id,
+    patientId.version,
+    "Keep curated patient reference",
+    "",
+  );
+
+  const response = await app.inject({
+    method: "POST",
+    url: `/catalog/databases/${database.id}/descriptions/consolidate`,
+    payload: { target: "columns", targetIds: [id.id, patientId.id] },
+  });
+
+  expect(response.statusCode).toBe(200);
+  expect(response.json()).toEqual({ copied: 1, skipped: 1 });
+  expect(await repository.getColumn(database.id, visits.id, id.id)).toMatchObject({
+    description: "Generated visit identifier",
+    generatedDescription: "Generated visit identifier",
+    version: id.version + 2,
+  });
+  expect(await repository.getColumn(database.id, visits.id, patientId.id)).toMatchObject({
+    description: "Keep curated patient reference",
+    generatedDescription: "",
+    version: patientId.version + 1,
+  });
+  expect(scan).not.toHaveBeenCalled();
+});
+
+test("rejects description consolidation while the Workspace Database is reserved", async () => {
+  const { app, repository, database, operations } = await setup();
+  await seedCatalog(repository, database);
+  const table = (await repository.listTables(database.id))[0]!;
+  const edited = await repository.updateTableMetadata(
+    database.id,
+    table.id,
+    table.version,
+    "Existing curated text",
+    "Generated text",
+  );
+  const release = operations.reserve(database.id);
+  try {
+    const response = await app.inject({
+      method: "POST",
+      url: `/catalog/databases/${database.id}/descriptions/consolidate`,
+      payload: { target: "tables", targetIds: [table.id] },
+    });
+
+    expect(response.statusCode).toBe(409);
+    expect(response.json()).toEqual({
+      code: "database_operation_in_progress",
+      message: "A database operation is already in progress.",
+    });
+    expect(await repository.getTable(database.id, table.id)).toMatchObject({
+      description: "Existing curated text",
+      generatedDescription: "Generated text",
+      version: edited!.version,
+    });
+  } finally {
+    release();
+  }
+});
+
+test("requires database.manage for description consolidation", async () => {
+  const { app, repository, database } = await setup({ AUTH_MODE: "upstream" });
+  await seedCatalog(repository, database);
+  const table = (await repository.listTables(database.id))[0]!;
+  const response = await app.inject({
+    method: "POST",
+    url: `/catalog/databases/${database.id}/descriptions/consolidate`,
+    headers: {
+      "x-thoth-principal-issuer": "portal",
+      "x-thoth-principal-subject": "catalog-reader",
+      "x-thoth-is-admin": "0",
+    },
+    payload: { target: "tables", targetIds: [table.id] },
+  });
+
+  expect(response.statusCode).toBe(403);
+  expect(response.json()).toEqual({ code: "auth_forbidden", error: "This operation is not permitted" });
+});
+
+test("strictly validates description consolidation database and target ids", async () => {
+  const { app, repository, database } = await setup();
+  await seedCatalog(repository, database);
+  const table = (await repository.listTables(database.id))[0]!;
+
+  const responses = await Promise.all([
+    app.inject({
+      method: "POST",
+      url: "/catalog/databases/not-a-uuid/descriptions/consolidate",
+      payload: { target: "tables", targetIds: [table.id] },
+    }),
+    app.inject({
+      method: "POST",
+      url: `/catalog/databases/${database.id}/descriptions/consolidate`,
+      payload: { target: "tables", targetIds: ["not-a-uuid"] },
+    }),
+    app.inject({
+      method: "POST",
+      url: `/catalog/databases/${database.id}/descriptions/consolidate`,
+      payload: { target: "tables", targetIds: [table.id], unexpected: true },
+    }),
+  ]);
+
+  expect(responses.map((response) => response.statusCode)).toEqual([400, 400, 400]);
+  for (const response of responses) {
+    expect(response.json()).toEqual({
+      code: "description_consolidation_invalid",
+      message: "Description consolidation request is invalid.",
+    });
+  }
+});
+
+test("rejects a missing consolidation target without copying valid selections", async () => {
+  const { app, repository, database } = await setup();
+  await seedCatalog(repository, database);
+  const table = (await repository.listTables(database.id))[0]!;
+  const edited = await repository.updateTableMetadata(
+    database.id,
+    table.id,
+    table.version,
+    "Existing curated text",
+    "Generated text",
+  );
+
+  const response = await app.inject({
+    method: "POST",
+    url: `/catalog/databases/${database.id}/descriptions/consolidate`,
+    payload: {
+      target: "tables",
+      targetIds: [table.id, "99999999-9999-4999-8999-999999999999"],
+    },
+  });
+
+  expect(response.statusCode).toBe(404);
+  expect(await repository.getTable(database.id, table.id)).toMatchObject({
+    description: "Existing curated text",
+    generatedDescription: "Generated text",
+    version: edited!.version,
+  });
+});
+
 test("waits for confirmation and rescans before applying destructive changes", async () => {
   const { app, repository, database, scan, setObserved } = await setup();
   const first = await app.inject({ method: "POST", url: `/catalog/databases/${database.id}/sync-runs`, payload: { version: database.version, scope: "all", tableIds: [] } });

backend/test/config.test.ts

@@ -290,6 +290,14 @@ test("loadConfig accepts only an absolute generic model key file", () => {
     .toThrow(/model credential configuration is invalid/);
 });
 
+test("loadConfig accepts only an absolute runtime installation descriptor path", () => {
+  expect(loadConfig({
+    THT_INSTALLATION_CONFIG_FILE: "/run/thothii-installation/thothii-installation.yaml",
+  }).installationConfigFile).toBe("/run/thothii-installation/thothii-installation.yaml");
+  expect(() => loadConfig({ THT_INSTALLATION_CONFIG_FILE: "host/thothii-installation.yaml" }))
+    .toThrow("installation configuration is invalid");
+});
+
 test("loadConfig accepts a file-backed catalog role and rejects partial catalog configuration", () => {
   expect(loadConfig({
     THT_CATALOG_DB_HOST: "catalog-db",

backend/test/metadata-generation-models.test.ts

@@ -0,0 +1,271 @@
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test, vi } from "vitest";
+import { buildApp } from "../src/app.js";
+import { MemoryCatalogRepository } from "../src/catalog/memory-repository.js";
+import {
+  loadMetadataGenerationModels,
+  MetadataGenerationModelUnavailableError,
+} from "../src/catalog/metadata-generation-models.js";
+import { loadConfig } from "../src/config.js";
+import type { WorkspaceRegistry } from "../src/workspaces/registry.js";
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function metadataConfiguration(
+  metadataGeneration: string,
+  secrets = "OPENAI_API_KEY=raw-provider-secret\n",
+) {
+  const root = mkdtempSync(join(tmpdir(), "thothii-metadata-models-"));
+  roots.push(root);
+  const installationFile = join(root, "thothii-installation.yaml");
+  const secretsFile = join(root, "thothii.secrets");
+  writeFileSync(installationFile, metadataGeneration, { mode: 0o600 });
+  writeFileSync(secretsFile, secrets, { mode: 0o600 });
+  chmodSync(installationFile, 0o600);
+  chmodSync(secretsFile, 0o600);
+  return { installationFile, secretsFile };
+}
+
+function appFor(installationFile: string, secretsFile: string) {
+  const config = loadConfig({
+    NODE_ENV: "test",
+    THT_HARNESS_DIR: "/missing",
+    THT_INSTALLATION_CONFIG_FILE: installationFile,
+    THT_SECRETS_FILE: secretsFile,
+    PI_PROVIDER: "unrelated-pi-provider",
+    PI_MODEL: "unrelated-pi-model",
+  });
+  return buildApp(config, {
+    thtRunner: {} as never,
+    workspaceRegistry: { list: vi.fn(async () => []) } as unknown as WorkspaceRegistry,
+    workspaceDiagnoser: vi.fn(),
+    catalogRepository: new MemoryCatalogRepository(),
+  });
+}
+
+test("exposes only safe metadata-generation choices and their configured default", async () => {
+  const { installationFile, secretsFile } = metadataConfiguration(`metadataGeneration:
+  default: openai-mini
+  models:
+    - id: openai-mini
+      label: OpenAI Mini
+      litellm:
+        provider: openai
+        model: gpt-4.1-mini
+        endpoint:
+          baseUrl: https://api.openai.example/v1
+          apiVersion: "2026-08-01"
+      apiKeyEnv: OPENAI_API_KEY
+`);
+  const app = appFor(installationFile, secretsFile);
+
+  const response = await app.inject({ method: "GET", url: "/catalog/metadata-generation/models" });
+
+  expect(response.statusCode).toBe(200);
+  expect(response.json()).toEqual({
+    models: [{ id: "openai-mini", label: "OpenAI Mini" }],
+    default: "openai-mini",
+  });
+  expect(response.body).not.toMatch(/openai\/gpt|gpt-4\.1|api\.openai|OPENAI_API_KEY|raw-provider-secret/);
+  await app.close();
+});
+
+test("rejects an unprotected installation descriptor", () => {
+  const { installationFile, secretsFile } = metadataConfiguration(`metadataGeneration:
+  default: openai-mini
+  models:
+    - id: openai-mini
+      label: OpenAI Mini
+      litellm: {provider: openai, model: gpt-4.1-mini}
+      apiKeyEnv: OPENAI_API_KEY
+`);
+  chmodSync(installationFile, 0o644);
+
+  expect(() => loadMetadataGenerationModels({ installationFile, secretsFile }))
+    .toThrow("metadata-generation installation is unavailable");
+});
+
+test("returns an empty safe catalog when no metadata-generation model is configured", async () => {
+  const { installationFile, secretsFile } = metadataConfiguration("profile: local\n");
+  const app = appFor(installationFile, secretsFile);
+
+  const response = await app.inject({ method: "GET", url: "/catalog/metadata-generation/models" });
+
+  expect(response.statusCode).toBe(200);
+  expect(response.json()).toEqual({ models: [], default: null });
+  await app.close();
+});
+
+test("resolves only a configured selection for the later generation boundary", () => {
+  const { installationFile, secretsFile } = metadataConfiguration(`metadataGeneration:
+  default: openai-mini
+  models:
+    - id: openai-mini
+      label: OpenAI Mini
+      litellm:
+        provider: openai
+        model: gpt-4.1-mini
+        endpoint: {baseUrl: https://api.openai.example/v1, apiVersion: "2026-08-01"}
+      apiKeyEnv: OPENAI_API_KEY
+`);
+  const models = loadMetadataGenerationModels({ installationFile, secretsFile });
+
+  expect(models.resolve("openai-mini")).toEqual({
+    id: "openai-mini",
+    provider: "openai",
+    model: "gpt-4.1-mini",
+    endpoint: { baseUrl: "https://api.openai.example/v1", apiVersion: "2026-08-01" },
+    apiKeyEnv: "OPENAI_API_KEY",
+    apiKey: "raw-provider-secret",
+  });
+  expect(() => models.resolve("unknown-model")).toThrow(MetadataGenerationModelUnavailableError);
+});
+
+test("loads DeepSeek, GLM, and an explicit keyless Qwen endpoint from installation setup", () => {
+  const { installationFile, secretsFile } = metadataConfiguration(`metadataGeneration:
+  default: glm-53
+  models:
+    - id: deepseek-v4-pro
+      label: DeepSeek V4 Pro
+      litellm: {provider: deepseek, model: deepseek-v4-pro}
+      apiKeyEnv: DEEPSEEK_API_KEY
+    - id: glm-53
+      label: GLM 5.3
+      litellm:
+        provider: openai
+        model: glm-5.3
+        endpoint: {baseUrl: https://api.z.ai/api/coding/paas/v4}
+      apiKeyEnv: ZAI_API_KEY
+    - id: qwen-36
+      label: Qwen 3.6
+      litellm:
+        provider: openai
+        model: qwen3.6-35b-a3b
+        disableThinking: true
+        endpoint: {baseUrl: https://models.internal.example/v1}
+`, "DEEPSEEK_API_KEY=deepseek-secret\nZAI_API_KEY=zai-secret\n");
+
+  const models = loadMetadataGenerationModels({ installationFile, secretsFile });
+
+  expect(models.catalog()).toEqual({
+    models: [
+      { id: "deepseek-v4-pro", label: "DeepSeek V4 Pro" },
+      { id: "glm-53", label: "GLM 5.3" },
+      { id: "qwen-36", label: "Qwen 3.6" },
+    ],
+    default: "glm-53",
+  });
+  expect(models.resolve("deepseek-v4-pro")).toMatchObject({
+    apiKeyEnv: "DEEPSEEK_API_KEY",
+    apiKey: "deepseek-secret",
+  });
+  expect(models.resolve("qwen-36")).toEqual({
+    id: "qwen-36",
+    provider: "openai",
+    model: "qwen3.6-35b-a3b",
+    disableThinking: true,
+    endpoint: { baseUrl: "https://models.internal.example/v1" },
+  });
+});
+
+test("loads an explicit keyless endpoint without a secret bundle", () => {
+  const { installationFile } = metadataConfiguration(`metadataGeneration:
+  default: qwen-36
+  models:
+    - id: qwen-36
+      label: Qwen 3.6
+      litellm:
+        provider: openai
+        model: qwen3.6-35b-a3b
+        disableThinking: true
+        endpoint: {baseUrl: https://models.internal.example/v1}
+`);
+
+  expect(loadMetadataGenerationModels({ installationFile }).resolve("qwen-36")).toEqual({
+    id: "qwen-36",
+    provider: "openai",
+    model: "qwen3.6-35b-a3b",
+    disableThinking: true,
+    endpoint: { baseUrl: "https://models.internal.example/v1" },
+  });
+});
+
+test.each([
+  ["invalid YAML", "metadataGeneration: [\n", "OPENAI_API_KEY=secret\n", /invalid YAML/],
+  ["duplicate ids", `metadataGeneration:
+  default: openai-mini
+  models:
+    - {id: openai-mini, label: One, litellm: {provider: openai, model: gpt-4.1-mini}, apiKeyEnv: OPENAI_API_KEY}
+    - {id: openai-mini, label: Two, litellm: {provider: openai, model: gpt-4.1}, apiKeyEnv: OPENAI_API_KEY}
+`, "OPENAI_API_KEY=secret\n", /model id "openai-mini" is duplicated/],
+  ["missing default", `metadataGeneration:
+  models:
+    - {id: openai-mini, label: One, litellm: {provider: openai, model: gpt-4.1-mini}, apiKeyEnv: OPENAI_API_KEY}
+`, "OPENAI_API_KEY=secret\n", /default is required/],
+  ["unknown default", `metadataGeneration:
+  default: absent
+  models:
+    - {id: openai-mini, label: One, litellm: {provider: openai, model: gpt-4.1-mini}, apiKeyEnv: OPENAI_API_KEY}
+`, "OPENAI_API_KEY=secret\n", /default "absent" is not configured/],
+  ["malformed settings", `metadataGeneration:
+  default: openai-mini
+  models:
+    - {id: openai-mini, label: One, litellm: {provider: "open ai", model: gpt-4.1-mini}, apiKeyEnv: OPENAI_API_KEY}
+`, "OPENAI_API_KEY=secret\n", /configuration is invalid/],
+  ["malformed endpoint", `metadataGeneration:
+  default: openai-mini
+  models:
+    - id: openai-mini
+      label: One
+      litellm: {provider: openai, model: gpt-4.1-mini, endpoint: {baseUrl: not-a-url}}
+      apiKeyEnv: OPENAI_API_KEY
+`, "OPENAI_API_KEY=secret\n", /configuration is invalid/],
+  ["keyless hosted model without endpoint", `metadataGeneration:
+  default: openai-mini
+  models:
+    - {id: openai-mini, label: One, litellm: {provider: openai, model: gpt-4.1-mini}}
+`, "", /configuration is invalid/],
+  ["disable thinking without endpoint", `metadataGeneration:
+  default: openai-mini
+  models:
+    - id: openai-mini
+      label: One
+      litellm: {provider: openai, model: gpt-4.1-mini, disableThinking: true}
+      apiKeyEnv: OPENAI_API_KEY
+`, "OPENAI_API_KEY=secret\n", /configuration is invalid/],
+  ["unallowed secret reference", `metadataGeneration:
+  default: openai-mini
+  models:
+    - {id: openai-mini, label: One, litellm: {provider: openai, model: gpt-4.1-mini}, apiKeyEnv: THT_DWH_API_KEY}
+`, "THT_DWH_API_KEY=secret\n", /configuration is invalid/],
+  ["missing referenced secret", `metadataGeneration:
+  default: openai-mini
+  models:
+    - {id: openai-mini, label: One, litellm: {provider: openai, model: gpt-4.1-mini}, apiKeyEnv: OPENAI_API_KEY}
+`, "THT_DWH_API_KEY=secret\n", /secret "OPENAI_API_KEY" is missing/],
+  ["unusable referenced secret", `metadataGeneration:
+  default: openai-mini
+  models:
+    - {id: openai-mini, label: One, litellm: {provider: openai, model: gpt-4.1-mini}, apiKeyEnv: OPENAI_API_KEY}
+`, "OPENAI_API_KEY=secret with whitespace\n", /secret "OPENAI_API_KEY" is unusable/],
+] as const)("rejects %s metadata-generation configuration", (_name, yaml, secrets, expected) => {
+  const { installationFile, secretsFile } = metadataConfiguration(yaml, secrets);
+  expect(() => loadMetadataGenerationModels({ installationFile, secretsFile })).toThrow(expected);
+});
+
+test("rejects a missing secret-bundle declaration for configured models", () => {
+  const { installationFile } = metadataConfiguration(`metadataGeneration:
+  default: openai-mini
+  models:
+    - {id: openai-mini, label: One, litellm: {provider: openai, model: gpt-4.1-mini}, apiKeyEnv: OPENAI_API_KEY}
+`);
+
+  expect(() => loadMetadataGenerationModels({ installationFile }))
+    .toThrow("metadata-generation keyed models require THT_SECRETS_FILE");
+});

backend/test/model-completer.test.ts

@@ -0,0 +1,256 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test } from "vitest";
+import {
+  ModelCompletionProviderError,
+  PythonModelCompleter,
+} from "../src/catalog/model-completer.js";
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function helper(source: string, options: { terminationGraceMs?: number } = {}) {
+  const root = mkdtempSync(join(tmpdir(), "thothii-model-completer-"));
+  roots.push(root);
+  writeFileSync(join(root, "fake_completion_helper.py"), source, "utf8");
+  return new PythonModelCompleter({
+    pythonExecutable: "python3",
+    cwd: root,
+    helperModule: "fake_completion_helper",
+    timeoutMs: 5_000,
+    ...options,
+  });
+}
+
+async function waitUntil(predicate: () => boolean, timeoutMs = 2_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error("condition was not met before timeout");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+test("uses the short-lived Python helper stdin/stdout protocol without process arguments", async () => {
+  const completer = helper(`
+import json
+import pathlib
+import sys
+
+request = json.loads(sys.stdin.read())
+pathlib.Path("request.json").write_text(
+    json.dumps({"request": request, "argv": sys.argv}, sort_keys=True),
+    encoding="utf-8",
+)
+sys.stdout.write(json.dumps({"ok": True, "content": "Descrizione italiana"}))
+`);
+
+  const content = await completer.complete({
+    model: {
+      id: "openai-mini",
+      provider: "openai",
+      model: "gpt-4.1-mini",
+      endpoint: { baseUrl: "https://models.example.test/v1", apiVersion: "2026-08-01" },
+      apiKeyEnv: "OPENAI_API_KEY",
+      apiKey: "test-provider-secret",
+    },
+    messages: [
+      { role: "system", content: "Return one description." },
+      { role: "user", content: "Private metadata prompt." },
+    ],
+    signal: new AbortController().signal,
+  });
+
+  expect(content).toBe("Descrizione italiana");
+  const captured = JSON.parse(readFileSync(join(roots[0]!, "request.json"), "utf8"));
+  expect(captured.request).toEqual({
+    model: "openai/gpt-4.1-mini",
+    api_key: "test-provider-secret",
+    messages: [
+      { role: "system", content: "Return one description." },
+      { role: "user", content: "Private metadata prompt." },
+    ],
+    api_base: "https://models.example.test/v1",
+    api_version: "2026-08-01",
+  });
+  expect(JSON.stringify(captured.argv)).not.toMatch(/test-provider-secret|Private metadata prompt/);
+});
+
+test("omits api_key for an explicitly configured keyless endpoint", async () => {
+  const completer = helper(`
+import json
+import pathlib
+import sys
+
+request = json.loads(sys.stdin.read())
+pathlib.Path("request.json").write_text(json.dumps(request, sort_keys=True), encoding="utf-8")
+sys.stdout.write(json.dumps({"ok": True, "content": "Descrizione Qwen"}))
+`);
+
+  await expect(completer.complete({
+    model: {
+      id: "qwen-36",
+      provider: "openai",
+      model: "qwen3.6-35b-a3b",
+      disableThinking: true,
+      endpoint: { baseUrl: "https://models.internal.example/v1" },
+    },
+    messages: [{ role: "user", content: "Describe invented metadata." }],
+    signal: new AbortController().signal,
+  })).resolves.toBe("Descrizione Qwen");
+
+  expect(JSON.parse(readFileSync(join(roots[0]!, "request.json"), "utf8"))).toEqual({
+    model: "openai/qwen3.6-35b-a3b",
+    messages: [{ role: "user", content: "Describe invented metadata." }],
+    api_base: "https://models.internal.example/v1",
+    disable_thinking: true,
+  });
+});
+
+test("normalizes helper failures and rejects non-pristine stdout without leaking diagnostics", async () => {
+  const secret = "test-provider-secret";
+  const prompt = "private metadata prompt";
+  const completers = [
+    helper(`
+import json
+import sys
+request = json.loads(sys.stdin.read())
+print(request["api_key"] + " " + request["messages"][0]["content"], file=sys.stderr)
+sys.stdout.write(json.dumps({"ok": False, "error": "provider_failure"}))
+`),
+    helper(`
+import json
+import sys
+sys.stdin.read()
+sys.stdout.write(json.dumps({"ok": True, "content": "first"}) + "\\n" + json.dumps({"ok": True, "content": "second"}))
+`),
+  ];
+
+  for (const completer of completers) {
+    let failure: unknown;
+    try {
+      await completer.complete({
+        model: {
+          id: "openai-mini",
+          provider: "openai",
+          model: "gpt-4.1-mini",
+          apiKeyEnv: "OPENAI_API_KEY",
+          apiKey: secret,
+        },
+        messages: [{ role: "user", content: prompt }],
+        signal: new AbortController().signal,
+      });
+    } catch (error) {
+      failure = error;
+    }
+    expect(failure).toBeInstanceOf(ModelCompletionProviderError);
+    expect(String(failure)).not.toMatch(new RegExp(`${secret}|${prompt}`));
+  }
+});
+
+test("aborting a completion terminates its Python helper and returns a cancellation error", async () => {
+  const completer = helper(`
+import os
+import pathlib
+import signal
+import sys
+import time
+
+sys.stdin.read()
+
+def terminate(_signum, _frame):
+    pathlib.Path("terminated.txt").write_text("SIGTERM", encoding="utf-8")
+    raise SystemExit(0)
+
+signal.signal(signal.SIGTERM, terminate)
+pathlib.Path("pid.txt").write_text(str(os.getpid()), encoding="utf-8")
+while True:
+    time.sleep(0.05)
+`);
+  const controller = new AbortController();
+  const completion = completer.complete({
+    model: {
+      id: "openai-mini",
+      provider: "openai",
+      model: "gpt-4.1-mini",
+      apiKeyEnv: "OPENAI_API_KEY",
+      apiKey: "test-provider-secret",
+    },
+    messages: [{ role: "user", content: "Private metadata prompt." }],
+    signal: controller.signal,
+  });
+  const observed = completion.then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+  const root = roots[0]!;
+  await waitUntil(() => existsSync(join(root, "pid.txt")));
+  const pid = Number(readFileSync(join(root, "pid.txt"), "utf8"));
+
+  controller.abort();
+
+  await expect(observed).resolves.toMatchObject({ name: "ModelCompletionCancelledError" });
+  await waitUntil(() => {
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+  expect(readFileSync(join(root, "terminated.txt"), "utf8")).toBe("SIGTERM");
+});
+
+test("aborting escalates to SIGKILL when the Python helper does not exit after SIGTERM", async () => {
+  const completer = helper(`
+import os
+import pathlib
+import signal
+import sys
+import time
+
+sys.stdin.read()
+
+def ignore_term(_signum, _frame):
+    pathlib.Path("sigterm.txt").write_text("received", encoding="utf-8")
+
+signal.signal(signal.SIGTERM, ignore_term)
+pathlib.Path("pid.txt").write_text(str(os.getpid()), encoding="utf-8")
+while True:
+    time.sleep(0.05)
+`, { terminationGraceMs: 25 });
+  const controller = new AbortController();
+  const observed = completer.complete({
+    model: {
+      id: "openai-mini",
+      provider: "openai",
+      model: "gpt-4.1-mini",
+      apiKeyEnv: "OPENAI_API_KEY",
+      apiKey: "test-provider-secret",
+    },
+    messages: [{ role: "user", content: "Private metadata prompt." }],
+    signal: controller.signal,
+  }).then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+  const root = roots[0]!;
+  await waitUntil(() => existsSync(join(root, "pid.txt")));
+  const pid = Number(readFileSync(join(root, "pid.txt"), "utf8"));
+
+  controller.abort();
+
+  await expect(observed).resolves.toMatchObject({ name: "ModelCompletionCancelledError" });
+  expect(readFileSync(join(root, "sigterm.txt"), "utf8")).toBe("received");
+  await waitUntil(() => {
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+});

backend/test/secret-bundle.test.ts

@@ -2,7 +2,12 @@ import { afterEach, expect, test } from "vitest";
 import { chmodSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { loadSecretBundle, loadSecretBundleWithFs, secretValue } from "../src/config/secret-bundle.js";
+import {
+  loadSecretBundle,
+  loadSecretBundleWithFs,
+  METADATA_GENERATION_SECRET_KEYS,
+  secretValue,
+} from "../src/config/secret-bundle.js";
 
 const dirs: string[] = [];
 afterEach(() => { for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }); });
@@ -22,6 +27,15 @@ test("parses comments, blank lines and values containing equals", () => {
   ]));
 });
 
+test("existing secret consumers accept a bundle containing an allowed metadata-model key", () => {
+  const file = bundle("THT_DWH_API_KEY=dwh-secret\nOPENAI_API_KEY=metadata-secret\n");
+  expect(secretValue({ secretsFile: file }, "THT_DWH_API_KEY")).toBe("dwh-secret");
+});
+
+test.each(METADATA_GENERATION_SECRET_KEYS)("accepts audited metadata-model key %s", (name) => {
+  expect(loadSecretBundle(bundle(`${name}=metadata-secret\n`)).get(name)).toBe("metadata-secret");
+});
+
 test("accepts the fixed OIDC and Authentik secret references", () => {
   const file = bundle("THT_OIDC_CLIENT_SECRET=oidc-secret\nTHT_AUTHENTIK_API_TOKEN=authentik-token\n");
   expect(loadSecretBundle(file)).toEqual(new Map([