@hamak/smart-data-dico 1.19.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];
@@ -37683,7 +37683,8 @@ function normalizeRelationship(rel) {
 }
 function fillAttributeDefaults(entity) {
   const fix = /* @__PURE__ */ __name((attrs) => {
-    for (const a of attrs ?? []) {
+    if (!Array.isArray(attrs)) return;
+    for (const a of attrs) {
       if (a.required === void 0) a.required = false;
       if (a.description === void 0) a.description = "";
       if (a.properties) fix(a.properties);
@@ -44015,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);
@@ -44603,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) => ({
@@ -45760,7 +45761,7 @@ var init_dictionaryService = __esm({
         let relationships = [];
         let cases = [];
         try {
-          const model = await loadPackage(packageName);
+          const model = await loadPackage(String(dirPath));
           entities = model.entities;
           relationships = model.relationships;
           cases = model.cases.map((c) => ({
@@ -48507,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 = [];
@@ -48518,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}`);
@@ -48645,6 +48657,51 @@ var init_serviceService = __esm({
           };
         }
       }
+      /**
+       * Move an entity from one package to another (#move-entity). The entity keeps
+       * its UUID, so every UUID-based reference (relationships — cross-package is
+       * first-class — cases, diagrams, perspectives) keeps resolving; nothing is
+       * orphaned. We write the entity into the target package, then remove it from
+       * the source via the projection directly — this bypasses deleteEntity's
+       * same-package relationship guard, which is meant for destruction, not a
+       * relocation where the references remain valid.
+       */
+      async moveEntity(sourcePackage, entityName, targetPackage) {
+        logger.info(`Moving entity: ${sourcePackage}.${entityName} -> ${targetPackage}`);
+        if (!targetPackage || targetPackage === sourcePackage) {
+          return { success: false, errors: ["Target package must differ from the source package"] };
+        }
+        try {
+          const entity = await readEntityFile(sourcePackage, entityName);
+          if (!entity) {
+            return { success: false, errors: [`Entity ${sourcePackage}.${entityName} not found`] };
+          }
+          const packages = await listMicroservices();
+          if (!packages.includes(targetPackage)) {
+            return { success: false, errors: [`Target package '${targetPackage}' does not exist`] };
+          }
+          const existingInTarget = await readEntityFile(targetPackage, entityName);
+          if (existingInTarget) {
+            return {
+              success: false,
+              errors: [`Target package '${targetPackage}' already has an entity named '${entityName}'`]
+            };
+          }
+          const projection = getProjection(wsId("dictionaries"));
+          entity.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+          await projection.writeEntity(`packages/${targetPackage}/entities/${entity.name}`, entity);
+          const removed = await projection.deleteEntity(`packages/${sourcePackage}/entities/${entity.name}`);
+          if (!removed) {
+            await projection.deleteEntity(`packages/${targetPackage}/entities/${entity.name}`).catch(() => {
+            });
+            return { success: false, errors: ["Failed to remove the entity from the source package"] };
+          }
+          return { success: true, errors: [] };
+        } catch (error48) {
+          logger.error(`Error moving entity: ${error48}`);
+          return { success: false, errors: [`Error moving entity: ${error48}`] };
+        }
+      }
       // --- Relationship CRUD ---
       async getPackageRelationships(packageName) {
         const packagePath = getPackagePath(packageName);
@@ -49107,424 +49164,6 @@ var init_serviceService = __esm({
   }
 });
 
-// backend/src/models/Rule.ts
-function validateRule(rule) {
-  const errors = [];
-  if (!rule.name || typeof rule.name !== "string") {
-    errors.push("Rule name is required");
-  } else if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(rule.name)) {
-    errors.push("Rule name must be kebab-case (lowercase letters, numbers, hyphens)");
-  }
-  if (!rule.description || typeof rule.description !== "string") {
-    errors.push("Rule description is required");
-  }
-  if (!rule.severity || !["info", "warning", "error"].includes(rule.severity)) {
-    errors.push("Rule severity must be one of: info, warning, error");
-  }
-  if (!rule.enforcement || !["save", "process", "advisory"].includes(rule.enforcement)) {
-    errors.push("Rule enforcement must be one of: save, process, advisory");
-  }
-  if (!rule.scope || !["entity", "package", "case", "global"].includes(rule.scope)) {
-    errors.push("Rule scope must be one of: entity, package, case, global");
-  }
-  if (!Array.isArray(rule.targets) || rule.targets.length === 0) {
-    errors.push("Rule must have at least one target");
-  }
-  if (rule.scope === "entity" && !rule.entityUuid) {
-    errors.push("Entity-scoped rules must specify entityUuid");
-  }
-  if (rule.scope === "package" && !rule.packageName) {
-    errors.push("Package-scoped rules must specify packageName");
-  }
-  if (rule.scope === "case" && !rule.caseUuid) {
-    errors.push("Case-scoped rules must specify caseUuid");
-  }
-  if (rule.enforcement === "process") {
-    const stageField = (rule.metadata || []).find((m) => m.name === "process-stage-field");
-    if (!stageField || !stageField.value) {
-      errors.push("Process-enforcement rules must reference a metadata field via process-stage-field");
-    }
-  }
-  return errors;
-}
-var init_Rule = __esm({
-  "backend/src/models/Rule.ts"() {
-    "use strict";
-    __name(validateRule, "validateRule");
-  }
-});
-
-// backend/src/services/ruleService.ts
-var ruleService_exports = {};
-__export(ruleService_exports, {
-  ruleService: () => ruleService
-});
-var RuleService, ruleService;
-var init_ruleService = __esm({
-  "backend/src/services/ruleService.ts"() {
-    "use strict";
-    init_Rule();
-    init_fileOperations();
-    init_uuid();
-    init_logger();
-    init_ProjectionRegistry();
-    init_types();
-    RuleService = class {
-      static {
-        __name(this, "RuleService");
-      }
-      /** List all rules from all storage scopes, optionally filtered. */
-      async listRules(filters = {}) {
-        const all = [];
-        if (!filters.scope || filters.scope === "entity") {
-          const files = await listAllEntityRuleFiles();
-          for (const { service, entityUuid } of files) {
-            const rules = await readEntityRules(service, entityUuid);
-            all.push(...rules);
-          }
-        }
-        if (!filters.scope || filters.scope === "package") {
-          const packages = filters.packageName ? [filters.packageName] : await listPackagesWithRules();
-          for (const pkg of packages) {
-            const rules = await readPackageRules(pkg);
-            all.push(...rules);
-          }
-        }
-        if (!filters.scope || filters.scope === "global") {
-          const globalRules = await readGlobalRules();
-          all.push(...globalRules);
-        }
-        if (!filters.scope || filters.scope === "case") {
-          if (filters.caseUuid) {
-            const rules = await readCaseRules(filters.caseUuid);
-            all.push(...rules);
-          } else {
-            const cases = await listCases();
-            for (const c of cases) {
-              const rules = c.rules || [];
-              all.push(...rules);
-            }
-          }
-        }
-        for (const rule of all) {
-          if (!rule.enforcement) rule.enforcement = "advisory";
-        }
-        return all.filter((rule) => {
-          if (filters.severity && rule.severity !== filters.severity) return false;
-          if (filters.enforcement && rule.enforcement !== filters.enforcement) return false;
-          if (filters.targetUuid) {
-            const hit = rule.targets.some(
-              (t) => t.uuid === filters.targetUuid || t.entityUuid === filters.targetUuid
-            );
-            if (!hit) return false;
-          }
-          return true;
-        });
-      }
-      /** Get a single rule by uuid (scans all scopes). */
-      async getRule(uuid3) {
-        const all = await this.listRules();
-        return all.find((r) => r.uuid === uuid3) || null;
-      }
-      /** List rules whose targets include this entity (or any of its attributes). */
-      async listRulesForEntity(entityUuid) {
-        const all = await this.listRules();
-        return all.filter(
-          (rule) => rule.targets.some(
-            (t) => t.uuid === entityUuid || t.entityUuid === entityUuid
-          )
-        );
-      }
-      /** Create a rule. Storage location is determined by `scope`. */
-      async createRule(input) {
-        if (!input.enforcement) input.enforcement = "advisory";
-        const errors = validateRule(input);
-        if (errors.length > 0) {
-          return { success: false, errors };
-        }
-        let rule = {
-          uuid: generateUUID(),
-          name: input.name,
-          description: input.description,
-          severity: input.severity,
-          enforcement: input.enforcement,
-          scope: input.scope,
-          targets: input.targets,
-          packageName: input.packageName,
-          entityUuid: input.entityUuid,
-          caseUuid: input.caseUuid,
-          expression: input.expression,
-          tags: input.tags,
-          metadata: input.metadata,
-          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-        };
-        rule = await this.applyAutoScope(rule);
-        const saved = await this.saveRuleToScope(rule);
-        if (!saved) return { success: false, errors: ["Failed to write rule to storage"] };
-        return { success: true, rule };
-      }
-      /** Update an existing rule by uuid. Re-routes to new scope if scope changed. */
-      async updateRule(uuid3, input) {
-        const existing = await this.getRule(uuid3);
-        if (!existing) return { success: false, errors: [`Rule ${uuid3} not found`] };
-        let merged = {
-          ...existing,
-          ...input,
-          uuid: existing.uuid,
-          createdAt: existing.createdAt,
-          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-        };
-        const errors = validateRule(merged);
-        if (errors.length > 0) return { success: false, errors };
-        merged = await this.applyAutoScope(merged, existing.scope, existing.packageName);
-        const scopeMoved = existing.scope !== merged.scope || existing.packageName !== merged.packageName || existing.entityUuid !== merged.entityUuid || existing.caseUuid !== merged.caseUuid;
-        if (scopeMoved) {
-          await this.removeRuleFromScope(existing);
-        }
-        const saved = await this.saveRuleToScope(merged);
-        if (!saved) return { success: false, errors: ["Failed to write updated rule to storage"] };
-        return { success: true, rule: merged };
-      }
-      /** Delete a rule by uuid. */
-      async deleteRule(uuid3) {
-        const existing = await this.getRule(uuid3);
-        if (!existing) return { success: false, errors: [`Rule ${uuid3} not found`] };
-        const removed = await this.removeRuleFromScope(existing);
-        if (!removed) return { success: false, errors: ["Failed to remove rule from storage"] };
-        return { success: true };
-      }
-      // ─── Private helpers: route to the right storage location ────────────────
-      async saveRuleToScope(rule) {
-        const projection = getProjection(wsId("dictionaries"));
-        switch (rule.scope) {
-          case "entity": {
-            if (!rule.entityUuid) return false;
-            const files = await listAllEntityRuleFiles();
-            let service = files.find((f) => f.entityUuid === rule.entityUuid)?.service;
-            if (!service) service = rule.packageName;
-            if (!service) {
-              logger.error(`Cannot determine service for entity ${rule.entityUuid}`);
-              return false;
-            }
-            const entity = await this.findEntityByUuid(service, rule.entityUuid);
-            if (!entity) {
-              logger.error(`Entity ${rule.entityUuid} not found in service ${service}`);
-              return false;
-            }
-            const existing = entity.rules || [];
-            const updatedRules = [...existing.filter((r) => r.uuid !== rule.uuid), rule];
-            entity.rules = updatedRules.length > 0 ? updatedRules : void 0;
-            const logicalPath = `packages/${service}/entities/${entity.name}`;
-            try {
-              await projection.writeEntity(logicalPath, entity);
-              return true;
-            } catch (e) {
-              logger.error(`Failed to write entity-scope rule via projection: ${e.message}`);
-              return false;
-            }
-          }
-          case "package": {
-            if (!rule.packageName) return false;
-            const existing = await readPackageRules(rule.packageName);
-            const updated = [...existing.filter((r) => r.uuid !== rule.uuid), rule];
-            const packageLogicalPath = `packages/${rule.packageName}`;
-            try {
-              await projection.writePackageRules(packageLogicalPath, updated);
-              return true;
-            } catch (e) {
-              logger.error(`Failed to write package-scope rules via projection: ${e.message}`);
-              return false;
-            }
-          }
-          case "case": {
-            if (!rule.caseUuid) return false;
-            const c = await readCaseFile(rule.caseUuid);
-            if (!c) return false;
-            const existing = c.rules || [];
-            c.rules = [...existing.filter((r) => r.uuid !== rule.uuid), rule];
-            c.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-            const targetPackage = await this.resolveCaseHomePackage(c);
-            if (!targetPackage) return false;
-            const caseLogicalPath = `packages/${targetPackage}/cases/${c.name}`;
-            try {
-              await projection.writeCase(caseLogicalPath, c);
-              return true;
-            } catch (e) {
-              logger.error(`Failed to write case-scope rule via projection: ${e.message}`);
-              return false;
-            }
-          }
-          case "global": {
-            const existing = await readGlobalRules();
-            const updated = [...existing.filter((r) => r.uuid !== rule.uuid), rule];
-            try {
-              await projection.writeGlobalRules(updated);
-              return true;
-            } catch (e) {
-              logger.error(`Failed to write global rules via projection: ${e.message}`);
-              return false;
-            }
-          }
-          default:
-            return false;
-        }
-      }
-      async removeRuleFromScope(rule) {
-        const projection = getProjection(wsId("dictionaries"));
-        switch (rule.scope) {
-          case "entity": {
-            if (!rule.entityUuid) return false;
-            const files = await listAllEntityRuleFiles();
-            const service = files.find((f) => f.entityUuid === rule.entityUuid)?.service ?? rule.packageName;
-            if (!service) return false;
-            const entity = await this.findEntityByUuid(service, rule.entityUuid);
-            if (!entity) return false;
-            const existing = entity.rules || [];
-            const updatedRules = existing.filter((r) => r.uuid !== rule.uuid);
-            entity.rules = updatedRules.length > 0 ? updatedRules : void 0;
-            const logicalPath = `packages/${service}/entities/${entity.name}`;
-            try {
-              await projection.writeEntity(logicalPath, entity);
-              return true;
-            } catch (e) {
-              logger.error(`Failed to remove entity-scope rule via projection: ${e.message}`);
-              return false;
-            }
-          }
-          case "package": {
-            if (!rule.packageName) return false;
-            const existing = await readPackageRules(rule.packageName);
-            const updated = existing.filter((r) => r.uuid !== rule.uuid);
-            const packageLogicalPath = `packages/${rule.packageName}`;
-            try {
-              await projection.writePackageRules(packageLogicalPath, updated);
-              return true;
-            } catch (e) {
-              logger.error(`Failed to remove package-scope rule via projection: ${e.message}`);
-              return false;
-            }
-          }
-          case "case": {
-            if (!rule.caseUuid) return false;
-            const c = await readCaseFile(rule.caseUuid);
-            if (!c) return false;
-            const existing = c.rules || [];
-            const updated = existing.filter((r) => r.uuid !== rule.uuid);
-            c.rules = updated.length > 0 ? updated : void 0;
-            c.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-            const targetPackage = await this.resolveCaseHomePackage(c);
-            if (!targetPackage) return false;
-            const caseLogicalPath = `packages/${targetPackage}/cases/${c.name}`;
-            try {
-              await projection.writeCase(caseLogicalPath, c);
-              return true;
-            } catch (e) {
-              logger.error(`Failed to remove case-scope rule via projection: ${e.message}`);
-              return false;
-            }
-          }
-          case "global": {
-            const existing = await readGlobalRules();
-            const updated = existing.filter((r) => r.uuid !== rule.uuid);
-            try {
-              await projection.writeGlobalRules(updated);
-              return true;
-            } catch (e) {
-              logger.error(`Failed to remove global rule via projection: ${e.message}`);
-              return false;
-            }
-          }
-          default:
-            return false;
-        }
-      }
-      /**
-       * Load an entity from a package by uuid. Returns null if not found.
-       * Used by entity-scope rule writes to round-trip the parent entity
-       * through `projection.writeEntity`.
-       */
-      async findEntityByUuid(service, entityUuid) {
-        try {
-          const pkg = await loadPackage(service);
-          return pkg.entities.find((e) => e.uuid === entityUuid) ?? null;
-        } catch (error48) {
-          logger.error(`Error loading package ${service} for entity lookup: ${error48}`);
-          return null;
-        }
-      }
-      /**
-       * Resolve the home package for a case so we can construct a
-       * `packages/<pkg>/cases/<name>` logical path. Mirrors the heuristic in
-       * caseService.ts / fileOperations.ts: existing-owner lookup by uuid first,
-       * then first root entity's package, then first package on disk.
-       */
-      async resolveCaseHomePackage(c) {
-        const { listPackages: listPackages3 } = await Promise.resolve().then(() => (init_fileOperations(), fileOperations_exports));
-        const packages = await listPackages3();
-        for (const pkg of packages) {
-          try {
-            const model = await loadPackage(pkg);
-            if (model.ownership.caseByUuid.has(c.uuid)) return pkg;
-          } catch {
-          }
-        }
-        if (c.rootEntities && c.rootEntities.length > 0) {
-          const rootUuid = c.rootEntities[0];
-          for (const pkg of packages) {
-            try {
-              const model = await loadPackage(pkg);
-              if (model.ownership.entityByUuid.has(rootUuid)) return pkg;
-            } catch {
-            }
-          }
-        }
-        return packages[0] || null;
-      }
-      // ─── Auto-promote / auto-demote (#75) ────────────────────────────────
-      /**
-       * Determine the correct scope for a rule based on its targets.
-       * Called before save. If targets span 2+ packages → global.
-       * If all targets are in one package → that package's scope (keep
-       * the caller's intent for entity vs package).
-       */
-      resolveScope(rule) {
-        const packages = /* @__PURE__ */ new Set();
-        for (const t of rule.targets) {
-          if (t.packageName) packages.add(t.packageName);
-        }
-        if (packages.size >= 2) {
-          return { scope: "global" };
-        }
-        if (packages.size === 1) {
-          const pkg = [...packages][0];
-          if (rule.scope === "global") {
-            return { scope: "package", packageName: pkg };
-          }
-        }
-        return { scope: rule.scope, packageName: rule.packageName };
-      }
-      /**
-       * Wrap around createRule/updateRule to apply auto-promote/demote.
-       * Checks if the resolved scope differs from what the caller requested
-       * and adjusts accordingly — including moving the rule between files.
-       */
-      async applyAutoScope(rule, _oldScope, _oldPkg) {
-        const resolved = this.resolveScope(rule);
-        if (resolved.scope !== rule.scope) {
-          logger.info(`Auto-${resolved.scope === "global" ? "promote" : "demote"} rule ${rule.uuid}: ${rule.scope} \u2192 ${resolved.scope}`);
-        }
-        rule.scope = resolved.scope;
-        if (resolved.packageName !== void 0) {
-          rule.packageName = resolved.packageName;
-        }
-        return rule;
-      }
-    };
-    ruleService = new RuleService();
-  }
-});
-
 // backend/node_modules/zod/v4/core/core.js
 // @__NO_SIDE_EFFECTS__
 function $constructor(name21, initializer3, params) {
@@ -50508,7 +50147,7 @@ var init_errors = __esm({
 });
 
 // backend/node_modules/zod/v4/core/parse.js
-var _parse, parse4, _parseAsync, parseAsync, _safeParse, safeParse, _safeParseAsync, safeParseAsync, _encode, encode, _decode, decode, _encodeAsync, encodeAsync, _decodeAsync, decodeAsync, _safeEncode, safeEncode, _safeDecode, safeDecode, _safeEncodeAsync, safeEncodeAsync, _safeDecodeAsync, safeDecodeAsync;
+var _parse, parse3, _parseAsync, parseAsync, _safeParse, safeParse, _safeParseAsync, safeParseAsync, _encode, encode, _decode, decode, _encodeAsync, encodeAsync, _decodeAsync, decodeAsync, _safeEncode, safeEncode, _safeDecode, safeDecode, _safeEncodeAsync, safeEncodeAsync, _safeDecodeAsync, safeDecodeAsync;
 var init_parse = __esm({
   "backend/node_modules/zod/v4/core/parse.js"() {
     init_core();
@@ -50527,7 +50166,7 @@ var init_parse = __esm({
       }
       return result.value;
     }, "_parse");
-    parse4 = /* @__PURE__ */ _parse($ZodRealError);
+    parse3 = /* @__PURE__ */ _parse($ZodRealError);
     _parseAsync = /* @__PURE__ */ __name((_Err) => async (schema, value, _ctx, params) => {
       const ctx = _ctx ? Object.assign(_ctx, { async: true }) : { async: true };
       let result = schema._zod.run({ value, issues: [] }, ctx);
@@ -53285,10 +52924,10 @@ var init_schemas = __esm({
           throw new Error("implement() must be called with a function");
         }
         return function(...args) {
-          const parsedArgs = inst._def.input ? parse4(inst._def.input, args) : args;
+          const parsedArgs = inst._def.input ? parse3(inst._def.input, args) : args;
           const result = Reflect.apply(func, this, parsedArgs);
           if (inst._def.output) {
-            return parse4(inst._def.output, result);
+            return parse3(inst._def.output, result);
           }
           return result;
         };
@@ -61906,7 +61545,7 @@ __export(core_exports2, {
   isValidJWT: () => isValidJWT,
   locales: () => locales_exports,
   meta: () => meta,
-  parse: () => parse4,
+  parse: () => parse3,
   parseAsync: () => parseAsync,
   prettifyError: () => prettifyError,
   process: () => process2,
@@ -62085,12 +61724,12 @@ var init_errors2 = __esm({
 });
 
 // backend/node_modules/zod/v4/classic/parse.js
-var parse5, parseAsync2, safeParse2, safeParseAsync2, encode2, decode2, encodeAsync2, decodeAsync2, safeEncode2, safeDecode2, safeEncodeAsync2, safeDecodeAsync2;
+var parse4, parseAsync2, safeParse2, safeParseAsync2, encode2, decode2, encodeAsync2, decodeAsync2, safeEncode2, safeDecode2, safeEncodeAsync2, safeDecodeAsync2;
 var init_parse2 = __esm({
   "backend/node_modules/zod/v4/classic/parse.js"() {
     init_core2();
     init_errors2();
-    parse5 = /* @__PURE__ */ _parse(ZodRealError);
+    parse4 = /* @__PURE__ */ _parse(ZodRealError);
     parseAsync2 = /* @__PURE__ */ _parseAsync(ZodRealError);
     safeParse2 = /* @__PURE__ */ _safeParse(ZodRealError);
     safeParseAsync2 = /* @__PURE__ */ _safeParseAsync(ZodRealError);
@@ -62766,7 +62405,7 @@ var init_schemas2 = __esm({
         reg.add(inst, meta3);
         return inst;
       });
-      inst.parse = (data, params) => parse5(inst, data, params, { callee: inst.parse });
+      inst.parse = (data, params) => parse4(inst, data, params, { callee: inst.parse });
       inst.safeParse = (data, params) => safeParse2(inst, data, params);
       inst.parseAsync = async (data, params) => parseAsync2(inst, data, params, { callee: inst.parseAsync });
       inst.safeParseAsync = async (data, params) => safeParseAsync2(inst, data, params);
@@ -64193,7 +63832,7 @@ __export(external_exports, {
   object: () => object,
   optional: () => optional,
   overwrite: () => _overwrite,
-  parse: () => parse5,
+  parse: () => parse4,
   parseAsync: () => parseAsync2,
   partialRecord: () => partialRecord,
   pipe: () => pipe,
@@ -64308,6 +63947,424 @@ var init_agentToolRegistry = __esm({
   }
 });
 
+// backend/src/models/Rule.ts
+function validateRule(rule) {
+  const errors = [];
+  if (!rule.name || typeof rule.name !== "string") {
+    errors.push("Rule name is required");
+  } else if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(rule.name)) {
+    errors.push("Rule name must be kebab-case (lowercase letters, numbers, hyphens)");
+  }
+  if (!rule.description || typeof rule.description !== "string") {
+    errors.push("Rule description is required");
+  }
+  if (!rule.severity || !["info", "warning", "error"].includes(rule.severity)) {
+    errors.push("Rule severity must be one of: info, warning, error");
+  }
+  if (!rule.enforcement || !["save", "process", "advisory"].includes(rule.enforcement)) {
+    errors.push("Rule enforcement must be one of: save, process, advisory");
+  }
+  if (!rule.scope || !["entity", "package", "case", "global"].includes(rule.scope)) {
+    errors.push("Rule scope must be one of: entity, package, case, global");
+  }
+  if (!Array.isArray(rule.targets) || rule.targets.length === 0) {
+    errors.push("Rule must have at least one target");
+  }
+  if (rule.scope === "entity" && !rule.entityUuid) {
+    errors.push("Entity-scoped rules must specify entityUuid");
+  }
+  if (rule.scope === "package" && !rule.packageName) {
+    errors.push("Package-scoped rules must specify packageName");
+  }
+  if (rule.scope === "case" && !rule.caseUuid) {
+    errors.push("Case-scoped rules must specify caseUuid");
+  }
+  if (rule.enforcement === "process") {
+    const stageField = (rule.metadata || []).find((m) => m.name === "process-stage-field");
+    if (!stageField || !stageField.value) {
+      errors.push("Process-enforcement rules must reference a metadata field via process-stage-field");
+    }
+  }
+  return errors;
+}
+var init_Rule = __esm({
+  "backend/src/models/Rule.ts"() {
+    "use strict";
+    __name(validateRule, "validateRule");
+  }
+});
+
+// backend/src/services/ruleService.ts
+var ruleService_exports = {};
+__export(ruleService_exports, {
+  ruleService: () => ruleService
+});
+var RuleService, ruleService;
+var init_ruleService = __esm({
+  "backend/src/services/ruleService.ts"() {
+    "use strict";
+    init_Rule();
+    init_fileOperations();
+    init_uuid();
+    init_logger();
+    init_ProjectionRegistry();
+    init_types();
+    RuleService = class {
+      static {
+        __name(this, "RuleService");
+      }
+      /** List all rules from all storage scopes, optionally filtered. */
+      async listRules(filters = {}) {
+        const all = [];
+        if (!filters.scope || filters.scope === "entity") {
+          const files = await listAllEntityRuleFiles();
+          for (const { service, entityUuid } of files) {
+            const rules = await readEntityRules(service, entityUuid);
+            all.push(...rules);
+          }
+        }
+        if (!filters.scope || filters.scope === "package") {
+          const packages = filters.packageName ? [filters.packageName] : await listPackagesWithRules();
+          for (const pkg of packages) {
+            const rules = await readPackageRules(pkg);
+            all.push(...rules);
+          }
+        }
+        if (!filters.scope || filters.scope === "global") {
+          const globalRules = await readGlobalRules();
+          all.push(...globalRules);
+        }
+        if (!filters.scope || filters.scope === "case") {
+          if (filters.caseUuid) {
+            const rules = await readCaseRules(filters.caseUuid);
+            all.push(...rules);
+          } else {
+            const cases = await listCases();
+            for (const c of cases) {
+              const rules = c.rules || [];
+              all.push(...rules);
+            }
+          }
+        }
+        for (const rule of all) {
+          if (!rule.enforcement) rule.enforcement = "advisory";
+        }
+        return all.filter((rule) => {
+          if (filters.severity && rule.severity !== filters.severity) return false;
+          if (filters.enforcement && rule.enforcement !== filters.enforcement) return false;
+          if (filters.targetUuid) {
+            const hit = rule.targets.some(
+              (t) => t.uuid === filters.targetUuid || t.entityUuid === filters.targetUuid
+            );
+            if (!hit) return false;
+          }
+          return true;
+        });
+      }
+      /** Get a single rule by uuid (scans all scopes). */
+      async getRule(uuid3) {
+        const all = await this.listRules();
+        return all.find((r) => r.uuid === uuid3) || null;
+      }
+      /** List rules whose targets include this entity (or any of its attributes). */
+      async listRulesForEntity(entityUuid) {
+        const all = await this.listRules();
+        return all.filter(
+          (rule) => rule.targets.some(
+            (t) => t.uuid === entityUuid || t.entityUuid === entityUuid
+          )
+        );
+      }
+      /** Create a rule. Storage location is determined by `scope`. */
+      async createRule(input) {
+        if (!input.enforcement) input.enforcement = "advisory";
+        const errors = validateRule(input);
+        if (errors.length > 0) {
+          return { success: false, errors };
+        }
+        let rule = {
+          uuid: generateUUID(),
+          name: input.name,
+          description: input.description,
+          severity: input.severity,
+          enforcement: input.enforcement,
+          scope: input.scope,
+          targets: input.targets,
+          packageName: input.packageName,
+          entityUuid: input.entityUuid,
+          caseUuid: input.caseUuid,
+          expression: input.expression,
+          tags: input.tags,
+          metadata: input.metadata,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        rule = await this.applyAutoScope(rule);
+        const saved = await this.saveRuleToScope(rule);
+        if (!saved) return { success: false, errors: ["Failed to write rule to storage"] };
+        return { success: true, rule };
+      }
+      /** Update an existing rule by uuid. Re-routes to new scope if scope changed. */
+      async updateRule(uuid3, input) {
+        const existing = await this.getRule(uuid3);
+        if (!existing) return { success: false, errors: [`Rule ${uuid3} not found`] };
+        let merged = {
+          ...existing,
+          ...input,
+          uuid: existing.uuid,
+          createdAt: existing.createdAt,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        const errors = validateRule(merged);
+        if (errors.length > 0) return { success: false, errors };
+        merged = await this.applyAutoScope(merged, existing.scope, existing.packageName);
+        const scopeMoved = existing.scope !== merged.scope || existing.packageName !== merged.packageName || existing.entityUuid !== merged.entityUuid || existing.caseUuid !== merged.caseUuid;
+        if (scopeMoved) {
+          await this.removeRuleFromScope(existing);
+        }
+        const saved = await this.saveRuleToScope(merged);
+        if (!saved) return { success: false, errors: ["Failed to write updated rule to storage"] };
+        return { success: true, rule: merged };
+      }
+      /** Delete a rule by uuid. */
+      async deleteRule(uuid3) {
+        const existing = await this.getRule(uuid3);
+        if (!existing) return { success: false, errors: [`Rule ${uuid3} not found`] };
+        const removed = await this.removeRuleFromScope(existing);
+        if (!removed) return { success: false, errors: ["Failed to remove rule from storage"] };
+        return { success: true };
+      }
+      // ─── Private helpers: route to the right storage location ────────────────
+      async saveRuleToScope(rule) {
+        const projection = getProjection(wsId("dictionaries"));
+        switch (rule.scope) {
+          case "entity": {
+            if (!rule.entityUuid) return false;
+            const files = await listAllEntityRuleFiles();
+            let service = files.find((f) => f.entityUuid === rule.entityUuid)?.service;
+            if (!service) service = rule.packageName;
+            if (!service) {
+              logger.error(`Cannot determine service for entity ${rule.entityUuid}`);
+              return false;
+            }
+            const entity = await this.findEntityByUuid(service, rule.entityUuid);
+            if (!entity) {
+              logger.error(`Entity ${rule.entityUuid} not found in service ${service}`);
+              return false;
+            }
+            const existing = entity.rules || [];
+            const updatedRules = [...existing.filter((r) => r.uuid !== rule.uuid), rule];
+            entity.rules = updatedRules.length > 0 ? updatedRules : void 0;
+            const logicalPath = `packages/${service}/entities/${entity.name}`;
+            try {
+              await projection.writeEntity(logicalPath, entity);
+              return true;
+            } catch (e) {
+              logger.error(`Failed to write entity-scope rule via projection: ${e.message}`);
+              return false;
+            }
+          }
+          case "package": {
+            if (!rule.packageName) return false;
+            const existing = await readPackageRules(rule.packageName);
+            const updated = [...existing.filter((r) => r.uuid !== rule.uuid), rule];
+            const packageLogicalPath = `packages/${rule.packageName}`;
+            try {
+              await projection.writePackageRules(packageLogicalPath, updated);
+              return true;
+            } catch (e) {
+              logger.error(`Failed to write package-scope rules via projection: ${e.message}`);
+              return false;
+            }
+          }
+          case "case": {
+            if (!rule.caseUuid) return false;
+            const c = await readCaseFile(rule.caseUuid);
+            if (!c) return false;
+            const existing = c.rules || [];
+            c.rules = [...existing.filter((r) => r.uuid !== rule.uuid), rule];
+            c.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+            const targetPackage = await this.resolveCaseHomePackage(c);
+            if (!targetPackage) return false;
+            const caseLogicalPath = `packages/${targetPackage}/cases/${c.name}`;
+            try {
+              await projection.writeCase(caseLogicalPath, c);
+              return true;
+            } catch (e) {
+              logger.error(`Failed to write case-scope rule via projection: ${e.message}`);
+              return false;
+            }
+          }
+          case "global": {
+            const existing = await readGlobalRules();
+            const updated = [...existing.filter((r) => r.uuid !== rule.uuid), rule];
+            try {
+              await projection.writeGlobalRules(updated);
+              return true;
+            } catch (e) {
+              logger.error(`Failed to write global rules via projection: ${e.message}`);
+              return false;
+            }
+          }
+          default:
+            return false;
+        }
+      }
+      async removeRuleFromScope(rule) {
+        const projection = getProjection(wsId("dictionaries"));
+        switch (rule.scope) {
+          case "entity": {
+            if (!rule.entityUuid) return false;
+            const files = await listAllEntityRuleFiles();
+            const service = files.find((f) => f.entityUuid === rule.entityUuid)?.service ?? rule.packageName;
+            if (!service) return false;
+            const entity = await this.findEntityByUuid(service, rule.entityUuid);
+            if (!entity) return false;
+            const existing = entity.rules || [];
+            const updatedRules = existing.filter((r) => r.uuid !== rule.uuid);
+            entity.rules = updatedRules.length > 0 ? updatedRules : void 0;
+            const logicalPath = `packages/${service}/entities/${entity.name}`;
+            try {
+              await projection.writeEntity(logicalPath, entity);
+              return true;
+            } catch (e) {
+              logger.error(`Failed to remove entity-scope rule via projection: ${e.message}`);
+              return false;
+            }
+          }
+          case "package": {
+            if (!rule.packageName) return false;
+            const existing = await readPackageRules(rule.packageName);
+            const updated = existing.filter((r) => r.uuid !== rule.uuid);
+            const packageLogicalPath = `packages/${rule.packageName}`;
+            try {
+              await projection.writePackageRules(packageLogicalPath, updated);
+              return true;
+            } catch (e) {
+              logger.error(`Failed to remove package-scope rule via projection: ${e.message}`);
+              return false;
+            }
+          }
+          case "case": {
+            if (!rule.caseUuid) return false;
+            const c = await readCaseFile(rule.caseUuid);
+            if (!c) return false;
+            const existing = c.rules || [];
+            const updated = existing.filter((r) => r.uuid !== rule.uuid);
+            c.rules = updated.length > 0 ? updated : void 0;
+            c.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+            const targetPackage = await this.resolveCaseHomePackage(c);
+            if (!targetPackage) return false;
+            const caseLogicalPath = `packages/${targetPackage}/cases/${c.name}`;
+            try {
+              await projection.writeCase(caseLogicalPath, c);
+              return true;
+            } catch (e) {
+              logger.error(`Failed to remove case-scope rule via projection: ${e.message}`);
+              return false;
+            }
+          }
+          case "global": {
+            const existing = await readGlobalRules();
+            const updated = existing.filter((r) => r.uuid !== rule.uuid);
+            try {
+              await projection.writeGlobalRules(updated);
+              return true;
+            } catch (e) {
+              logger.error(`Failed to remove global rule via projection: ${e.message}`);
+              return false;
+            }
+          }
+          default:
+            return false;
+        }
+      }
+      /**
+       * Load an entity from a package by uuid. Returns null if not found.
+       * Used by entity-scope rule writes to round-trip the parent entity
+       * through `projection.writeEntity`.
+       */
+      async findEntityByUuid(service, entityUuid) {
+        try {
+          const pkg = await loadPackage(service);
+          return pkg.entities.find((e) => e.uuid === entityUuid) ?? null;
+        } catch (error48) {
+          logger.error(`Error loading package ${service} for entity lookup: ${error48}`);
+          return null;
+        }
+      }
+      /**
+       * Resolve the home package for a case so we can construct a
+       * `packages/<pkg>/cases/<name>` logical path. Mirrors the heuristic in
+       * caseService.ts / fileOperations.ts: existing-owner lookup by uuid first,
+       * then first root entity's package, then first package on disk.
+       */
+      async resolveCaseHomePackage(c) {
+        const { listPackages: listPackages3 } = await Promise.resolve().then(() => (init_fileOperations(), fileOperations_exports));
+        const packages = await listPackages3();
+        for (const pkg of packages) {
+          try {
+            const model = await loadPackage(pkg);
+            if (model.ownership.caseByUuid.has(c.uuid)) return pkg;
+          } catch {
+          }
+        }
+        if (c.rootEntities && c.rootEntities.length > 0) {
+          const rootUuid = c.rootEntities[0];
+          for (const pkg of packages) {
+            try {
+              const model = await loadPackage(pkg);
+              if (model.ownership.entityByUuid.has(rootUuid)) return pkg;
+            } catch {
+            }
+          }
+        }
+        return packages[0] || null;
+      }
+      // ─── Auto-promote / auto-demote (#75) ────────────────────────────────
+      /**
+       * Determine the correct scope for a rule based on its targets.
+       * Called before save. If targets span 2+ packages → global.
+       * If all targets are in one package → that package's scope (keep
+       * the caller's intent for entity vs package).
+       */
+      resolveScope(rule) {
+        const packages = /* @__PURE__ */ new Set();
+        for (const t of rule.targets) {
+          if (t.packageName) packages.add(t.packageName);
+        }
+        if (packages.size >= 2) {
+          return { scope: "global" };
+        }
+        if (packages.size === 1) {
+          const pkg = [...packages][0];
+          if (rule.scope === "global") {
+            return { scope: "package", packageName: pkg };
+          }
+        }
+        return { scope: rule.scope, packageName: rule.packageName };
+      }
+      /**
+       * Wrap around createRule/updateRule to apply auto-promote/demote.
+       * Checks if the resolved scope differs from what the caller requested
+       * and adjusts accordingly — including moving the rule between files.
+       */
+      async applyAutoScope(rule, _oldScope, _oldPkg) {
+        const resolved = this.resolveScope(rule);
+        if (resolved.scope !== rule.scope) {
+          logger.info(`Auto-${resolved.scope === "global" ? "promote" : "demote"} rule ${rule.uuid}: ${rule.scope} \u2192 ${resolved.scope}`);
+        }
+        rule.scope = resolved.scope;
+        if (resolved.packageName !== void 0) {
+          rule.packageName = resolved.packageName;
+        }
+        return rule;
+      }
+    };
+    ruleService = new RuleService();
+  }
+});
+
 // backend/src/services/versionService.ts
 var versionService_exports = {};
 __export(versionService_exports, {
@@ -83464,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) {
@@ -104496,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`;
@@ -104541,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.
@@ -104586,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;
@@ -104599,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.
@@ -104609,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;
@@ -104617,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");
@@ -116829,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);
@@ -116850,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 } : {} } } : {},
@@ -116858,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(() => []);
@@ -116916,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 "";
   }
@@ -116930,8 +117189,8 @@ function resolveToolCategory(toolName, trustByName) {
   const clean = toolName.replace(/^functions\./, "").split(":")[0];
   const builtin = TOOL_CATEGORY_MAP[clean];
   if (builtin) return builtin;
-  const registered4 = getAgentTool(clean)?.category;
-  if (registered4) return registered4;
+  const registered5 = getAgentTool(clean)?.category;
+  if (registered5) return registered5;
   if (clean.includes(".")) {
     const trust = trustByName.get(clean);
     return trust === "auto" ? "read" : "modify";
@@ -117084,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();
@@ -117096,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 || "";
@@ -117112,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) {
@@ -117170,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: {} } } }
@@ -117235,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);
@@ -117288,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");
@@ -117415,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";
@@ -117425,6 +117682,8 @@ var init_aiController = __esm({
     init_config();
     init_agentToolRegistry();
     init_authoringRules();
+    init_physicalMapping();
+    init_modelOverviewCache();
     init_systemPromptStore();
     init_appDir();
     init_conversationService();
@@ -117496,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");
@@ -117523,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)
@@ -117568,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");
@@ -117620,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) {
@@ -117791,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 };
                 }
@@ -117824,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 };
                 }
