L2.1 : résout entity_type via l'API Metadata (D21)

Context.{entity_type} attend le TableName du Metadata, pas le nom
d'entité de l'AD (Container -> Containers, mais Alias -> Alias) : un nom
faux partait en HTTP 500 de compilation LINQ. Nouveau service
entity-resolver.js : table Name|TableName (insensible à la casse) ->
TableName, agrégée sur les applications déployées (via
GET /configuration/applications — les applications sans contexte
requêtable n'y figurent pas et n'apportent 0 entité Metadata), cache TTL
partagé, invalidation par onSwitch (D8). Branché dans wms-query-service
(query/count/schema/search) et call_query_api.

Nom inconnu -> échec avant tout appel réseau de requête, suggestions
proches + renvoi vers get_entity_metadata. Metadata injoignable -> le
nom passe tel quel avec un warning dans la réponse.

Mesures (LIMAGRAIN, via le protocole) :
- query_wms_entities("Container", limit 1) -> succès, 1 ligne, résolu
  Containers
- query_wms_entities("Alias") -> succès, invariant (pas de pluriel)
- query_wms_entities("Item") -> "Item" n'existe pas dans le modèle
  Reading. Proches : RFMenuItems, Sites. 288 entités disponibles —
  aucune ligne [API] POST dans stderr
- count_wms_entities("Product") -> 51160
- get_entity_schema("Container") et call_query_api("Container") : mêmes
  résolutions
- 288 TableName distincts sur 5 applications, aucun conflit
  Name -> TableName (mesuré le 24/08/2026)

Docs : D21 dans DECISIONS.md ; CLAUDE.md (piège retiré des points
ouverts, liste d'entités corrigée Aliases -> Alias, entity-resolver dans
la structure) ; exemple singulier/pluriel dans wms://query-examples ;
ROADMAP allégée (cause racine + L2.1 + L3.3 livrés).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/resources/query-examples.js

