archgraph-argo 0.27.0 → 0.28.0

package/argo/scripts/{argob-schema.js → schema-bundle.js}

@@ -1,4 +1,4 @@
-'use strict';
+'use strict';
 
 // ARGO schema-bundle resolution and ontology construction.
 //
@@ -6,18 +6,18 @@
 // "schema bundle" is a directory that carries the graph contract:
 //
 //   <bundle>/SystemArchitecture.schema.json   (required) JSON Schema of the graph
-//   <bundle>/argob.config.json                (optional) bundle descriptor:
+//   <bundle>/schema-bundle.config.json                (optional) bundle descriptor:
 //                                               language, enum locations, guide,
 //                                               rules file, invariant switches
-//   <bundle>/argob-rules.json                 (optional) ontology rules data
+//   <bundle>/schema-bundle.rules.json                 (optional) ontology rules data
 //                                               (type metadata, relationship
 //                                               categories, endpoint matrix)
-//   <bundle>/ARGOB.md                         (optional) human-readable guide
+//   <bundle>/GUIDE.md                         (optional) human-readable guide
 //
 // Resolution precedence (first bundle that has SystemArchitecture.schema.json):
-//   1. ARGO_SCHEMA_DIR                     — explicit override (tests / hosts)
-//   2. <workspaceRoot>/.argo/schema        — the repository's own schema
-//   3. <argoRoot>/schema                   — the default ArgoBument schema
+//   1. ARGO_SCHEMA_DIR                     鈥?explicit override (tests / hosts)
+//   2. <workspaceRoot>/.argo/schema        鈥?the repository's own schema
+//   3. <argoRoot>/schema                   鈥?the default ArchiMate 3.2 schema
 //
 // The default bundle keeps the historical ArchiMate 3.2 + ARGO behaviour. A
 // custom bundle may define its own element/relationship types and, optionally,
@@ -29,9 +29,9 @@ const path = require('node:path');
 const { getArgoRoot } = require('./argo-paths.js');
 
 const SCHEMA_BASENAME = 'SystemArchitecture.schema.json';
-const CONFIG_BASENAME = 'argob.config.json';
-const RULES_BASENAME = 'argob-rules.json';
-const GUIDE_BASENAME = 'ARGOB.md';
+const CONFIG_BASENAME = 'schema-bundle.config.json';
+const RULES_BASENAME = 'schema-bundle.rules.json';
+const GUIDE_BASENAME = 'GUIDE.md';
 const DEFAULT_GUIDE_BASENAME = 'archimate3.2.md';
 const DEFAULT_LANGUAGE = 'ArchiMate 3.2';
 const DEFAULT_ROOT_VIEW_NAME = 'SystemArchitecture';
@@ -39,8 +39,8 @@ const DEFAULT_MAX_ELEMENTS_PER_VIEW = 15;
 const DEFAULT_ACTOR_ELEMENT_TYPE = 'Business Actor';
 
 // Which relationship types express a delivery dependency and in which direction.
