archgraph-argo 0.27.0 → 0.28.0

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

@@ -130,12 +130,13 @@ const {
   validateGraphSemantics,
   validateArchiMateEndpointMatrix,
   validateViewElementLimits,
+  validateAttributeContracts,
 } = require('./graph-semantics.js');
 const {
   loadSchemaBundleAndOntology,
   resolveSchemaBundle,
   resolveTypeEnums,
-} = require('./argob-schema.js');
+} = require('./schema-bundle.js');
 const {
   createProductionGraphRagRuntime,
 } = require('./graph-rag/productionGraphRagRuntime.js');
@@ -226,12 +227,12 @@ const TOOLS = [
   },
   {
     name: 'getIntentElementContext',
-    description: 'read-only query that returns an intent subgraph context for one element. Uses ArchiMate semantic dependency traversal with dependencyDepth and dependentDepth, preserving native subgraph elements, relationships, and views.',
+    description: 'read-only query that returns an intent subgraph context for one element. Uses ArchiMate semantic dependency traversal with dependencyDepth and dependentDepth, preserving native subgraph elements, relationships, and views. Output is bounded by maxBytes (default ARGO_CONTEXT_MAX_BYTES or 32000): beyond it non-focus members degrade to identity (id/type/name) and a complete id manifest is returned under truncation, so the host never silently cuts the payload. On a large/hub element leave includeAttributes/includeTestcases off (they are the ledger and can dominate the size) and prefer queryNeo4jGraph to locate ids, then read them narrowly.',
     inputSchema: intentElementContextInputSchema(),
   },
   {
     name: 'getArchitectureViewContext',
-    description: 'read-only query that resolves one view by view_id into its complete membership: the view object, every member element (from included_elements), every member relationship (from included_relationships), the parent element, and optionally child sub-views declared by member elements. Resolves ids into full canonical objects instead of returning raw id lists. Optional includeEaGeometry (default false) additionally returns the EA diagram geometry of the resolved view: element boxes plus each connector ROUTE (t_diagramlinks.Path as `path` + parsed `points`, with the non-route Geometry override kept separately under `geometry`).',
+    description: 'read-only query that resolves one view by view_id into its complete membership: the view object, every member element (from included_elements), every member relationship (from included_relationships), the parent element, and optionally child sub-views declared by member elements. Resolves ids into full canonical objects instead of returning raw id lists. Output is bounded by maxBytes (default ARGO_CONTEXT_MAX_BYTES or 32000): beyond it members degrade to identity (id/type/name) with a complete id manifest under truncation. Optional includeEaGeometry (default false) additionally returns the EA diagram geometry of the resolved view: element boxes plus each connector ROUTE (t_diagramlinks.Path as `path` + parsed `points`, with the non-route Geometry override kept separately under `geometry`).',
     inputSchema: viewContextInputSchema(),
   },
   {
@@ -246,12 +247,18 @@ const TOOLS = [
   },
   {
     name: 'addArchitectureElement',
-    description: 'Use for one element. Creates a new element or adds an existing element to view_ids. view_ids is required so elements never exist outside views. Set dryRun to preview without writing.',
+    description: 'Use for one element. Creates a new element or adds an existing element to view_ids. view_ids is required so elements never exist outside views. element.id is OPTIONAL: omit it and the server auto-allocates a unique id (returned in the result); provide it to pin a specific id (must not collide with a different element). Set dryRun to preview without writing.',
     inputSchema: {
       type: 'object',
       required: ['element', 'view_ids'],
       properties: {
-        element: { type: 'object' },
+        element: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Element id (OPTIONAL). Omit to let the server auto-allocate a unique id (a semantic slug from the name, e.g. "graph-wiki-federation-center", suffixed -002.. if taken). If provided it must not collide with a DIFFERENT element (a same (type,name) match is idempotent reuse).' },
+          },
+          description: 'The element to create/attach. `id` is optional — omit it and the server allocates one (returned in the result).',
+        },
         view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
         onConflict: { type: 'string', enum: ['reuse', 'allowDuplicate'], description: 'Dedup policy (default reuse). reuse: find-or-create — attach an existing exact (type, name) match; a same-type semantic near-duplicate also blocks creation. allowDuplicate: create anyway (even if a duplicate exists), requires a justification.' },
         justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
@@ -293,7 +300,7 @@ const TOOLS = [
   },
   {
     name: 'addArchitectureRelationship',
-    description: 'Use for one relationship. Creates a new relationship or adds an existing relationship to view_ids. relationship.type is the ArchiMate 3.2 relationship type and is validated against endpoint element types. Set dryRun to preview without writing.',
+    description: 'Use for one relationship. Creates a new relationship or adds an existing relationship to view_ids. relationship.type is the ArchiMate 3.2 relationship type and is validated against endpoint element types. relationship.id is OPTIONAL: omit it and the server auto-allocates a unique id (returned in the result). Set dryRun to preview without writing.',
     inputSchema: {
       type: 'object',
       required: ['relationship', 'view_ids'],
@@ -340,7 +347,7 @@ const TOOLS = [
   },
   {
     name: 'addArchitectureView',
-    description: 'Use for one view. The graph must have exactly one top-level view named SystemArchitecture; all sub-views must attach to an element with parent_element_id. Set dryRun to preview without writing.',
+    description: 'Use for one view. The graph must have exactly one top-level view named SystemArchitecture; all sub-views must attach to an element with parent_element_id. view.view_id is OPTIONAL: omit it and the server auto-allocates a unique view_id (returned in the result). Set dryRun to preview without writing.',
     inputSchema: {
       type: 'object',
       required: ['view'],
@@ -476,8 +483,9 @@ function intentElementContextInputSchema() {
       dependentDepth: { type: 'number', description: 'Default: 1. Semantic dependents that rely on the focus element.' },
       associationDepth: { type: 'number', description: 'Default: 1. Association neighbors are expanded at least one layer.' },
       associationNeighborDependencyDepth: { type: 'number', description: 'Default: 0. Optional dependency expansion from association neighbors.' },
-      includeAttributes: { type: 'boolean', description: 'Default: false. Include `attributes` (commit/session/release ledgers) verbatim. Omitted by default from this structural read; the focus element always keeps its own. Semantic retrieval embeds attributes, so semantic hits keep them.' },
-      includeTestcases: { type: 'boolean', description: 'Default: false. Include member `testcases` verbatim. Omitted by default from this structural read (bookkeeping); pass true when you need acceptance cases. Semantic retrieval embeds testcase descriptions, so semantic hits keep them.' },
+      includeAttributes: { type: 'boolean', description: 'Default: false. Include `attributes` (commit/session/release ledgers) verbatim. Omitted by default from this structural read; the focus element always keeps its own. Semantic retrieval embeds attributes, so semantic hits keep them. On a hub element this ledger can dominate the payload — prefer leaving it off and reading bookkeeping narrowly.' },
+      includeTestcases: { type: 'boolean', description: 'Default: false. Include member `testcases` verbatim. Omitted by default from this structural read (bookkeeping); pass true when you need acceptance cases. Semantic retrieval embeds testcase descriptions, so semantic hits keep them. On a hub element this can be large — prefer leaving it off.' },
+      maxBytes: { type: 'number', description: 'Optional output budget in UTF-8 bytes (the exact serialized response). Default: ARGO_CONTEXT_MAX_BYTES env or 32000. 0 = unlimited. When the payload exceeds the budget, non-focus members degrade to identity (id/type/name) and a complete id manifest is returned under `truncation` — the payload is never silently truncated by the host.' },
     },
     additionalProperties: false,
   };
@@ -495,6 +503,7 @@ function viewContextInputSchema() {
       includeAttributes: { type: 'boolean', description: 'Default: false. Include member/relationship `attributes` (commit/session/release ledgers) verbatim. Omitted by default from this structural read (bookkeeping); pass true when you need provenance.' },
       includeTestcases: { type: 'boolean', description: 'Default: false. Include member `testcases` verbatim. Omitted by default from this structural read; pass true for acceptance-case lookups.' },
       includeEaGeometry: { type: 'boolean', description: 'Default: false (opt-in). When true, additionally resolve the diagram GEOMETRY (element boxes + connector line routes) for this view from the workspace EA model (.qea) and return it under a `geometry` field aligned by schema id with the resolved members. Each geometry relationship carries: `path` (the EA route from t_diagramlinks.Path, "" when EA auto-routes), `points` (the parsed [{x,y}] waypoints), `edge` (the EDGE route-style token or null) and `geometry` (the raw SX/SY/EX/EY override string, which contains NO waypoints). By default the EA model is never touched and no `geometry` field is returned; a missing EA model/diagram yields geometry.present=false, never an error.' },
+      maxBytes: { type: 'number', description: 'Optional output budget in UTF-8 bytes (the exact serialized response). Default: ARGO_CONTEXT_MAX_BYTES env or 32000. 0 = unlimited. When the payload exceeds the budget, members degrade to identity (id/type/name) and a complete id manifest is returned under `truncation` — the payload is never silently truncated by the host.' },
     },
     additionalProperties: false,
   };
@@ -616,6 +625,7 @@ function validateDocument(document, schema, options = {}) {
   }
   validateAgainstSchema(document, schema, '#', errors, schema);
   validateGraphSemantics(document, errors, ontology);
+  validateAttributeContracts(document, errors, ontology);
   validateArchiMateEndpointMatrix(document, errors, {
     ontology,
     touchedRelationshipIds: options.touchedRelationshipIds,
@@ -678,6 +688,233 @@ function buildAgentProjection(omitted) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Context output budget (bounded, well-formed structural reads)
+// ---------------------------------------------------------------------------
+// A hub element/view can expand a semantic subgraph to tens of KB, which the
+// HOST then cuts mid-JSON — the agent receives a malformed partial observation.
+// This budget makes the ceiling the framework's, not the host's: above maxBytes
+// the non-focus members degrade to identity (id/type/name), the focus element +
+// boundary/explorationHints are kept, and EVERY included id is listed under
+// `truncation` — so the payload is always valid JSON and always navigable.
+// Default (or ARGO_CONTEXT_MAX_BYTES); 0 = unlimited. Semantic retrieval is NOT
+// affected (only these two structural builders).
+const DEFAULT_CONTEXT_MAX_BYTES = 32000;
+const CONTEXT_BUDGET_NOTE =
+  'The full payload exceeded maxBytes, so non-focus members are reduced to identity '
+  + '(id/type/name). The focus element and boundary/explorationHints are kept and every '
+  + 'included id is listed here. Raise maxBytes (0 = unlimited) or narrow the traversal '
+  + '(dependencyDepth/dependentDepth) to read details.';
+
+function resolveContextMaxBytes(args = {}) {
+  const raw = args && args.maxBytes !== undefined ? args.maxBytes : process.env.ARGO_CONTEXT_MAX_BYTES;
+  if (raw === undefined || raw === null || raw === '') {
+    return DEFAULT_CONTEXT_MAX_BYTES;
+  }
+  const numeric = Number(raw);
+  if (!Number.isFinite(numeric) || numeric < 0) {
+    return DEFAULT_CONTEXT_MAX_BYTES;
+  }
+  return Math.floor(numeric);
+}
+
+// Budget is measured on the EXACT serialization the caller receives
+// (`toolResult` pretty-prints with 2 spaces), in UTF-8 bytes.
+function payloadByteLength(value) {
+  try { return Buffer.byteLength(JSON.stringify(value, null, 2)); } catch (_) { return 0; }
+}
+
+function identityElementRecord(element) {
+  return { id: element.id, name: element.name, type: element.type };
+}
+
+function identityRelationshipRecord(relationship) {
+  return {
+    id: relationship.id,
+    name: relationship.name,
+    type: relationship.type,
+    source_id: relationship.source_id,
+    target_id: relationship.target_id,
+  };
+}
+
+function identityViewRecord(view) {
+  return { view_id: view.view_id, view_name: view.view_name };
+}
+
+function budgetTruncationBase(result, maxBytes, fullBytes, ids) {
+  return {
+    truncated: true,
+    reason: 'context_budget_exceeded',
+    maxBytes,
+    fullBytes,
+    includedElementIds: ids.elements,
+    includedRelationshipIds: ids.relationships,
+    includedViewIds: ids.views,
+    note: CONTEXT_BUDGET_NOTE,
+  };
+}
+
+// Shrink the manifest id lists (last resort) so even a pathological hub stays
+// within budget. The focus id is never dropped; `manifestTruncated` records any
+// real loss of a listed id.
+function trimManifestToBudget(result, maxBytes) {
+  const truncation = result.truncation;
+  const focusId = result.focusElementId;
+  // If the FOCUS element alone already exceeds the budget, trimming the (cheap)
+  // id manifest cannot get us under it — and dropping ids would only lose
+  // navigation for nothing. Keep the COMPLETE manifest and say why.
+  const focusOnly = {
+    ...result,
+    truncation: {
+      ...truncation,
+      includedElementIds: focusId ? [focusId] : [],
+      includedRelationshipIds: [],
+      includedViewIds: [],
+    },
+  };
+  if (focusId && payloadByteLength(focusOnly) > maxBytes) {
+    truncation.overBudgetByFocus = true;
+    return;
+  }
+  const arrays = ['includedElementIds', 'includedRelationshipIds', 'includedViewIds'];
+  for (let ratio = 0.9; ratio >= 0; ratio -= 0.1) {
+    for (const key of arrays) {
+      const full = truncation[key] || [];
+      const kept = full.slice(0, Math.ceil(full.length * ratio));
+      if (key === 'includedElementIds' && focusId && !kept.includes(focusId)) {
+        kept.unshift(focusId);
+      }
+      truncation[key] = kept;
+    }
+    truncation.manifestTruncated = true;
+    if (payloadByteLength(result) <= maxBytes) return;
+  }
+  truncation.manifestTruncated = true;
+}
+
+function applyContextBudget(result, maxBytes) {
+  if (!result || result.status !== 'passed' || !maxBytes || maxBytes <= 0) {
+    return result;
+  }
+  const fullBytes = payloadByteLength(result);
+  if (fullBytes <= maxBytes) {
+    return result;
+  }
+
+  const subgraph = result.subgraph || {};
+  const elements = Array.isArray(subgraph.elements) ? subgraph.elements : [];
+  const relationships = Array.isArray(subgraph.relationships) ? subgraph.relationships : [];
+  const views = Array.isArray(subgraph.views) ? subgraph.views : [];
+  const focusId = result.focusElementId;
+  const ids = {
+    elements: elements.map((entry) => entry.id),
+    relationships: relationships.map((entry) => entry.id),
+    views: views.map((entry) => entry.view_id),
+  };
+  const truncated = (tier) => budgetTruncationBase(result, maxBytes, fullBytes, ids);
+  const nonFocusCount = elements.filter((entry) => entry.id !== focusId).length;
+
+  const compact = {
+    ...result,
+    subgraph: {
+      ...subgraph,
+      elements: elements.map((entry) => (entry.id === focusId ? entry : identityElementRecord(entry))),
+      relationships: relationships.map(identityRelationshipRecord),
+      views: views.map(identityViewRecord),
+    },
+    truncation: { ...truncated('identity'), omittedElementDetails: nonFocusCount },
+  };
+  if (payloadByteLength(compact) <= maxBytes) {
+    return compact;
+  }
+
+  const idsOnly = {
+    ...result,
+    subgraph: {
+      ...subgraph,
+      elements: elements.map((entry) => (entry.id === focusId ? entry : { id: entry.id })),
+      relationships: relationships.map((entry) => ({ id: entry.id })),
+      views: views.map((entry) => ({ view_id: entry.view_id })),
+    },
+    truncation: truncated('ids-only'),
+  };
+  if (payloadByteLength(idsOnly) <= maxBytes) {
+    return idsOnly;
+  }
+
+  const manifestOnly = {
+    ...result,
+    subgraph: {
+      elements: elements.filter((entry) => entry.id === focusId),
+      relationships: [],
+      views: [],
+    },
+    truncation: truncated('manifest-only'),
+  };
+  trimManifestToBudget(manifestOnly, maxBytes);
+  return manifestOnly;
+}
+
+function applyViewContextBudget(result, maxBytes) {
+  if (!result || result.status !== 'passed' || !maxBytes || maxBytes <= 0) {
+    return result;
+  }
+  const fullBytes = payloadByteLength(result);
+  if (fullBytes <= maxBytes) {
+    return result;
+  }
+
+  const elements = Array.isArray(result.elements) ? result.elements : [];
+  const relationships = Array.isArray(result.relationships) ? result.relationships : [];
+  const childViews = Array.isArray(result.childViews) ? result.childViews : [];
+  const ids = {
+    elements: elements.map((entry) => entry.id),
+    relationships: relationships.map((entry) => entry.id),
+    views: childViews.map((entry) => entry.view_id),
+  };
+  const strippedView = result.view
+    ? { ...result.view, included_elements: [], included_relationships: [] }
+    : result.view;
+  const truncated = (tier) => ({ ...budgetTruncationBase(result, maxBytes, fullBytes, ids), tier });
+
+  const compact = {
+    ...result,
+    elements: elements.map(identityElementRecord),
+    relationships: relationships.map(identityRelationshipRecord),
+    parentElement: result.parentElement ? identityElementRecord(result.parentElement) : result.parentElement,
+    childViews: childViews.map(identityViewRecord),
+    truncation: { ...truncated('identity'), omittedElementDetails: elements.length },
+  };
+  if (payloadByteLength(compact) <= maxBytes) {
+    return compact;
+  }
+
+  const idsOnly = {
+    ...result,
+    elements: elements.map((entry) => ({ id: entry.id })),
+    relationships: relationships.map((entry) => ({ id: entry.id })),
+    parentElement: result.parentElement ? { id: result.parentElement.id } : result.parentElement,
+    childViews: childViews.map((entry) => ({ view_id: entry.view_id })),
+    truncation: truncated('ids-only'),
+  };
+  if (payloadByteLength(idsOnly) <= maxBytes) {
+    return idsOnly;
+  }
+
+  const manifestOnly = {
+    ...result,
+    view: strippedView,
+    elements: [],
+    relationships: [],
+    parentElement: null,
+    childViews: [],
+    truncation: truncated('manifest-only'),
+  };
+  trimManifestToBudget(manifestOnly, maxBytes);
+  return manifestOnly;
+}
+
 function buildIntentElementContext(context, args = {}) {
   const profile = args.profile || 'generic-agent';
   const focusResult = resolveFocusElement(context.document, args);
@@ -804,7 +1041,7 @@ function buildIntentElementContext(context, args = {}) {
   };
   const projection = buildAgentProjection(omitted);
   if (projection) result.projection = projection;
-  return result;
+  return applyContextBudget(result, resolveContextMaxBytes(args));
 }
 
 // ---------------------------------------------------------------------------
@@ -948,7 +1185,7 @@ function buildViewContext(context, args = {}) {
   }
   const projection = buildAgentProjection(omitted);
   if (projection) result.projection = projection;
-  return result;
+  return applyViewContextBudget(result, resolveContextMaxBytes(args));
 }
 
 function resolveFocusElement(document, args) {
@@ -1017,7 +1254,7 @@ function buildGraphIndex(document, ontology) {
 }
 
 // Dependency direction for the semantic-edge walk comes from the active schema
-// bundle's deliveryDependencies; this is the ArgoBument fallback by default.
+// bundle's deliveryDependencies; this is the ArchiMate 3.2 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']),
@@ -1389,6 +1626,207 @@ function resolveDuplicateConflict(options, candidates) {
   return { action: 'create', justification: options.justification };
 }
 
+function mutationNodeId(mutation) {
+  if (!mutation || typeof mutation !== 'object') {
+    return '(invalid)';
+  }
+  if (mutation.type === 'addElement') {
+    return (mutation.element && mutation.element.id) || '(addElement)';
+  }
+  if (mutation.type === 'addRelationship') {
+    return (mutation.relationship && mutation.relationship.id) || '(addRelationship)';
+  }
+  if (mutation.type === 'addView') {
+    return (mutation.view && mutation.view.view_id) || '(addView)';
+  }
+  if (mutation.type === 'updateView') {
+    return mutation.view_id || mutation.id || '(updateView)';
+  }
+  return mutation.id || mutation.view_id || `(${mutation.type})`;
+}
+
+// Order a batch so it is order-independent: a mutation that references an object
+// created later in the SAME batch is applied after its producer. Dependencies:
+//   addElement     -> views it joins (view_ids)
+//   addRelationship-> views it joins + its source/target elements
+//   addView        -> its parent element + included elements/relationships
+//   update*/remove*-> the object they target (when that object is produced here)
+// A genuine cycle is reported with the id chain so the caller can split the batch.
+function orderMutationsForApplication(mutations) {
+  const n = mutations.length;
+  const producers = new Map();
+  const addProducer = (key, index) => {
+    if (!key) {
+      return;
+    }
+    if (!producers.has(key)) {
+      producers.set(key, []);
+    }
+    producers.get(key).push(index);
+  };
+
+  mutations.forEach((mutation, index) => {
+    if (!mutation || typeof mutation !== 'object') {
+      return;
+    }
+    if (mutation.type === 'addElement' && mutation.element) {
+      addProducer('element:' + mutation.element.id, index);
+    }
+    if (mutation.type === 'addRelationship' && mutation.relationship) {
+      addProducer('relationship:' + mutation.relationship.id, index);
+    }
+    if (mutation.type === 'addView' && mutation.view) {
+      addProducer('view:' + mutation.view.view_id, index);
+    }
+  });
+
+  const dependencies = mutations.map(() => new Set());
+  mutations.forEach((mutation, index) => {
+    if (!mutation || typeof mutation !== 'object') {
+      return;
+    }
+    const requireKey = (key) => {
+      const matches = producers.get(key);
+      if (!matches) {
+        return;
+      }
+      for (const producerIndex of matches) {
+        if (producerIndex !== index) {
+          dependencies[index].add(producerIndex);
+        }
+      }
+    };
+
+    if (mutation.type === 'addElement') {
+      for (const viewId of Array.isArray(mutation.view_ids) ? mutation.view_ids : []) {
+        requireKey('view:' + viewId);
+      }
+    } else if (mutation.type === 'addRelationship') {
+      for (const viewId of Array.isArray(mutation.view_ids) ? mutation.view_ids : []) {
+        requireKey('view:' + viewId);
+      }
+      if (mutation.relationship) {
+        requireKey('element:' + mutation.relationship.source_id);
+        requireKey('element:' + mutation.relationship.target_id);
+      }
+    } else if (mutation.type === 'addView') {
+      if (mutation.view) {
+        requireKey('element:' + mutation.view.parent_element_id);
+        for (const elementId of Array.isArray(mutation.view.included_elements) ? mutation.view.included_elements : []) {
+          requireKey('element:' + elementId);
+        }
+        for (const relationshipId of Array.isArray(mutation.view.included_relationships) ? mutation.view.included_relationships : []) {
+          requireKey('relationship:' + relationshipId);
+        }
+      }
+    } else if (mutation.type === 'updateElement') {
+      requireKey('element:' + mutation.id);
+    } else if (mutation.type === 'updateRelationship') {
+      requireKey('relationship:' + mutation.id);
+    } else if (mutation.type === 'updateView') {
+      requireKey('view:' + (mutation.view_id || mutation.id));
+    } else if (mutation.type === 'removeView') {
+      requireKey('view:' + mutation.view_id);
+    } else if (mutation.type === 'removeElement') {
+      requireKey('element:' + mutation.id);
+    } else if (mutation.type === 'removeRelationship') {
+      requireKey('relationship:' + mutation.id);
+    }
+  });
+
+  const indegree = mutations.map((_, index) => dependencies[index].size);
+  const dependents = mutations.map(() => []);
+  dependencies.forEach((set, index) => {
+    for (const dependency of set) {
+      dependents[dependency].push(index);
+    }
+  });
+
+  const remaining = new Set();
+  for (let index = 0; index < n; index += 1) {
+    remaining.add(index);
+  }
+  const ready = [];
+  for (let index = 0; index < n; index += 1) {
+    if (indegree[index] === 0) {
+      ready.push(index);
+    }
+  }
+  ready.sort((a, b) => a - b);
+
+  const ordered = [];
+  while (ready.length > 0) {
+    const index = ready.shift();
+    if (!remaining.has(index)) {
+      continue;
+    }
+    remaining.delete(index);
+    ordered.push(mutations[index]);
+    for (const dependent of dependents[index]) {
+      indegree[dependent] -= 1;
+      if (indegree[dependent] === 0) {
+        ready.push(dependent);
+      }
+    }
+    ready.sort((a, b) => a - b);
+  }
+
+  if (ordered.length !== n) {
+    const chain = findMutationCycle(mutations, dependencies, remaining);
+    throw new Error(
+      `Cyclic mutation dependencies in batch: ${chain.join(' -> ')}. `
+      + 'Order the batch so each referenced object is created first, or split the mutually-dependent objects into separate calls.',
+    );
+  }
+
+  return ordered;
+}
+
+function findMutationCycle(mutations, dependencies, remaining) {
+  const visited = new Set();
+  const inStack = new Set();
+  const stack = [];
+  let cycle = null;
+
+  const visit = (index) => {
+    if (cycle) {
+      return;
+    }
+    visited.add(index);
+    inStack.add(index);
+    stack.push(index);
+    for (const dependency of dependencies[index]) {
+      if (!remaining.has(dependency)) {
+        continue;
+      }
+      if (inStack.has(dependency)) {
+        cycle = stack.slice(stack.indexOf(dependency)).concat(dependency);
+        return;
+      }
+      if (!visited.has(dependency)) {
+        visit(dependency);
+      }
+      if (cycle) {
+        return;
+      }
+    }
+    inStack.delete(index);
+    stack.pop();
+  };
+
+  for (const index of remaining) {
+    if (!visited.has(index)) {
+      visit(index);
+    }
+    if (cycle) {
+      break;
+    }
+  }
+
+  const chain = cycle || [...remaining];
+  return chain.map((index) => mutationNodeId(mutations[index]));
+}
+
 function applyMutations(document, mutations, options = {}) {
   const nextDocument = clone(document);
   const touchedElementIds = new Set();
@@ -1401,7 +1839,11 @@ function applyMutations(document, mutations, options = {}) {
     throw new Error('mutations must contain at least one mutation');
   }
 
-  for (const mutation of mutations) {
+  // Apply in dependency order so a batch is order-independent (see
+  // orderMutationsForApplication); a genuine cycle throws with the id chain.
+  const orderedMutations = orderMutationsForApplication(mutations);
+
+  for (const mutation of orderedMutations) {
     if (!mutation || typeof mutation !== 'object' || !HANDLED_MUTATION_TYPES.has(mutation.type)) {
       throw new Error(`Unsupported mutation type: ${mutation && mutation.type}`);
     }
@@ -1409,11 +1851,30 @@ function applyMutations(document, mutations, options = {}) {
     if (mutation.type === 'addElement') {
       requireObject(mutation.element, 'mutation.element');
       const scopedViews = requireViewScope(nextDocument.views, mutation.view_ids, 'mutation.view_ids');
-      requireId(mutation.element.id, 'mutation.element.id');
-      const existingElement = findById(nextDocument.elements, mutation.element.id);
-      let targetElementId = mutation.element.id;
-      let reusedElement = false;
-      if (!existingElement) {
+      const requestedElementId = typeof mutation.element.id === 'string' && mutation.element.id !== ''
+        ? mutation.element.id
+        : null;
+      let targetElementId;
+      let elementCreated = false;
+      let elementReused = false;
+
+      const existingById = requestedElementId ? findById(nextDocument.elements, requestedElementId) : undefined;
+      if (existingById) {
+        // An explicit id that already exists: idempotent ONLY if it is the same
+        // (type,name). Otherwise the caller picked a taken id — fail loudly instead
+        // of silently attaching an unrelated element (issue #8 collision safety).
+        const sameIdentity = existingById.type === mutation.element.type
+          && normalizeDedupName(existingById.name) === normalizeDedupName(mutation.element.name);
+        if (!sameIdentity) {
+          throw new Error(
+            `addElement id '${requestedElementId}' is already used by a different element `
+            + `(type '${existingById.type}', name '${existingById.name}'). Choose another id (or omit id to auto-allocate one), `
+            + `attach the existing element by using its id, or update it with updateArchitectureElement.`,
+          );
+        }
+        targetElementId = requestedElementId;
+        elementReused = true;
+      } else {
         const candidates = findDuplicateElements(nextDocument.elements, mutation.element);
         const resolution = resolveDuplicateConflict({
           onConflict: mutation.onConflict,
@@ -1422,12 +1883,19 @@ function applyMutations(document, mutations, options = {}) {
         }, candidates);
         if (resolution.action === 'reuse') {
           targetElementId = resolution.existing.id;
-          reusedElement = true;
+          elementReused = true;
         } else {
-          nextDocument.elements.push(clone(mutation.element));
-          syncViewsToElementSubdiagramViews(nextDocument, findById(nextDocument.elements, mutation.element.id));
+          targetElementId = requestedElementId || allocateUniqueId(
+            nextDocument.elements.map(entry => entry.id),
+            mutation.element.name,
+            slugifyId(mutation.element.type) || 'element',
+          );
+          nextDocument.elements.push({ ...clone(mutation.element), id: targetElementId });
+          syncViewsToElementSubdiagramViews(nextDocument, findById(nextDocument.elements, targetElementId));
+          elementCreated = true;
         }
       }
+
       for (const view of scopedViews) {
         view.included_elements = addUnique(view.included_elements || [], [targetElementId]);
         touchedViewIds.add(view.view_id);
@@ -1438,8 +1906,10 @@ function applyMutations(document, mutations, options = {}) {
         type: mutation.type,
         id: targetElementId,
         view_ids: mutation.view_ids,
-        created: !existingElement && !reusedElement,
-        ...(reusedElement ? { reused: true, reusedId: targetElementId, requestedId: mutation.element.id } : {}),
+        created: elementCreated,
+        ...(elementReused ? { reused: true, reusedId: targetElementId } : {}),
+        ...(requestedElementId === null && elementCreated ? { allocatedId: targetElementId } : {}),
+        ...(elementReused && requestedElementId && requestedElementId !== targetElementId ? { requestedId: requestedElementId } : {}),
       });
       continue;
     }
@@ -1538,13 +2008,35 @@ function applyMutations(document, mutations, options = {}) {
     if (mutation.type === 'addRelationship') {
       requireObject(mutation.relationship, 'mutation.relationship');
       const scopedViews = requireViewScope(nextDocument.views, mutation.view_ids, 'mutation.view_ids');
-      requireId(mutation.relationship.id, 'mutation.relationship.id');
-      const existingRelationship = findById(nextDocument.relationships, mutation.relationship.id);
-      let targetRelationshipId = mutation.relationship.id;
+      const requestedRelationshipId = typeof mutation.relationship.id === 'string' && mutation.relationship.id !== ''
+        ? mutation.relationship.id
+        : null;
+      let targetRelationshipId;
       let sourceElementId = mutation.relationship.source_id;
       let targetEndpointId = mutation.relationship.target_id;
-      let reusedRelationship = false;
-      if (!existingRelationship) {
+      let relationshipCreated = false;
+      let relationshipReused = false;
+
+      const existingById = requestedRelationshipId ? findById(nextDocument.relationships, requestedRelationshipId) : undefined;
+      if (existingById) {
+        // Explicit id that already exists: idempotent only for the same natural key;
+        // otherwise fail loudly instead of silently attaching an unrelated edge.
+        const sameIdentity = existingById.source_id === mutation.relationship.source_id
+          && existingById.type === mutation.relationship.type
+          && existingById.target_id === mutation.relationship.target_id
+          && normalizeDedupName(existingById.name) === normalizeDedupName(mutation.relationship.name);
+        if (!sameIdentity) {
+          throw new Error(
+            `addRelationship id '${requestedRelationshipId}' is already used by a different relationship `
+            + `(source '${existingById.source_id}', type '${existingById.type}', target '${existingById.target_id}'). `
+            + 'Choose another id (or omit id to auto-allocate one), or update it with updateArchitectureRelationship.',
+          );
+        }
+        targetRelationshipId = requestedRelationshipId;
+        sourceElementId = existingById.source_id;
+        targetEndpointId = existingById.target_id;
+        relationshipReused = true;
+      } else {
         const candidates = findDuplicateRelationships(nextDocument.relationships, mutation.relationship);
         const resolution = resolveDuplicateConflict({
           onConflict: mutation.onConflict,
@@ -1555,9 +2047,15 @@ function applyMutations(document, mutations, options = {}) {
           targetRelationshipId = resolution.existing.id;
           sourceElementId = resolution.existing.source_id;
           targetEndpointId = resolution.existing.target_id;
-          reusedRelationship = true;
+          relationshipReused = true;
         } else {
-          nextDocument.relationships.push(clone(mutation.relationship));
+          targetRelationshipId = requestedRelationshipId || allocateUniqueId(
+            nextDocument.relationships.map(entry => entry.id),
+            mutation.relationship.name || `${mutation.relationship.source_id}-${mutation.relationship.type}-${mutation.relationship.target_id}`,
+            'relationship',
+          );
+          nextDocument.relationships.push({ ...clone(mutation.relationship), id: targetRelationshipId });
+          relationshipCreated = true;
         }
       }
       for (const view of scopedViews) {
@@ -1573,8 +2071,9 @@ function applyMutations(document, mutations, options = {}) {
         type: mutation.type,
         id: targetRelationshipId,
         view_ids: mutation.view_ids,
-        created: !existingRelationship && !reusedRelationship,
-        ...(reusedRelationship ? { reused: true, reusedId: targetRelationshipId, requestedId: mutation.relationship.id } : {}),
+        created: relationshipCreated,
+        ...(relationshipReused ? { reused: true, reusedId: targetRelationshipId } : {}),
+        ...(requestedRelationshipId === null && relationshipCreated ? { allocatedId: targetRelationshipId } : {}),
       });
       continue;
     }
@@ -1658,38 +2157,65 @@ function applyMutations(document, mutations, options = {}) {
 
     if (mutation.type === 'addView') {
       requireObject(mutation.view, 'mutation.view');
-      if (findView(nextDocument.views, mutation.view.view_id)) {
-        throw new Error(`View '${mutation.view.view_id}' already exists`);
-      }
-      const candidates = findDuplicateViews(nextDocument.views, mutation.view);
-      const resolution = resolveDuplicateConflict({
-        onConflict: mutation.onConflict,
-        justification: mutation.justification,
-        label: `view (name '${mutation.view.view_name}')`,
-      }, candidates);
-      if (resolution.action === 'reuse') {
-        mutationSummaries.push({
-          type: mutation.type,
-          id: resolution.existing.view_id,
-          created: false,
-          reused: true,
-          reusedId: resolution.existing.view_id,
-          requestedId: mutation.view.view_id,
-        });
-      } else {
-        const newView = clone(mutation.view);
-        if (Array.isArray(newView.included_elements)) {
-          newView.included_elements = addUnique([], newView.included_elements);
+      const requestedViewId = typeof mutation.view.view_id === 'string' && mutation.view.view_id !== ''
+        ? mutation.view.view_id
+        : null;
+      let targetViewId;
+      let viewCreated = false;
+      let viewReused = false;
+
+      const existingById = requestedViewId ? findView(nextDocument.views, requestedViewId) : undefined;
+      if (existingById) {
+        // Explicit view_id that already exists: idempotent only for the same
+        // (parent,name); otherwise fail loudly.
+        const sameIdentity = (existingById.parent_element_id || '') === (mutation.view.parent_element_id || '')
+          && normalizeDedupName(existingById.view_name) === normalizeDedupName(mutation.view.view_name);
+        if (!sameIdentity) {
+          throw new Error(
+            `addView view_id '${requestedViewId}' is already used by a different view `
+            + `(name '${existingById.view_name}', parent '${existingById.parent_element_id || ''}'). `
+            + 'Choose another view_id (or omit it to auto-allocate one), or update it with updateArchitectureView.',
+          );
         }
-        if (Array.isArray(newView.included_relationships)) {
-          newView.included_relationships = addUnique([], newView.included_relationships);
+        targetViewId = requestedViewId;
+        viewReused = true;
+      } else {
+        const candidates = findDuplicateViews(nextDocument.views, mutation.view);
+        const resolution = resolveDuplicateConflict({
+          onConflict: mutation.onConflict,
+          justification: mutation.justification,
+          label: `view (name '${mutation.view.view_name}')`,
+        }, candidates);
+        if (resolution.action === 'reuse') {
+          targetViewId = resolution.existing.view_id;
+          viewReused = true;
+        } else {
+          targetViewId = requestedViewId || allocateUniqueId(
+            nextDocument.views.map(entry => entry.view_id),
+            mutation.view.view_name,
+            'view',
+          );
+          const newView = { ...clone(mutation.view), view_id: targetViewId };
+          if (Array.isArray(newView.included_elements)) {
+            newView.included_elements = addUnique([], newView.included_elements);
+          }
+          if (Array.isArray(newView.included_relationships)) {
+            newView.included_relationships = addUnique([], newView.included_relationships);
+          }
+          nextDocument.views.push(newView);
+          upsertSubdiagramViewIntoElement(nextDocument, newView.parent_element_id, newView);
+          touchedViewIds.add(newView.view_id);
+          viewLimitCheckIds.add(newView.view_id);
+          viewCreated = true;
         }
-        nextDocument.views.push(newView);
-        upsertSubdiagramViewIntoElement(nextDocument, newView.parent_element_id, newView);
-        touchedViewIds.add(newView.view_id);
-        viewLimitCheckIds.add(newView.view_id);
-        mutationSummaries.push({ type: mutation.type, id: newView.view_id });
       }
+      mutationSummaries.push({
+        type: mutation.type,
+        id: targetViewId,
+        created: viewCreated,
+        ...(viewReused ? { reused: true, reusedId: targetViewId } : {}),
+        ...(requestedViewId === null && viewCreated ? { allocatedId: targetViewId } : {}),
+      });
       continue;
     }
 
@@ -1761,6 +2287,33 @@ function requireObject(value, label) {
   }
 }
 
+function slugifyId(seed) {
+  return String(seed == null ? '' : seed)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// One unified id strategy for the whole framework (issue #8): a semantic slug
+// derived from the entity's human name, made unique within its collection by a
+// numeric suffix. Callers MAY omit an id; the server allocates one. There is no
+// per-repository id strategy — ArchGraph has a single one.
+function allocateUniqueId(existingIds, seed, fallbackBase) {
+  const taken = new Set((Array.isArray(existingIds) ? existingIds : []).map(String));
+  const base = slugifyId(seed) || fallbackBase || 'item';
+  if (!taken.has(base)) {
+    return base;
+  }
+  for (let n = 2; n < 100000; n += 1) {
+    const candidate = `${base}-${String(n).padStart(3, '0')}`;
+    if (!taken.has(candidate)) {
+      return candidate;
+    }
+  }
+  return `${base}-${Date.now()}`;
+}
+
 function requireId(value, label) {
   if (typeof value !== 'string' || value.length === 0) {
     throw new Error(`${label} must be a non-empty string`);
@@ -2655,6 +3208,18 @@ function compactMutationResponse(payload) {
     status: payload && payload.status,
     written: Boolean(payload && payload.written),
   };
+  // A successful write must tell the caller which id was used/allocated and whether
+  // it created or reused — otherwise an omitted (auto-allocated) id is invisible
+  // and an id collision would look like a create. Kept to a few fields (issue #8).
+  if (Array.isArray(payload && payload.mutations) && payload.mutations.length > 0) {
+    compact.mutations = payload.mutations.map((entry) => ({
+      type: entry.type,
+      id: entry.id,
+      created: entry.created,
+      ...(entry.reused ? { reused: true, reusedId: entry.reusedId } : {}),
+      ...(entry.allocatedId ? { allocatedId: entry.allocatedId } : {}),
+    }));
+  }
   if (payload && payload.embeddingLifecycle && payload.embeddingLifecycle.state) {
     compact.embeddingLifecycle = { state: payload.embeddingLifecycle.state };
   }
@@ -2699,15 +3264,51 @@ function compactMutationResponse(payload) {
   return compact;
 }
 
-function getSystemArchitectureResult(payload) {
-  const failed = payload.status === 'failed';
-  return toolResult(payload, {
+// The typed getSystemArchitecture output contract (see
+// GET_SYSTEM_ARCHITECTURE_OUTPUT_SCHEMA). The error variant allows only the
+// listed keys, so any error (local or mirrored from a cross-project read) is
+// projected onto that shape with category + message guaranteed. Exposed so the
+// argo MCP server can build the SAME structuredContent for a cross-project read
+// (which bypasses this module's callTool) instead of returning a result without
+// structuredContent — which violates the declared outputSchema (-32600).
+const GET_SYSTEM_ARCHITECTURE_ERROR_KEYS = Object.freeze([
+  'category', 'message', 'action', 'fullSnapshotFallback', 'state',
+  'canonicalVersion', 'contentVersion', 'indexVersion',
+  'completedChannels', 'missingChannels', 'mismatchedChannels',
+]);
+
+function normalizeGetSystemArchitectureError(error) {
+  const source = error && typeof error === 'object' ? error : {};
+  const normalized = {};
+  for (const key of GET_SYSTEM_ARCHITECTURE_ERROR_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(source, key) && source[key] !== undefined) {
+      normalized[key] = source[key];
+    }
+  }
+  if (typeof normalized.category !== 'string' || normalized.category === '') {
+    normalized.category = 'GET_SYSTEM_ARCHITECTURE_ERROR';
+  }
+  if (typeof normalized.message !== 'string' || normalized.message === '') {
+    normalized.message = typeof source.reason === 'string' && source.reason !== ''
+      ? source.reason
+      : 'getSystemArchitecture failed';
+  }
+  return normalized;
+}
+
+function buildGetSystemArchitectureStructuredContent(payload) {
+  const failed = Boolean(payload) && payload.status === 'failed';
+  return {
     version: '1.0',
     mode: failed ? 'error' : 'semantic-query',
-    document: failed ? null : (payload.document === undefined ? null : payload.document),
-    query: failed ? null : (payload.query || null),
-    error: failed ? payload.error : null,
-  });
+    document: failed ? null : (payload && payload.document === undefined ? null : payload.document),
+    query: failed ? null : ((payload && payload.query) || null),
+    error: failed ? normalizeGetSystemArchitectureError(payload.error) : null,
+  };
+}
+
+function getSystemArchitectureResult(payload) {
+  return toolResult(payload, buildGetSystemArchitectureStructuredContent(payload));
 }
 
 async function callTool(name, args = {}, dependencies = undefined) {
@@ -4488,8 +5089,12 @@ if (require.main === module) {
 
 module.exports = {
   GET_SYSTEM_ARCHITECTURE_OUTPUT_SCHEMA,
+  buildGetSystemArchitectureStructuredContent,
   TOOLS,
   applyMutations,
+  applyContextBudget,
+  applyViewContextBudget,
+  resolveContextMaxBytes,
   buildBusinessSemanticSummary,
   buildSemanticDedupAdvisory,
   selectCreatedElementAdds,