@@ -42,6 +42,20 @@ function getQueryExamples() {
 > (QueryType=Reading). Status/enum fields are **strings** (enum names), never integers.
 > Always verify enum values via \`docs://entities/\` or \`get_entity_metadata\` before filtering.
 
+## Entity names — singular AD name or TableName, both accepted
+
+\`entity_type\` is resolved case-insensitively against the Metadata API: the AD
+entity name (singular) and the TableName both work. The mapping is **not** a
+pluralisation rule — only the Metadata \`TableName\` is authoritative:
+
+\`\`\`
+query_wms_entities(entity_type="Container")   # AD name  -> resolved to Containers
+query_wms_entities(entity_type="Containers")  # TableName -> used as-is
+query_wms_entities(entity_type="Alias")       # invariant: TableName IS "Alias" (no plural)
+query_wms_entities(entity_type="Item")        # fails fast: not in the Reading model,
+                                              # error lists close matches + get_entity_metadata
+\`\`\`
+
 ---
 
 ## Diagnostic Recipes

src/services/entity-resolver.js

@@ -0,0 +1,186 @@
+/**
+ * Entity Resolver Service
+ * Résout un nom d'entité (Name de l'AD ou TableName, insensible à la casse)
+ * vers le TableName attendu par Context.{...} dans les requêtes LINQ (D21).
+ *
+ * Le mapping n'est PAS une pluralisation (Container -> Containers, mais
+ * Alias -> Alias) : seul le TableName de l'API Metadata fait foi. Le contexte
+ * de lecture étant commun au tenant, la table agrège le Metadata de toutes
+ * les applications installées.
+ */
+
+const apiService = require('./api-service').getInstance();
+const profileManager = require('../config/profile-manager');
+
+// Cache state — même TTL que les autres caches (D10)
+let resolutionMap = null; // Map lower(Name | TableName) -> TableName
+let tableNames = null;    // TableName[] triés (suggestions + comptage)
+let cacheTimestamp = null;
+const CACHE_TTL = parseInt(process.env.WORKFLOW_CACHE_TTL) || 3600000;
+
+// La table de résolution est par tenant — invalidée à chaque bascule (D8).
+profileManager.onSwitch(() => invalidateCache());
+
+function isCacheValid() {
+  if (!resolutionMap || !cacheTimestamp) return false;
+  return Date.now() - cacheTimestamp < CACHE_TTL;
+}
+
+/**
+ * Charge la table de résolution depuis l'API Metadata, agrégée sur toutes
+ * les applications installées.
+ * GET /configuration/applications ne liste que les applications déployées
+ * avec une version — les applications EasyBuilder sans contexte requêtable
+ * (CustomApp...) n'y figurent pas et ne fournissent de toute façon aucune
+ * entité Metadata.
+ */
+async function loadResolutionMap() {
+  if (isCacheValid()) return;
+
+  console.error('[EntityResolver] Cache expired or empty, fetching Metadata...');
+
+  const apps = await apiService.get('/configuration/applications');
+  const appNames = (Array.isArray(apps) ? apps : [])
+    .map(a => a.Name || a.name)
+    .filter(Boolean);
+
+  if (appNames.length === 0) {
+    throw new Error('GET /configuration/applications returned no application');
+  }
+
+  const map = new Map();
+  const names = new Set();
+
+  for (const app of appNames) {
+    const entities = await apiService.getMetadataEntities(app);
+    for (const e of (Array.isArray(entities) ? entities : [])) {
+      const tableName = e.TableName || e.tableName;
+      const name = e.Name || e.name;
+      if (!tableName) continue;
+      names.add(tableName);
+      map.set(tableName.toLowerCase(), tableName);
+      if (name) map.set(name.toLowerCase(), tableName);
+    }
+  }
+
+  if (names.size === 0) {
+    throw new Error('Metadata API returned no entity for any application');
+  }
+
+  resolutionMap = map;
+  tableNames = Array.from(names).sort();
+  cacheTimestamp = Date.now();
+  console.error(`[EntityResolver] Cached ${tableNames.size} entities from ${appNames.length} application(s)`);
+}
+
+/**
+ * Distance de Levenshtein — uniquement pour suggérer des noms proches.
+ */
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const curr = [i];
+    for (let j = 1; j <= n; j++) {
+      curr[j] = Math.min(
+        prev[j] + 1,
+        curr[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+    prev = curr;
+  }
+  return prev[n];
+}
+
+/**
+ * Suggère les TableName les plus proches d'un nom inconnu :
+ * correspondances par sous-chaîne d'abord, puis distance d'édition.
+ */
+function suggestClosest(input, limit = 5) {
+  const lower = input.toLowerCase();
+  const scored = tableNames.map(tn => {
+    const l = tn.toLowerCase();
+    const score = (l.includes(lower) || lower.includes(l))
+      ? Math.abs(l.length - lower.length)          // sous-chaîne : quasi-match
+      : 100 + levenshtein(lower, l);               // sinon : distance d'édition
+    return { tn, score };
+  });
+  scored.sort((a, b) => a.score - b.score || a.tn.localeCompare(b.tn));
+  const maxEditDistance = Math.max(3, Math.floor(lower.length / 2));
+  return scored
+    .filter(s => s.score < 100 + maxEditDistance)
+    .slice(0, limit)
+    .map(s => s.tn);
+}
+
+/**
+ * Résout un nom d'entité vers son TableName.
+ *
+ * @param {string} entityType - Name AD ou TableName, insensible à la casse
+ * @returns {Promise<{tableName: string, warning?: string}>}
+ *   - nom connu   : { tableName } (le TableName exact)
+ *   - Metadata injoignable : { tableName: entityType, warning } — on laisse
+ *     passer le nom tel quel (comportement historique) plutôt que de tout
+ *     bloquer, et on le dit dans la réponse
+ * @throws {Error} nom inconnu du modèle Reading — AVANT tout appel réseau de
+ *   requête, avec suggestions proches et renvoi vers get_entity_metadata
+ */
+async function resolveEntityType(entityType) {
+  if (!entityType || typeof entityType !== 'string' || entityType.trim() === '') {
+    throw new Error('entity_type est requis. Utilisez get_entity_metadata pour la liste des entités interrogeables.');
+  }
+  const trimmed = entityType.trim();
+
+  try {
+    await loadResolutionMap();
+  } catch (err) {
+    console.error(`[EntityResolver] Metadata unreachable, passing "${trimmed}" through as-is: ${err.message}`);
+    return {
+      tableName: trimmed,
+      warning: `Le nom d'entité "${trimmed}" n'a pas pu être validé (API Metadata injoignable : ${err.message}). Il est transmis tel quel au WMS.`,
+    };
+  }
+
+  const tableName = resolutionMap.get(trimmed.toLowerCase());
+  if (tableName) {
+    return { tableName };
+  }
+
+  const suggestions = suggestClosest(trimmed);
+  const closest = suggestions.length > 0 ? ` Proches : ${suggestions.join(', ')}.` : '';
+  throw new Error(
+    `"${trimmed}" n'existe pas dans le modèle Reading.${closest} ` +
+    `${tableNames.length} entités disponibles — utilisez get_entity_metadata pour la liste.`
+  );
+}
+
+/**
+ * Invalide la table de résolution (bascule de profil).
+ */
+function invalidateCache() {
+  resolutionMap = null;
+  tableNames = null;
+  cacheTimestamp = null;
+  console.error('[EntityResolver] Cache cleared');
+}
+
+/**
+ * État du cache (exposé par get_application_summary si besoin).
+ */
+function getCacheStatus() {
+  return {
+    cached: resolutionMap !== null,
+    count: tableNames ? tableNames.length : 0,
+    timestamp: cacheTimestamp,
+    age: cacheTimestamp ? Math.floor((Date.now() - cacheTimestamp) / 1000) : null,
+    valid: isCacheValid(),
+  };
+}
+
+module.exports = {
+  resolveEntityType,
+  invalidateCache,
+  getCacheStatus,
+};