-// Declared per bundle via argob.config.json "deliveryDependencies"; the default
-// ArgoBument bundle keeps the ArchiMate mapping below (previous behaviour).
+// Declared per bundle via schema-bundle.config.json "deliveryDependencies"; the default
+// ArchiMate 3.2 bundle keeps the ArchiMate mapping below (previous behaviour).
 const ARCHIMATE_DELIVERY_DEPENDENCIES = Object.freeze({
   sourceDependsOnTarget: Object.freeze(['Access', 'Assignment', 'Specialization', 'Composition', 'Aggregation']),
   targetDependsOnSource: Object.freeze(['Serving', 'Realization', 'Flow', 'Triggering', 'Influence']),
@@ -99,12 +99,13 @@ function relativeLabel(workspaceRoot, absolutePath) {
 
 function buildBundle(kind, dir, workspaceRoot) {
   const schemaFile = path.join(dir, SCHEMA_BASENAME);
-  const schema = readJsonFile(schemaFile);
+  const schemaExists = isFile(schemaFile);
+  const schema = schemaExists ? readJsonFile(schemaFile) : null;
 
   const configFile = path.join(dir, CONFIG_BASENAME);
   const fileConfig = isFile(configFile) ? readJsonFile(configFile) : {};
-  const inlineConfig = schema && typeof schema['x-argob'] === 'object' && schema['x-argob'] !== null
-    ? schema['x-argob']
+  const inlineConfig = schema && typeof schema['x-schema-bundle'] === 'object' && schema['x-schema-bundle'] !== null
+    ? schema['x-schema-bundle']
     : {};
   const config = { ...inlineConfig, ...fileConfig };
 
@@ -135,10 +136,9 @@ function buildBundle(kind, dir, workspaceRoot) {
     kind,
     dir,
     relativeDir: relativeLabel(workspaceRoot, dir),
-    schema: {
-      absolutePath: schemaFile,
-      relativePath: relativeLabel(workspaceRoot, schemaFile),
-    },
+    schema: schemaExists
+      ? { absolutePath: schemaFile, relativePath: relativeLabel(workspaceRoot, schemaFile) }
+      : null,
     schemaDocument: schema,
     config: {
       filePath: isFile(configFile) ? { absolutePath: configFile, relativePath: relativeLabel(workspaceRoot, configFile) } : null,
@@ -154,6 +154,262 @@ function buildBundle(kind, dir, workspaceRoot) {
   };
 }
 
+// --- Bundle inheritance (issue #4) -----------------------------------------
+// A bundle may declare `extends` to inherit a base bundle (the built-in default,
+// or another bundle directory) and add/override on top of it instead of forking
+// the whole rules file. `addElementTypes` / `addRelationships` / `overrideMatrix`
+// are the delta; the effective element universe becomes base ∪ add (single
+// source of truth), matrix/metadata merge by key.
+
+function bundleConfig(dir) {
+  const configFile = path.join(dir, CONFIG_BASENAME);
+  if (!isFile(configFile)) {
+    return {};
+  }
+  try {
+    return readJsonFile(configFile);
+  } catch {
+    return {};
+  }
+}
+
+function hasExtendsConfig(dir) {
+  const config = bundleConfig(dir);
+  return typeof config.extends === 'string' && config.extends.trim() !== '';
+}
+
+// Symbolic names a bundle declares about itself (`id` + `aliases`) in its config.
+// The framework resolves an `extends` value against these DECLARED names — never a
+// name hardcoded in framework logic — so a bundle's identity/aliases are data.
+function bundleSymbolicNames(dir) {
+  const config = bundleConfig(dir);
+  const names = new Set();
+  if (typeof config.id === 'string' && config.id.trim() !== '') {
+    names.add(config.id.trim());
+  }
+  if (Array.isArray(config.aliases)) {
+    for (const alias of config.aliases) {
+      if (typeof alias === 'string' && alias.trim() !== '') {
+        names.add(alias.trim());
+      }
+    }
+  }
+  return names;
+}
+
+function isPathLikeExt(value) {
+  return value.includes('/') || value.includes('\\') || value.startsWith('.') || value.startsWith('~')
+    || /^[a-zA-Z]:/.test(value);
+}
+
+// Bounded, general candidate list for symbolic bundle resolution: the built-in
+// default bundle, any directory a bundle lists in its own `basePaths`, the bundle's
+// own directory, and its immediate sub-directories. The framework matches a name
+// against each candidate's SELF-DECLARED id/aliases (data) — it hardcodes no
+// modeling-language name. A non-matching symbolic name falls back to a path, so
+// bare relative directory references keep working.
+function candidateBaseDirs(childDir, config) {
+  const dirs = [];
+  const seen = new Set();
+  const push = (dir) => {
+    if (!dir) {
+      return;
+    }
+    const resolved = path.resolve(dir);
+    const key = resolved.toLowerCase();
+    if (!seen.has(key)) {
+      seen.add(key);
+      dirs.push(resolved);
+    }
+  };
+  push(path.join(getArgoRoot(), 'schema'));
+  const basePaths = config && Array.isArray(config.basePaths) ? config.basePaths : [];
+  for (const basePath of basePaths) {
+    if (typeof basePath === 'string' && basePath.trim() !== '') {
+      push(path.resolve(childDir, basePath.trim()));
+    }
+  }
+  push(childDir);
+  let entries = [];
+  try {
+    entries = fs.readdirSync(childDir, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      push(path.join(childDir, entry.name));
+    }
+  }
+  return dirs;
+}
+
+function resolveBaseBundleDir(ext, childDir, config) {
+  const value = String(ext).trim();
+  // `default` is the reserved, language-neutral name of the built-in bundle.
+  if (value === 'default') {
+    return path.join(getArgoRoot(), 'schema');
+  }
+  if (!isPathLikeExt(value)) {
+    for (const dir of candidateBaseDirs(childDir, config)) {
+      if (bundleSymbolicNames(dir).has(value)) {
+        return dir;
+      }
+    }
+  }
+  // Not a symbolic hit: treat as a path relative to the bundle directory.
+  return path.resolve(childDir, value);
+}
+
+function deepCloneJson(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function mergeMatrixInto(target, source) {
+  if (!source || typeof source !== 'object') {
+    return target;
+  }
+  for (const [relationshipType, bySource] of Object.entries(source)) {
+    if (!bySource || typeof bySource !== 'object') {
+      target[relationshipType] = deepCloneJson(bySource);
+      continue;
+    }
+    if (!target[relationshipType] || typeof target[relationshipType] !== 'object') {
+      target[relationshipType] = {};
+    }
+    for (const [sourceType, targets] of Object.entries(bySource)) {
+      target[relationshipType][sourceType] = deepCloneJson(targets);
+    }
+  }
+  return target;
+}
+
+// Append added types to a JSON-Schema enum def (the element/relationship type
+// universe), so a schema-less inheriting Profile's own added types are structurally
+// valid — not just present at the ontology level.
+function extendSchemaEnum(schemaDocument, enumKeys, additions) {
+  const defs = schemaDocument && typeof schemaDocument.$defs === 'object' ? schemaDocument.$defs : null;
+  if (!defs) {
+    return;
+  }
+  for (const key of enumKeys) {
+    const node = defs[key];
+    if (node && Array.isArray(node.enum)) {
+      for (const value of additions) {
+        if (typeof value === 'string' && value !== '' && !node.enum.includes(value)) {
+          node.enum.push(value);
+        }
+      }
+      return;
+    }
+  }
+}
+
+function mergeExtendsBundle(base, child) {
+  const baseRules = base.rules || {};
+  const childRules = child.rules || {};
+  const config = { ...(base.config || {}), ...(child.config || {}) };
+
+  const elementTypeMetadata = { ...(baseRules.elementTypeMetadata || {}), ...(childRules.elementTypeMetadata || {}) };
+  const archimateClassByElementType = { ...(baseRules.archimateClassByElementType || {}), ...(childRules.archimateClassByElementType || {}) };
+  const relationshipCategoryByType = { ...(baseRules.relationshipCategoryByType || {}), ...(childRules.relationshipCategoryByType || {}) };
+
+  const addElementTypes = config.addElementTypes && typeof config.addElementTypes === 'object' ? config.addElementTypes : {};
+  for (const [type, meta] of Object.entries(addElementTypes)) {
+    if (!elementTypeMetadata[type]) {
+      elementTypeMetadata[type] = { layer: (meta && meta.layer) || null, aspect: (meta && meta.aspect) || null };
+    }
+    if (meta && typeof meta.class === 'string' && meta.class !== '') {
+      archimateClassByElementType[type] = meta.class;
+    }
+  }
+  const addRelationships = config.addRelationships && typeof config.addRelationships === 'object' ? config.addRelationships : {};
+  for (const [type, category] of Object.entries(addRelationships)) {
+    relationshipCategoryByType[type] = category;
+  }
+
+  // Guarantee base ∪ add for the element/relationship universe regardless of the
+  // base dialect (class-matrix derives types from rules metadata, type-matrix from
+  // schema enums) — an inheriting Profile must never silently drop a base type.
+  const baseOntology = buildOntology(base);
+  for (const type of baseOntology.elementTypes) {
+    if (!elementTypeMetadata[type]) {
+      elementTypeMetadata[type] = { layer: null, aspect: null };
+    }
+  }
+  for (const type of baseOntology.relationshipTypes) {
+    if (!relationshipCategoryByType[type]) {
+      relationshipCategoryByType[type] = 'Custom';
+    }
+  }
+
+  const relationshipTargetMatrix = deepCloneJson(baseRules.relationshipTargetMatrix || {}) || {};
+  mergeMatrixInto(relationshipTargetMatrix, childRules.relationshipTargetMatrix || {});
+  mergeMatrixInto(relationshipTargetMatrix, config.overrideMatrix || {});
+
+  // Inherit the base dialect as-is; never default to a specific dialect NAME here
+  // (that would couple the generic merge to one modeling language). When both are
+  // absent the ontology builder decides from the bundle's declared rules.
+  const dialect = childRules.dialect || baseRules.dialect;
+  const rules = {
+    ...baseRules,
+    ...childRules,
+    dialect,
+    elementTypeMetadata,
+    archimateClassByElementType,
+    relationshipCategoryByType,
+    relationshipTargetMatrix,
+  };
+
+  // Structural schema: when the child has none, it inherits the base schema — but
+  // its added types must be valid against the base's $defs enum too, otherwise
+  // whole-graph validation (validateAgainstSchema) rejects elements of the added
+  // types. Extend the inherited schema enum in place (clone, never mutate base).
+  let schemaDocument = child.schemaDocument || base.schemaDocument;
+  if (!child.schemaDocument && base.schemaDocument) {
+    const extraElementTypes = Object.keys(addElementTypes).filter(Boolean);
+    const extraRelationshipTypes = Object.keys(addRelationships).filter(Boolean);
+    const extraFromConfigElements = Array.isArray(config.elementTypes) ? config.elementTypes : [];
+    const extraFromConfigRelationships = Array.isArray(config.relationshipTypes) ? config.relationshipTypes : [];
+    if (extraElementTypes.length || extraRelationshipTypes.length || extraFromConfigElements.length || extraFromConfigRelationships.length) {
+      schemaDocument = deepCloneJson(base.schemaDocument);
+      extendSchemaEnum(schemaDocument, ELEMENT_ENUM_KEYS, extraElementTypes.concat(extraFromConfigElements));
+      extendSchemaEnum(schemaDocument, RELATIONSHIP_ENUM_KEYS, extraRelationshipTypes.concat(extraFromConfigRelationships));
+    }
+  }
+
+  return {
+    ...child,
+    schema: child.schema || base.schema,
+    schemaDocument,
+    rules,
+    config,
+    inheritedFrom: base.dir,
+    chainDirs: Array.from(new Set([
+      ...(Array.isArray(base.chainDirs) && base.chainDirs.length > 0 ? base.chainDirs : [path.resolve(base.dir).toLowerCase()]),
+      path.resolve(child.dir).toLowerCase(),
+    ])),
+  };
+}
+
+function applyExtends(bundle, workspaceRoot, seen = new Set()) {
+  const ext = bundle && bundle.config && typeof bundle.config.extends === 'string' ? bundle.config.extends.trim() : '';
+  if (!ext) {
+    return bundle;
+  }
+  seen.add(path.resolve(bundle.dir).toLowerCase());
+  const baseDir = resolveBaseBundleDir(ext, bundle.dir, bundle.config);
+  const baseKey = path.resolve(baseDir).toLowerCase();
+  if (seen.has(baseKey)) {
+    throw new Error(`schema bundle extends cycle detected at '${baseDir}'`);
+  }
+  if (!isFile(path.join(baseDir, SCHEMA_BASENAME)) && !hasExtendsConfig(baseDir)) {
+    throw new Error(`schema bundle extends '${ext}' could not be resolved: no schema bundle at '${baseDir}'`);
+  }
+  const baseBundle = applyExtends(buildBundle('extends', baseDir, workspaceRoot), workspaceRoot, seen);
+  return mergeExtendsBundle(baseBundle, bundle);
+}
+
 function resolveSchemaBundle(workspaceRoot, options = {}) {
   const root = path.resolve(workspaceRoot || process.cwd());
   const candidates = [];
@@ -172,8 +428,8 @@ function resolveSchemaBundle(workspaceRoot, options = {}) {
       continue;
     }
     seen.add(key);
-    if (isFile(path.join(candidate.dir, SCHEMA_BASENAME))) {
-      return buildBundle(candidate.kind, candidate.dir, root);
+    if (isFile(path.join(candidate.dir, SCHEMA_BASENAME)) || hasExtendsConfig(candidate.dir)) {
+      return applyExtends(buildBundle(candidate.kind, candidate.dir, root), root);
     }
   }
 
@@ -258,7 +514,77 @@ function resolveActorElementType(config) {
   return DEFAULT_ACTOR_ELEMENT_TYPE;
 }
 
-function validateBundle({ language, dialect, elementTypes, relationshipTypes, actorElementType, matrix, deliveryDependencies }) {
+// Per-element-type attribute contract (issue #3): declare that an element type
+// must carry certain attributes, that some attribute values are a controlled
+// vocabulary, and that some attribute values are unique within the type.
+//   { "Rule": { "required": ["ruleId","normativity"], "unique": ["ruleId"],
+//               "enumByAttr": { "normativity": ["MUST","SHOULD","MAY","MUST_NOT"] } } }
+// Absent => no per-type attribute contract (backward compatible).
+function resolveAttributeContracts(config) {
+  const raw = config && typeof config.attributesByElementType === 'object' && config.attributesByElementType !== null
+    ? config.attributesByElementType
+    : null;
+  if (!raw) {
+    return undefined;
+  }
+  const contracts = {};
+  for (const [type, contract] of Object.entries(raw)) {
+    if (!contract || typeof contract !== 'object') {
+      contracts[type] = {};
+      continue;
+    }
+    contracts[type] = {
+      required: Array.isArray(contract.required) ? contract.required.slice() : undefined,
+      unique: Array.isArray(contract.unique) ? contract.unique.slice() : undefined,
+      enumByAttr: contract.enumByAttr && typeof contract.enumByAttr === 'object' ? { ...contract.enumByAttr } : undefined,
+    };
+  }
+  return contracts;
+}
+
+function validateAttributeContracts(language, elementTypeList, contracts) {
+  const errors = [];
+  if (!contracts || typeof contracts !== 'object') {
+    return errors;
+  }
+  for (const [type, contract] of Object.entries(contracts)) {
+    if (!elementTypeList.includes(type)) {
+      errors.push(`schema bundle '${language}' attributesByElementType references unknown element type '${type}'`);
+    }
+    if (!contract || typeof contract !== 'object') {
+      continue;
+    }
+    for (const key of ['required', 'unique']) {
+      const list = contract[key];
+      if (list === undefined) {
+        continue;
+      }
+      if (!Array.isArray(list)) {
+        errors.push(`schema bundle '${language}' attributesByElementType['${type}'].${key} must be an array`);
+        continue;
+      }
+      for (const name of list) {
+        if (typeof name !== 'string' || name === '') {
+          errors.push(`schema bundle '${language}' attributesByElementType['${type}'].${key} entries must be non-empty strings`);
+        }
+      }
+    }
+    if (contract.enumByAttr !== undefined) {
+      if (!contract.enumByAttr || typeof contract.enumByAttr !== 'object') {
+        errors.push(`schema bundle '${language}' attributesByElementType['${type}'].enumByAttr must be an object`);
+      } else {
+        for (const [attr, allowed] of Object.entries(contract.enumByAttr)) {
+          if (!Array.isArray(allowed) || allowed.length === 0) {
+            errors.push(`schema bundle '${language}' attributesByElementType['${type}'].enumByAttr['${attr}'] must be a non-empty array`);
+          }
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+function validateBundle({ language, dialect, elementTypes, relationshipTypes, actorElementType, matrix, deliveryDependencies, attributesByElementType }) {
   const errors = [];
   const elementTypeList = Array.isArray(elementTypes) ? elementTypes : [];
   const relationshipTypeList = Array.isArray(relationshipTypes) ? relationshipTypes : [];
@@ -276,7 +602,7 @@ function validateBundle({ language, dialect, elementTypes, relationshipTypes, ac
     if (!elementTypeList.includes(actorElementType)) {
       errors.push(
         `schema bundle '${language}' declares actorElementType '${actorElementType}' which is not one of its element types; ` +
-        `set a valid actorElementType in argob.config.json (one of: ${elementTypeList.join(', ') || '(none)'}) ` +
+        `set a valid actorElementType in schema-bundle.config.json (one of: ${elementTypeList.join(', ') || '(none)'}) ` +
         `or set "actorElementType": null if the schema has no actor concept`,
       );
     }
@@ -304,6 +630,7 @@ function validateBundle({ language, dialect, elementTypes, relationshipTypes, ac
   }
 
   errors.push(...validateDeliveryDependencies(language, relationshipTypeList, deliveryDependencies));
+  errors.push(...validateAttributeContracts(language, elementTypeList, attributesByElementType));
 
   return { status: errors.length === 0 ? 'passed' : 'failed', errors };
 }
@@ -338,7 +665,7 @@ function buildClassMatrixOntology(bundle) {
   let validateRelationshipEndpointTypes;
 
   if (rules) {
-    // Data-driven default: the bundle ships its own rule data (argob-rules.json),
+    // Data-driven default: the bundle ships its own rule data (schema-bundle.rules.json),
     // so the DEFAULT schema is replaceable file-for-file exactly like a custom one.
     const classByType = rules.archimateClassByElementType || {};
     const classMatrix = rules.relationshipTargetMatrix || {};
@@ -371,7 +698,7 @@ function buildClassMatrixOntology(bundle) {
       return [];
     };
   } else {
-    // Legacy fallback: an installation without argob-rules.json uses the bundled module.
+    // Legacy fallback: an installation without schema-bundle.rules.json uses the bundled module.
     const mod = require('./archimate32-rules.js');
     elementTypeMetadata = mod.elementTypeMetadata;
     relationshipCategoryByType = mod.relationshipCategoryByType;
@@ -386,6 +713,7 @@ function buildClassMatrixOntology(bundle) {
   const relationshipTypes = Array.from(relationshipCategoryByType.keys());
   const actorElementType = resolveActorElementType(bundle.config);
   const deliveryDependencies = resolveDeliveryDependencies(bundle.config, 'archimate-class-matrix');
+  const attributesByElementType = resolveAttributeContracts(bundle.config);
   return finalizeOntology({
     kind: bundle.kind,
     dialect: 'archimate-class-matrix',
@@ -397,7 +725,8 @@ function buildClassMatrixOntology(bundle) {
     relationshipTypes,
     actorElementType,
     deliveryDependencies,
-    bundleValidation: validateBundle({ language, dialect: 'archimate-class-matrix', elementTypes, relationshipTypes, actorElementType, matrix: null, deliveryDependencies }),
+    attributesByElementType,
+    bundleValidation: validateBundle({ language, dialect: 'archimate-class-matrix', elementTypes, relationshipTypes, actorElementType, matrix: null, deliveryDependencies, attributesByElementType }),
     elementTypeMetadata,
     relationshipCategoryByType,
     isSupportedElementType,
@@ -456,6 +785,7 @@ function buildTypeMatrixOntology(bundle) {
   const elementTypes = Array.from(elementTypeMetadata.keys());
   const relationshipTypes = Array.from(relationshipCategoryByType.keys());
   const deliveryDependencies = resolveDeliveryDependencies(config, 'type-matrix');
+  const attributesByElementType = resolveAttributeContracts(config);
   const getArchiMateClass = (elementOrType) => {
     const type = typeof elementOrType === 'string' ? elementOrType : elementOrType && elementOrType.type;
     return type;
@@ -494,7 +824,8 @@ function buildTypeMatrixOntology(bundle) {
     relationshipTypes,
     actorElementType,
     deliveryDependencies,
-    bundleValidation: validateBundle({ language, dialect: 'type-matrix', elementTypes, relationshipTypes, actorElementType, matrix, deliveryDependencies }),
+    attributesByElementType,
+    bundleValidation: validateBundle({ language, dialect: 'type-matrix', elementTypes, relationshipTypes, actorElementType, matrix, deliveryDependencies, attributesByElementType }),
     elementTypeMetadata,
     relationshipCategoryByType,
     isSupportedElementType: (type) => elementTypeMetadata.has(type),
@@ -552,9 +883,36 @@ function buildOntology(bundle) {
   return bundle.kind === 'default' ? buildClassMatrixOntology(bundle) : buildTypeMatrixOntology(bundle);
 }
 
+// Cheap on-disk fingerprint of a bundle (and its extends chain) so a running MCP
+// picks up edits to the bundle files without a restart: the ontology cache key
+// changes when any key file's mtime/size changes.
+function bundleFingerprint(bundle) {
+  const dirs = Array.isArray(bundle.chainDirs) && bundle.chainDirs.length > 0
+    ? bundle.chainDirs
+    : [path.resolve(bundle.dir).toLowerCase()];
+  const statFile = (absolutePath) => {
+    try {
+      const stat = fs.statSync(absolutePath);
+      return `${Math.round(stat.mtimeMs)}:${stat.size}`;
+    } catch {
+      return '-';
+    }
+  };
+  const parts = [];
+  for (const dir of dirs) {
+    for (const name of [SCHEMA_BASENAME, CONFIG_BASENAME, RULES_BASENAME]) {
+      parts.push(`${name}=${statFile(path.join(dir, name))}`);
+    }
+  }
+  if (bundle.config && typeof bundle.config.rules === 'string' && bundle.config.rules.trim() !== '') {
+    parts.push(`rules=${statFile(path.resolve(bundle.dir, bundle.config.rules))}`);
+  }
+  return parts.join('|');
+}
+
 function loadSchemaBundleAndOntology(workspaceRoot, options = {}) {
   const bundle = resolveSchemaBundle(workspaceRoot, options);
-  const cacheKey = `${bundle.kind}:${path.resolve(bundle.dir).toLowerCase()}`;
+  const cacheKey = `${bundle.kind}:${path.resolve(bundle.dir).toLowerCase()}:${bundleFingerprint(bundle)}`;
   if (ontologyCache.has(cacheKey)) {
     return { bundle, ontology: ontologyCache.get(cacheKey) };
   }