archgraph-argo 0.26.1 → 0.27.0

package/argo/scripts/systemarchitecture-mcp-server.js

@@ -6,7 +6,6 @@ const readline = require('node:readline');
 const crypto = require('node:crypto');
 
 const {
-  getArgoRoot,
   resolveCallWorkspaceRoot,
 } = require('./argo-paths.js');
 
@@ -132,6 +131,11 @@ const {
   validateArchiMateEndpointMatrix,
   validateViewElementLimits,
 } = require('./graph-semantics.js');
+const {
+  loadSchemaBundleAndOntology,
+  resolveSchemaBundle,
+  resolveTypeEnums,
+} = require('./argob-schema.js');
 const {
   createProductionGraphRagRuntime,
 } = require('./graph-rag/productionGraphRagRuntime.js');
@@ -168,6 +172,7 @@ const {
 } = require('./neo4j-system-architecture-store.js');
 
 const losslessWriteGate = require('./lossless-write-gate.js');
+const { EXTERNAL_READ_TOOLS } = require('./external-graph-query.js');
 
 const HANDLED_MUTATION_TYPES = new Set([
   'addElement',
@@ -231,7 +236,7 @@ const TOOLS = [
   },
   {
     name: 'previewSystemArchitectureMutation',
-    description: 'Use before apply for complex or risky changes. Performs a dry-run of one or more mutations, runs schema, graph, view, and ArchiMate 3.2 validation, and does not write the graph.',
+    description: 'Use before apply for complex or risky changes. Performs a dry-run of one or more mutations, runs schema, graph, view, and modeling-language validation, and does not write the graph.',
     inputSchema: mutationInputSchema(),
   },
   {
@@ -380,7 +385,7 @@ const TOOLS = [
   },
   {
     name: 'queryNeo4jGraph',
-    description: 'Run a read-only Cypher query against the Neo4j structural projection of the intent architecture, or request the projection schema so an agent can construct its own Cypher. Pass {schema: true} to return node labels, relationship types, property keys, and the legal ArchiMate element/relationship type enums. Pass {cypher: "..."} to execute a read-only query; scope it with {graphKey: $graphKey}. Write clauses (CREATE/MERGE/DELETE/SET/REMOVE/DROP/LOAD CSV/FOREACH/IN TRANSACTIONS) are rejected.',
+    description: 'Run a read-only Cypher query against the Neo4j structural projection of the intent architecture, or request the projection schema so an agent can construct its own Cypher. Pass {schema: true} to return node labels, relationship types, property keys, and the legal element/relationship type enums of the workspace-resolved schema bundle. Pass {cypher: "..."} to execute a read-only query; scope it with {graphKey: $graphKey}. Write clauses (CREATE/MERGE/DELETE/SET/REMOVE/DROP/LOAD CSV/FOREACH/IN TRANSACTIONS) are rejected.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -415,6 +420,13 @@ const WORKSPACE_ROOT_PARAM = Object.freeze({
   description:
     'Optional absolute workspace root for this call. When provided it is used as-is; otherwise the server launch directory is used.',
 });
+// Cross-project graph query: the 5 read tools accept an optional `projectId`;
+// provided => routed to the federation center, omitted => the local workspace.
+const PROJECT_ID_PARAM = Object.freeze({
+  type: 'string',
+  description:
+    'Optional external project id. When provided, the query is routed to the federation center to read that project\'s graph (this project must be registered in .argo/federation.json); omitted = the local workspace (unchanged).',
+});
 // Lossless write gate: every update/remove helper accepts an explicit loss
 // acknowledgement (see lossless-write-gate.js). add* is purely additive and is
 // left alone. Without the acknowledgement a shrinking text edit or a destructive
@@ -436,6 +448,9 @@ for (const tool of TOOLS) {
   if (!Object.prototype.hasOwnProperty.call(inputSchema.properties, 'workspaceRoot')) {
     inputSchema.properties.workspaceRoot = WORKSPACE_ROOT_PARAM;
   }
+  if (EXTERNAL_READ_TOOLS.has(tool.name) && !Object.prototype.hasOwnProperty.call(inputSchema.properties, 'projectId')) {
+    inputSchema.properties.projectId = PROJECT_ID_PARAM;
+  }
   if (tool.name && /^(update|remove)Architecture/.test(tool.name)) {
     for (const [key, value] of Object.entries(LOSS_ACK_INPUT_PROPS)) {
       if (!Object.prototype.hasOwnProperty.call(inputSchema.properties, key)) {
@@ -559,22 +574,7 @@ function normalizeRelativePath(value) {
 }
 
 function resolveSchemaPath(workspaceRoot) {
-  const bundledSchemaPath = path.join(getArgoRoot(), 'schema', 'SystemArchitecture.schema.json');
-  if (fs.existsSync(bundledSchemaPath)) {
-    return { absolutePath: bundledSchemaPath, relativePath: SCHEMA_PATH_CANDIDATES[0] };
-  }
-
-  for (const candidate of SCHEMA_PATH_CANDIDATES) {
-    const absolutePath = path.join(workspaceRoot, candidate);
-    if (fs.existsSync(absolutePath)) {
-      return { absolutePath, relativePath: candidate };
-    }
-    const bundledPath = path.resolve(__dirname, '..', '..', candidate);
-    if (fs.existsSync(bundledPath)) {
-      return { absolutePath: bundledPath, relativePath: candidate };
-    }
-  }
-  throw new Error(`Unable to locate SystemArchitecture schema. Checked: ${SCHEMA_PATH_CANDIDATES.join(', ')}`);
+  return resolveSchemaBundle(workspaceRoot).schema;
 }
 
 function readJson(filePath, label) {
@@ -588,13 +588,17 @@ function readJson(filePath, label) {
 async function loadContext(args = {}) {
   const workspaceRoot = resolveWorkspaceRoot(args);
   const graphPath = resolveWorkspacePath(workspaceRoot, args.architecturePath || DEFAULT_GRAPH_PATH);
-  const schemaPath = resolveSchemaPath(workspaceRoot);
+  // Resolve the modeling language for THIS workspace: a repository that ships
+  // its own bundle under .argo/schema is validated against that schema.
+  const { bundle, ontology } = loadSchemaBundleAndOntology(workspaceRoot);
   const context = {
     workspaceRoot,
     graphPath,
-    schemaPath,
+    schemaPath: bundle.schema,
+    schemaBundle: bundle,
+    ontology,
     document: readJson(graphPath.absolutePath, graphPath.relativePath),
-    schema: readJson(schemaPath.absolutePath, schemaPath.relativePath),
+    schema: bundle.schemaDocument,
   };
   context.neo4jSyncRecovery = await recoverNeo4jSyncIfNeeded({
     architecturePath: graphPath.relativePath,
@@ -605,13 +609,19 @@ async function loadContext(args = {}) {
 }
 
 function validateDocument(document, schema, options = {}) {
+  const ontology = options.ontology;
   const errors = [];
+  if (ontology && ontology.bundleValidation && ontology.bundleValidation.status === 'failed') {
+    errors.push(...ontology.bundleValidation.errors.map(error => `schema bundle: ${error}`));
+  }
   validateAgainstSchema(document, schema, '#', errors, schema);
-  validateGraphSemantics(document, errors);
+  validateGraphSemantics(document, errors, ontology);
   validateArchiMateEndpointMatrix(document, errors, {
+    ontology,
     touchedRelationshipIds: options.touchedRelationshipIds,
   });
   validateViewElementLimits(document, errors, {
+    ontology,
     touchedViewIds: options.validateAllViewElementLimits
       ? (document.views || []).map(view => view && view.view_id)
       : options.touchedViewIds,
@@ -629,29 +639,42 @@ function validateDocument(document, schema, options = {}) {
 // also NOT the semantic match surface — semantic retrieval embeds attributes and
 // testcase descriptions (semanticRecordText.js), so semantic results keep them;
 // and the focus element of an intent-element read always keeps its own.
+function byteLenLocal(value) {
+  try { return Buffer.byteLength(JSON.stringify(value)); } catch (_) { return 0; }
+}
+
 function projectAgentFields(record, opts = {}) {
   const value = clone(record);
   let omittedAttributes = 0;
   let omittedTestcases = 0;
+  let omittedBytes = 0;
   if (!opts.includeAttributes && Array.isArray(value.attributes) && value.attributes.length) {
     omittedAttributes = value.attributes.length;
+    omittedBytes += byteLenLocal(value.attributes);
     delete value.attributes;
   }
   if (!opts.includeTestcases && Array.isArray(value.testcases) && value.testcases.length) {
     omittedTestcases = value.testcases.length;
+    omittedBytes += byteLenLocal(value.testcases);
     delete value.testcases;
   }
-  return { value, omittedAttributes, omittedTestcases };
+  return { value, omittedAttributes, omittedTestcases, omittedBytes };
 }
 
 function buildAgentProjection(omitted) {
   if (!omitted || (omitted.attributes === 0 && omitted.testcases === 0)) {
     return null;
   }
+  // Only attach the explanation when the omission actually saves more than the
+  // note costs, so trimming a read can NEVER make it larger (cross-scenario
+  // no-degradation). The opt-in flags are documented in the tool description.
+  if ((omitted.bytes || 0) < 160) {
+    return null;
+  }
   return {
     attributesOmitted: omitted.attributes,
     testcasesOmitted: omitted.testcases,
-    note: 'Member attributes/testcases are bookkeeping (commit/session/release ledgers, acceptance cases) and are omitted from this structural read by default. Pass includeAttributes:true / includeTestcases:true to include them verbatim. Semantic retrieval already embeds their text, so semantic hits keep them.',
+    note: 'includeAttributes/includeTestcases=true to include (omitted by default; semantic hits keep them).',
   };
 }
 
@@ -666,7 +689,7 @@ function buildIntentElementContext(context, args = {}) {
   const dependentDepth = normalizeDepth(args.dependentDepth, 1);
   const associationDepth = Math.max(1, normalizeDepth(args.associationDepth, 1));
   const associationNeighborDependencyDepth = normalizeDepth(args.associationNeighborDependencyDepth, 0);
-  const graphIndex = buildGraphIndex(context.document);
+  const graphIndex = buildGraphIndex(context.document, context.ontology);
   const focusElement = focusResult.element;
   const includedElementIds = new Set([focusElement.id]);
   const includedRelationshipIds = new Set();
@@ -740,7 +763,7 @@ function buildIntentElementContext(context, args = {}) {
   const subgraph = buildNativeSubgraph(context.document, includedElementIds, includedRelationshipIds);
   const includeAttributes = args.includeAttributes === true;
   const includeTestcases = args.includeTestcases === true;
-  const omitted = { attributes: 0, testcases: 0 };
+  const omitted = { attributes: 0, testcases: 0, bytes: 0 };
   if (!(includeAttributes && includeTestcases)) {
     subgraph.elements = subgraph.elements.map((element) => {
       if (element.id === focusElement.id) {
@@ -749,11 +772,13 @@ function buildIntentElementContext(context, args = {}) {
       const projected = projectAgentFields(element, { includeAttributes, includeTestcases });
       omitted.attributes += projected.omittedAttributes;
       omitted.testcases += projected.omittedTestcases;
+      omitted.bytes += projected.omittedBytes;
       return projected.value;
     });
     subgraph.relationships = subgraph.relationships.map((relationship) => {
       const projected = projectAgentFields(relationship, { includeAttributes });
       omitted.attributes += projected.omittedAttributes;
+      omitted.bytes += projected.omittedBytes;
       return projected.value;
     });
   }
@@ -851,11 +876,12 @@ function buildViewContext(context, args = {}) {
 
   const includeAttributes = args.includeAttributes === true;
   const includeTestcases = args.includeTestcases === true;
-  const omitted = { attributes: 0, testcases: 0 };
+  const omitted = { attributes: 0, testcases: 0, bytes: 0 };
   const project = (record) => {
     const projected = projectAgentFields(record, { includeAttributes, includeTestcases });
     omitted.attributes += projected.omittedAttributes;
     omitted.testcases += projected.omittedTestcases;
+    omitted.bytes += projected.omittedBytes;
     return projected.value;
   };
 
@@ -975,7 +1001,7 @@ function normalizeDepth(value, defaultValue) {
   return Math.floor(numericValue);
 }
 
-function buildGraphIndex(document) {
+function buildGraphIndex(document, ontology) {
   const relationshipById = new Map();
   const elementById = new Map((document.elements || []).map(element => [element.id, element]));
   const relationshipsByElementId = new Map();
@@ -984,9 +1010,19 @@ function buildGraphIndex(document) {
     addIndexedRelationship(relationshipsByElementId, relationship.source_id, relationship);
     addIndexedRelationship(relationshipsByElementId, relationship.target_id, relationship);
   }
-  return { elementById, relationshipById, relationshipsByElementId };
+  const deliveryDependencies = ontology && ontology.deliveryDependencies
+    ? ontology.deliveryDependencies
+    : DEFAULT_DELIVERY_DEPENDENCIES;
+  return { elementById, relationshipById, relationshipsByElementId, deliveryDependencies };
 }
 
+// Dependency direction for the semantic-edge walk comes from the active schema
+// bundle's deliveryDependencies; this is the ArgoBument fallback by default.
+const DEFAULT_DELIVERY_DEPENDENCIES = Object.freeze({
+  sourceDependsOnTarget: Object.freeze(['Access', 'Assignment', 'Specialization', 'Composition', 'Aggregation']),
+  targetDependsOnSource: Object.freeze(['Serving', 'Realization', 'Flow', 'Triggering', 'Influence']),
+});
+
 function addIndexedRelationship(index, elementId, relationship) {
   if (!index.has(elementId)) {
     index.set(elementId, []);
@@ -1041,8 +1077,9 @@ function resolveSemanticEdges(elementId, graphIndex) {
       continue;
     }
 
-    const sourceDependsOnTarget = ['Access', 'Assignment', 'Specialization', 'Composition', 'Aggregation'].includes(relationshipType);
-    const targetDependsOnSource = ['Serving', 'Realization', 'Flow', 'Triggering', 'Influence'].includes(relationshipType);
+    const deliveryDependencies = graphIndex.deliveryDependencies || DEFAULT_DELIVERY_DEPENDENCIES;
+    const sourceDependsOnTarget = deliveryDependencies.sourceDependsOnTarget.includes(relationshipType);
+    const targetDependsOnSource = deliveryDependencies.targetDependsOnSource.includes(relationshipType);
     if (sourceDependsOnTarget) {
       edges.push({ kind: isSource ? 'dependency' : 'dependent', neighborId, relationship });
       continue;
@@ -1914,7 +1951,7 @@ async function buildMutationResult(context, mutations, write, dependencies, loss
       before: beforeSummary,
       after: beforeSummary,
       errors,
-      guidance: buildFailureGuidance(errors),
+      guidance: buildFailureGuidance(errors, context.ontology),
     };
     if (error && Array.isArray(error.duplicateConflicts) && error.duplicateConflicts.length > 0) {
       failed.duplicateConflicts = error.duplicateConflicts;
@@ -1925,6 +1962,7 @@ async function buildMutationResult(context, mutations, write, dependencies, loss
     return failed;
   }
   const errors = validateDocument(mutationResult.document, context.schema, {
+    ontology: context.ontology,
     touchedRelationshipIds: mutationResult.touchedRelationshipIds,
     touchedViewIds: mutationResult.viewLimitCheckIds,
   });
@@ -1944,7 +1982,7 @@ async function buildMutationResult(context, mutations, write, dependencies, loss
     errors,
   };
   if (errors.length > 0) {
-    result.guidance = buildFailureGuidance(errors);
+    result.guidance = buildFailureGuidance(errors, context.ontology);
   }
 
   // Semantic dedup gate: a would-be element create is blocked when a same-type
@@ -2199,10 +2237,10 @@ function buildMutationEmbeddingLifecycleFailure(error, result) {
   });
 }
 
-function buildFailureGuidance(errors) {
+function buildFailureGuidance(errors, ontology) {
   const guidance = [];
   for (const error of errors || []) {
-    addGuidanceForError(guidance, String(error));
+    addGuidanceForError(guidance, String(error), ontology);
   }
   if (guidance.length === 0 && Array.isArray(errors) && errors.length > 0) {
     guidance.push('Inspect the error text, call getSystemArchitecture with an explicit semantic query to refresh relevant ids, use getIntentElementContext for focused dependency context when needed, then retry with previewSystemArchitectureMutation before writing. Use an omitted-query full snapshot only when exact complete view membership is required.');
@@ -2210,15 +2248,17 @@ function buildFailureGuidance(errors) {
   return guidance;
 }
 
-function addGuidanceForError(guidance, error) {
+function addGuidanceForError(guidance, error, ontology) {
+  const language = ontology && ontology.language ? ontology.language : 'ArchiMate 3.2';
+  const matrixLabel = ontology && ontology.matrixErrorLabel ? ontology.matrixErrorLabel : 'ArchiMate 3.2 relationship matrix';
   if (error.includes('mutation.view_ids must contain at least one view id')) {
     pushUnique(guidance, 'Select the target view_ids explicitly. Prefer getSystemArchitecture with an explicit semantic query to find relevant views, then use getIntentElementContext for focused element dependencies when needed. Use a full snapshot only if exact complete view membership is required.');
   }
-  if (error.includes('violates ArchiMate 3.2 relationship matrix')) {
-    pushUnique(guidance, 'Check relationship.type and the source and target element types against ArchiMate 3.2. If the intended meaning is still valid, choose a compliant relationship type or change the endpoint element types by remove-and-add.');
+  if (error.includes(`violates ${matrixLabel}`)) {
+    pushUnique(guidance, `Check relationship.type and the source and target element types against ${language}. If the intended meaning is still valid, choose a compliant relationship type or change the endpoint element types by remove-and-add.`);
   }
-  if (error.includes('uses unsupported ArchiMate relationship type')) {
-    pushUnique(guidance, 'Use relationship.type for the ArchiMate relationship type and choose one of the schema-supported ArchiMate 3.2 relationship types.');
+  if (error.includes('uses unsupported') && error.includes('relationship type')) {
+    pushUnique(guidance, `Use relationship.type for the relationship type and choose one of the schema-supported ${language} relationship types.`);
   }
   if (error.includes('id cannot be updated') || error.includes('type cannot be updated')) {
     pushUnique(guidance, 'Do not patch immutable identity or type fields. To change an id or type, remove the existing element or relationship, then add the replacement with the desired id or type.');
@@ -2227,10 +2267,16 @@ function addGuidanceForError(guidance, error) {
     pushUnique(guidance, 'Every element and relationship must belong to at least one view. Add it with view_ids, or add the existing object to an appropriate view before validating again.');
   }
   if (error.includes('must declare parent_element_id') || error.includes('top-level view')) {
-    pushUnique(guidance, 'Keep exactly one top-level view named SystemArchitecture. For any sub-view, set parent_element_id to an existing element and keep parent_element_name aligned with that element name.');
+    const rootViewName = ontology && ontology.invariants && ontology.invariants.rootViewName
+      ? ontology.invariants.rootViewName
+      : 'SystemArchitecture';
+    pushUnique(guidance, `Keep exactly one top-level view${rootViewName ? ` named ${rootViewName}` : ''}. For any sub-view, set parent_element_id to an existing element and keep parent_element_name aligned with that element name.`);
   }
-  if (error.includes('must contain at most 15 elements')) {
-    pushUnique(guidance, 'Do not force more than 15 included_elements into one view. Pause and think about layered architecture: split the view into layered sub-views, attach each sub-view with parent_element_id, and move lower-level elements into the appropriate child view before retrying.');
+  if (error.includes('must contain at most') && error.includes('elements')) {
+    const maxElements = ontology && ontology.invariants && ontology.invariants.maxElementsPerView !== undefined && ontology.invariants.maxElementsPerView !== null
+      ? ontology.invariants.maxElementsPerView
+      : 15;
+    pushUnique(guidance, `Do not force more than ${maxElements} included_elements into one view. Pause and think about layered architecture: split the view into layered sub-views, attach each sub-view with parent_element_id, and move lower-level elements into the appropriate child view before retrying.`);
   }
   if (error.includes('does not exist') || error.includes('references missing')) {
     pushUnique(guidance, 'Refresh current ids with getSystemArchitecture semantic query first, then call getIntentElementContext for any returned element that needs dependency context. Do not guess ids; use existing element, relationship, and view ids or create missing objects first.');
@@ -3086,13 +3132,25 @@ async function queryNeo4jGraphTool(args = {}) {
 function queryNeo4jGraphSchemaResult(architecturePath, workspaceRoot) {
   const schema = buildNeo4jGraphSchema(architecturePath);
   let typeEnums = {};
+  let schemaBundleInfo = {};
   try {
     const resolvedRoot = workspaceRoot || resolveWorkspaceRoot({ architecturePath });
-    const schemaPath = resolveSchemaPath(resolvedRoot);
-    const jsonSchema = readJson(schemaPath.absolutePath, schemaPath.relativePath);
+    const { bundle, ontology } = loadSchemaBundleAndOntology(resolvedRoot);
+    const enums = resolveTypeEnums(bundle);
     typeEnums = {
-      archimateElementTypes: (jsonSchema.$defs.archimateElementType || {}).enum || [],
-      archimateRelationshipTypes: (jsonSchema.$defs.archimateRelationshipType || {}).enum || [],
+      archimateElementTypes: enums.elementTypes,
+      archimateRelationshipTypes: enums.relationshipTypes,
+      schemaLanguage: (bundle.config && bundle.config.language) || null,
+      schemaKind: bundle.kind,
+      schemaDialect: ontology.dialect,
+      actorElementType: ontology.actorElementType,
+      bundleValidation: ontology.bundleValidation,
+    };
+    schemaBundleInfo = {
+      schemaPath: bundle.schema.relativePath,
+      schemaKind: bundle.kind,
+      schemaDir: bundle.relativeDir,
+      guidePath: bundle.guidePath ? bundle.guidePath.relativePath : null,
     };
   } catch (error) {
     typeEnums = {
@@ -3109,6 +3167,7 @@ function queryNeo4jGraphSchemaResult(architecturePath, workspaceRoot) {
     schema: {
       ...schema,
       ...typeEnums,
+      ...schemaBundleInfo,
     },
     usage: {
       scopeGraph: 'MATCH (e:Element {graphKey: $graphKey}) ...',