src/services/wms-query-service.js

@@ -4,6 +4,7 @@
  */
 
 const apiService = require('./api-service').getInstance();
+const entityResolver = require('./entity-resolver');
 
 /**
  * Build a LINQ select expression
@@ -20,13 +21,17 @@ const apiService = require('./api-service').getInstance();
  * @param {number} limit - Result limit
  */
 async function queryEntities(entityType, selectExpression = 'z => z', filter = null, limit = 100) {
+  // Résolution Name/TableName -> TableName (D21). Un nom inconnu échoue ici,
+  // avant tout appel réseau de requête — l'erreur porte les suggestions.
+  const { tableName, warning } = await entityResolver.resolveEntityType(entityType);
+
   try {
     // Enforce max limit
     const maxLimit = parseInt(process.env.MAX_QUERY_ROWS) || 1000;
     const actualLimit = Math.min(limit, maxLimit);
 
     // Build expression: Context + optional Where + OrderBy (required by EF when Take is used)
-    let expression = `Context.${entityType}`;
+    let expression = `Context.${tableName}`;
     if (filter) {
       const whereExpr = /^\s*\w+\s*=>/.test(filter) ? filter : `z => ${filter}`;
       expression += `.Where(${whereExpr})`;
@@ -43,6 +48,8 @@ async function queryEntities(entityType, selectExpression = 'z => z', filter = n
 
     return {
       entityType,
+      resolvedTableName: tableName,
+      ...(warning ? { warning } : {}),
       expression,
       limit: actualLimit,
       count: Array.isArray(result) ? result.length : 0,
@@ -144,9 +151,13 @@ async function getEntitySchema(entityType) {
  * @param {string|null} filter - Optional filter
  */
 async function countEntities(entityType, filter = null) {
+  // Résolution Name/TableName -> TableName (D21) — échec avant appel réseau
+  // sur nom inconnu.
+  const { tableName, warning } = await entityResolver.resolveEntityType(entityType);
+
   try {
     // Build: Context.Entity.Where(...).Count()
-    const parts = [`Context.${entityType}`];
+    const parts = [`Context.${tableName}`];
     if (filter) {
       const whereExpr = /^\s*\w+\s*=>/.test(filter) ? filter : `z => ${filter}`;
       parts.push(`Where(${whereExpr})`);
@@ -160,6 +171,8 @@ async function countEntities(entityType, filter = null) {
 
     return {
       entityType,
+      resolvedTableName: tableName,
+      ...(warning ? { warning } : {}),
       filter,
       count
     };

src/tools/api-tools.js

@@ -1,4 +1,5 @@
 const apiService = require('../services/api-service').getInstance();
+const entityResolver = require('../services/entity-resolver');
 
 /**
  * Tools MCP pour interagir avec les APIs WMS
@@ -18,7 +19,7 @@ function listTools() {
         properties: {
           entity_type: {
             type: 'string',
-            description: 'Type d\'entité (Containers, Stocks, ProductLocations, Tasks, Products, Accounts, Suppliers, Kits, Aliases, InboundOrders, Receptions, OutboundOrders)',
+            description: 'Type d\'entité — nom AD (Container) ou TableName (Containers), insensible à la casse, résolu via l\'API Metadata. Ex: Containers, Stocks, ProductLocations, Tasks, Products, Accounts, Suppliers, Kits, Alias, InboundOrders, Receptions, OutboundOrders. Liste complète via get_entity_metadata.',
           },
           expression: {
             type: 'string',
@@ -85,8 +86,12 @@ async function callQueryAPI(args) {
   const { entity_type, expression = 'z => z', filter, limit = 100 } = args;
 
   try {
+    // Résolution Name/TableName -> TableName (D21) — échec avant appel réseau
+    // sur nom inconnu.
+    const { tableName, warning } = await entityResolver.resolveEntityType(entity_type);
+
     // Expression = Context.Entity + optional Where + OrderBy (required by EF when Take is used)
-    let linqExpression = `Context.${entity_type}`;
+    let linqExpression = `Context.${tableName}`;
     if (filter) {
       const whereExpr = /^\s*\w+\s*=>/.test(filter) ? filter : `z => ${filter}`;
       linqExpression += `.Where(${whereExpr})`;
@@ -106,6 +111,8 @@ async function callQueryAPI(args) {
             {
               success: true,
               entityType: entity_type,
+              resolvedTableName: tableName,
+              ...(warning ? { warning } : {}),
               result,
             },
             null,

src/tools/wms-query-tools.js

@@ -14,7 +14,8 @@ function listTools() {
       name: 'query_wms_entities',
       description: `Query WMS entities using LINQ expressions. Returns rows (up to 1000).
 Uses QueryExecute with QueryType=Reading — status fields are STRINGS (enum names, not integers).
-Common entities: Products, Containers, Tasks, Stocks, ProductLocations, Location, InboundOrders, OutboundOrders, Receptions, Accounts, Suppliers, Kits, Aliases.
+Common entities: Products, Containers, Tasks, Stocks, ProductLocations, Locations, InboundOrders, OutboundOrders, Receptions, Accounts, Suppliers, Kits, Alias. Full list via get_entity_metadata.
+entity_type accepts the AD entity name (Container) or the TableName (Containers), case-insensitive — resolved via the Metadata API.
 
 IMPORTANT — before building a filter with a status/enum field:
 1. Check docs first: read resource docs://entities/ (e.g. easywms_reading_entites_outboundorder_OutboundOrderStatus for OutboundOrders)
@@ -26,7 +27,7 @@ Never guess enum string values — they differ between Reading and Writing model
         properties: {
           entity_type: {
             type: 'string',
-            description: 'Entity type (Products, Containers, Tasks, Stocks, ProductLocations, InboundOrders, OutboundOrders, Accounts, Suppliers, Kits, Aliases, Receptions)',
+            description: 'Entity type — AD name (Container) or TableName (Containers), case-insensitive, resolved via the Metadata API. E.g. Products, Containers, Tasks, Stocks, ProductLocations, InboundOrders, OutboundOrders, Accounts, Suppliers, Kits, Alias, Receptions.',
           },
           select_expression: {
             type: 'string',