@databrainhq/mcp-server 0.3.0-rc.5 → 0.3.0-rc.7

package/dist/{chunk-5IQ7MVUH.js → chunk-JSYG7ULR.js}

@@ -18,7 +18,7 @@ import {
   toolError,
   toolSuccess,
   validateBundle
-} from "./chunk-PRE4CGOV.js";
+} from "./chunk-ETXH5HTT.js";
 
 // src/apps/contract.ts
 import { z } from "zod";
@@ -178,6 +178,12 @@ var TOOL_METADATA = {
   preview_chart: { category: "internal_analytics", workflowIntent: "query_data", effect: "view" },
   save_chart_as_dashboard: { category: "internal_analytics", workflowIntent: "author_dashboard", effect: "commit" },
   // Semantic layer
+  search_semantic_model: { category: "semantic_layer", workflowIntent: "query_data", effect: "read" },
+  get_semantic_entity: { category: "semantic_layer", workflowIntent: "query_data", effect: "read" },
+  propose_semantic_change: { category: "semantic_layer", workflowIntent: "model_data", effect: "read" },
+  apply_semantic_change: { category: "semantic_layer", workflowIntent: "model_data", effect: "commit" },
+  eval_semantic_model: { category: "semantic_layer", workflowIntent: "query_data", effect: "read" },
+  semantic_readiness: { category: "semantic_layer", workflowIntent: "model_data", effect: "read" },
   get_semantic_layer: { category: "semantic_layer", workflowIntent: "query_data", effect: "read" },
   update_semantic_layer: { category: "semantic_layer", workflowIntent: "query_data", effect: "commit" },
   start_semantic_layer_generation: { category: "semantic_layer", workflowIntent: "query_data", effect: "commit" },
@@ -492,18 +498,18 @@ var QueryApi = class {
       throw err;
     }
   }
