archgraph-argo 0.17.1 → 0.18.0

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',
@@ -3839,7 +3843,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({

package/package.json

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