@@ -117842,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 {
@@ -118275,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" }
           ]
         },
@@ -118297,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)" }
           ]
         },
@@ -150095,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;
@@ -150105,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];
@@ -150157,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;
@@ -150489,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) {
@@ -150508,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))
@@ -150666,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) {
@@ -159537,6 +159802,24 @@ var setEntityHidden = /* @__PURE__ */ __name(async (req, res) => {
     res.status(500).json({ message: "Error setting entity visibility", error: error48 });
   }
 }, "setEntityHidden");
+var moveEntity = /* @__PURE__ */ __name(async (req, res) => {
+  try {
+    const { service, entity } = req.params;
+    const targetPackage = typeof req.body?.targetPackage === "string" ? req.body.targetPackage : "";
+    if (!targetPackage) {
+      return res.status(400).json({ message: "targetPackage is required" });
+    }
+    const result = await serviceService.moveEntity(service, entity, targetPackage);
+    if (!result.success) {
+      const notFound = result.errors.some((e) => e.includes("not found"));
+      return res.status(notFound ? 404 : 400).json({ message: "Failed to move entity", errors: result.errors });
+    }
+    res.json({ message: "Entity moved", data: { service, entity, targetPackage } });
+  } catch (error48) {
+    logger.error(`Error moving entity: ${error48}`);
+    res.status(500).json({ message: "Error moving entity", error: error48 });
+  }
+}, "moveEntity");
 var setEntityStyle = /* @__PURE__ */ __name(async (req, res) => {
   try {
     const { service, entity } = req.params;
@@ -159763,7 +160046,46 @@ var deleteRelationship = /* @__PURE__ */ __name(async (req, res) => {
   }
 }, "deleteRelationship");
 
+// backend/src/services/entityMove/agentTools.ts
+init_zod();
+init_agentToolRegistry();
+init_serviceService();
+var registered = false;
+function registerMoveEntityAgentTool() {
+  if (registered) return;
+  registered = true;
+  registerAgentTool({
+    name: "moveEntity",
+    category: "modify",
+    description: "Move an entity from one package to another. The entity keeps its UUID, so relationships (cross-package is first-class), cases and diagrams that reference it keep resolving \u2014 nothing is orphaned. Fails if the target package doesn't exist or already has an entity with the same name.",
+    jsonSchema: {
+      type: "object",
+      required: ["sourcePackage", "entityName", "targetPackage"],
+      properties: {
+        sourcePackage: { type: "string", description: "Package the entity currently lives in" },
+        entityName: { type: "string", description: "Name of the entity to move" },
+        targetPackage: { type: "string", description: "Package to move the entity into" }
+      }
+    },
+    inputSchema: external_exports.object({
+      sourcePackage: external_exports.string(),
+      entityName: external_exports.string(),
+      targetPackage: external_exports.string()
+    }),
+    execute: /* @__PURE__ */ __name(async (args) => {
+      const r = await serviceService.moveEntity(
+        String(args.sourcePackage),
+        String(args.entityName),
+        String(args.targetPackage)
+      );
+      return r.success ? { success: true, entity: args.entityName, from: args.sourcePackage, to: args.targetPackage } : { success: false, errors: r.errors };
+    }, "execute")
+  });
+}
+__name(registerMoveEntityAgentTool, "registerMoveEntityAgentTool");
+
 // backend/src/routes/data-dictionary/entity.routes.ts
+registerMoveEntityAgentTool();
 var router3 = (0, import_express4.Router)();
 router3.get("/api/entities/:microservice/:entityName/attributes", getEntityAttributes);
 router3.get("/api/entities/:microservice/:entityName/related", getRelatedEntities);
@@ -159777,6 +160099,7 @@ router3.put("/api/services/:service/entities/:entity", authorizeJwt(["admin" /*
 router3.delete("/api/services/:service/entities/:entity", authorizeJwt(["admin" /* ADMIN */]), deleteEntity);
 router3.put("/api/services/:service/entities/:entity/hidden", authorizeJwt(["admin" /* ADMIN */, "editor" /* EDITOR */]), setEntityHidden);
 router3.put("/api/services/:service/entities/:entity/style", authorizeJwt(["admin" /* ADMIN */, "editor" /* EDITOR */]), setEntityStyle);
+router3.put("/api/services/:service/entities/:entity/move", authorizeJwt(["admin" /* ADMIN */, "editor" /* EDITOR */]), moveEntity);
 router3.post("/api/services/:service/entities/:entity/submit", authorizeJwt(["admin" /* ADMIN */, "editor" /* EDITOR */]), submitEntity);
 router3.post("/api/services/:service/entities/:entity/approve", authorizeJwt(["admin" /* ADMIN */]), approveEntity);
 router3.post("/api/services/:service/entities/:entity/return", authorizeJwt(["admin" /* ADMIN */]), returnEntity);
@@ -160321,10 +160644,10 @@ init_zod();
 init_agentToolRegistry();
 init_dicoConfigService();
 init_serviceService();
-var registered = false;
+var registered2 = false;
 function registerElementStyleAgentTools() {
-  if (registered) return;
-  registered = true;
+  if (registered2) return;
+  registered2 = true;
   registerAgentTool({
     name: "defineElementStyle",
     category: "modify",
@@ -165089,10 +165412,10 @@ init_zod();
 init_agentToolRegistry();
 init_searchIndexService();
 var KINDS = ["entity", "attribute", "package", "relationship", "rule", "metadata", "case"];
-var registered2 = false;
+var registered3 = false;
 function registerSearchAgentTools() {
-  if (registered2) return;
-  registered2 = true;
+  if (registered3) return;
+  registered3 = true;
   registerAgentTool({
     name: "searchModel",
     category: "read",
@@ -173535,10 +173858,10 @@ function getSynthesisBrief(dataDir, entityName) {
 __name(getSynthesisBrief, "getSynthesisBrief");
 
 // backend/src/services/reverseEngineer/agentTools.ts
-var registered3 = false;
+var registered4 = false;
 function registerReverseEngineerAgentTools() {
-  if (registered3) return;
-  registered3 = true;
+  if (registered4) return;
+  registered4 = true;
   registerAgentTool({
     name: "listSynthesisBriefs",
     category: "read",
@@ -174207,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)}`);
     }