archgraph-argo 0.19.0 → 0.20.0

package/README.md

@@ -7,6 +7,10 @@ An architecture-graph driven framework for Agentic Engineering.
 ArchGraph builds a **unified language** that puts harness design and target product design into
 **one model** — so you get a single view to work and observe, and real control over your agents.
 
+It doubles as a **long-term memory for coding agents**: an ArchiMate 3.2 intent graph exposed through
+a single read/write MCP interface. Writes are deduplicated, so the graph stays clean and semantic
+recall stays precise. See the [home page](https://archgraph.org/) for the full capability set.
+
 ![alt text](docs/diagrams/image.png)
 
 ## Architecture
@@ -71,7 +75,9 @@ After installing, open your project and start a coding agent. It will:
 
 1. locate the architecture element behind the task before changing anything,
 2. arm itself with that element's Skills and Rules,
-3. work test-first (GIVEN-WHEN-THEN), and trace every commit back to the graph.
+3. work test-first (GIVEN-WHEN-THEN), and trace every commit back to the graph,
+4. reuse an existing element, relationship, or view instead of creating a duplicate — the write path
+   deduplicates by identity and flags a semantically near element of the same type.
 
 The intent architecture graph — modelled in **ArchiMate 3.2** — is the single source of truth.
 

package/argo/scripts/ea-qea-sync-lib.js

@@ -698,6 +698,7 @@ function syncGraphToQea(graph, qeaPath, opts) {
           RectRight: 40 + col * 260 + 180, RectBottom: 40 + row * 160 + 90,
           Sequence: seq,
         });
