archgraph-argo 0.20.6 → 0.20.8

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();
+        }
+      }
     },
   });
 }
@@ -236,8 +254,9 @@ async function executeWpP2Retrieval({
     configuration: configurationEvidence.configuration,
     transport: composition.transport,
   });
-  markPhase('retrieval:embed');
+  markPhase('retrieval:embed:start');
   const vector = await provider.embed(request.intent);
+  markPhase('retrieval:embed:done');
   requireQualifiedVector(vector);
   const purpose = request && typeof request.purpose === 'string' ? request.purpose : '';
   const strict = AUDIT_PURPOSES.has(purpose);
@@ -254,6 +273,7 @@ async function executeWpP2Retrieval({
   const pool = rerank ? Math.max(topK, rerankOptions.poolSize) : topK;
   const channelSeeds = [];
   for (const channel of CHANNELS) {
+    markPhase('retrieval:vector:' + channel.channel);
     const vectorSeeds = await exhaustChannel({
       channel,
       neo4jDriver: composition.neo4jDriver,
@@ -264,6 +284,7 @@ async function executeWpP2Retrieval({
     });
     let seeds = vectorSeeds;
     if (hybrid) {
+      markPhase('retrieval:lexical:' + channel.channel);
       const lexicalSeeds = await exhaustLexicalChannel({
         channel,
         neo4jDriver: composition.neo4jDriver,
@@ -276,7 +297,7 @@ async function executeWpP2Retrieval({
     channelSeeds.push({ channel, seeds });
   }
   if (rerank) {
-    markPhase('retrieval:rerank');
+    markPhase('retrieval:rerank:start');
     // Rerank every channel CONCURRENTLY: the LLM calls dominate latency and are
     // independent, so parallelizing turns the cost from sum(channels) into
     // ~one call. fail-open: a null/empty order keeps the original ordering.
@@ -292,6 +313,7 @@ async function executeWpP2Retrieval({
         : seeds
     )));
     channelSeeds.forEach((entry, index) => { entry.seeds = rerankedSeeds[index]; });
+    markPhase('retrieval:rerank:done');
   }
   const seedsByType = {};
   for (const { channel, seeds } of channelSeeds) {
@@ -329,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({
@@ -350,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 }) {
@@ -741,6 +787,7 @@ async function exhaustChannel({
   const effectiveMax = Number.isInteger(maxSeeds) && maxSeeds > 0 ? maxSeeds : Number.POSITIVE_INFINITY;
   let offset = 0;
   while (accepted.length < effectiveMax) {
+    markPhase('retrieval:vector-window:' + channel.channel);
     const parameters = Object.freeze({
       indexName: channel.indexName,
       channel: channel.channel,

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/package.json

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