archgraph-argo 0.20.7 → 0.20.9

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

@@ -154,65 +154,83 @@ function createDefaultSemanticRetrieval(dependencies = {}) {
   return Object.freeze({
     async retrieve(request = {}) {
       const composition = await resolveRetrievalComposition(dependencies);
-      const activeTestComposition = testCompositionStorage.getStore();
-      const activeReadinessBoundary = activeTestComposition
-        && activeTestComposition.useReadinessBoundary !== true
-        ? undefined
-        : readinessBoundary;
-      let configurationEvidence = await composition.resolveConfiguration();
-      let evidence = await readAndEvaluatePersistentReadiness(
-        composition,
-        canonicalGraph,
-        activeReadinessBoundary,
-      );
-      if (!evidence.alignment.aligned) {
-        await attemptAutomaticAlignment({
-          composition,
-          request,
-          alignment: evidence.alignment,
-        });
-        evidence = await readAndEvaluatePersistentReadiness(
+      try {
+        const activeTestComposition = testCompositionStorage.getStore();
+        const activeReadinessBoundary = activeTestComposition
+          && activeTestComposition.useReadinessBoundary !== true
+          ? undefined
+          : readinessBoundary;
+        let configurationEvidence = await composition.resolveConfiguration();
+        let evidence = await readAndEvaluatePersistentReadiness(
           composition,
           canonicalGraph,
           activeReadinessBoundary,
         );
         if (!evidence.alignment.aligned) {
-          throw semanticAutomaticAlignmentFailed(evidence.alignment);
+          await attemptAutomaticAlignment({
+            composition,
+            request,
+            alignment: evidence.alignment,
+          });
+          evidence = await readAndEvaluatePersistentReadiness(
+            composition,
+            canonicalGraph,
+            activeReadinessBoundary,
+          );
+          if (!evidence.alignment.aligned) {
+            throw semanticAutomaticAlignmentFailed(evidence.alignment);
+          }
+        }
+        return await executeWpP2Retrieval({
+          composition,
+          request,
+          canonicalGraph,
+          readiness: evidence.readiness,
+          configurationEvidence,
+        });
+      } finally {
+        if (typeof composition.dispose === 'function') {
+          await composition.dispose();
         }
       }
-      return executeWpP2Retrieval({
-        composition,
-        request,
-        canonicalGraph,
-        readiness: evidence.readiness,
-        configurationEvidence,
-      });
     },
     async probeQueryability(request = {}, readiness = {}) {
       const composition = await resolveRetrievalComposition(dependencies);
-      const configurationEvidence = await composition.resolveConfiguration();
-      return executeWpP2Retrieval({
-        composition,
-        request,
-        canonicalGraph,
-        readiness,
-        configurationEvidence,
-      });
+      try {
+        const configurationEvidence = await composition.resolveConfiguration();
+        return await executeWpP2Retrieval({
+          composition,
+          request,
+          canonicalGraph,
+          readiness,
+          configurationEvidence,
+        });
+      } finally {
+        if (typeof composition.dispose === 'function') {
+          await composition.dispose();
+        }
+      }
     },
     async readReadiness() {
       const composition = await resolveRetrievalComposition(dependencies);
-      const activeTestComposition = testCompositionStorage.getStore();
-      const activeReadinessBoundary = activeTestComposition
-        && activeTestComposition.useReadinessBoundary !== true
-        ? undefined
-        : readinessBoundary;
-      await composition.resolveConfiguration();
-      const evidence = await readAndEvaluatePersistentReadiness(
-        composition,
-        canonicalGraph,
-        activeReadinessBoundary,
-      );
-      return publicReadinessOutcome(evidence.alignment);
+      try {
+        const activeTestComposition = testCompositionStorage.getStore();
+        const activeReadinessBoundary = activeTestComposition
+          && activeTestComposition.useReadinessBoundary !== true
+          ? undefined
+          : readinessBoundary;
+        await composition.resolveConfiguration();
+        const evidence = await readAndEvaluatePersistentReadiness(
+          composition,
+          canonicalGraph,
+          activeReadinessBoundary,
+        );
+        return publicReadinessOutcome(evidence.alignment);
+      } finally {
+        if (typeof composition.dispose === 'function') {
+          await composition.dispose();
+        }
+      }
     },
   });
 }
@@ -244,7 +262,7 @@ async function executeWpP2Retrieval({
   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 hybrid = isHybridEnabled() && request.hybrid !== false;
   const lexicalTopK = hybridTopK();
   const fusionK = rrfK();
   const fusionWeights = hybridWeights();
@@ -333,6 +351,28 @@ async function createProductionComposition(dependencies) {
   const repositoryRoot = dependencies.repositoryRoot
     || getWorkspaceRoot();
   let configurationEvidence;
+  let neo4jHandle = null;
+  async function disposeNeo4j() {
+    const handle = neo4jHandle;
+    neo4jHandle = null;
+    if (!handle) return;
+    try { await handle.session.close(); } catch { /* ignore */ }
+    try { await handle.driver.close(); } catch { /* ignore */ }
+  }
+  function ensureNeo4jSession() {
+    if (neo4jHandle) return neo4jHandle.session;
+    const configuration = configurationEvidence.configuration;
+    const neo4j = require('neo4j-driver');
+    const driver = neo4j.driver(
+      configuration.neo4jDatabaseUrl,
+      neo4j.auth.basic(configuration.neo4jDatabaseUsername, configuration.neo4jDatabasePassword),
+    );
+    const session = driver.session(configuration.neo4jDatabase === undefined
+      ? undefined
+      : { database: configuration.neo4jDatabase });
+    neo4jHandle = { driver, session };
+    return session;
+  }
   return Object.freeze({
     async resolveConfiguration() {
       configurationEvidence = await resolveApprovedLiveConfiguration({
@@ -354,59 +394,61 @@ async function createProductionComposition(dependencies) {
         if (!configurationEvidence) {
           throw safeError('EXTERNAL_CREDENTIALS_REQUIRED');
         }
-        return executeProductionNeo4jOperation(configurationEvidence.configuration, operation);
+        if (operation && operation.kind === 'semantic-auto-alignment-attempt') {
+          return runScriptOwnedSemanticAlignment(operation);
+        }
+        try {
+          return await runOperationOnSession(ensureNeo4jSession(), operation);
+        } catch (error) {
+          // A failed run may leave the session unusable; drop the handle so the
+          // rest of this retrieval (or the next one) reconnects cleanly.
+          await disposeNeo4j();
+          throw error;
+        }
       },
     }),
+    async dispose() {
+      await disposeNeo4j();
+    },
   });
 }
 
-async function executeProductionNeo4jOperation(configuration, operation) {
-  if (operation && operation.kind === 'semantic-auto-alignment-attempt') {
-    return runScriptOwnedSemanticAlignment(operation);
+// Pure operation runner: runs one Cypher operation on a caller-owned Neo4j
+// session and maps the result. The session/driver lifecycle lives in the
+// production composition (ONE handle per retrieval, reused across every vector
+// window, then closed) -- correctly reused without leaving a lingering handle,
+// which would keep short-lived processes alive. Creating AND closing a driver
+// per operation caused the rapid handle churn that intermittently aborted the
+// MCP with a native libuv assertion on Windows (confirmed crash phase:
+// retrieval:vector-window:ArchitectureRelationship).
+async function runOperationOnSession(session, operation) {
+  const result = await session.run(operation.cypher, operation.parameters);
+  if (operation.kind === 'semantic-readiness-read') {
+    const readiness = result.records[0] && result.records[0].get('readiness');
+    return { records: readiness ? [readiness] : [] };
   }
-  const neo4j = require('neo4j-driver');
-  const driver = neo4j.driver(
-    configuration.neo4jDatabaseUrl,
-    neo4j.auth.basic(
-      configuration.neo4jDatabaseUsername,
-      configuration.neo4jDatabasePassword,
-    ),
-  );
-  const session = driver.session(configuration.neo4jDatabase === undefined
-    ? undefined
-    : { database: configuration.neo4jDatabase });
-  try {
-    const result = await session.run(operation.cypher, operation.parameters);
-    if (operation.kind === 'semantic-readiness-read') {
-      const readiness = result.records[0] && result.records[0].get('readiness');
-      return { records: readiness ? [readiness] : [] };
-    }
-    const records = result.records.map(record => ({
-      ...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);
-    const hasMore = records.length === operation.parameters.topK;
-    return {
-      records,
-      windowEvidence: {
-        offset,
-        windowSize,
-        returnedCount,
-        hasMore,
-        nextOffset: hasMore ? operation.parameters.topK : null,
-        windowExhausted: !hasMore,
-      },
-    };
-  } finally {
-    await session.close();
-    await driver.close();
+  const records = result.records.map(record => ({
+    ...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);
+  const hasMore = records.length === operation.parameters.topK;
+  return {
+    records,
+    windowEvidence: {
+      offset,
+      windowSize,
+      returnedCount,
+      hasMore,
+      nextOffset: hasMore ? operation.parameters.topK : null,
+      windowExhausted: !hasMore,
+    },
+  };
 }
 
 async function attemptAutomaticAlignment({ composition, request, alignment }) {

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

@@ -46,6 +46,18 @@ function isProjectInitialized(repositoryRoot) {
   }
 }
 
+// A readiness record proves the workspace was initialized (argo init) before.
+// The preheat only RECONCILES a previously-initialized-but-now-stale workspace;
+// a never-aligned workspace (brand-new project, or a synthetic test copy) must
+// be initialized explicitly, never rebuilt in the background.
+function hasReadinessRecord(repositoryRoot) {
+  try {
+    return fs.existsSync(readinessRecordPath(repositoryRoot));
+  } catch {
+    return false;
+  }
+}
+
 function alignmentError() {
   const error = new Error('SEMANTIC_AUTO_ALIGNMENT_FAILED');
   error.category = 'SEMANTIC_AUTO_ALIGNMENT_FAILED';
@@ -57,7 +69,7 @@ function alignmentError() {
 
 // Run the alignment (once). Returns a promise resolving to { status: 'aligned' }
 // or rejecting with the SEMANTIC_AUTO_ALIGNMENT_FAILED envelope.
-function runSemanticAlignment(repositoryRoot = getWorkspaceRoot()) {
+function runSemanticAlignment(repositoryRoot = getWorkspaceRoot(), options = {}) {
   if (inFlight) {
     return inFlight;
   }
@@ -70,6 +82,11 @@ function runSemanticAlignment(repositoryRoot = getWorkspaceRoot()) {
       env: process.env,
       stdio: ['ignore', 'ignore', 'inherit'],
     });
+    if (options.unref && typeof child.unref === 'function') {
+      // Background preheat must NOT keep the MCP process alive (a spawnSync-driven
+      // caller waits for the server to exit; an attached child would hang it).
+      child.unref();
+    }
     const finish = (failed, cause) => {
       inFlight = null;
       const ms = Date.now() - startedAt;
@@ -94,9 +111,14 @@ function preheatSemanticAlignment(repositoryRoot = getWorkspaceRoot()) {
   if (preheated || !repositoryRoot || !isProjectInitialized(repositoryRoot) || isSemanticReady(repositoryRoot)) {
     return;
   }
+  // Only reconcile a workspace that was initialized before (a readiness record
+  // exists); never rebuild a never-aligned project in the background.
+  if (!hasReadinessRecord(repositoryRoot)) {
+    return;
+  }
   preheated = true;
   console.error('[argo] readiness not aligned at startup; preheating semantic alignment in background…');
-  runSemanticAlignment(repositoryRoot).catch(() => {});
+  runSemanticAlignment(repositoryRoot, { unref: true }).catch(() => {});
 }
 
 module.exports = {
@@ -104,5 +126,6 @@ module.exports = {
   preheatSemanticAlignment,
   isSemanticReady,
   isProjectInitialized,
+  hasReadinessRecord,
   readinessRecordPath,
 };

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

@@ -2810,7 +2810,7 @@ async function buildSemanticDedupAdvisory(context, mutations, dependencies) {
       const intent = [element.type, element.name, element.description]
         .filter(part => typeof part === 'string' && part.trim() !== '')
         .join(' ');
-      const retrieved = await journey.query({ purpose: 'general', intent, topK: SEMANTIC_DEDUP_TOP_K, rerank: false });
+      const retrieved = await journey.query({ purpose: 'general', intent, topK: SEMANTIC_DEDUP_TOP_K, rerank: false, hybrid: false, scoreMode: 'similarity' });
       const source = retrieved && (retrieved.result || retrieved.document) || retrieved;
       const subset = buildCanonicalSemanticDocumentSubset(source, context.document);
       const elements = subset && subset.status === 'passed' && subset.document
@@ -3001,7 +3001,11 @@ async function executeSemanticSystemArchitectureQuery(args, dependencies) {
   try {
     const retrieved = await semanticRetrievalBoundary.retrieve(queryForRetrieval);
     if (canonicalSubsetContract) {
-      const subset = buildCanonicalSemanticDocumentSubset(retrieved, context.document);
+      // scoreMode:'similarity' (used by the write-path dedup gate) returns the
+      // true vector similarity instead of the closure rank-derived score.
+      const subset = buildCanonicalSemanticDocumentSubset(retrieved, context.document, {
+        preferSeedSimilarity: !!(query && query.scoreMode === 'similarity'),
+      });
       if (subset.status === 'failed') {
         return getSystemArchitectureResult(subset);
       }
@@ -3306,7 +3310,7 @@ function normalizeFailedSemanticResponse(payload, fallbackResponse) {
   });
 }
 
-function buildCanonicalSemanticDocumentSubset(source, canonicalDocument = undefined) {
+function buildCanonicalSemanticDocumentSubset(source, canonicalDocument = undefined, options = {}) {
   const evidence = source && typeof source === 'object' ? source : {};
   const endpointClosureRelationships = arrayAt(evidence, ['endpointClosure', 'relationships']);
   const viewClosureViews = arrayAt(evidence, ['viewClosure', 'views']);
@@ -3464,10 +3468,12 @@ function buildCanonicalSemanticDocumentSubset(source, canonicalDocument = undefi
       }
     }
   }
-  // buildCanonicalSemanticDocumentSubset may run a second time over a prior
-  // subset document (which no longer carries seedsByType); carry scores forward
-  // from evidence elements that already expose semanticScore.
-  for (const item of evidenceElements) {
+  // The closure's rank-derived score (0.99..0.8, by closure rank) must NOT
+  // overwrite a seed's TRUE similarity: when preferSeedSimilarity is set the
+  // caller needs the cosine, so this override is skipped (otherwise the dedup
+  // gate would flag every same-type seed in the top window regardless of actual
+  // similarity -- the false-positive defect).
+  if (!options.preferSeedSimilarity) for (const item of evidenceElements) {
     if (!item) continue;
     const numericScore = Number(item.semanticScore);
     if (!Number.isFinite(numericScore)) continue;

package/package.json

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