-  async startSemanticLayerGeneration(datamartId) {
+  async startSemanticLayerGeneration(datamartId2) {
     return this.client.request({
       method: "POST",
-      path: `/api/v2/data-app/datamarts/${encodeURIComponent(datamartId)}/semantic-layer/generate`,
+      path: `/api/v2/data-app/datamarts/${encodeURIComponent(datamartId2)}/semantic-layer/generate`,
       auth: "service",
       invalidateCache: ["semantic_layer_"]
     });
   }
-  async getSemanticLayerGenerationStatus(datamartId) {
+  async getSemanticLayerGenerationStatus(datamartId2) {
     return this.client.request({
       method: "GET",
-      path: `/api/v2/data-app/datamarts/${encodeURIComponent(datamartId)}/semantic-layer/generation-status`,
+      path: `/api/v2/data-app/datamarts/${encodeURIComponent(datamartId2)}/semantic-layer/generation-status`,
       auth: "service"
     });
   }
@@ -526,9 +532,9 @@ function normalizeRecords(value) {
     record.items,
     record.data
   ];
-  for (const candidate of candidates) {
-    if (Array.isArray(candidate)) {
-      return candidate.filter((item) => asRecord(item) !== null);
+  for (const candidate2 of candidates) {
+    if (Array.isArray(candidate2)) {
+      return candidate2.filter((item) => asRecord(item) !== null);
     }
   }
   return [];
@@ -557,6 +563,65 @@ var ScheduledReportsApi = class {
   }
 };
 
+// src/api/semantic-model-api.ts
+var SemanticModelApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  path(id2, verb) {
+    return `/api/v2/semantic/${encodeURIComponent(id2)}/${verb}`;
+  }
+  pull(id2) {
+    return this.client.request({ method: "GET", path: this.path(id2, "pull"), auth: "service" });
+  }
+  retrieve(id2, q, k) {
+    return this.client.request({
+      method: "GET",
+      path: this.path(id2, "retrieve"),
+      auth: "service",
+      query: { q, k: String(k) }
+    });
+  }
+  validate(id2, source2) {
+    return this.client.request({
+      method: "POST",
+      path: this.path(id2, "validate"),
+      auth: "service",
+      body: { source: source2 }
+    });
+  }
+  plan(id2, source2, expected_content_hash) {
+    return this.client.request({
+      method: "POST",
+      path: this.path(id2, "plan"),
+      auth: "service",
+      body: { source: source2, expected_content_hash }
+    });
+  }
+  apply(id2, source2, expected_content_hash) {
+    return this.client.request({
+      method: "POST",
+      path: this.path(id2, "apply"),
+      auth: "service",
+      body: { source: source2, expected_content_hash },
+      noRetryOnTimeout: true
+    });
+  }
+  evaluate(id2, body) {
+    return this.client.request({
+      method: "POST",
+      path: this.path(id2, "eval"),
+      auth: "service",
+      body,
+      timeoutMs: 3e5,
+      noRetryOnTimeout: true
+    });
+  }
+  readiness(id2) {
+    return this.client.request({ method: "GET", path: this.path(id2, "readiness"), auth: "service" });
+  }
+};
+
 // src/api/tenants-api.ts
 var TenantsApi = class {
   constructor(client) {
@@ -739,8 +804,8 @@ function extractAccessSettings(embed) {
     asRecord2(metadataConfig?.accessSettings),
     asRecord2(options?.accessSettings)
   ].filter((c) => !!c);
-  for (const candidate of candidates) {
-    if (Object.keys(candidate).length > 0) return candidate;
+  for (const candidate2 of candidates) {
+    if (Object.keys(candidate2).length > 0) return candidate2;
   }
   return null;
 }
@@ -1472,6 +1537,7 @@ function createServiceBundle(client) {
   const guestTokenApi = new GuestTokenApi(client);
   const queryApi = new QueryApi(client);
   const scheduledReportsApi = new ScheduledReportsApi(client);
+  const semanticModelApi = new SemanticModelApi(client);
   const customChartsApi = new CustomChartsApi(client);
   const tenantsApi = new TenantsApi(client);
   const widgetsApi = new WidgetsApi(client);
@@ -1487,6 +1553,7 @@ function createServiceBundle(client) {
     workspacesApi,
     queryApi,
     scheduledReportsApi,
+    semanticModelApi,
     customChartsApi,
     tenantsApi,
     widgetsApi,
@@ -5316,16 +5383,403 @@ ${result.feedback}`);
   );
 }
 
-// src/tools/query/update-semantic-layer.ts
+// src/tools/query/semantic-model.ts
 import { z as z27 } from "zod";
-var columnSchema2 = z27.object({
-  name: z27.string().describe("Column name (must exist in the datamart)"),
-  description: z27.string().optional().describe("Business-friendly description of what this column represents"),
-  synonyms: z27.array(z27.string()).optional().describe(
+
+// src/services/semantic-source.ts
+import { parseDocument, stringify as stringify2 } from "yaml";
+var ENTITY_COLLECTIONS = {
+  table: ["tables"],
+  column: ["columns"],
+  measure: ["measures"],
+  metric: ["metrics"],
+  join: ["joins"],
+  entity: ["entities"],
+  glossary: ["glossary"],
+  saved_query: ["saved_queries", "verified_queries"],
+  instruction: ["instructions", "agent_instructions"],
+  access_rule: ["access", "policies"]
+};
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function assertSafe(value, seen = /* @__PURE__ */ new Set(), depth = 0) {
+  if (depth > 100) throw new Error("Semantic source nesting exceeds 100 levels.");
+  if (!value || typeof value !== "object") return;
+  if (seen.has(value)) throw new Error("Recursive YAML aliases are not supported.");
+  seen.add(value);
+  for (const [key, child] of Object.entries(value)) {
+    if (["__proto__", "constructor", "prototype"].includes(key)) throw new Error(`Unsupported source key: ${key}.`);
+    assertSafe(child, seen, depth + 1);
+  }
+  seen.delete(value);
+}
+function parseSemanticSource(source2) {
+  const document = parseDocument(source2, { prettyErrors: false, uniqueKeys: true });
+  if (document.errors.length || document.warnings.length) {
+    throw new Error((document.errors[0] ?? document.warnings[0]).message);
+  }
+  const value = document.toJS({ maxAliasCount: 100 });
+  if (!isObject(value)) throw new Error("Semantic source must be a YAML mapping.");
+  assertSafe(value);
+  return value;
+}
+function semanticEntities(source2, visibleOnly = false) {
+  const out = [];
+  for (const [kind, keys] of Object.entries(ENTITY_COLLECTIONS)) {
+    if (kind === "column") continue;
+    const key = keys.find((key2) => Array.isArray(source2[key2]));
+    const entries = key ? source2[key] : [];
+    for (const entry of entries) {
+      if (!isObject(entry) || typeof entry.name !== "string" || visibleOnly && entry.hidden === true) continue;
+      const columns = Array.isArray(entry.columns) ? entry.columns.filter(isObject) : [];
+      const entity = visibleOnly && kind === "table" ? { ...entry, columns: columns.filter((column) => column.hidden !== true) } : entry;
+      out.push({ id: `${kind}:${entry.name}`, kind, name: entry.name, entity });
+      if (kind === "table") for (const column of columns) {
+        if (typeof column.name !== "string" || visibleOnly && column.hidden === true) continue;
+        const name = `${entry.name}.${column.name}`;
+        out.push({ id: `column:${name}`, kind: "column", name, entity: column });
+      }
+    }
+  }
+  return out;
+}
+function mergePatch(base, patch) {
+  if (isObject(patch)) {
+    const next = isObject(base) ? { ...base } : {};
+    for (const [key, value] of Object.entries(patch)) {
+      if (value === null) delete next[key];
+      else next[key] = mergePatch(next[key], value);
+    }
+    return next;
+  }
+  if (Array.isArray(patch) && patch.length && patch.every((item) => isObject(item) && typeof item.name === "string")) {
+    const next = Array.isArray(base) ? [...base] : [];
+    const names = /* @__PURE__ */ new Set();
+    for (const item of patch) {
+      const name = item.name;
+      if (names.has(name)) throw new Error(`Duplicate patch entity: ${name}.`);
+      names.add(name);
+      const index = next.findIndex((entry) => isObject(entry) && entry.name === name);
+      if (index < 0) next.push(mergePatch({}, item));
+      else next[index] = mergePatch(next[index], item);
+    }
+    return next;
+  }
+  return patch;
+}
+function changeSemanticSource(source2, input) {
+  const model = parseSemanticSource(source2);
+  if (input.yaml_patch !== void 0) return stringify2(mergePatch(model, parseSemanticSource(input.yaml_patch)));
+  const change = input.change;
+  assertSafe(change);
+  let parent = model;
+  if (change.kind === "column") {
+    if (!change.table) throw new Error("A column change requires table and an unqualified column name.");
+    const table = (Array.isArray(model.tables) ? model.tables : []).find(
+      (item) => isObject(item) && item.name === change.table
+    );
+    if (!isObject(table)) throw new Error(`Table not found: ${change.table}.`);
+    parent = table;
+  } else if (change.table) throw new Error("table is only valid for a column change.");
+  const keys = ENTITY_COLLECTIONS[change.kind];
+  const key = keys.find((key2) => Array.isArray(parent[key2])) ?? keys[0];
+  const entries = Array.isArray(parent[key]) ? [...parent[key]] : [];
+  const index = entries.findIndex((entry) => isObject(entry) && entry.name === change.name);
+  if (change.operation === "remove") {
+    if (change.value !== void 0) throw new Error("A remove change must not include value.");
+    if (index < 0) throw new Error(`Entity not found: ${change.kind} ${change.name}.`);
+    entries.splice(index, 1);
+  } else {
+    if (!change.value) throw new Error("An upsert change requires value.");
+    if (change.value.name !== void 0 && change.value.name !== change.name) throw new Error("value.name must match name.");
+    const value = mergePatch(index < 0 ? {} : entries[index], { ...change.value, name: change.name });
+    if (index < 0) entries.push(value);
+    else entries[index] = value;
+  }
+  parent[key] = entries;
+  return stringify2(model);
+}
+
+// src/services/semantic-retrieval.ts
+function tokens(text2) {
+  return text2.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+}
+function text(value) {
+  return typeof value === "string" ? value : Array.isArray(value) ? value.map(text).join(" ") : "";
+}
+function retrieveSemanticSource(source2, question, k) {
+  const nodes = semanticEntities(parseSemanticSource(source2), true);
+  const query = new Set(tokens(question));
+  const score = (node) => {
+    const fields = [
+      [node.name, 8],
+      [node.entity.alias ?? node.entity.term, 6],
+      [node.entity.synonyms, 4],
+      [node.entity.description ?? node.entity.definition ?? node.entity.question, 2]
+    ];
+    return fields.reduce((sum, [value, weight]) => {
+      const words = new Set(tokens(text(value)));
+      return sum + [...query].filter((word) => words.has(word)).length * weight;
+    }, 0);
+  };
+  const ranked = nodes.map((node) => ({ ...node, score: score(node), match: "lexical" })).filter((node) => node.score > 0).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, k);
+  const edges = new Map(nodes.map((node) => [node.id, /* @__PURE__ */ new Set()]));
+  const byName = /* @__PURE__ */ new Map();
+  for (const node of nodes) byName.set(node.name, [...byName.get(node.name) ?? [], node.id]);
+  const link = (a, b) => {
+    if (a === b || !edges.has(b)) return;
+    edges.get(a).add(b);
+    edges.get(b).add(a);
+  };
+  const refKeys = /* @__PURE__ */ new Set([
+    "table",
+    "column",
+    "columns",
+    "references",
+    "measure",
+    "numerator",
+    "denominator",
+    "metrics",
+    "measures",
+    "glossary_refs",
+    "left",
+    "right",
+    "from",
+    "to",
+    "on",
+    "bindings",
+    "scope",
+    "targets",
+    "tables",
+    "grain",
+    "identifiers",
+    "default_time_dimension",
+    "expression",
+    "sql",
+    "on_sql",
+    "predicate",
+    "type_config"
+  ]);
+  const refs = (value) => {
+    if (typeof value === "string") return value.match(/[\p{L}_][\p{L}\p{N}_]*(?:\.[\p{L}_][\p{L}\p{N}_]*)?/gu) ?? [];
+    if (Array.isArray(value)) return value.flatMap(refs);
+    if (isObject(value)) return Object.entries(value).flatMap(([key, child]) => refKeys.has(key) ? refs(child) : []);
+    return [];
+  };
+  for (const node of nodes) {
+    if (node.kind === "column") link(node.id, `table:${node.name.split(".")[0]}`);
+    for (const ref of refs(node.entity)) for (const id2 of byName.get(ref) ?? []) link(node.id, id2);
+  }
+  const chosen = new Map(ranked.map((node) => [node.id, node]));
+  for (const node of ranked) {
+    for (const id2 of [...edges.get(node.id)].sort()) {
+      if (!chosen.has(id2)) {
+        const adjacent = nodes.find((node2) => node2.id === id2);
+        chosen.set(id2, { ...adjacent, score: 0, match: "adjacency" });
+      }
+    }
+  }
+  return { results: [...chosen.values()], k, lexical_matches: ranked.length, retrieval: "local_lexical" };
+}
+
+// src/tools/query/semantic-model.ts
+var datamartId = z27.string().trim().min(1).max(256).describe("Datamart ID from list_datamarts.");
+var source = z27.string().min(1).max(2e6).describe("Complete proposed semantic model as YAML.");
+var entityKind = z27.enum(["table", "column", "measure", "metric", "join", "entity", "glossary", "saved_query", "instruction", "access_rule"]);
+var changeInputs = {
+  source: source.optional(),
+  yaml_patch: z27.string().min(1).max(2e6).optional().describe("YAML mapping merged into the pulled model. Named lists merge by name. Other lists replace. Null removes a field. An empty list clears it."),
+  change: z27.object({
+    operation: z27.enum(["upsert", "remove"]),
+    kind: entityKind,
+    name: z27.string().trim().min(1),
+    table: z27.string().trim().min(1).optional().describe("Required for columns. Use the table name and an unqualified column name."),
+    value: z27.record(z27.unknown()).optional().describe("Fields to merge for upsert. Omit for remove.")
+  }).strict().optional().describe("One named entity change. Supply exactly one of source, yaml_patch or change.")
+};
+var expectedHash = z27.string().trim().min(1).nullable().optional().describe("Stored content_hash from the reviewed proposal. Null explicitly means the first apply. Required when dry_run is false.");
+function errorCode(error) {
+  const nested = isObject(error.details) && isObject(error.details.error) ? error.details.error : void 0;
+  return typeof nested?.code === "string" ? nested.code : error.code;
+}
+function failure(error) {
+  if (error instanceof DatabrainApiError) {
+    if (error.status === 409 || error.status === 422) {
+      return toolError(stringify({
+        status: error.status,
+        code: errorCode(error),
+        reason: error.message,
+        details: error.details,
+        recovery: error.status === 409 ? "Pull the current model and review a new proposal before applying." : "Correct the validation errors and propose the change again."
+      }));
+    }
+    return error.toToolResponse();
+  }
+  return toolError(`Semantic model error: ${error instanceof Error ? error.message : String(error)}`);
+}
+async function candidate(api, id2, input) {
+  if ([input.source, input.yaml_patch, input.change].filter((value) => value !== void 0).length !== 1) {
+    throw new Error("Supply exactly one of source, yaml_patch or change.");
+  }
+  let stored;
+  try {
+    stored = await api.pull(id2);
+  } catch (error) {
+    if (!(error instanceof DatabrainApiError && error.status === 404 && errorCode(error) === "layer_not_found" && input.source !== void 0)) throw error;
+  }
+  const hash = stored?.content_hash ?? null;
+  if (input.expected_content_hash !== void 0 && input.expected_content_hash !== hash) {
+    throw new DatabrainApiError(409, "content_hash_mismatch", "The model changed since the proposal was reviewed.", { current_hash: hash });
+  }
+  return {
+    source: input.source ?? changeSemanticSource(stored.source, input),
+    expected_content_hash: input.expected_content_hash === void 0 ? hash : input.expected_content_hash
+  };
+}
+async function proposal(api, id2, input) {
+  const next = await candidate(api, id2, input);
+  const validation = await api.validate(id2, next.source);
+  const plan = validation.ok ? await api.plan(id2, next.source, next.expected_content_hash) : null;
+  return { ...next, validation, errors: validation.errors, plan, dry_run: true };
+}
+function registerSearchSemanticModel(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "search_semantic_model",
+    "Find semantic model entities relevant to a question. Ranks names, aliases, synonyms and descriptions, then includes related entities. Uses the stored model and never writes.",
+    { datamartId, question: z27.string().trim().min(1).max(1e4), k: z27.number().int().min(1).max(100).default(10) },
+    READ_ONLY,
+    async ({ datamartId: datamartId2, question, k }) => {
+      try {
+        try {
+          return toolSuccess(stringify(await api.retrieve(datamartId2, question, k)));
+        } catch (error) {
+          if (!(error instanceof DatabrainApiError && [404, 405, 501].includes(error.status))) throw error;
+          if (["datamart_not_found", "layer_not_found", "forbidden", "unauthorized"].includes(errorCode(error))) throw error;
+        }
+        const stored = await api.pull(datamartId2);
+        return toolSuccess(stringify({ ...retrieveSemanticSource(stored.source, question, k), content_hash: stored.content_hash }));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+function registerGetSemanticEntity(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "get_semantic_entity",
+    "Read one entity by kind and exact name from the stored semantic model. For a column, use table.column. Returns the stored content hash for change review.",
+    { datamartId, kind: entityKind, name: z27.string().trim().min(1) },
+    READ_ONLY,
+    async ({ datamartId: datamartId2, kind, name }) => {
+      try {
+        const stored = await api.pull(datamartId2);
+        const found = semanticEntities(parseSemanticSource(stored.source)).filter((entity) => entity.kind === kind && entity.name === name);
+        if (found.length !== 1) return toolError(`Expected one ${kind} named ${name}; found ${found.length}. Use search_semantic_model to find its exact name.`);
+        return toolSuccess(stringify({ ...found[0], content_hash: stored.content_hash }));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+function registerProposeSemanticChange(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "propose_semantic_change",
+    "Prepare a semantic model change from complete YAML, a YAML patch or one structured change. Returns validation errors, the server plan, candidate YAML and the stored hash. Never writes.",
+    { datamartId, ...changeInputs },
+    READ_ONLY,
+    async (params) => {
+      try {
+        return toolSuccess(stringify(await proposal(api, params.datamartId, params)));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+function registerApplySemanticChange(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "apply_semantic_change",
+    "Preview a semantic change by default. Setting dry_run to false applies it live and can remove entities. Requires the reviewed content hash and confirm set to APPLY_TO_PRODUCTION supplied by the user.",
+    {
+      datamartId,
+      ...changeInputs,
+      dry_run: z27.boolean().default(true),
+      expected_content_hash: expectedHash,
+      confirm: z27.string().optional().describe("User supplied APPLY_TO_PRODUCTION after reviewing the plan. Never invent confirmation.")
+    },
+    DESTRUCTIVE,
+    async (params) => {
+      try {
+        if (params.dry_run !== false) return toolSuccess(stringify(await proposal(api, params.datamartId, params)));
+        const refusal = validateProductionApply(params);
+        if (refusal) return toolError(refusal);
+        if (params.expected_content_hash === void 0) return toolError("expected_content_hash is required. Use the stored hash from the reviewed proposal, or null for the first apply.");
+        const next = await candidate(api, params.datamartId, params);
+        const validation = await api.validate(params.datamartId, next.source);
+        if (!validation.ok) return failure(new DatabrainApiError(422, "validation_failed", "Apply refused because the model does not validate.", { validation }));
+        return toolSuccess(stringify(await api.apply(params.datamartId, next.source, next.expected_content_hash)));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+function registerEvalSemanticModel(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "eval_semantic_model",
+    "Evaluate saved queries and optional questions against a proposed or stored semantic model. Returns the pass rate and each verdict with its reason. Runs warehouse queries without changing the model.",
+    { datamartId, source: source.optional(), questions: z27.array(z27.union([z27.string().trim().min(1), z27.object({
+      name: z27.string().optional(),
+      question: z27.string().min(1),
+      sql: z27.string().optional(),
+      expected_columns: z27.array(z27.string()).optional(),
+      expected_empty: z27.boolean().optional()
+    }).strict()])).max(100).optional() },
+    READ_ONLY,
+    async ({ datamartId: datamartId2, source: source2, questions }) => {
+      const shaped = questions?.map((entry) => typeof entry === "string" ? { question: entry } : entry);
+      try {
+        return toolSuccess(stringify(await api.evaluate(datamartId2, { source: source2, questions: shaped })));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+function registerSemanticReadiness(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "semantic_readiness",
+    "Read the semantic readiness number, verdict and open checks for a stored model. Uses the server result without changing the model.",
+    { datamartId },
+    READ_ONLY,
+    async ({ datamartId: datamartId2 }) => {
+      try {
+        return toolSuccess(stringify(await api.readiness(datamartId2)));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+
+// src/tools/query/update-semantic-layer.ts
+import { z as z28 } from "zod";
+var columnSchema2 = z28.object({
+  name: z28.string().describe("Column name (must exist in the datamart)"),
+  description: z28.string().optional().describe("Business-friendly description of what this column represents"),
+  synonyms: z28.array(z28.string()).optional().describe(
     'Alternative names users might use for this column (e.g. ["revenue", "sales amount"])'
   ),
-  miscellaneousInfo: z27.string().optional().describe("Additional context such as valid values, units, or caveats"),
-  columnType: z27.enum([
+  miscellaneousInfo: z28.string().optional().describe("Additional context such as valid values, units, or caveats"),
+  columnType: z28.enum([
     "String",
     "Long String",
     "String (Custom)",
@@ -5340,21 +5794,21 @@ var columnSchema2 = z27.object({
   // The public PUT accepts these three as well (docs: Update Semantic Layer).
   // They were missing here, and zod strips unknown keys, so a caller who set
   // `isIdentifier: true` got a success message and a row with `false`.
-  columnTypeConfig: z27.union([z27.record(z27.string(), z27.string()), z27.string(), z27.object({ lowerLimit: z27.number(), upperLimit: z27.number() }), z27.null()]).optional().describe("Shape depends on columnType: value-to-description object for String / String (Custom) / ENUM / Mapper, { lowerLimit, upperLimit } for Range, a string for Expression and JSON. Omit for Identifier, Number and Long String."),
-  isIdentifier: z27.boolean().optional().describe("Mark the column as an identifier (primary or foreign key)."),
-  isNotIndexed: z27.boolean().optional().describe("Exclude the column from AI indexing.")
+  columnTypeConfig: z28.union([z28.record(z28.string(), z28.string()), z28.string(), z28.object({ lowerLimit: z28.number(), upperLimit: z28.number() }), z28.null()]).optional().describe("Shape depends on columnType: value-to-description object for String / String (Custom) / ENUM / Mapper, { lowerLimit, upperLimit } for Range, a string for Expression and JSON. Omit for Identifier, Number and Long String."),
+  isIdentifier: z28.boolean().optional().describe("Mark the column as an identifier (primary or foreign key)."),
+  isNotIndexed: z28.boolean().optional().describe("Exclude the column from AI indexing.")
 });
-var tableSchema2 = z27.object({
-  name: z27.string().describe("Table name (must exist in the datamart)"),
-  schemaName: z27.string().optional().describe("Schema the table lives in, when the datamart has the same table name in more than one schema."),
-  description: z27.string().optional().describe(
+var tableSchema2 = z28.object({
+  name: z28.string().describe("Table name (must exist in the datamart)"),
+  schemaName: z28.string().optional().describe("Schema the table lives in, when the datamart has the same table name in more than one schema."),
+  description: z28.string().optional().describe(
     "Business-friendly description of what this table represents"
   ),
-  synonyms: z27.array(z27.string()).optional().describe("Alternative names for this table"),
-  miscellaneousInfo: z27.string().optional().describe(
+  synonyms: z28.array(z28.string()).optional().describe("Alternative names for this table"),
+  miscellaneousInfo: z28.string().optional().describe(
     "Additional context such as how the table relates to other tables"
   ),
-  columns: z27.array(columnSchema2).optional().describe("Column-level semantic definitions to update")
+  columns: z28.array(columnSchema2).optional().describe("Column-level semantic definitions to update")
 });
 function columnKey(tableName, columnName) {
   return `${tableName.toLowerCase()}\0${columnName.toLowerCase()}`;
@@ -5431,13 +5885,13 @@ function registerUpdateSemanticLayer(server, client) {
     "update_semantic_layer",
     "Populate or update the semantic layer for a datamart. Add table/column descriptions, synonyms, context. Required before ask_question works. Auto-generate descriptions from column names when empty.",
     {
-      datamartName: z27.string().optional().describe(
+      datamartName: z28.string().optional().describe(
         "Name of the datamart to update. Omit to list available datamarts."
       ),
-      tables: z27.array(tableSchema2).optional().describe(
+      tables: z28.array(tableSchema2).optional().describe(
         "Table and column definitions to update. Only include tables/columns you want to change."
       ),
-      feedback: z27.string().optional().describe(
+      feedback: z28.string().optional().describe(
         'General feedback or context about the datamart (e.g. "This datamart contains e-commerce data for the US market").'
       )
     },
@@ -5499,7 +5953,7 @@ You can now:
 }
 
 // src/tools/query/semantic-generation.ts
-import { z as z28 } from "zod";
+import { z as z29 } from "zod";
 function nonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
@@ -5531,9 +5985,9 @@ async function resolveDatamartFromWorkspace(params) {
   });
   if (resolution.kind !== "resolved") return { ok: false, response: resolution.response };
   const selected = resolution.selected;
-  const datamartId = workspaceDatamartIdFrom(selected);
+  const datamartId2 = workspaceDatamartIdFrom(selected);
   const workspaceDatamartName = workspaceDatamartNameFrom(selected);
-  if (!datamartId) {
+  if (!datamartId2) {
     return {
       ok: false,
       response: toolError(
@@ -5551,8 +6005,8 @@ async function resolveDatamartFromWorkspace(params) {
   }
   return {
     ok: true,
-    datamartName: workspaceDatamartName || params.datamartName || datamartId,
-    datamartId,
+    datamartName: workspaceDatamartName || params.datamartName || datamartId2,
+    datamartId: datamartId2,
     workspaceName: resolution.name
   };
 }
@@ -5584,8 +6038,8 @@ async function resolveDatamart(params) {
     toolName: params.toolName
   });
   if (resolution.kind !== "resolved") return { ok: false, response: resolution.response };
-  const datamartId = datamartIdFrom(resolution.selected);
-  if (!datamartId) {
+  const datamartId2 = datamartIdFrom(resolution.selected);
+  if (!datamartId2) {
     return {
       ok: false,
       response: toolError(
@@ -5596,7 +6050,7 @@ async function resolveDatamart(params) {
   return {
     ok: true,
     datamartName: resolution.name,
-    datamartId
+    datamartId: datamartId2
   };
 }
 function registerStartSemanticLayerGeneration(server, client) {
@@ -5605,9 +6059,9 @@ function registerStartSemanticLayerGeneration(server, client) {
     "start_semantic_layer_generation",
     "Start backend semantic-layer auto-generation for a datamart. Returns an async job id to poll.",
     {
-      datamartName: z28.string().optional().describe("Datamart name. Omit to list available datamarts"),
-      workspaceName: z28.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
-      datamartId: z28.string().optional().describe("Datamart UUID. Use only when already known.")
+      datamartName: z29.string().optional().describe("Datamart name. Omit to list available datamarts"),
+      workspaceName: z29.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
+      datamartId: z29.string().optional().describe("Datamart UUID. Use only when already known.")
     },
     WRITE_CREATE,
     async (params) => {
@@ -5649,9 +6103,9 @@ function registerGetSemanticLayerGenerationStatus(server, client) {
     "get_semantic_layer_generation_status",
     "Get semantic-layer auto-generation job status for a datamart.",
     {
-      datamartName: z28.string().optional().describe("Datamart name. Omit to list available datamarts"),
-      workspaceName: z28.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
-      datamartId: z28.string().optional().describe("Datamart UUID. Use only when already known.")
+      datamartName: z29.string().optional().describe("Datamart name. Omit to list available datamarts"),
+      workspaceName: z29.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
+      datamartId: z29.string().optional().describe("Datamart UUID. Use only when already known.")
     },
     READ_ONLY,
     async (params) => {
@@ -5688,10 +6142,10 @@ function registerGetSemanticLayerGenerationStatus(server, client) {
 }
 
 // src/tools/widgets/list-widgets.ts
-import { z as z29 } from "zod";
+import { z as z30 } from "zod";
 function widgetReferenceId(widget) {
-  for (const candidate of [widget.externalMetricId, widget.id, widget._id, widget.metricId]) {
-    if (typeof candidate === "string" && candidate.trim().length > 0) return candidate.trim();
+  for (const candidate2 of [widget.externalMetricId, widget.id, widget._id, widget.metricId]) {
+    if (typeof candidate2 === "string" && candidate2.trim().length > 0) return candidate2.trim();
   }
   return void 0;
 }
@@ -5701,10 +6155,10 @@ function registerListWidgets(server, client) {
     "list_widgets",
     "List widgets on a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous). Returns each widget's externalMetricId (uuid, used for update/remove), metricId (slug), name, published state, and creator identifier.",
     {
-      clientId: z29.string().describe("Client/tenant identifier for this dashboard"),
-      dashboardName: z29.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z29.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z29.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier.")
+      clientId: z30.string().describe("Client/tenant identifier for this dashboard"),
+      dashboardName: z30.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z30.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z30.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier.")
     },
     READ_ONLY,
     async (params) => {
@@ -5768,29 +6222,29 @@ function registerListWidgets(server, client) {
 }
 
 // src/tools/widgets/add-widget.ts
-import { z as z30 } from "zod";
+import { z as z31 } from "zod";
 function registerAddWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "add_widget",
     "Add a widget to a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous). Cloning via `templateMetricId` is the recommended path \u2014 query, chart config, and datasource are all inherited. Data app and datasource auto-resolve; never ask the user for them.",
     {
-      clientId: z30.string().describe("Client/tenant identifier (widget is created in their scope)"),
-      dashboardName: z30.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z30.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z30.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z30.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
-      templateMetricId: z30.string().optional().describe("Source widget metricId to clone from. Copies query, chartOptions, and datasource fields; caller can override via other params."),
-      name: z30.string().optional().describe("Widget name (overrides template)"),
-      metricId: z30.string().optional().describe("Unique slug for the new widget (auto-generated if omitted)"),
-      query: z30.string().optional().describe("SQL query body (overrides template)"),
-      chartOptions: z30.record(z30.unknown()).optional().describe("Chart config JSON (chart type, colors, legend, axes). Overrides template."),
-      description: z30.string().optional(),
-      companyIntegrationId: z30.string().optional().describe("Datasource UUID override. Auto-resolved from `embedId` or sole active datasource; leave blank unless the user explicitly picked one by ID."),
-      integrationName: z30.string().optional().describe('Datasource display name (e.g. "Snowflake"). Use this when the user picks a datasource by name \u2014 the id is looked up automatically.'),
-      isPublished: z30.boolean().optional().describe("Publish immediately (default true)"),
-      body: z30.record(z30.unknown()).optional().describe("Raw createMetric body passthrough. If provided, used as-is (after defaults). Overrides all other params."),
-      widgets: z30.array(z30.record(z30.unknown())).min(1).max(50).optional().describe("Batch of raw createMetric bodies. Dashboard attachment is added to each body.")
+      clientId: z31.string().describe("Client/tenant identifier (widget is created in their scope)"),
+      dashboardName: z31.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z31.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z31.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z31.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
+      templateMetricId: z31.string().optional().describe("Source widget metricId to clone from. Copies query, chartOptions, and datasource fields; caller can override via other params."),
+      name: z31.string().optional().describe("Widget name (overrides template)"),
+      metricId: z31.string().optional().describe("Unique slug for the new widget (auto-generated if omitted)"),
+      query: z31.string().optional().describe("SQL query body (overrides template)"),
+      chartOptions: z31.record(z31.unknown()).optional().describe("Chart config JSON (chart type, colors, legend, axes). Overrides template."),
+      description: z31.string().optional(),
+      companyIntegrationId: z31.string().optional().describe("Datasource UUID override. Auto-resolved from `embedId` or sole active datasource; leave blank unless the user explicitly picked one by ID."),
+      integrationName: z31.string().optional().describe('Datasource display name (e.g. "Snowflake"). Use this when the user picks a datasource by name \u2014 the id is looked up automatically.'),
+      isPublished: z31.boolean().optional().describe("Publish immediately (default true)"),
+      body: z31.record(z31.unknown()).optional().describe("Raw createMetric body passthrough. If provided, used as-is (after defaults). Overrides all other params."),
+      widgets: z31.array(z31.record(z31.unknown())).min(1).max(50).optional().describe("Batch of raw createMetric bodies. Dashboard attachment is added to each body.")
     },
     WRITE_CREATE,
     async (params) => {
@@ -5938,20 +6392,20 @@ Use \`list_widgets\` to verify, or \`update_widget\`/\`remove_widget\` to adjust
 }
 
 // src/tools/widgets/update-widget.ts
-import { z as z31 } from "zod";
+import { z as z32 } from "zod";
 function registerUpdateWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "update_widget",
     "Update a widget on a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous) + `externalMetricId` + `set`. Data app auto-resolves from the dashboard.",
     {
-      externalMetricId: z31.string().describe("Internal uuid of the widget (externalMetrics.id). Not the user-facing metricId slug."),
-      clientId: z31.string().describe("Client/tenant identifier"),
-      dashboardName: z31.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z31.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z31.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z31.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank."),
-      set: z31.record(z31.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
+      externalMetricId: z32.string().describe("Internal uuid of the widget (externalMetrics.id). Not the user-facing metricId slug."),
+      clientId: z32.string().describe("Client/tenant identifier"),
+      dashboardName: z32.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z32.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z32.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z32.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank."),
+      set: z32.record(z32.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
     },
     WRITE_IDEMPOTENT,
     async (params) => {
@@ -6014,19 +6468,19 @@ Use \`list_widgets\` to verify.`
 }
 
 // src/tools/widgets/remove-widget.ts
-import { z as z32 } from "zod";
+import { z as z33 } from "zod";
 function registerRemoveWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "remove_widget",
     "Remove a widget from a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous) + `externalMetricId`. Per-client soft delete \u2014 the widget stays on the template dashboard and on other customers' dashboards.",
     {
-      externalMetricId: z32.string().describe("Internal uuid of the widget (externalMetrics.id)"),
-      clientId: z32.string().describe("Client/tenant identifier \u2014 the widget will be hidden for this client only"),
-      dashboardName: z32.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z32.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z32.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z32.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank.")
+      externalMetricId: z33.string().describe("Internal uuid of the widget (externalMetrics.id)"),
+      clientId: z33.string().describe("Client/tenant identifier \u2014 the widget will be hidden for this client only"),
+      dashboardName: z33.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z33.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z33.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z33.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank.")
     },
     DESTRUCTIVE,
     async (params) => {
@@ -6082,21 +6536,21 @@ Note: this is a per-client soft delete. The widget remains available for other c
 }
 
 // src/tools/widgets/generate-widget.ts
-import { z as z33 } from "zod";
+import { z as z34 } from "zod";
 function registerGenerateWidget(server, client) {
   const services = createServiceBundle(client);
   const tool = server.tool(
     "generate_widget",
     "AI-generate a widget draft from a natural-language prompt. Does NOT persist \u2014 returns a draft to pass to `add_widget`. Non-technical flow: `clientId` + `dashboardName` (+ `workspaceName` if ambiguous); data app and datasource auto-resolve. Never ask the user for data app, datasource, or integration.",
     {
-      clientId: z33.string().describe("Client/tenant identifier"),
-      userInputs: z33.record(z33.unknown()).describe('Prompt + context object. Typical shape: { prompt: "calls per day over last 30 days", schema: {...}, examples: [...] }. Backend decides which keys it honors.'),
-      dashboardName: z33.string().optional().describe("Dashboard name (non-technical). Preferred input for CS/CX flows \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z33.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z33.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z33.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
-      integrationId: z33.string().optional().describe("Technical override \u2014 the datasource UUID. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets."),
-      integrationName: z33.string().optional().describe("Technical override \u2014 datasource display name. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets.")
+      clientId: z34.string().describe("Client/tenant identifier"),
+      userInputs: z34.record(z34.unknown()).describe('Prompt + context object. Typical shape: { prompt: "calls per day over last 30 days", schema: {...}, examples: [...] }. Backend decides which keys it honors.'),
+      dashboardName: z34.string().optional().describe("Dashboard name (non-technical). Preferred input for CS/CX flows \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z34.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z34.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z34.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
+      integrationId: z34.string().optional().describe("Technical override \u2014 the datasource UUID. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets."),
+      integrationName: z34.string().optional().describe("Technical override \u2014 datasource display name. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets.")
     },
     READ_ONLY,
     async (params) => {
@@ -6181,9 +6635,9 @@ function registerGenerateWidget(server, client) {
 }
 
 // src/tools/widgets/create-or-update-metric-from-query.ts
-import { z as z34 } from "zod";
-var modeSchema = z34.enum(["dry_run", "apply"]).default("dry_run");
-var conflictStrategySchema = z34.enum(["fail", "update", "create_new"]).default("fail");
+import { z as z35 } from "zod";
+var modeSchema = z35.enum(["dry_run", "apply"]).default("dry_run");
+var conflictStrategySchema = z35.enum(["fail", "update", "create_new"]).default("fail");
 function makePlanText(plan) {
   return JSON.stringify(plan, null, 2);
 }
@@ -6200,22 +6654,22 @@ function registerCreateOrUpdateMetricFromQuery(server, client) {
     "[EMBEDDING] Create or update a production metric/widget on a customer dashboard from validated SQL. Requires clientId (multi-tenant embed). Defaults to dry-run; apply requires explicit confirmation.",
     {
       mode: modeSchema.describe("dry_run returns the plan only; apply executes after confirmation"),
-      confirm: z34.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
+      confirm: z35.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
       conflictStrategy: conflictStrategySchema.describe("What to do if metricId already exists on the target dashboard"),
-      clientId: z34.string().describe("Client/tenant identifier for the dashboard widget scope"),
-      workspaceName: z34.string().describe("Target workspace name"),
-      dashboardName: z34.string().optional().describe("Dashboard name to attach to"),
-      embedId: z34.string().optional().describe("Technical embed id alternative to dashboardName"),
-      dataAppName: z34.string().optional().describe("Optional data app override"),
-      name: z34.string().describe("Metric/widget display name"),
-      metricId: z34.string().describe("Stable metric slug to create or update"),
-      query: z34.string().describe("SQL query already validated against the warehouse"),
-      description: z34.string().optional().describe("Metric description"),
-      chartOptions: z34.record(z34.unknown()).optional().describe("Chart configuration JSON"),
-      companyIntegrationId: z34.string().optional().describe("Datasource UUID override"),
-      integrationName: z34.string().optional().describe("Datasource display name override"),
-      isPublished: z34.boolean().optional().describe("Publish after apply. Defaults to false for production safety"),
-      requestedBy: z34.string().optional().describe("Human operator/request context to store on the metric when supported")
+      clientId: z35.string().describe("Client/tenant identifier for the dashboard widget scope"),
+      workspaceName: z35.string().describe("Target workspace name"),
+      dashboardName: z35.string().optional().describe("Dashboard name to attach to"),
+      embedId: z35.string().optional().describe("Technical embed id alternative to dashboardName"),
+      dataAppName: z35.string().optional().describe("Optional data app override"),
+      name: z35.string().describe("Metric/widget display name"),
+      metricId: z35.string().describe("Stable metric slug to create or update"),
+      query: z35.string().describe("SQL query already validated against the warehouse"),
+      description: z35.string().optional().describe("Metric description"),
+      chartOptions: z35.record(z35.unknown()).optional().describe("Chart configuration JSON"),
+      companyIntegrationId: z35.string().optional().describe("Datasource UUID override"),
+      integrationName: z35.string().optional().describe("Datasource display name override"),
+      isPublished: z35.boolean().optional().describe("Publish after apply. Defaults to false for production safety"),
+      requestedBy: z35.string().optional().describe("Human operator/request context to store on the metric when supported")
     },
     WRITE_IDEMPOTENT,
     async (params) => {
@@ -6375,8 +6829,8 @@ function registerCreateOrUpdateMetricFromQuery(server, client) {
 }
 
 // src/tools/widgets/create-workspace-metric.ts
-import { z as z35 } from "zod";
-var modeSchema2 = z35.enum(["dry_run", "apply"]).default("dry_run");
+import { z as z36 } from "zod";
+var modeSchema2 = z36.enum(["dry_run", "apply"]).default("dry_run");
 function registerCreateWorkspaceMetric(server, client) {
   server.tool(
     "create_workspace_metric",
@@ -6385,16 +6839,18 @@ function registerCreateWorkspaceMetric(server, client) {
       mode: modeSchema2.describe(
         "dry_run validates the SQL only (no write); apply creates or updates the metric after confirmation"
       ),
-      confirm: z35.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
-      workspaceName: z35.string().describe("Target workspace name"),
-      name: z35.string().describe("Metric display name"),
-      query: z35.string().describe("SQL query to validate and store"),
-      metricId: z35.string().optional().describe(
+      confirm: z36.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
+      workspaceName: z36.string().describe("Target workspace name"),
+      name: z36.string().describe("Metric display name"),
+      query: z36.string().describe(
+        "SQL query to validate and store. In a TABLE-tenancy workspace never compare the client column to a fixed client value; use `client_id_variable` so each client sees only its own rows (the backend refuses it with TENANT_KEY_LITERAL)."
+      ),
+      metricId: z36.string().optional().describe(
         "Stable metric slug. Pass an existing slug to UPDATE that metric in place. Omit to create \u2014 the slug is derived deterministically from the name (no random/uniqueness suffix), so re-running with the same name upserts the same metric rather than creating a duplicate."
       ),
-      description: z35.string().optional().describe("Metric description"),
-      datasourceId: z35.string().optional().describe("Datasource UUID override; defaults to the workspace datasource"),
-      isPublished: z35.boolean().optional().describe(
+      description: z36.string().optional().describe("Metric description"),
+      datasourceId: z36.string().optional().describe("Datasource UUID override; defaults to the workspace datasource"),
+      isPublished: z36.boolean().optional().describe(
         "Publish after apply. Defaults to false. Applies to creates; on updates the existing publish state is preserved."
       )
     },
@@ -6450,25 +6906,25 @@ function registerCreateWorkspaceMetric(server, client) {
 }
 
 // src/tools/widgets/validate-metric-spec.ts
-import { z as z36 } from "zod";
+import { z as z37 } from "zod";
 function registerValidateMetricSpec(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "validate_metric_spec",
     "Validate a production metric spec from SQL without saving it. Resolves dashboard, data app, datasource, conflicts, and required fields.",
     {
-      clientId: z36.string().describe("Client/tenant identifier used to validate dashboard widget scope"),
-      workspaceName: z36.string().describe("Target production-backed workspace name"),
-      dashboardName: z36.string().optional().describe("Dashboard name to attach to"),
-      embedId: z36.string().optional().describe("Technical embed id alternative to dashboardName"),
-      dataAppName: z36.string().optional().describe("Optional data app override"),
-      name: z36.string().describe("Metric/widget display name"),
-      metricId: z36.string().describe("Stable metric slug to create or update"),
-      query: z36.string().describe("SQL query already validated against the warehouse"),
-      description: z36.string().optional().describe("Metric description"),
-      chartOptions: z36.record(z36.unknown()).optional().describe("Chart configuration JSON"),
-      companyIntegrationId: z36.string().optional().describe("Datasource UUID override"),
-      integrationName: z36.string().optional().describe("Datasource display name override")
+      clientId: z37.string().describe("Client/tenant identifier used to validate dashboard widget scope"),
+      workspaceName: z37.string().describe("Target production-backed workspace name"),
+      dashboardName: z37.string().optional().describe("Dashboard name to attach to"),
+      embedId: z37.string().optional().describe("Technical embed id alternative to dashboardName"),
+      dataAppName: z37.string().optional().describe("Optional data app override"),
+      name: z37.string().describe("Metric/widget display name"),
+      metricId: z37.string().describe("Stable metric slug to create or update"),
+      query: z37.string().describe("SQL query already validated against the warehouse"),
+      description: z37.string().optional().describe("Metric description"),
+      chartOptions: z37.record(z37.unknown()).optional().describe("Chart configuration JSON"),
+      companyIntegrationId: z37.string().optional().describe("Datasource UUID override"),
+      integrationName: z37.string().optional().describe("Datasource display name override")
     },
     READ_ONLY,
     async (params) => {
@@ -6559,20 +7015,20 @@ function registerValidateMetricSpec(server, client) {
 }
 
 // src/tools/reports/list-scheduled-reports.ts
-import { z as z37 } from "zod";
+import { z as z38 } from "zod";
 function registerListScheduledReports(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "list_scheduled_reports",
     "List configured scheduled reports for a specific client/dashboard embed. Shows schedule metadata, not delivery success history.",
     {
-      clientId: z37.string().describe("Client/tenant identifier. Required by the current backend API for non-empty results"),
-      dashboardName: z37.string().optional().describe("Dashboard name to inspect"),
-      workspaceName: z37.string().optional().describe("Workspace name if dashboardName is ambiguous"),
-      embedId: z37.string().optional().describe("Technical embed id alternative to dashboardName"),
-      userIdentifier: z37.string().optional().describe("Optional creator/user filter"),
-      pageNumber: z37.number().int().positive().optional().describe("Page number when pagination is enabled"),
-      isPagination: z37.boolean().optional().describe("Enable backend pagination")
+      clientId: z38.string().describe("Client/tenant identifier. Required by the current backend API for non-empty results"),
+      dashboardName: z38.string().optional().describe("Dashboard name to inspect"),
+      workspaceName: z38.string().optional().describe("Workspace name if dashboardName is ambiguous"),
+      embedId: z38.string().optional().describe("Technical embed id alternative to dashboardName"),
+      userIdentifier: z38.string().optional().describe("Optional creator/user filter"),
+      pageNumber: z38.number().int().positive().optional().describe("Page number when pagination is enabled"),
+      isPagination: z38.boolean().optional().describe("Enable backend pagination")
     },
     READ_ONLY,
     async (params) => {
@@ -6682,19 +7138,19 @@ function registerWhoami(server, client) {
 }
 
 // src/tools/custom-chart/scaffold.ts
-import { z as z39 } from "zod";
+import { z as z40 } from "zod";
 
 // src/tools/custom-chart/shared.ts
-import { z as z38 } from "zod";
+import { z as z39 } from "zod";
 var slotInputSchema = slotSchema;
 var optionInputSchema = optionSchema;
-var manifestInputSchema = z38.record(z38.unknown()).describe("manifest.json as an object (schemaVersion 2). Validated with the same rules as the server.");
+var manifestInputSchema = z39.record(z39.unknown()).describe("manifest.json as an object (schemaVersion 2). Validated with the same rules as the server.");
 var bundleInputShape = {
   manifest: manifestInputSchema.optional(),
-  bundleJs: z38.string().optional().describe("dist/index.js from `databrain custom-chart build` (the shim plus the chart module)."),
-  bundleCss: z38.string().optional().describe("The raw chart.css, kept for provenance."),
-  iconSvg: z38.string().optional().describe("icon.svg, at most 16 KiB, no script, no foreignObject, no external href."),
-  projectDir: z38.string().optional().describe("Local only: a chart project folder. The tool reads it instead of manifest/bundleJs/iconSvg.")
+  bundleJs: z39.string().optional().describe("dist/index.js from `databrain custom-chart build` (the shim plus the chart module)."),
+  bundleCss: z39.string().optional().describe("The raw chart.css, kept for provenance."),
+  iconSvg: z39.string().optional().describe("icon.svg, at most 16 KiB, no script, no foreignObject, no external href."),
+  projectDir: z39.string().optional().describe("Local only: a chart project folder. The tool reads it instead of manifest/bundleJs/iconSvg.")
 };
 function formatProblems(problems) {
   if (problems.length === 0) return "No problems.";
@@ -6761,11 +7217,11 @@ function registerCustomChartScaffold(server, _client) {
     "custom_chart_scaffold",
     "Return the files of a new custom chart project (manifest.json, chart.ts, chart.css, icon.svg, sample data, guide). Nothing is written or persisted; write the files yourself.",
     {
-      key: z39.string().describe("Chart key, becomes chart type custom:<key>. Lowercase letters, digits, _ and -, 64 max."),
-      name: z39.string().describe("Display name shown in the chart picker, 1 to 256 characters."),
-      description: z39.string().optional().describe("Optional description, up to 500 characters."),
-      slots: z39.array(slotInputSchema).optional().describe("Data slots. Defaults to category (dimension), value (measure), target (optional measure)."),
-      options: z39.array(optionInputSchema).optional().describe("Chart options. Defaults to the template options (labels, subtitle, radius, colour, sort).")
+      key: z40.string().describe("Chart key, becomes chart type custom:<key>. Lowercase letters, digits, _ and -, 64 max."),
+      name: z40.string().describe("Display name shown in the chart picker, 1 to 256 characters."),
+      description: z40.string().optional().describe("Optional description, up to 500 characters."),
+      slots: z40.array(slotInputSchema).optional().describe("Data slots. Defaults to category (dimension), value (measure), target (optional measure)."),
+      options: z40.array(optionInputSchema).optional().describe("Chart options. Defaults to the template options (labels, subtitle, radius, colour, sort).")
     },
     READ_ONLY,
     async (params) => {
@@ -6857,18 +7313,18 @@ function registerCustomChartValidate(server, client) {
 }
 
 // src/tools/custom-chart/upload.ts
-import { z as z40 } from "zod";
+import { z as z41 } from "zod";
 function registerCustomChartUpload(server, client) {
   const api = createCustomChartsApi(client);
   server.tool(
     "custom_chart_upload",
     "Upload a built custom chart bundle to the company. Creates the chart (private, version 1) or a new preview version. Defaults to dry_run; apply requires explicit confirmation and can publish in the same call.",
     {
-      mode: z40.enum(["dry_run", "apply"]).default("dry_run").describe("dry_run validates and returns the plan; apply uploads."),
-      confirm: z40.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
-      publish: z40.boolean().default(false).describe("After a successful apply, publish the uploaded version so every builder can use it."),
-      name: z40.string().optional().describe("Display name override. Defaults to manifest.name."),
-      description: z40.string().optional().describe("Description override. Defaults to manifest.description."),
+      mode: z41.enum(["dry_run", "apply"]).default("dry_run").describe("dry_run validates and returns the plan; apply uploads."),
+      confirm: z41.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
+      publish: z41.boolean().default(false).describe("After a successful apply, publish the uploaded version so every builder can use it."),
+      name: z41.string().optional().describe("Display name override. Defaults to manifest.name."),
+      description: z41.string().optional().describe("Description override. Defaults to manifest.description."),
       ...bundleInputShape
     },
     WRITE_CREATE,
@@ -7009,17 +7465,17 @@ function registerListCustomCharts(server, client) {
 }
 
 // src/tools/custom-chart/publish.ts
-import { z as z41 } from "zod";
+import { z as z42 } from "zod";
 function registerPublishCustomChart(server, client) {
   const api = createCustomChartsApi(client);
   server.tool(
     "publish_custom_chart",
     "Publish a custom chart version so every builder in the company can use chart type custom:<key>. Defaults to the preview version. Defaults to dry_run; apply requires explicit confirmation.",
     {
-      key: z41.string().describe("The chart key (manifest.id), for example revenue-bars."),
-      versionId: z41.string().optional().describe("A specific version id to publish. Defaults to the preview version."),
-      mode: z41.enum(["dry_run", "apply"]).default("dry_run").describe("dry_run shows what would be published; apply publishes."),
-      confirm: z41.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`)
+      key: z42.string().describe("The chart key (manifest.id), for example revenue-bars."),
+      versionId: z42.string().optional().describe("A specific version id to publish. Defaults to the preview version."),
+      mode: z42.enum(["dry_run", "apply"]).default("dry_run").describe("dry_run shows what would be published; apply publishes."),
+      confirm: z42.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`)
     },
     WRITE_IDEMPOTENT,
     async (params) => {
@@ -7130,6 +7586,12 @@ function registerAllTools(server, client) {
   registerUpdateSemanticLayer(server, client);
   registerStartSemanticLayerGeneration(server, client);
   registerGetSemanticLayerGenerationStatus(server, client);
+  registerSearchSemanticModel(server, client);
+  registerGetSemanticEntity(server, client);
+  registerProposeSemanticChange(server, client);
+  registerApplySemanticChange(server, client);
+  registerEvalSemanticModel(server, client);
+  registerSemanticReadiness(server, client);
   registerListWidgets(server, client);
   registerValidateMetricSpec(server, client);
   registerCreateOrUpdateMetricFromQuery(server, client);
@@ -9024,6 +9486,20 @@ When the same flag is set at multiple levels, the highest precedence wins:
 
 // src/resources/content/semantic-layer-guide.ts
 var semanticLayerGuideContent = `
+
+## Semantic models v2
+
+The v2 source is one YAML document. Use the configured service credential and a datamart ID from \`list_datamarts\`.
+
+1. \`search_semantic_model\` finds entities by question. \`get_semantic_entity\` reads one entity by kind and name. Column names use table.column.
+2. \`propose_semantic_change\` takes complete source YAML, a YAML patch or one structured change. It returns candidate source, validation errors, a plan and the stored expected hash without writing.
+3. \`eval_semantic_model\` evaluates the proposed source. \`semantic_readiness\` returns the server score, verdict and open checks.
+4. \`apply_semantic_change\` defaults to a dry run. Live apply requires the exact reviewed source, \`expected_content_hash\`, \`dry_run: false\` and user supplied \`confirm: "APPLY_TO_PRODUCTION"\`. Never supply confirmation yourself. Apply changes the live model for all consumers. On a conflict, prepare a fresh proposal and review it again.
+
+YAML patches merge mappings and named lists by name. Other lists replace. Empty lists clear; null removes a field. Structured changes use operation upsert or remove, kind, name, and value for upsert. Column changes also require table. Patch output normalizes formatting and comments, so review the returned source before apply.
+
+The legacy maintenance workflow below applies to datamarts that have not moved to v2. Do not call \`update_semantic_layer\` for v2.
+
 # Databrain Semantic Layer Guide
 
 ## What Is the Semantic Layer?
@@ -10010,6 +10486,9 @@ If **no datamarts exist**, tell the user they need to create one in the **Databr
 
 If **no datasources exist either**, the user must first connect their database in the **Databrain UI**.
 
+**For a v2 semantic model**
+If the datamart uses v2, inspect the question's entities with \`search_semantic_model\` and \`get_semantic_entity\`. Read \`semantic_readiness\` for open checks, then continue to Step 2. If metadata needs correction, use \`propose_semantic_change\`, evaluate its source with \`eval_semantic_model\`, and show the plan. Only apply the reviewed source and expected hash through \`apply_semantic_change\` after the user supplies \`APPLY_TO_PRODUCTION\`. Never use the legacy \`update_semantic_layer\` steps below for v2.
+
 **Step 1b \u2014 Verify the Semantic Layer**
 After confirming a datamart exists, use \`get_semantic_layer\` to check its tables. The semantic layer is built on the **datamart** (not the raw datasource) \u2014 do NOT use \`discover_datasource_schema\` to populate it.
 
@@ -10091,6 +10570,15 @@ If the confidence is low or results seem wrong:
 // src/prompts/populate-semantic-layer.ts
 var populateSemanticLayerPrompt = `You are helping the user populate the semantic layer for a Databrain datamart. The semantic layer provides table/column descriptions, synonyms, and context that the AI needs to convert natural language questions into accurate SQL.
 
+**For a v2 semantic model**
+If \`list_datamarts\` reports \`semanticLayerVersion: "v2"\`, or the selected datamart is already known to use v2, use this workflow instead of the legacy steps below:
+1. Inspect relevant entities with \`search_semantic_model\` and \`get_semantic_entity\`, using the datamart ID.
+2. Call \`propose_semantic_change\` with a YAML patch or structured change. Show its errors and plan. Correct errors before continuing.
+3. Call \`eval_semantic_model\` with the returned source. Show the verdicts and let the user review the candidate.
+4. Stop for the user's explicit \`APPLY_TO_PRODUCTION\` confirmation. Never supply it yourself.
+5. Call \`apply_semantic_change\` with the exact reviewed source, its \`expected_content_hash\`, \`dry_run: false\` and the user's confirmation. A conflict requires a new proposal and review.
+6. Call \`semantic_readiness\` and inspect the changed entity. Do not call \`update_semantic_layer\` for a v2 model.
+
 **Why this matters:** Without a populated semantic layer, \`ask_question\` cannot generate SQL \u2014 every query will fail with "out of context." Populating the semantic layer is the critical step between having a datamart and being able to query it.
 
 **Step 1 \u2014 Identify the Datamart**
@@ -10475,4 +10963,4 @@ export {
   registerAllResources,
   registerAllPrompts
 };
-//# sourceMappingURL=chunk-5IQ7MVUH.js.map
+//# sourceMappingURL=chunk-JSYG7ULR.js.map