@hamak/smart-data-dico 1.20.0 → 1.22.0

package/backend/dist/server.mjs

@@ -26807,9 +26807,9 @@ var require_range2 = __commonJS({
       parseRange(range) {
         const memoOpts = (this.options.includePrerelease && FLAG_INCLUDE_PRERELEASE) | (this.options.loose && FLAG_LOOSE);
         const memoKey = memoOpts + ":" + range;
-        const cached2 = cache2.get(memoKey);
-        if (cached2) {
-          return cached2;
+        const cached3 = cache2.get(memoKey);
+        if (cached3) {
+          return cached3;
         }
         const loose = this.options.loose;
         const hr = loose ? re2[t.HYPHENRANGELOOSE] : re2[t.HYPHENRANGE];
@@ -44016,10 +44016,10 @@ var init_git_file_info_enricher = __esm({
        * Get cached status or fetch new one
        */
       async getCachedStatus(cacheKey, workspaceId, relativePath) {
-        const cached2 = this.statusCache.get(cacheKey);
+        const cached3 = this.statusCache.get(cacheKey);
         const now2 = Date.now();
-        if (cached2 && now2 - cached2.timestamp < this.cacheTimeout) {
-          return cached2.status;
+        if (cached3 && now2 - cached3.timestamp < this.cacheTimeout) {
+          return cached3.status;
         }
         try {
           const status = await this.gitService.getStatus(workspaceId, relativePath);
@@ -44604,8 +44604,8 @@ function invalidatePackageCache(packageName) {
   else _packageCache.delete(packageName);
 }
 async function loadPackage(packageName) {
-  const cached2 = _packageCache.get(packageName);
-  if (cached2 && cached2.expires > Date.now()) return cached2.model;
+  const cached3 = _packageCache.get(packageName);
+  if (cached3 && cached3.expires > Date.now()) return cached3.model;
   const files = await listPackageYamlFilePaths(packageName);
   const parsed = await Promise.all(
     files.map(async (p) => ({
@@ -48508,9 +48508,25 @@ var init_serviceService = __esm({
        * user to disambiguate.
        */
       async findEntityAcrossPackages(entityName, preferredPackage) {
+        const matches = await this.findEntityMatches(entityName, preferredPackage);
+        if (matches.length === 0) return null;
+        if (matches.length === 1) return matches[0];
+        const where = matches.map((m) => m.packageName).join(", ");
+        throw new Error(
+          `Entity "${entityName}" exists in multiple packages: ${where}. Specify the package explicitly.`
+        );
+      }
+      /**
+       * All `{ entity, packageName }` matches for a name. A hit in
+       * `preferredPackage` wins outright (single match, no wider scan) —
+       * same precedence findEntityAcrossPackages always had. Callers that
+       * want a disambiguation list instead of a thrown ambiguity error
+       * (e.g. the AI getEntityDetails tool) consume this directly.
+       */
+      async findEntityMatches(entityName, preferredPackage) {
         if (preferredPackage) {
           const e = await this.getEntitySchema(preferredPackage, entityName);
-          if (e) return { entity: e, packageName: preferredPackage };
+          if (e) return [{ entity: e, packageName: preferredPackage }];
         }
         const allPackages = await listMicroservices();
         const matches = [];
@@ -48519,12 +48535,7 @@ var init_serviceService = __esm({
           const e = await this.getEntitySchema(p, entityName);
           if (e) matches.push({ entity: e, packageName: p });
         }
-        if (matches.length === 0) return null;
-        if (matches.length === 1) return matches[0];
-        const where = matches.map((m) => m.packageName).join(", ");
-        throw new Error(
-          `Entity "${entityName}" exists in multiple packages: ${where}. Specify the package explicitly.`
-        );
+        return matches;
       }
       async createEntity(service, entity) {
         logger.info(`Creating entity: ${service}.${entity.name}`);
@@ -83510,6 +83521,79 @@ var init_authoringRules = __esm({
   }
 });
 
+// backend/src/services/ai/physicalMapping.ts
+function metaValue2(meta3, name21) {
+  const e = meta3?.find((m) => m.name === name21);
+  return e && e.value != null ? String(e.value) : void 0;
+}
+function metaFlag(meta3, name21) {
+  const v = meta3?.find((m) => m.name === name21)?.value;
+  return v === true || /^(true|yes|1)$/i.test(String(v ?? ""));
+}
+function resolveAttributePhysical(a) {
+  const columnName = metaValue2(a.metadata, "physical.columnName");
+  const dbType = metaValue2(a.metadata, "physical.dbType");
+  return {
+    ...columnName ? { columnName } : {},
+    ...dbType ? { dbType } : {},
+    // == null: a YAML `primaryKey:` left empty means "unset", not false —
+    // fall back to the legacy metadata flag in that case too.
+    primaryKey: a.primaryKey == null ? metaFlag(a.metadata, "isPrimaryKey") : !!a.primaryKey
+  };
+}
+var init_physicalMapping = __esm({
+  "backend/src/services/ai/physicalMapping.ts"() {
+    "use strict";
+    __name(metaValue2, "metaValue");
+    __name(metaFlag, "metaFlag");
+    __name(resolveAttributePhysical, "resolveAttributePhysical");
+  }
+});
+
+// backend/src/services/ai/modelOverviewCache.ts
+var modelOverviewCache_exports = {};
+__export(modelOverviewCache_exports, {
+  MODEL_OVERVIEW_TTL_MS: () => MODEL_OVERVIEW_TTL_MS,
+  getModelOverviewCached: () => getModelOverviewCached,
+  invalidateModelOverviewCache: () => invalidateModelOverviewCache,
+  subscribeModelOverviewCache: () => subscribeModelOverviewCache
+});
+function invalidateModelOverviewCache() {
+  cached2 = null;
+  generation++;
+}
+function subscribeModelOverviewCache(projection) {
+  return projection.onInvalidate(() => invalidateModelOverviewCache());
+}
+async function getModelOverviewCached(build) {
+  if (cached2 && Date.now() - cached2.builtAt < MODEL_OVERVIEW_TTL_MS) {
+    return cached2.value;
+  }
+  if (!inflight) {
+    const startedAt = generation;
+    inflight = build().then((value) => {
+      if (generation === startedAt) cached2 = { value, builtAt: Date.now() };
+      return value;
+    }).finally(() => {
+      inflight = null;
+    });
+  }
+  return inflight;
+}
+var MODEL_OVERVIEW_TTL_MS, cached2, inflight, generation;
+var init_modelOverviewCache = __esm({
+  "backend/src/services/ai/modelOverviewCache.ts"() {
+    "use strict";
+    MODEL_OVERVIEW_TTL_MS = 6e4;
+    cached2 = null;
+    inflight = null;
+    generation = 0;
+    __name(invalidateModelOverviewCache, "invalidateModelOverviewCache");
+    __name(subscribeModelOverviewCache, "subscribeModelOverviewCache");
+    __name(getModelOverviewCached, "getModelOverviewCached");
+  }
+});
+
 // backend/src/services/systemPromptStore.ts
 import { createHash as createHash2 } from "crypto";
 function systemPromptDigest(body) {
@@ -104542,10 +104626,6 @@ var init_aiMermaid = __esm({
 });
 
 // backend/src/controllers/aiSql.ts
-function metaValue2(meta3, name21) {
-  const e = meta3?.find((m) => m.name === name21);
-  return e && e.value != null ? String(e.value) : void 0;
-}
 function nameList(names, max = 8) {
   if (!names.length) return "";
   return names.length <= max ? names.join(", ") : `${names.slice(0, max).join(", ")} +${names.length - max} more`;
@@ -104587,44 +104667,107 @@ function sqlType(base, v, dialect) {
   }
 }
 function columnFor(a, derived, dialect) {
-  const physName = metaValue2(a.metadata, "physical.columnName");
-  const physType = metaValue2(a.metadata, "physical.dbType");
+  const phys = resolveAttributePhysical(a);
   const resolved = resolveBase(String(a.type || "string"), a.validation, derived);
   return {
     attribute: a.name,
-    column: physName ?? a.name,
-    dbType: physType ?? sqlType(resolved.base, resolved.validation, dialect),
+    column: phys.columnName ?? a.name,
+    dbType: phys.dbType ?? sqlType(resolved.base, resolved.validation, dialect),
     nullable: !a.required,
-    primaryKey: !!a.primaryKey,
-    ...physName || physType ? {} : { physicalMappingMissing: true }
+    primaryKey: phys.primaryKey,
+    ...phys.columnName || phys.dbType ? {} : { physicalMappingMissing: true }
   };
 }
 async function buildSqlSchema(input, services, opts) {
   const dialect = input.dialect ?? "generic";
   const { listMicroservices: listMicroservices2 } = await Promise.resolve().then(() => (init_fileOperations(), fileOperations_exports));
-  const pkgs = input.packageName ? [input.packageName] : await listMicroservices2();
+  const allPkgs = await listMicroservices2();
+  if (input.entityNames !== void 0 && !Array.isArray(input.entityNames)) {
+    return {
+      error: `entityNames must be an array of entity names, e.g. entityNames: ['Order']. Retry with an array, or call searchModel({ query: '<entity or business term>' }) to locate the entity first.`
+    };
+  }
+  const requestedNames = Array.isArray(input.entityNames) ? input.entityNames.map((n) => String(n).trim()).filter(Boolean) : void 0;
+  if (input.packageName && !allPkgs.includes(input.packageName)) {
+    return {
+      error: `Package '${input.packageName}' not found. Known packages: ${nameList(allPkgs, 12) || "none"}. Call searchModel({ query: '<entity or business term>' }) to locate the element, or retry with entityNames: ['<EntityName>'] \u2014 entity names resolve across all packages.`
+    };
+  }
   const derivedList = await services.derivedTypes.list().catch(() => []);
   const derived = new Map(derivedList.map((d) => [d.name, d]));
-  const allPkgs = await listMicroservices2();
-  const nameByUuid = /* @__PURE__ */ new Map();
+  const entitiesByPkg = /* @__PURE__ */ new Map();
   for (const p of allPkgs) {
-    for (const e of await services.serviceService.getServiceEntities(p).catch(() => [])) nameByUuid.set(e.uuid, e.name);
+    entitiesByPkg.set(p, await services.serviceService.getServiceEntities(p).catch(() => []));
+  }
+  const nameByUuid = /* @__PURE__ */ new Map();
+  for (const ents of entitiesByPkg.values()) {
+    for (const e of ents) nameByUuid.set(e.uuid, e.name);
+  }
+  const relsByPkg = /* @__PURE__ */ new Map();
+  const relsFor = /* @__PURE__ */ __name(async (p) => {
+    if (!relsByPkg.has(p)) relsByPkg.set(p, await services.serviceService.getPackageRelationships(p).catch(() => []));
+    return relsByPkg.get(p);
+  }, "relsFor");
+  let pkgs;
+  let include = null;
+  let scope;
+  const unresolved = [];
+  if (requestedNames?.length) {
+    pkgs = allPkgs;
+    const wanted = /* @__PURE__ */ new Set();
+    for (const name21 of requestedNames) {
+      const exact = [];
+      const loose = [];
+      for (const ents of entitiesByPkg.values()) {
+        for (const e of ents) {
+          if (e.name === name21) exact.push(e.uuid);
+          else if (e.name.toLowerCase() === name21.toLowerCase()) loose.push(e.uuid);
+        }
+      }
+      const hits = exact.length ? exact : loose;
+      if (hits.length) hits.forEach((u) => wanted.add(u));
+      else unresolved.push(name21);
+    }
+    if (!wanted.size) {
+      return {
+        error: `None of the requested entities (${requestedNames.join(", ")}) exist in any package. Call searchModel({ query: '<entity or business term>' }) to locate the right entity names, then retry.`
+      };
+    }
+    include = new Set(wanted);
+    for (const p of allPkgs) {
+      for (const r of await relsFor(p)) {
+        if (wanted.has(r.source.entity)) include.add(r.target.entity);
+        if (wanted.has(r.target.entity)) include.add(r.source.entity);
+      }
+    }
+    const resolved = requestedNames.filter((n) => !unresolved.includes(n));
+    scope = `entities: ${resolved.join(", ")} (+directly related)`;
+  } else {
+    pkgs = input.packageName ? [input.packageName] : allPkgs;
+    scope = input.packageName ?? "all packages";
   }
   const tables = [];
   const relationships = [];
   let missing = 0;
+  const fallbackTables = [];
   for (const p of pkgs) {
-    const entities = await services.serviceService.getServiceEntities(p).catch(() => []);
+    const entities = (entitiesByPkg.get(p) ?? []).filter((e) => !include || include.has(e.uuid));
     for (const e of entities) {
       const schema = metaValue2(e.metadata, "physical.schema") ?? (opts?.defaultSchema?.trim() || void 0);
       const table = metaValue2(e.metadata, "physical.tableName") ?? e.name;
+      let entityMissing = 0;
       const columns = (e.attributes ?? []).map((a) => {
         const c = columnFor(a, derived, dialect);
-        if ("physicalMappingMissing" in c) missing++;
+        if ("physicalMappingMissing" in c) entityMissing++;
         return c;
       });
+      if (entityMissing > 0) {
+        missing += entityMissing;
+        if (!fallbackTables.includes(table)) fallbackTables.push(table);
+      }
       tables.push({
         entity: e.name,
+        package: p,
         table,
         ...schema ? { schema } : {},
         // Ready-to-use name for SQL — schema.table when a schema is known.
@@ -104632,7 +104775,8 @@ async function buildSqlSchema(input, services, opts) {
         columns
       });
     }
-    for (const r of await services.serviceService.getPackageRelationships(p).catch(() => [])) {
+    for (const r of await relsFor(p)) {
+      if (include && !(include.has(r.source.entity) && include.has(r.target.entity))) continue;
       const from = nameByUuid.get(r.source.entity);
       const to = nameByUuid.get(r.target.entity);
       if (!from || !to) continue;
@@ -104645,7 +104789,6 @@ async function buildSqlSchema(input, services, opts) {
       });
     }
   }
-  const scope = input.packageName ?? "all packages";
   const tableNames = tables.map((t) => t.entity);
   return {
     // #tool-summary — concise line, NAMES the tables for the tool card.
@@ -104655,7 +104798,9 @@ async function buildSqlSchema(input, services, opts) {
     schemaQualifyTables: !!opts?.schemaQualifyTables,
     tables,
     relationships,
-    note: "Use these PHYSICAL table/column names and dbTypes when writing SQL. " + (opts?.schemaQualifyTables ? "Schema-qualify every table (use each table's qualifiedName). " : "") + (missing > 0 ? `${missing} column(s) have no physical mapping \u2014 their dbType is a fallback derived from the logical type; flag this to the user.` : "All columns have an explicit physical mapping.")
+    ...unresolved.length ? { unresolvedEntityNames: unresolved } : {},
+    ...fallbackTables.length ? { tablesWithFallbackColumns: fallbackTables } : {},
+    note: "Use these PHYSICAL table/column names and dbTypes when writing SQL. " + (opts?.schemaQualifyTables ? "Schema-qualify every table (use each table's qualifiedName). " : "") + (missing > 0 ? `${missing} column(s) in table(s) ${nameList(fallbackTables, 6)} have no explicit physical mapping \u2014 their column names/dbTypes are derived from the logical model; WARN the user before relying on them.` : "All columns have an explicit physical mapping.") + (unresolved.length ? ` Requested entities not found: ${unresolved.join(", ")} \u2014 call searchModel({ query: '<name>' }) to locate them.` : "")
   };
 }
 var getSqlSchemaInputSchema, getSqlSchemaParameters;
@@ -104663,18 +104808,20 @@ var init_aiSql = __esm({
   "backend/src/controllers/aiSql.ts"() {
     "use strict";
     init_zod();
+    init_physicalMapping();
     getSqlSchemaInputSchema = external_exports.object({
       packageName: external_exports.string().optional().describe("Scope to one package (omit for the whole model)"),
+      entityNames: external_exports.array(external_exports.string()).optional().describe("PREFERRED scope on large models: the target entity names (resolved across all packages). Their directly-related entities are included automatically so JOINs can be derived."),
       dialect: external_exports.enum(["generic", "postgres", "mysql", "mssql", "oracle", "sqlite"]).optional().describe("Target SQL dialect \u2014 tunes fallback column types (default generic)")
     });
     getSqlSchemaParameters = {
       type: "object",
       properties: {
         packageName: { type: "string", description: "Scope to one package (omit for the whole model)" },
+        entityNames: { type: "array", items: { type: "string" }, description: "PREFERRED scope on large models: target entity names, resolved across all packages; directly-related entities are included automatically for JOINs" },
         dialect: { type: "string", enum: ["generic", "postgres", "mysql", "mssql", "oracle", "sqlite"], description: "Target SQL dialect (default generic)" }
       }
     };
-    __name(metaValue2, "metaValue");
     __name(nameList, "nameList");
     __name(resolveBase, "resolveBase");
     __name(sqlType, "sqlType");
@@ -116875,16 +117022,15 @@ function buildEntityDetails(entity, packageName) {
   const tableName = metaValue3(entity.metadata, "physical.tableName");
   const schema = metaValue3(entity.metadata, "physical.schema");
   const attributes = (entity.attributes ?? []).map((a) => {
-    const columnName = metaValue3(a.metadata, "physical.columnName");
-    const dbType = metaValue3(a.metadata, "physical.dbType");
+    const phys = resolveAttributePhysical(a);
     return {
       name: a.name,
       type: a.type,
       description: a.description,
       required: a.required,
-      primaryKey: a.primaryKey,
+      primaryKey: phys.primaryKey,
       ...a.validation ? { validation: a.validation } : {},
-      ...columnName || dbType ? { physical: { ...columnName ? { columnName } : {}, ...dbType ? { dbType } : {} } } : {}
+      ...phys.columnName || phys.dbType ? { physical: { ...phys.columnName ? { columnName: phys.columnName } : {}, ...phys.dbType ? { dbType: phys.dbType } : {} } } : {}
     };
   });
   const hasPhysical = !!(tableName || schema) || attributes.some((a) => a.physical);
@@ -116896,6 +117042,7 @@ function buildEntityDetails(entity, packageName) {
     // #tool-summary — concise self-describing line for the tool card.
     summary: `${entity.name}${packageName ? ` (${packageName})` : ""} \u2014 ${attributes.length} attribute${attributes.length === 1 ? "" : "s"}${extras.length ? ` (${extras.join(", ")})` : ""}`,
     name: entity.name,
+    ...packageName ? { packageName } : {},
     description: entity.description,
     stereotype: entity.stereotype,
     ...tableName || schema ? { physical: { ...tableName ? { tableName } : {}, ...schema ? { schema } : {} } } : {},
@@ -116904,6 +117051,46 @@ function buildEntityDetails(entity, packageName) {
     ...entity.rules?.length ? { rules: entity.rules.map((r) => ({ name: r.name, description: r.description, severity: r.severity })) } : {}
   };
 }
+async function executeGetEntityDetails(args, services) {
+  if (!args?.entityName) return { error: "entityName is required." };
+  const matches = await services.serviceService.findEntityMatches(args.entityName, args.packageName || void 0);
+  if (matches.length === 1) {
+    return buildEntityDetails(matches[0].entity, matches[0].packageName);
+  }
+  if (matches.length > 1) {
+    return {
+      summary: `'${args.entityName}' matches ${matches.length} entities \u2014 specify packageName`,
+      ambiguous: true,
+      candidates: matches.map((m) => ({
+        entityName: m.entity.name,
+        packageName: m.packageName,
+        ...m.entity.description ? { description: m.entity.description } : {}
+      })),
+      note: "Several packages define an entity with this name. Call getEntityDetails again with the intended packageName."
+    };
+  }
+  return {
+    error: `Entity '${args.entityName}' not found in ${args.packageName ? `package '${args.packageName}' or ` : ""}any package. Call searchModel({ query: '${args.entityName}' }) to locate it by full-text search \u2014 the model may use a different name.`
+  };
+}
+async function executeListEntities(args, services) {
+  const { listMicroservices: listMicroservices2 } = await Promise.resolve().then(() => (init_fileOperations(), fileOperations_exports));
+  if (args?.packageName) {
+    const packages2 = await listMicroservices2().catch(() => []);
+    if (!packages2.includes(args.packageName)) {
+      return {
+        error: `Package '${args.packageName}' not found. Known packages: ${nameList2(packages2, 12) || "none"}. Call searchModel({ query: '<entity or business term>' }) to locate the element you are after.`
+      };
+    }
+    const entities = await services.serviceService.getServiceEntities(args.packageName);
+    return {
+      summary: `${args.packageName}: ${nameList2(entities.map((e) => e.name)) || "no entities"}`,
+      entities: entities.map((e) => ({ name: e.name, description: e.description, attrCount: e.attributes?.length || 0 }))
+    };
+  }
+  const packages = await listMicroservices2();
+  return { summary: `packages: ${nameList2(packages) || "none"}`, packages };
+}
 async function buildModelOverview(services) {
   const { listMicroservices: listMicroservices2 } = await Promise.resolve().then(() => (init_fileOperations(), fileOperations_exports));
   const pkgNames = await listMicroservices2().catch(() => []);
@@ -116962,9 +117149,35 @@ function formatModelOutline(o) {
 Packages:
 ${pkgLines}${extra.length ? "\n" + extra.join("\n") : ""}`;
 }
+function formatModelOutlineWithinBudget(o, maxChars = MODEL_OUTLINE_MAX_CHARS) {
+  const full = formatModelOutline(o);
+  if (full.length <= maxChars) return full;
+  const t = o.totals;
+  const head = `Current model snapshot \u2014 ${t.packages} package(s), ${t.entities} entities, ${t.relationships} relationships, ${t.cases} cases, ${t.rules} rules, ${t.events} events, ${t.actions} actions, ${t.stateMachines} state machines, ${t.derivedTypes} derived types, ${t.stereotypes} stereotypes.`;
+  const banner = `Entity lists omitted (${t.entities} entities across ${t.packages} packages \u2014 too large to inline). You do NOT have the full entity list. To locate any entity, call searchModel with its name or a business term, then getEntityDetails (packageName optional) or getSqlSchema with entityNames. Do NOT guess entity, package, or table names.`;
+  const pkgLines = o.packages.map((p) => `  - ${p.name}: ${p.entities.length} entit${p.entities.length === 1 ? "y" : "ies"}, ${p.relationships} relationship${p.relationships === 1 ? "" : "s"}`);
+  const fixed = head.length + banner.length + "Packages:\n".length + 4;
+  const lines = [];
+  let used = fixed;
+  for (let i = 0; i < pkgLines.length; i++) {
+    const remaining = pkgLines.length - i;
+    if (used + pkgLines[i].length + 1 > maxChars - 80 && remaining > 1) {
+      lines.push(`  \u2026 +${remaining} more packages (call listEntities to enumerate)`);
+      break;
+    }
+    lines.push(pkgLines[i]);
+    used += pkgLines[i].length + 1;
+  }
+  return `${head}
+${banner}
+Packages:
+${lines.join("\n")}`;
+}
 async function safeModelOutline(services) {
   try {
-    return formatModelOutline(await buildModelOverview(services));
+    return formatModelOutlineWithinBudget(
+      await getModelOverviewCached(() => buildModelOverview(services))
+    );
   } catch {
     return "";
   }
@@ -117130,7 +117343,7 @@ function buildSystemPrompt(pageContext, conversationSystemPrompt, mode = "design
   if (typeof modelOutline === "string" && modelOutline.trim().length > 0) {
     out += `
 
-${modelOutline.trim().slice(0, 2e3)}`;
+${modelOutline.trim().slice(0, MODEL_OUTLINE_MAX_CHARS)}`;
   }
   if (typeof pageContext === "string") {
     const trimmed2 = pageContext.trim();
@@ -117142,7 +117355,7 @@ Page context: ${trimmed2.slice(0, 500)}`;
   }
   return out;
 }
-function buildDirectChatMessages(rawMessages, maxToolResultChars = 2e3) {
+function buildDirectChatMessages(rawMessages, maxToolResultChars = DIRECT_TOOL_RESULT_MAX_CHARS) {
   const out = [];
   for (const msg of rawMessages) {
     const text2 = msg.parts?.find((p) => p.type === "text")?.text || msg.content || "";
@@ -117158,10 +117371,13 @@ function buildDirectChatMessages(rawMessages, maxToolResultChars = 2e3) {
         }))
       });
       for (const tc of toolCalls) {
+        const serialized = JSON.stringify(tc.output ?? {});
         out.push({
           role: "tool",
           tool_call_id: String(tc.id),
-          content: JSON.stringify(tc.output ?? {}).slice(0, maxToolResultChars)
+          // Truncation must be LOUD — a silent cut reads as a complete result
+          // and the model trusts a partial schema instead of narrowing scope.
+          content: serialized.length > maxToolResultChars ? serialized.slice(0, maxToolResultChars) + TOOL_RESULT_TRUNCATION_MARKER : serialized
         });
       }
     } else if (text2) {
@@ -117216,10 +117432,10 @@ async function handleDirectChat(req, res, cfg, rawMessages, services, pageContex
     { type: "function", function: { name: "createAction", description: "Create an Action/command (e.g. PlaceOrder) on an aggregate entity (ownerEntityName), optionally CQRS-classified, with an optional flow of steps. Use flow steps emitEvent {name} and wait {for} to wire a saga/process across actions+events.", parameters: createActionParameters } },
     { type: "function", function: { name: "createStateMachine", description: "Create a state machine on an entity (ownerEntityName) \u2014 its states, initialState, and transitions (from/to/on). Model an entity lifecycle, e.g. Order PENDING\u2192PAID\u2192SHIPPED.", parameters: createStateMachineParameters } },
     { type: "function", function: { name: "listEntities", description: "List packages or entities in a package", parameters: { type: "object", properties: { packageName: { type: "string", description: "Package name (omit to list all)" } } } } },
-    { type: "function", function: { name: "getEntityDetails", description: "Get full detail for one entity: attributes with type/required/primaryKey AND field validation, the PHYSICAL mapping (entity table name + schema, each attribute physical column name + DB type), physical constraints, and inline business rules. Call this before writing SQL/DDL so you use the real physical names and types.", parameters: { type: "object", required: ["packageName", "entityName"], properties: { packageName: { type: "string" }, entityName: { type: "string" } } } } },
+    { type: "function", function: { name: "getEntityDetails", description: "Get full detail for one entity: attributes with type/required/primaryKey AND field validation, the PHYSICAL mapping (entity table name + schema, each attribute physical column name + DB type), physical constraints, and inline business rules. packageName is OPTIONAL \u2014 omit it and the entity name is resolved across every package (ambiguous names return a candidate list). Call this before writing SQL/DDL so you use the real physical names and types.", parameters: { type: "object", required: ["entityName"], properties: { packageName: { type: "string", description: "Owning package if known (optional \u2014 resolved across packages when omitted)" }, entityName: { type: "string" } } } } },
     { type: "function", function: { name: "getModelOverview", description: "Get a whole-model outline: every package with its entity names, and a count of each concept (entities, relationships, cases, rules, events, actions, state machines, derived types, stereotypes). A snapshot is already in your context; call this to refresh after changes.", parameters: { type: "object", properties: {} } } },
     { type: "function", function: { name: "generateMermaid", description: 'Convert the model to Mermaid diagram source. diagram: "er" (entity-relationship of a package, or all), "class" (class diagram), "state" (a single entity state machine \u2014 pass entityName), "flow" (actions+events saga). Returns { mermaid }. Present it inside a ```mermaid code block.', parameters: generateMermaidParameters } },
-    { type: "function", function: { name: "getSqlSchema", description: "Get the PHYSICAL relational schema for writing SQL: per-entity table name + schema, each column (physical name, dbType, nullable, primaryKey), and relationships as join hints. Optional packageName scope and dialect. Call this before writing any SQL query or DDL so you use real physical names/types, not the conceptual (logical) names.", parameters: getSqlSchemaParameters } },
+    { type: "function", function: { name: "getSqlSchema", description: "Get the PHYSICAL relational schema for writing SQL: per-entity table name + schema, each column (physical name, dbType, nullable, primaryKey), and relationships as join hints. PREFER scoping with entityNames (target entities, resolved across packages; directly-related entities are included automatically for JOINs) or packageName \u2014 an unscoped call on a large model returns a huge result that may be truncated. Optional dialect. Call this before writing any SQL query or DDL so you use real physical names/types, not the conceptual (logical) names.", parameters: getSqlSchemaParameters } },
     { type: "function", function: { name: "listStereotypes", description: "List available stereotypes", parameters: { type: "object", properties: {} } } },
     { type: "function", function: { name: "navigateTo", description: 'Navigate user to a page. The path MUST be an absolute URL beginning with "/" that matches one of the patterns returned by listRoutes \u2014 call listRoutes first if you are unsure of the exact shape.', parameters: { type: "object", required: ["path", "reason"], properties: { path: { type: "string" }, reason: { type: "string" } } } } },
     { type: "function", function: { name: "listRoutes", description: "List every valid URL pattern in the app with a short description and (where useful) a concrete example. Call this BEFORE navigateTo if you are unsure of the exact path shape \u2014 e.g. plural vs singular, where attribute pages live, what the case route is.", parameters: { type: "object", properties: {} } } }
@@ -117281,21 +117497,13 @@ async function handleDirectChat(req, res, cfg, rawMessages, services, pageContex
         return await executeCreateStateMachine(args, conceptServices);
       }
       if (name21 === "listEntities") {
-        if (args.packageName) {
-          const entities = await services.serviceService.getServiceEntities(args.packageName);
-          return { summary: `${args.packageName}: ${nameList2(entities.map((e) => e.name)) || "no entities"}`, entities: entities.map((e) => ({ name: e.name, description: e.description })) };
-        }
-        const { listMicroservices: listMicroservices2 } = await Promise.resolve().then(() => (init_fileOperations(), fileOperations_exports));
-        const packages = await listMicroservices2();
-        return { summary: `packages: ${nameList2(packages) || "none"}`, packages };
+        return await executeListEntities(args, services);
       }
       if (name21 === "getEntityDetails") {
-        const entity = await services.serviceService.getEntitySchema(args.packageName || "default", args.entityName);
-        if (!entity) return { error: "Entity not found" };
-        return buildEntityDetails(entity, args.packageName);
+        return await executeGetEntityDetails(args, services);
       }
       if (name21 === "getModelOverview") {
-        return await buildModelOverview(services);
+        return await getModelOverviewCached(() => buildModelOverview(services));
       }
       if (name21 === "generateMermaid") {
         return await generateMermaidDiagram(args, services);
@@ -117334,8 +117542,11 @@ async function handleDirectChat(req, res, cfg, rawMessages, services, pageContex
       }
     }
     const out = await runTool(name21, args);
-    if (isGatedCategory(category) && out && typeof out === "object" && out.success === true) {
-      mutatingSuccessCount++;
+    if (isGatedCategory(category)) {
+      invalidateModelOverviewCache();
+      if (out && typeof out === "object" && out.success === true) {
+        mutatingSuccessCount++;
+      }
     }
     return out;
   }, "executeTool");
@@ -117461,7 +117672,7 @@ ${lines.join("\n")}` : "";
     return "";
   }
 }
-var TOOL_CATEGORY_MAP, READ_ONLY_TOOLS, MODE_SYSTEM_SUFFIX, GATED_CATEGORIES, DENIED_RESULT, SYSTEM_PROMPT, aiChat, aiChatApprove, aiStatus, aiGetConfig, aiSaveConfig, aiTestTools, aiTools, aiMentionsSearch, listConversations, getConversation, saveConversation, patchConversation, deleteConversation, getSystemPromptByDigest, listPrompts, getPrompt, createPrompt, updatePrompt, deletePrompt;
+var TOOL_CATEGORY_MAP, READ_ONLY_TOOLS, MODE_SYSTEM_SUFFIX, GATED_CATEGORIES, MODEL_OUTLINE_MAX_CHARS, DENIED_RESULT, SYSTEM_PROMPT, DIRECT_TOOL_RESULT_MAX_CHARS, TOOL_RESULT_TRUNCATION_MARKER, aiChat, aiChatApprove, aiStatus, aiGetConfig, aiSaveConfig, aiTestTools, aiTools, aiMentionsSearch, listConversations, getConversation, saveConversation, patchConversation, deleteConversation, getSystemPromptByDigest, listPrompts, getPrompt, createPrompt, updatePrompt, deletePrompt;
 var init_aiController = __esm({
   "backend/src/controllers/aiController.ts"() {
     "use strict";
@@ -117471,6 +117682,8 @@ var init_aiController = __esm({
     init_config();
     init_agentToolRegistry();
     init_authoringRules();
+    init_physicalMapping();
+    init_modelOverviewCache();
     init_systemPromptStore();
     init_appDir();
     init_conversationService();
@@ -117542,8 +117755,12 @@ Mode: REVIEW. You are reviewing the data model for quality issues. Use read-only
     __name(nameList2, "nameList");
     __name(metaValue3, "metaValue");
     __name(buildEntityDetails, "buildEntityDetails");
+    __name(executeGetEntityDetails, "executeGetEntityDetails");
+    __name(executeListEntities, "executeListEntities");
     __name(buildModelOverview, "buildModelOverview");
     __name(formatModelOutline, "formatModelOutline");
+    MODEL_OUTLINE_MAX_CHARS = 4e3;
+    __name(formatModelOutlineWithinBudget, "formatModelOutlineWithinBudget");
     __name(safeModelOutline, "safeModelOutline");
     __name(isGatedCategory, "isGatedCategory");
     __name(resolveToolCategory, "resolveToolCategory");
@@ -117569,21 +117786,24 @@ This system models a RICH domain \u2014 not just entities. You can author all of
 - Events \u2014 domain events emitted by aggregates, e.g. OrderPlaced (createEvent)
 - Actions \u2014 commands/queries on aggregates with a flow; emitEvent/wait steps wire a saga/process (createAction)
 - State machines \u2014 entity lifecycles: states + transitions, e.g. Order PENDING\u2192PAID\u2192SHIPPED (createStateMachine)
-- Read/inspect: searchModel (full-text search across the whole dictionary \u2014 use it to LOCATE an entity/attribute/rule when you don't know its exact name, then drill in), getModelOverview (whole-model outline \u2014 packages, entities, and concept counts; a current snapshot is already shown to you below), getEntityDetails (one entity in full incl. physical mapping), listEntities, listStereotypes; navigate with navigateTo (call listRoutes first if unsure)
+- Read/inspect: searchModel (full-text search across the whole dictionary \u2014 use it to LOCATE an entity/attribute/rule when you don't know its exact name, then drill in), getModelOverview (whole-model outline \u2014 packages, entities, and concept counts; a current snapshot is already shown to you below), getEntityDetails (one entity in full incl. physical mapping; packageName optional \u2014 the name resolves across packages), listEntities, listStereotypes; navigate with navigateTo (call listRoutes first if unsure)
 - Diagram: generateMermaid converts the model to Mermaid source \u2014 diagram: "er" (entity-relationship of a package/all), "class" (class diagram), "state" (an entity's state machine, needs entityName), or "flow" (actions+events saga). Use it when the user asks for a diagram, ERD, or visualization, and present the result in a fenced mermaid code block.
 
 A "process" or "saga" is NOT a separate object \u2014 it is the graph that emerges from Actions (with emitEvent/wait flow steps) and Events. To model a process, create the Actions and Events; the saga view is derived automatically.
 
 CONCEPTUAL vs PHYSICAL model \u2014 keep these two layers distinct:
 - CONCEPTUAL / LOGICAL is the business model: entity names (PascalCase, e.g. Order), attribute names (camelCase, e.g. orderNumber), and logical or derived types (e.g. money, email, currency-code). This is what you author and what users discuss.
-- PHYSICAL is how it is persisted in a database: a table name (physical.tableName) in a schema, per-column physical names (physical.columnName) and DB types (physical.dbType), plus constraints. The two layers can differ completely (logical Order.orderNumber \u2192 physical orders.order_no VARCHAR). getEntityDetails returns the physical mapping for one entity; getSqlSchema returns the whole physical relational schema.
+- PHYSICAL is how it is persisted in a database: a table name (physical.tableName) in a schema, per-column physical names (physical.columnName) and DB types (physical.dbType), plus constraints. The two layers can differ completely (logical Order.orderNumber \u2192 physical orders.order_no VARCHAR). getEntityDetails returns the physical mapping for one entity; getSqlSchema returns the physical relational schema (scope it with entityNames or packageName on anything but a small model).
 - A logical/derived type (money, email) is NOT a DB type \u2014 it maps to a physical dbType (money \u2192 DECIMAL(12,2), email \u2192 VARCHAR(254)).
 - NEVER write DDL or SQL using conceptual names. Always resolve to the physical table/column names and dbTypes first. If an element has no physical mapping yet, getSqlSchema returns a fallback dbType derived from the logical type and flags it \u2014 pass that flag on to the user.
 
 Generating database queries: when the user asks for a SQL query (SELECT / INSERT / UPDATE / DELETE), a report, or DDL \u2014
-1. Call getSqlSchema (optionally a packageName scope and the target dialect) to get the real table names, columns + dbTypes, primary keys, and relationships.
-2. Write the query using ONLY physical names; derive JOINs from the relationships (join the PK of the "one" side to the FK on the "many" side) and respect the requested dialect.
-3. Present the query in a fenced sql code block, and briefly note any assumption (an inferred join column, a missing physical mapping). You generate queries for the user to run \u2014 you do NOT execute them against a live database.
+1. LOCATE the entity first. Unless you already know its owning package (from the snapshot, page context, or an @mention), call searchModel with the entity name or business term to resolve entity \u2192 package. NEVER guess a package, entity, or table name \u2014 the snapshot above may not list every entity.
+2. Call getSqlSchema scoped NARROWLY: pass entityNames: [...] for the target entities (their directly-related entities are included automatically so you can derive JOINs), or a packageName; pass the target dialect. Do not call it unscoped on a large model \u2014 the result gets truncated and misleads you.
+3. Write the query using ONLY the physical names returned by the tool; derive JOINs from the relationships (join the PK of the "one" side to the FK on the "many" side) and respect the requested dialect.
+4. If any column is flagged physicalMappingMissing, tell the user those column names/types are unverified fallbacks derived from the logical model \u2014 do not silently pass them off as real.
+5. Present the query in a fenced sql code block, and briefly note any assumption (an inferred join column, a missing physical mapping). You generate queries for the user to run \u2014 you do NOT execute them against a live database.
+If a lookup tool returns an error or an empty result, do not retry the same guess \u2014 follow the error's guidance (usually: call searchModel), or ask the user.
 
 When creating data models:
 - Use meaningful names (PascalCase for entities/events, camelCase for attributes)
@@ -117614,6 +117834,8 @@ Be concise in your responses. Show a summary of what you created.`;
     __name(sqlSettingsInstruction, "sqlSettingsInstruction");
     __name(standingSystemPrompt, "standingSystemPrompt");
     __name(buildSystemPrompt, "buildSystemPrompt");
+    DIRECT_TOOL_RESULT_MAX_CHARS = 2e4;
+    TOOL_RESULT_TRUNCATION_MARKER = "\u2026[truncated \u2014 result too large; retry with a narrower scope, e.g. packageName or entityNames filter]";
     __name(buildDirectChatMessages, "buildDirectChatMessages");
     __name(buildUiMessagesWithToolParts, "buildUiMessagesWithToolParts");
     __name(handleDirectChat, "handleDirectChat");
@@ -117666,7 +117888,11 @@ Be concise in your responses. Show a summary of what you created.`;
             const decision = await awaitApproval(streamId, toolCallId);
             if (decision === "deny") return { ...DENIED_RESULT };
           }
-          return run();
+          try {
+            return await run();
+          } finally {
+            if (isGatedCategory(category)) invalidateModelOverviewCache();
+          }
         }, "gate");
         const mcpToolEntries = {};
         for (const mcpTool of mcpTools) {
@@ -117837,29 +118063,21 @@ Be concise in your responses. Show a summary of what you created.`;
               }),
               execute: /* @__PURE__ */ __name(async (params) => {
                 try {
-                  if (params.packageName) {
-                    const entities = await services.serviceService.getServiceEntities(params.packageName || "default");
-                    return { summary: `${params.packageName}: ${nameList2(entities.map((e) => e.name)) || "no entities"}`, entities: entities.map((e) => ({ name: e.name, description: e.description, attrCount: e.attributes?.length || 0 })) };
-                  }
-                  const { listMicroservices: listMicroservices2 } = await Promise.resolve().then(() => (init_fileOperations(), fileOperations_exports));
-                  const packages = await listMicroservices2();
-                  return { summary: `packages: ${nameList2(packages) || "none"}`, packages };
+                  return await executeListEntities(params, services);
                 } catch (err) {
                   return { error: err.message };
                 }
               }, "execute")
             }),
             getEntityDetails: tool({
-              description: "Get full detail for an entity: attributes with type/required/primaryKey AND field validation, the PHYSICAL mapping (entity table name + schema, each attribute physical column name + DB type), physical constraints, and inline business rules. Use this before writing SQL/DDL so you use the real physical names and types.",
+              description: "Get full detail for an entity: attributes with type/required/primaryKey AND field validation, the PHYSICAL mapping (entity table name + schema, each attribute physical column name + DB type), physical constraints, and inline business rules. packageName is OPTIONAL \u2014 omit it and the entity name is resolved across every package (ambiguous names return a candidate list). Use this before writing SQL/DDL so you use the real physical names and types.",
               inputSchema: external_exports.object({
-                packageName: external_exports.string(),
+                packageName: external_exports.string().optional().describe("Owning package if known (optional \u2014 resolved across packages when omitted)"),
                 entityName: external_exports.string()
               }),
               execute: /* @__PURE__ */ __name(async (params) => {
                 try {
-                  const entity = await services.serviceService.getEntitySchema(params.packageName || "default", params.entityName);
-                  if (!entity) return { error: "Entity not found" };
-                  return buildEntityDetails(entity, params.packageName);
+                  return await executeGetEntityDetails(params, services);
                 } catch (err) {
                   return { error: err.message };
                 }
@@ -117870,7 +118088,7 @@ Be concise in your responses. Show a summary of what you created.`;
               inputSchema: external_exports.object({}),
               execute: /* @__PURE__ */ __name(async () => {
                 try {
-                  return await buildModelOverview(services);
+                  return await getModelOverviewCached(() => buildModelOverview(services));
                 } catch (err) {
                   return { error: err.message };
                 }
@@ -117888,7 +118106,7 @@ Be concise in your responses. Show a summary of what you created.`;
               }, "execute")
             }),
             getSqlSchema: tool({
-              description: "Get the PHYSICAL relational schema for writing SQL: per-entity table name + schema, each column (physical name, dbType, nullable, primaryKey), and relationships as join hints. Optional packageName scope and dialect. Call this before writing any SQL query or DDL so you use real physical names/types, not the conceptual (logical) names.",
+              description: "Get the PHYSICAL relational schema for writing SQL: per-entity table name + schema, each column (physical name, dbType, nullable, primaryKey), and relationships as join hints. PREFER scoping with entityNames (target entities, resolved across packages; directly-related entities are included automatically for JOINs) or packageName \u2014 an unscoped call on a large model returns a huge result that may be truncated. Optional dialect. Call this before writing any SQL query or DDL so you use real physical names/types, not the conceptual (logical) names.",
               inputSchema: getSqlSchemaInputSchema,
               execute: /* @__PURE__ */ __name(async (params) => {
                 try {
@@ -118321,7 +118539,7 @@ Be concise in your responses. Show a summary of what you created.`;
           description: "Get full entity detail: attributes + validation, the physical mapping (table/schema, column names, DB types), constraints, and inline rules. Use before writing SQL/DDL.",
           source: "builtin",
           parameters: [
-            { name: "packageName", type: "string", required: true, description: "Package name" },
+            { name: "packageName", type: "string", required: false, description: "Owning package if known (omit to resolve the entity name across all packages)" },
             { name: "entityName", type: "string", required: true, description: "Entity name" }
           ]
         },
@@ -118343,10 +118561,11 @@ Be concise in your responses. Show a summary of what you created.`;
         },
         {
           name: "getSqlSchema",
-          description: "Physical relational schema for writing SQL: tables, columns (physical name + dbType + nullable + PK), and relationships as join hints. Use before generating any SQL query/DDL.",
+          description: "Physical relational schema for writing SQL: tables, columns (physical name + dbType + nullable + PK), and relationships as join hints. Use before generating any SQL query/DDL. Prefer scoping with entityNames or packageName on large models.",
           source: "builtin",
           parameters: [
             { name: "packageName", type: "string", required: false, description: "Scope to one package (omit for all)" },
+            { name: "entityNames", type: "string[]", required: false, description: "Preferred scope: target entity names, resolved across packages; directly-related entities are included automatically for JOINs" },
             { name: "dialect", type: "generic|postgres|mysql|mssql|oracle|sqlite", required: false, description: "Target SQL dialect (default generic)" }
           ]
         },
@@ -150141,8 +150360,8 @@ var require_inflight = __commonJS({
     var wrappy = require_wrappy();
     var reqs = /* @__PURE__ */ Object.create(null);
     var once = require_once();
-    module.exports = wrappy(inflight);
-    function inflight(key2, cb) {
+    module.exports = wrappy(inflight2);
+    function inflight2(key2, cb) {
       if (reqs[key2]) {
         reqs[key2].push(cb);
         return null;
@@ -150151,7 +150370,7 @@ var require_inflight = __commonJS({
         return makeres(key2);
       }
     }
-    __name(inflight, "inflight");
+    __name(inflight2, "inflight");
     function makeres(key2) {
       return once(/* @__PURE__ */ __name(function RES() {
         var cbs = reqs[key2];
@@ -150203,7 +150422,7 @@ var require_glob = __commonJS({
     var alphasorti = common.alphasorti;
     var setopts = common.setopts;
     var ownProp = common.ownProp;
-    var inflight = require_inflight();
+    var inflight2 = require_inflight();
     var util2 = __require("util");
     var childrenIgnored = common.childrenIgnored;
     var isIgnored = common.isIgnored;
@@ -150535,7 +150754,7 @@ var require_glob = __commonJS({
         return this._readdir(abs, false, cb);
       var lstatkey = "lstat\0" + abs;
       var self2 = this;
-      var lstatcb = inflight(lstatkey, lstatcb_);
+      var lstatcb = inflight2(lstatkey, lstatcb_);
       if (lstatcb)
         fs16.lstat(abs, lstatcb);
       function lstatcb_(er, lstat) {
@@ -150554,7 +150773,7 @@ var require_glob = __commonJS({
     Glob.prototype._readdir = function(abs, inGlobStar, cb) {
       if (this.aborted)
         return;
-      cb = inflight("readdir\0" + abs + "\0" + inGlobStar, cb);
+      cb = inflight2("readdir\0" + abs + "\0" + inGlobStar, cb);
       if (!cb)
         return;
       if (inGlobStar && !ownProp(this.symlinks, abs))
@@ -150712,7 +150931,7 @@ var require_glob = __commonJS({
         }
       }
       var self2 = this;
-      var statcb = inflight("stat\0" + abs, lstatcb_);
+      var statcb = inflight2("stat\0" + abs, lstatcb_);
       if (statcb)
         fs16.lstat(abs, statcb);
       function lstatcb_(er, lstat) {
@@ -174311,6 +174530,12 @@ async function mountFrameworkRoutes() {
       } catch (searchError) {
         logger.warn(`SearchIndex initialization failed: ${searchError instanceof Error ? searchError.message : String(searchError)}`);
       }
+      try {
+        const { subscribeModelOverviewCache: subscribeModelOverviewCache2 } = await Promise.resolve().then(() => (init_modelOverviewCache(), modelOverviewCache_exports));
+        subscribeModelOverviewCache2(projection);
+      } catch (cacheError) {
+        logger.warn(`ModelOverviewCache subscription failed: ${cacheError instanceof Error ? cacheError.message : String(cacheError)}`);
+      }
     } catch (e) {
       logger.warn(`Projection/UuidIndex initialization failed: ${e instanceof Error ? e.message : String(e)}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamak/smart-data-dico",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Collaborative data dictionary management system — model, document, and govern your data landscape",
   "type": "module",
   "bin": {