+        placedObjs.add(Number(oid));
         seq++;
       }
       if (newObjs.length > 0 && !o.dryRun) {
@@ -731,6 +732,7 @@ function syncGraphToQea(graph, qeaPath, opts) {
         if (cid === undefined || cid < 0) { continue; }
         if (placedLinks.has(Number(cid))) { continue; }
         newLinks.push({ DiagramID: diagramId, ConnectorID: Number(cid), Style: '', Geometry: '' });
+        placedLinks.add(Number(cid));
       }
       if (newLinks.length > 0 && !o.dryRun) {
         insertMany(db, 't_diagramlinks', ['DiagramID', 'ConnectorID', 'Style', 'Geometry'], newLinks);

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

@@ -14,6 +14,21 @@ const {
   getWorkspaceRoot,
   resolveArgoPath,
 } = require('../argo-paths.js');
+const {
+  isHybridEnabled,
+  hybridTopK,
+  hybridWeights,
+  rrfK,
+  fuseChannelSeeds,
+  sanitizeFulltextQuery,
+} = require('./hybridRetrieval.js');
+const {
+  isRerankEnabled,
+  rerankConfig,
+  resolveRerankProvider,
+  rerankCandidates,
+  applyRerankOrder,
+} = require('./rerankRetrieval.js');
 
 const APPROVED_SOURCE_KEYS = Object.freeze([
   'ARGO_EMBEDDING_BASE_URL',
@@ -75,6 +90,20 @@ const VECTOR_QUERY_CYPHER_SCOPED = [
   'RETURN properties(node) AS record, score',
   'ORDER BY score DESC',
 ].join('\n');
+const LEXICAL_QUERY_CYPHER = [
+  'CALL db.index.fulltext.queryNodes($indexName, $queryText, { limit: $topK })',
+  'YIELD node, score',
+  'WHERE node.channel = $channel',
+  'RETURN properties(node) AS record, score',
+  'ORDER BY score DESC',
+].join('\n');
+const LEXICAL_QUERY_CYPHER_SCOPED = [
+  'CALL db.index.fulltext.queryNodes($indexName, $queryText, { limit: $topK })',
+  'YIELD node, score',
+  'WHERE node.channel = $channel AND node.canonicalIdentity IN $canonicalIdentities',
+  'RETURN properties(node) AS record, score',
+  'ORDER BY score DESC',
+].join('\n');
 const READINESS_QUERY_CYPHER = [
   'MATCH (readiness:ArgoProductionSemanticReadiness {identity: $identity})',
   'RETURN properties(readiness) AS readiness',
@@ -206,18 +235,49 @@ async function executeWpP2Retrieval({
   const purpose = request && typeof request.purpose === 'string' ? request.purpose : '';
   const strict = AUDIT_PURPOSES.has(purpose);
   const topK = Number.isInteger(request.topK) && request.topK > 0 ? request.topK : resolveTopK();
+  const scoped = Array.isArray(canonicalIdentities) && canonicalIdentities.length > 0;
+  const hybrid = isHybridEnabled();
+  const lexicalTopK = hybridTopK();
+  const fusionK = rrfK();
+  const fusionWeights = hybridWeights();
+  const rerank = isRerankEnabled();
+  const rerankOptions = rerankConfig();
+  const rerankProvider = rerank ? resolveRerankProvider(configurationEvidence.configuration) : null;
+  // Rerank needs a larger candidate pool than the final top-K.
+  const pool = rerank ? Math.max(topK, rerankOptions.poolSize) : topK;
   const seedsByType = {};
   for (const channel of CHANNELS) {
-    seedsByType[channel.key] = await exhaustChannel({
+    const vectorSeeds = await exhaustChannel({
       channel,
       neo4jDriver: composition.neo4jDriver,
       vector,
       threshold: strict ? auditThresholdFor(channel) : memoryThresholdFor(channel),
-      maxSeeds: topK,
-      ...(Array.isArray(canonicalIdentities) && canonicalIdentities.length > 0
-        ? { canonicalIdentities }
-        : {}),
+      maxSeeds: pool,
+      ...(scoped ? { canonicalIdentities } : {}),
     });
+    let seeds = vectorSeeds;
+    if (hybrid) {
+      const lexicalSeeds = await exhaustLexicalChannel({
+        channel,
+        neo4jDriver: composition.neo4jDriver,
+        queryText: request.intent,
+        maxSeeds: lexicalTopK,
+        ...(scoped ? { canonicalIdentities } : {}),
+      });
+      seeds = fuseChannelSeeds({ vectorSeeds, lexicalSeeds, k: fusionK, limit: Math.max(pool, lexicalTopK), weights: fusionWeights });
+    }
+    if (rerank && seeds.length > 1) {
+      const ordered = await rerankCandidates({
+        query: request.intent,
+        candidates: seeds,
+        provider: rerankProvider,
+        transport: composition.transport,
+        maxReturn: rerankOptions.maxReturn,
+      });
+      // fail-open: a null/empty order keeps the original ordering
+      seeds = applyRerankOrder(seeds, ordered, topK);
+    }
+    seedsByType[channel.key] = seeds;
   }
   return completeSemanticResult({
     request: completeRequest,
@@ -303,6 +363,9 @@ async function executeProductionNeo4jOperation(configuration, operation) {
       ...record.get('record'),
       score: numberValue(record.get('score')),
     }));
+    if (operation.kind === 'semantic-lexical-query') {
+      return { records };
+    }
     const offset = operation.parameters.offset;
     const windowSize = operation.parameters.windowSize;
     const returnedCount = Math.max(0, records.length - offset);
@@ -709,6 +772,53 @@ async function exhaustChannel({
   return Object.freeze(accepted);
 }
 
+// Lexical (full-text/BM25) sibling of exhaustChannel. Additive and fail-open:
+// it returns [] when the query text is blank, when the full-text index is
+// missing, or on any error, so hybrid retrieval can never break the baseline.
+async function exhaustLexicalChannel({
+  channel,
+  neo4jDriver,
+  queryText,
+  maxSeeds,
+  canonicalIdentities,
+}) {
+  if (typeof queryText !== 'string' || queryText.trim() === '') {
+    return Object.freeze([]);
+  }
+  const safeQuery = sanitizeFulltextQuery(queryText);
+  if (safeQuery === '') {
+    return Object.freeze([]);
+  }
+  const scoped = Array.isArray(canonicalIdentities) && canonicalIdentities.length > 0;
+  const scopedCanonicalIdentities = scoped
+    ? scopeCanonicalIdentitiesForChannel(canonicalIdentities, channel)
+    : canonicalIdentities;
+  const effectiveMax = Number.isInteger(maxSeeds) && maxSeeds > 0 ? maxSeeds : INITIAL_WINDOW_SIZE;
+  const indexName = `${channel.indexName}_fulltext`;
+  try {
+    const result = await neo4jDriver.execute(Object.freeze({
+      kind: 'semantic-lexical-query',
+      channel: channel.channel,
+      indexName,
+      cypher: scoped ? LEXICAL_QUERY_CYPHER_SCOPED : LEXICAL_QUERY_CYPHER,
+      parameters: Object.freeze({
+        indexName,
+        channel: channel.channel,
+        queryText: safeQuery,
+        topK: effectiveMax,
+        ...(scoped ? { canonicalIdentities: scopedCanonicalIdentities } : {}),
+      }),
+    }));
+    const records = Array.isArray(result && result.records) ? result.records : [];
+    return Object.freeze(records
+      .map(raw => normalizeVectorRecord(raw, channel))
+      .filter(Boolean)
+      .slice(0, effectiveMax));
+  } catch {
+    return Object.freeze([]);
+  }
+}
+
 // Scope identities come from the canonical graph as BARE ids (e.g.
 // "memory-eval-bench-wp-001"), but the semantic vector records store their
 // canonicalIdentity with a channel prefix (e.g. "Element:memory-eval-bench-wp-001").

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

@@ -0,0 +1,114 @@
+'use strict';
+
+// Hybrid retrieval fusion (P2). Pure, dependency-free helpers so the fusion
+// logic is fully unit-testable and the production retrieval path can stay
+// additive: when hybrid is OFF nothing here is invoked.
+//
+// Design:
+// - vector (dense) and lexical (full-text/BM25) ranked lists are fused with
+//   Reciprocal Rank Fusion: score(id) = sum over lists of 1/(k + rank).
+// - RRF needs no score normalization between the two very different score
+//   scales, and guarantees the union is retained (recall can only increase).
+
+const DEFAULT_RRF_K = 60;
+const DEFAULT_HYBRID_TOP_K = 16;
+// Vector-first weighting: the dense channel is the stronger signal on this
+// graph, so lexical only nudges the ranking and rescues misses.
+const DEFAULT_VECTOR_WEIGHT = 3;
+const DEFAULT_LEXICAL_WEIGHT = 1;
+
+function isHybridEnabled(env = process.env) {
+  return String((env && env.ARGO_SEMANTIC_HYBRID) || '') === '1';
+}
+
+function hybridWeights(env = process.env) {
+  const vector = Number(env && env.ARGO_SEMANTIC_HYBRID_VECTOR_WEIGHT);
+  const lexical = Number(env && env.ARGO_SEMANTIC_HYBRID_LEXICAL_WEIGHT);
+  return [
+    Number.isFinite(vector) && vector >= 0 ? vector : DEFAULT_VECTOR_WEIGHT,
+    Number.isFinite(lexical) && lexical >= 0 ? lexical : DEFAULT_LEXICAL_WEIGHT,
+  ];
+}
+
+function hybridTopK(env = process.env) {
+  const value = Number(env && env.ARGO_SEMANTIC_HYBRID_TOP_K);
+  return Number.isInteger(value) && value > 0 ? value : DEFAULT_HYBRID_TOP_K;
+}
+
+function rrfK(env = process.env) {
+  const value = Number(env && env.ARGO_SEMANTIC_HYBRID_RRF_K);
+  return Number.isFinite(value) && value > 0 ? value : DEFAULT_RRF_K;
+}
+
+// Lucene full-text queries reject raw punctuation (e.g. "A --(Flow)--> B") and
+// blow the maxClauseCount on very long text (long Chinese descriptions become
+// hundreds of single-character clauses). Truncate first, then escape the
+// reserved query-syntax characters so any intent/name/statement is literal.
+// Returns '' for blank input (caller skips).
+const MAX_FULLTEXT_QUERY_LENGTH = 256;
+
+function sanitizeFulltextQuery(text) {
+  const value = String(text === undefined || text === null ? '' : text)
+    .trim()
+    .slice(0, MAX_FULLTEXT_QUERY_LENGTH);
+  if (!value) return '';
+  return value
+    .replace(/&&/g, '\\&\\&')
+    .replace(/\|\|/g, '\\|\\|')
+    .replace(/([+\-!(){}[\]^"~*?:\\/])/g, '\\$1');
+}
+
+// Fuse ranked record lists by id (canonicalIdentity). Each list is expected to be
+// already sorted best-first. Returns records carrying the fused `score`, with
+// the first-seen record object preserved (so downstream keeps its fields).
+function rrfFuse(lists, options = {}) {
+  const k = Number.isFinite(options.k) && options.k > 0 ? options.k : DEFAULT_RRF_K;
+  const weights = Array.isArray(options.weights) ? options.weights : [];
+  const byId = new Map();
+  (Array.isArray(lists) ? lists : []).forEach((list, listIndex) => {
+    const weight = Number.isFinite(weights[listIndex]) && weights[listIndex] >= 0 ? weights[listIndex] : 1;
+    (Array.isArray(list) ? list : []).forEach((record, rank) => {
+      if (!record || !record.id) return;
+      const entry = byId.get(record.id) || { id: record.id, record, score: 0, matchedLists: 0 };
+      entry.score += weight / (k + rank + 1);
+      entry.matchedLists += 1;
+      if (!entry.record) entry.record = record;
+      byId.set(record.id, entry);
+    });
+  });
+  return [...byId.values()]
+    .sort((left, right) => (right.score - left.score) || String(left.id).localeCompare(String(right.id)))
+    .map(entry => Object.freeze({
+      ...entry.record,
+      id: entry.id,
+      canonicalIdentity: entry.id,
+      score: entry.score,
+      rrfScore: entry.score,
+      matchedLists: entry.matchedLists,
+    }));
+}
+
+// Fuse the two per-channel seed lists. With an empty lexical list this preserves
+// the vector ordering (RRF on a single list is order-preserving) — which is what
+// makes "hybrid ON but no lexical hit" behave like the vector-only baseline.
+function fuseChannelSeeds({ vectorSeeds = [], lexicalSeeds = [], k = DEFAULT_RRF_K, limit, weights } = {}) {
+  const fused = rrfFuse([
+    Array.isArray(vectorSeeds) ? vectorSeeds.filter(Boolean) : [],
+    Array.isArray(lexicalSeeds) ? lexicalSeeds.filter(Boolean) : [],
+  ], { k, ...(Array.isArray(weights) ? { weights } : {}) });
+  return Number.isInteger(limit) && limit > 0 ? fused.slice(0, limit) : fused;
+}
+
+module.exports = {
+  DEFAULT_RRF_K,
+  DEFAULT_HYBRID_TOP_K,
+  DEFAULT_VECTOR_WEIGHT,
+  DEFAULT_LEXICAL_WEIGHT,
+  isHybridEnabled,
+  hybridTopK,
+  hybridWeights,
+  rrfK,
+  rrfFuse,
+  fuseChannelSeeds,
+  sanitizeFulltextQuery,
+};

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

@@ -34,6 +34,17 @@ const RETRIEVAL_TUNING_KEYS = Object.freeze([
   'ARGO_SEMANTIC_AUDIT_THRESHOLD_RELATIONSHIP',
   'ARGO_SEMANTIC_AUDIT_THRESHOLD_VIEW',
   'ARGO_SEMANTIC_TOP_K',
+  // Rerank (P3) tuning + optional dedicated rerank provider. When the provider
+  // keys are unset the reranker falls back to the embedding provider (qwen).
+  'ARGO_SEMANTIC_RERANK',
+  'ARGO_SEMANTIC_RERANK_MODEL',
+  'ARGO_SEMANTIC_RERANK_POOL',
+  'ARGO_SEMANTIC_RERANK_RETURN',
+  'ARGO_SEMANTIC_RERANK_TIMEOUT_MS',
+  'ARGO_RERANK_BASE_URL',
+  'ARGO_RERANK_API_KEY',
+  'ARGO_RERANK_PROVIDER',
+  'ARGO_RERANK_MODEL',
 ]);
 const OPT_IN_KEYS = Object.freeze({
   ARGO_LIVE_PROVIDER_E2E: 'LIVE_PROVIDER_E2E_OPT_IN_REQUIRED',
@@ -47,7 +58,7 @@ const READABLE_KEYS = Object.freeze([
 ]);
 const LEGACY_KEYS = Object.freeze(['ARGO_NEO4J_URI', 'ARGO_NEO4J_USERNAME', 'ARGO_NEO4J_PASSWORD']);
 const PROHIBITED_RUNTIME_FIELD_KEYS = Object.freeze(['neo4jUri', 'embeddingCredential']);
-const SECRET_KEYS = new Set(['ARGO_NEO4J_DATABASE_PASSWORD', 'QWEN_KEY']);
+const SECRET_KEYS = new Set(['ARGO_NEO4J_DATABASE_PASSWORD', 'QWEN_KEY', 'ARGO_RERANK_API_KEY']);
 const APPROVED = Object.freeze({
   ARGO_EMBEDDING_BASE_URL: 'https://llm-clids9mqc5o1mbvb.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
   ARGO_EMBEDDING_MODEL: 'qwen3.7-text-embedding',

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

@@ -531,6 +531,7 @@ function buildPersistentWork(canonicalWrite, configuration, versions) {
           contentVersion: `content:${fingerprint(content)}`,
           indexVersion: `index:${fingerprint({ objectId, content, canonicalVersion: versions.canonicalVersion })}`,
           content,
+          searchText: content,
         }));
       } else {
         tombstones.push(Object.freeze(base));

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

@@ -0,0 +1,150 @@
+'use strict';
+
+// Two-stage rerank (P3): after the (vector, or hybrid) candidate pool is
+// retrieved, an LLM listwise reranker reorders it by relevance to the query.
+// Additive and fail-open: when disabled nothing runs; any error returns null so
+// the caller keeps the original ordering. Pure helpers are exported for tests.
+
+const DEFAULT_RERANK_MODEL = 'qwen-turbo';
+const DEFAULT_RERANK_POOL = 20;
+const DEFAULT_RERANK_RETURN = 8;
+const DEFAULT_RERANK_TIMEOUT_MS = 8000;
+
+function rerankTimeoutMs(env = process.env) {
+  const value = Number(env && env.ARGO_SEMANTIC_RERANK_TIMEOUT_MS);
+  return Number.isFinite(value) && value > 0 ? value : DEFAULT_RERANK_TIMEOUT_MS;
+}
+
+function isRerankEnabled(env = process.env) {
+  return String((env && env.ARGO_SEMANTIC_RERANK) || '') === '1';
+}
+
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim() !== '') return value.trim();
+  }
+  return '';
+}
+
+// Rerank provider resolution, DECOUPLED from the embedding provider:
+// - dedicated keys (ARGO_RERANK_BASE_URL / ARGO_RERANK_API_KEY / ARGO_RERANK_PROVIDER
+//   / ARGO_RERANK_MODEL) win when set, so a different provider/model can be used;
+// - otherwise it falls back to the embedding configuration (qwen by default).
+function resolveRerankProvider(configuration = {}, env = process.env) {
+  const baseUrl = firstNonEmpty(env.ARGO_RERANK_BASE_URL, configuration.embeddingBaseUrl);
+  const apiKey = firstNonEmpty(env.ARGO_RERANK_API_KEY, configuration.qwenKey);
+  const model = firstNonEmpty(env.ARGO_RERANK_MODEL, env.ARGO_SEMANTIC_RERANK_MODEL, DEFAULT_RERANK_MODEL);
+  const provider = firstNonEmpty(env.ARGO_RERANK_PROVIDER, configuration.embeddingProvider, 'qwen');
+  return { baseUrl, apiKey, model, provider };
+}
+
+function rerankConfig(env = process.env) {
+  const model = (env && typeof env.ARGO_SEMANTIC_RERANK_MODEL === 'string' && env.ARGO_SEMANTIC_RERANK_MODEL.trim())
+    ? env.ARGO_SEMANTIC_RERANK_MODEL.trim()
+    : DEFAULT_RERANK_MODEL;
+  const pool = Number(env && env.ARGO_SEMANTIC_RERANK_POOL);
+  const maxReturn = Number(env && env.ARGO_SEMANTIC_RERANK_RETURN);
+  return {
+    model,
+    poolSize: Number.isInteger(pool) && pool > 0 ? pool : DEFAULT_RERANK_POOL,
+    maxReturn: Number.isInteger(maxReturn) && maxReturn > 0 ? maxReturn : DEFAULT_RERANK_RETURN,
+  };
+}
+
+function candidateText(record) {
+  const raw = record && (record.searchText || record.description || record.name || '');
+  return String(raw).replace(/\s+/g, ' ').slice(0, 160);
+}
+
+// Accept the canonical id or its bare/suffix form (models often drop the
+// channel prefix), dedupe, ignore anything not in the candidate set.
+function parseRerankOrder(content, candidateIds) {
+  let parsed;
+  try { parsed = JSON.parse(content); } catch { return []; }
+  const raw = Array.isArray(parsed && parsed.order) ? parsed.order : [];
+  const byKey = new Map();
+  for (const id of candidateIds) {
+    const text = String(id);
+    byKey.set(text, id);
+    byKey.set(text.split(':').slice(1).join(':'), id);
+    byKey.set(text.split(':').pop(), id);
+  }
+  const seen = new Set();
+  const order = [];
+  for (const value of raw) {
+    const canonical = byKey.get(String(value));
+    if (canonical && !seen.has(canonical)) {
+      seen.add(canonical);
+      order.push(canonical);
+    }
+  }
+  return order;
+}
+
+// Reorder seeds by the model's order, then append any seeds the model omitted
+// (nothing is lost), bounded by `limit`.
+function applyRerankOrder(seeds, orderedIds, limit) {
+  const list = Array.isArray(seeds) ? seeds.filter(Boolean) : [];
+  const byId = new Map(list.map(seed => [seed.id, seed]));
+  const out = [];
+  const seen = new Set();
+  for (const id of (Array.isArray(orderedIds) ? orderedIds : [])) {
+    const seed = byId.get(id);
+    if (seed && !seen.has(id)) { seen.add(id); out.push(seed); }
+  }
+  for (const seed of list) {
+    if (!seen.has(seed.id)) { seen.add(seed.id); out.push(seed); }
+  }
+  return Number.isInteger(limit) && limit > 0 ? out.slice(0, limit) : out;
+}
+
+async function rerankCandidates({ query, candidates, provider, transport, maxReturn, timeoutMs } = {}) {
+  const list = Array.isArray(candidates) ? candidates.filter(candidate => candidate && candidate.id) : [];
+  if (list.length < 2 || typeof query !== 'string' || query.trim() === '') return null;
+  if (!provider || !transport || typeof transport.request !== 'function') return null;
+  const baseUrl = typeof provider.baseUrl === 'string' ? provider.baseUrl : '';
+  const apiKey = typeof provider.apiKey === 'string' ? provider.apiKey : '';
+  if (baseUrl === '' || apiKey === '') return null;
+  const model = provider.model || DEFAULT_RERANK_MODEL;
+  const body = {
+    model,
+    temperature: 0,
+    response_format: { type: 'json_object' },
+    messages: [
+      { role: 'system', content: 'You rank architecture elements by relevance to a query. Return ONLY JSON {"order":[ids best-first]} using only the candidate ids.' },
+      { role: 'user', content: `Query: ${query}\n\nCandidates (id\\ttext):\n${list.map(candidate => `${candidate.id}\t${candidateText(candidate)}`).join('\n')}\n\nReturn up to ${Math.min(maxReturn || DEFAULT_RERANK_RETURN, list.length)} ids best-first.` },
+    ],
+  };
+  const controller = typeof AbortController === 'function' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs || rerankTimeoutMs()) : null;
+  try {
+    const response = await transport.request(`${baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      ...(controller ? { signal: controller.signal } : {}),
+    });
+    if (!response || response.ok !== true || typeof response.json !== 'function') return null;
+    const payload = await response.json();
+    const content = payload && payload.choices && payload.choices[0] && payload.choices[0].message && payload.choices[0].message.content;
+    return parseRerankOrder(content, list.map(candidate => candidate.id));
+  } catch {
+    return null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+module.exports = {
+  DEFAULT_RERANK_MODEL,
+  DEFAULT_RERANK_POOL,
+  DEFAULT_RERANK_RETURN,
+  DEFAULT_RERANK_TIMEOUT_MS,
+  isRerankEnabled,
+  rerankConfig,
+  rerankTimeoutMs,
+  resolveRerankProvider,
+  parseRerankOrder,
+  applyRerankOrder,
+  rerankCandidates,
+};

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

@@ -154,8 +154,9 @@ async function processChannel(options) {
 }
 
 function buildSemanticRecord(record, vector, options) {
+  const searchText = buildSemanticRecordText(record.channel, record.canonicalObject);
   const contentHash = crypto.createHash('sha256')
-    .update(buildSemanticRecordText(record.channel, record.canonicalObject))
+    .update(searchText)
     .digest('hex');
   return Object.freeze({
     canonicalIdentity: record.canonicalIdentity,
@@ -167,6 +168,7 @@ function buildSemanticRecord(record, vector, options) {
     model: options.qualification.model,
     modelVersion: options.qualification.version,
     dimensions: options.qualification.dimensions,
+    searchText,
     vector: Object.freeze([...vector]),
   });
 }

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

@@ -30,6 +30,7 @@ function createProductionSemanticNeo4jAdapter(dependencies = {}) {
       }
       return withSession(driver, dependencies.configuration, async session => {
         await ensureVectorIndexes(session);
+        await ensureFulltextIndexes(session);
         const results = [];
         for (const [channel, definition] of Object.entries(CHANNEL_INDEXES)) {
           const channelRecords = records.filter(record => record.channel === channel).map(cloneRecord);
@@ -121,6 +122,19 @@ async function ensureVectorIndexes(session) {
   }
 }
 
+async function ensureFulltextIndexes(session) {
+  for (const definition of Object.values(CHANNEL_INDEXES)) {
+    await executeWrite(
+      session,
+      [
+        `CREATE FULLTEXT INDEX ${definition.indexName}_fulltext IF NOT EXISTS`,
+        `FOR (semantic:${definition.label}) ON EACH [semantic.searchText]`,
+      ].join('\n'),
+      {},
+    );
+  }
+}
+
 async function withSession(driver, configuration, action) {
   const database = configuration && configuration.neo4jDatabase;
   const session = driver.session(database === undefined ? undefined : { database });

package/argo/scripts/graph-semantics.js

@@ -116,12 +116,19 @@ function validateGraphSemantics(document, errors) {
       }
     }
     const includedElementIds = new Set(view.included_elements || []);
+    if (includedElementIds.size !== (view.included_elements || []).length) {
+      errors.push(`views '${view.view_id}' must not contain duplicate included_elements`);
+    }
     for (const elementId of view.included_elements || []) {
       elementIdsIncludedInViews.add(elementId);
       if (!elementById.has(elementId)) {
         errors.push(`views '${view.view_id}' references missing included element '${elementId}'`);
       }
     }
+    const includedRelationshipIds = new Set(view.included_relationships || []);
+    if (includedRelationshipIds.size !== (view.included_relationships || []).length) {
+      errors.push(`views '${view.view_id}' must not contain duplicate included_relationships`);
+    }
     for (const relationshipId of view.included_relationships || []) {
       relationshipIdsIncludedInViews.add(relationshipId);
       const rel = relationshipById.get(relationshipId);

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

@@ -1519,11 +1519,18 @@ function applyMutations(document, mutations) {
           requestedId: mutation.view.view_id,
         });
       } else {
-        nextDocument.views.push(clone(mutation.view));
-        upsertSubdiagramViewIntoElement(nextDocument, mutation.view.parent_element_id, mutation.view);
-        touchedViewIds.add(mutation.view.view_id);
-        viewLimitCheckIds.add(mutation.view.view_id);
-        mutationSummaries.push({ type: mutation.type, id: mutation.view.view_id });
+        const newView = clone(mutation.view);
+        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);
+        mutationSummaries.push({ type: mutation.type, id: newView.view_id });
       }
       continue;
     }
@@ -1538,7 +1545,14 @@ function applyMutations(document, mutations) {
       }
       const oldParentId = view.parent_element_id;
       const oldViewId = view.view_id;
-      Object.assign(view, clone(mutation.patch));
+      const patch = clone(mutation.patch);
+      if (Array.isArray(patch.included_elements)) {
+        patch.included_elements = addUnique([], patch.included_elements);
+      }
+      if (Array.isArray(patch.included_relationships)) {
+        patch.included_relationships = addUnique([], patch.included_relationships);
+      }
+      Object.assign(view, patch);
       if (oldParentId !== view.parent_element_id) {
         removeSubdiagramViewFromElement(nextDocument, oldParentId, oldViewId);
       }

package/package.json

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