archgraph-argo 0.17.1 → 0.18.1

package/argo/scripts/graph-rag/mutationEmbeddingVectorLifecycle.js

@@ -15,6 +15,9 @@ const {
 const {
   createLiveEmbeddingProviderClient,
 } = require('./liveEmbeddingProviderClient.js');
+const {
+  buildSemanticRecordText,
+} = require('./semanticRecordText.js');
 const {
   createProductionSemanticNeo4jAdapter,
 } = require('./semantic-persistence/productionSemanticNeo4jAdapter.js');
@@ -218,7 +221,7 @@ function createProductionPersistentLifecycleDependencies(options = {}) {
     provider: Object.freeze({
       async embed(content) {
         const active = await requireResources();
-        return active.provider.embed(JSON.stringify(content));
+        return active.provider.embed(typeof content === 'string' ? content : JSON.stringify(content));
       },
     }),
     projectionStore: Object.freeze({
@@ -513,7 +516,8 @@ function buildPersistentWork(canonicalWrite, configuration, versions) {
   const tombstones = [];
   for (const definition of definitions) {
     for (const objectId of definition.ids) {
-      const content = definition.entries.find(entry => entry && entry[definition.idField] === objectId);
+      const object = definition.entries.find(entry => entry && entry[definition.idField] === objectId);
+      const content = object ? buildSemanticRecordText(definition.channel, object) : undefined;
       const base = {
         objectId,
         canonicalIdentity: `${definition.channel}:${objectId}`,

package/argo/scripts/graph-rag/semantic-persistence/productionSemanticBackfill.js

@@ -2,6 +2,9 @@ const crypto = require('node:crypto');
 const {
   evaluateEmbeddingQualification,
 } = require('../embeddingQualificationGate.js');
+const {
+  buildSemanticRecordText,
+} = require('../semanticRecordText.js');
 
 const CHANNELS = Object.freeze(['Element', 'ArchitectureRelationship', 'View']);
 const CHANNEL_SOURCES = Object.freeze({
@@ -152,7 +155,7 @@ async function processChannel(options) {
 
 function buildSemanticRecord(record, vector, options) {
   const contentHash = crypto.createHash('sha256')
-    .update(JSON.stringify(record.canonicalObject))
+    .update(buildSemanticRecordText(record.channel, record.canonicalObject))
     .digest('hex');
   return Object.freeze({
     canonicalIdentity: record.canonicalIdentity,

package/argo/scripts/graph-rag/semanticRecordText.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// Curated embedding text for a canonical semantic record.
+//
+// The canonical JSON (design/KG/SystemArchitecture.json) remains the structural
+// source of truth. The vector index, however, only encodes the human-meaningful
+// fields of each record — never ids, endpoint ids, view member-id arrays, or
+// JSON syntax — because embedding the raw object measurably dilutes retrieval
+// (most severely for Views, whose member-id arrays dominate the text, and for
+// Relationships, which are mostly structural). Both the full backfill and the
+// incremental mutation lifecycle MUST embed through this single composer so the
+// indexed text is identical across both paths.
+
+function meaningful(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function formatAttributes(attributes) {
+  if (!Array.isArray(attributes)) {
+    return [];
+  }
+  const lines = [];
+  for (const attribute of attributes) {
+    if (!attribute || !meaningful(attribute.name)) {
+      continue;
+    }
+    const detail = meaningful(attribute.value)
+      ? attribute.value
+      : (meaningful(attribute.description) ? attribute.description : '');
+    lines.push(detail ? `${attribute.name.trim()}: ${detail.trim()}` : attribute.name.trim());
+  }
+  return lines;
+}
+
+function buildSemanticRecordText(channel, object) {
+  const record = object && typeof object === 'object' ? object : {};
+  const lines = [];
+  const add = value => {
+    if (meaningful(value)) {
+      lines.push(value.trim());
+    }
+  };
+
+  if (channel === 'ArchitectureRelationship' || channel === 'Relationship') {
+    add(record.statement);
+    add(record.name);
+    add(record.description);
+    add(record.document);
+    lines.push(...formatAttributes(record.attributes));
+    return lines.join('\n');
+  }
+
+  if (channel === 'View') {
+    add(record.view_name);
+    add(record.description);
+    return lines.join('\n');
+  }
+
+  // Element (default channel)
+  add(record.type);
+  add(record.name);
+  add(record.alias);
+  add(record.description);
+  lines.push(...formatAttributes(record.attributes));
+  if (Array.isArray(record.testcases)) {
+    for (const testcase of record.testcases) {
+      if (testcase && meaningful(testcase.description)) {
+        lines.push(testcase.description.trim());
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+module.exports = { buildSemanticRecordText };

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

@@ -9,6 +9,10 @@ const {
   resolveCallWorkspaceRoot,
 } = require('./argo-paths.js');
 
+const {
+  buildSemanticRecordText,
+} = require('./graph-rag/semanticRecordText.js');
+
 const DEFAULT_GRAPH_PATH = 'design/KG/SystemArchitecture.json';
 const LEGAL_QUERY_PURPOSES = new Set([
   'general',
@@ -1809,9 +1813,13 @@ async function buildMutationResult(context, mutations, write, dependencies) {
   }
 
   // L1 advisory: semantic near-duplicate suggestions for element adds. Never
-  // blocks or fails the write; preview and apply both surface it.
+  // blocks or fails the write; preview and apply both surface it. Only adds the
+  // applied mutation actually CREATED are advised — a reuse that found an exact
+  // natural-key match creates nothing and is skipped, while a reuse that fell
+  // through to creation is advised like any other new element.
   if (errors.length === 0) {
-    const semanticDedup = await buildSemanticDedupAdvisory(context, mutations, dependencies);
+    const createdAdds = selectCreatedElementAdds(mutations, mutationResult.mutationSummaries);
+    const semanticDedup = await buildSemanticDedupAdvisory(context, createdAdds, dependencies);
     if (semanticDedup) {
       result.semanticDedup = semanticDedup;
     }
@@ -2691,6 +2699,24 @@ function collectViewMemberElementIds(document, viewIds) {
   return ids;
 }
 
+// Only element adds that the applied mutation actually CREATED are subject to
+// the L1 advisory. A reuse that found an exact natural-key match creates nothing
+// (created:false) and is skipped; a reuse that fell through to creation
+// (created:true, id === requested id) is advised like any other new element.
+function selectCreatedElementAdds(mutations, mutationSummaries) {
+  const createdIds = new Set(
+    (Array.isArray(mutationSummaries) ? mutationSummaries : [])
+      .filter(summary => summary && summary.type === 'addElement' && summary.created === true)
+      .map(summary => summary.id),
+  );
+  return (Array.isArray(mutations) ? mutations : []).filter(mutation => (
+    mutation
+    && mutation.type === 'addElement'
+    && mutation.element
+    && createdIds.has(mutation.element.id)
+  ));
+}
+
 async function buildSemanticDedupAdvisory(context, mutations, dependencies) {
   if (process.env.ARGO_MCP_SEMANTIC_DEDUP === '0') {
     return undefined;
@@ -2701,7 +2727,6 @@ async function buildSemanticDedupAdvisory(context, mutations, dependencies) {
     && mutation.element
     && typeof mutation.element.name === 'string'
     && mutation.element.name.trim() !== ''
-    && mutation.onConflict !== 'reuse'
   ));
   if (addedElements.length === 0) {
     return undefined;
@@ -3839,7 +3864,7 @@ async function createDefaultProductionSemanticRuntime(options = {}) {
             try {
               vectors.push(Object.freeze({
                 canonicalIdentity: record.canonicalIdentity,
-                vector: Object.freeze(await providerClient.embed(JSON.stringify(record.canonicalObject))),
+                vector: Object.freeze(await providerClient.embed(buildSemanticRecordText(record.channel, record.canonicalObject))),
               }));
             } catch (error) {
               failures.push(Object.freeze({
@@ -4102,6 +4127,7 @@ module.exports = {
   TOOLS,
   applyMutations,
   buildSemanticDedupAdvisory,
+  selectCreatedElementAdds,
   callTool,
   compactMutationResponse,
   createDefaultCanonicalSemanticInitComposition,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {