archgraph-argo 0.1.0

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

@@ -0,0 +1,59 @@
+function evaluateEmbeddingQualification(qualification) {
+  const supplied = qualification && typeof qualification === 'object'
+    ? qualification
+    : {};
+
+  if (supplied.approvedByHuman !== true) {
+    throw blockingError(
+      'EMBEDDING_QUALIFICATION_REQUIRED',
+      'Embedding configuration requires explicit human approval',
+      'approvedByHuman',
+    );
+  }
+
+  if (supplied.source === 'implicit-default') {
+    throw blockingError(
+      'IMPLICIT_EMBEDDING_DEFAULT_PROHIBITED',
+      'Implicit embedding defaults cannot qualify index delivery',
+      'source',
+    );
+  }
+
+  for (const field of ['provider', 'model', 'version']) {
+    if (typeof supplied[field] !== 'string' || supplied[field].trim().length === 0) {
+      throw blockingError(
+        'EMBEDDING_CONFIGURATION_REQUIRED',
+        `${field} must be explicitly supplied`,
+        field,
+      );
+    }
+  }
+
+  if (!Number.isInteger(supplied.dimensions) || supplied.dimensions <= 0) {
+    throw blockingError(
+      'EMBEDDING_CONFIGURATION_REQUIRED',
+      'dimensions must be an explicitly supplied positive integer',
+      'dimensions',
+    );
+  }
+
+  return {
+    status: 'approved',
+    approvedByHuman: true,
+    provider: supplied.provider.trim(),
+    model: supplied.model.trim(),
+    version: supplied.version.trim(),
+    dimensions: supplied.dimensions,
+  };
+}
+
+function blockingError(category, message, field) {
+  const error = new Error(message);
+  error.category = category;
+  error.field = field;
+  return error;
+}
+
+module.exports = {
+  evaluateEmbeddingQualification,
+};

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

@@ -0,0 +1,74 @@
+const REQUIRED_FIELDS = [
+  'neo4jUri',
+  'neo4jUsername',
+  'neo4jPassword',
+  'embeddingCredential',
+];
+const APPROVED_SOURCE_KEYS = new Map([
+  ['neo4jUri', 'ARGO_NEO4J_DATABASE_URL'],
+  ['neo4jUsername', 'ARGO_NEO4J_DATABASE_USERNAME'],
+  ['neo4jPassword', 'ARGO_NEO4J_DATABASE_PASSWORD'],
+  ['embeddingCredential', 'QWEN_KEY'],
+]);
+
+function resolveExternalProductionConfig(configuration, context = {}) {
+  const supplied = configuration && typeof configuration === 'object'
+    ? configuration
+    : {};
+  validateApprovedSourceKeys(context.sourceKeys);
+
+  for (const field of REQUIRED_FIELDS) {
+    const value = supplied[field];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+      throw blockingError(
+        'EXTERNAL_CREDENTIALS_REQUIRED',
+        `${field} is required for ${context.operation || 'production operation'}`,
+        field,
+      );
+    }
+  }
+
+  return {
+    neo4jUri: supplied.neo4jUri.trim(),
+    neo4jUsername: supplied.neo4jUsername.trim(),
+    neo4jPassword: supplied.neo4jPassword,
+    embeddingCredential: supplied.embeddingCredential,
+    ...(supplied.neo4jDatabase === undefined
+      ? {}
+      : { neo4jDatabase: supplied.neo4jDatabase }),
+  };
+}
+
+function validateApprovedSourceKeys(sourceKeys) {
+  if (sourceKeys === undefined) {
+    return;
+  }
+  if (!(sourceKeys instanceof Map)) {
+    throw blockingError(
+      'UNAPPROVED_RUNTIME_CONFIG_SOURCE',
+      'runtime configuration source provenance is invalid',
+      'sourceKeys',
+    );
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (sourceKeys.get(field) !== APPROVED_SOURCE_KEYS.get(field)) {
+      throw blockingError(
+        'UNAPPROVED_RUNTIME_CONFIG_SOURCE',
+        `${field} is not resolved from its approved source`,
+        field,
+      );
+    }
+  }
+}
+
+function blockingError(category, message, field) {
+  const error = new Error(message);
+  error.category = category;
+  error.field = field;
+  return error;
+}
+
+module.exports = {
+  resolveExternalProductionConfig,
+};

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

@@ -0,0 +1,129 @@
+const { evaluateEmbeddingQualification } = require('./embeddingQualificationGate.js');
+const { createLiveEmbeddingProviderClient } = require('./liveEmbeddingProviderClient.js');
+
+const IDENTITY_FIELDS = Object.freeze([
+  'canonicalIdentity',
+  'canonicalVersion',
+  'contentIdentity',
+  'contentVersion',
+  'indexIdentity',
+  'indexVersion',
+]);
+
+function buildSemanticIndexEvidenceRecord(input = {}) {
+  const qualification = input.qualification && typeof input.qualification === 'object'
+    ? input.qualification
+    : {};
+  const objectType = input.objectType || 'Element';
+  const objectId = input.objectId || input.id || `${objectType.toLowerCase()}-record`;
+  const indexVersion = input.indexVersion || incrementVersion(input.contentVersion || input.canonicalVersion);
+  return Object.freeze({
+    objectType,
+    objectId,
+    channel: input.channel || channelForObjectType(objectType),
+    canonicalVersion: input.canonicalVersion || 'canonical-v1',
+    contentVersion: input.contentVersion || 'content-v1',
+    indexVersion,
+    provider: input.provider || qualification.provider || 'approved-test-provider',
+    model: input.model || qualification.model || 'approved-test-model',
+    version: input.version || input.modelVersion || qualification.version || '2026-07-24',
+    modelVersion: input.modelVersion || qualification.version || '2026-07-24',
+    dimensions: input.dimensions || qualification.dimensions || 1536,
+    ...(Array.isArray(input.vector) ? { vector: [...input.vector] } : {}),
+  });
+}
+
+function createLiveEmbeddingIndexGate(dependencies = {}) {
+  const { configuration, transport, indexBoundary } = dependencies;
+  if (!configuration || !indexBoundary || typeof indexBoundary.writeEvidence !== 'function') {
+    throw safeError('LIVE_PROVIDER_E2E_BOUNDARY_MISSING');
+  }
+  const client = createLiveEmbeddingProviderClient({ configuration, transport });
+  return Object.freeze({
+    async executeApprovedEmbedding(input) {
+      const qualification = evaluateEmbeddingQualification(input && input.qualification);
+      requireApprovedConfiguration(configuration, qualification);
+      requireInput(input);
+      const vector = await client.embed(input.input);
+      if (
+        vector.length !== 1024
+        || vector.some(value => typeof value !== 'number' || !Number.isFinite(value))
+      ) {
+        throw safeError('LIVE_PROVIDER_RESPONSE_INVALID');
+      }
+      const evidence = {
+        provider: qualification.provider,
+        model: qualification.model,
+        qualificationVersion: qualification.version,
+        dimensions: qualification.dimensions,
+        ...Object.fromEntries(IDENTITY_FIELDS.map(field => [field, input[field]])),
+        vector,
+      };
+      try {
+        await indexBoundary.writeEvidence(evidence);
+      } catch {
+        throw safeError('LIVE_PROVIDER_INDEX_WRITE_PROHIBITED');
+      }
+      return Object.freeze({
+        qualification: Object.freeze({ ...qualification }),
+        vector,
+        evidence: Object.freeze(evidence),
+      });
+    },
+  });
+}
+
+function requireApprovedConfiguration(configuration, qualification) {
+  if (
+    qualification.provider !== configuration.embeddingProvider
+    || qualification.model !== configuration.embeddingModel
+    || qualification.version !== configuration.embeddingModelVersion
+    || qualification.dimensions !== configuration.embeddingDimensions
+    || qualification.dimensions !== 1024
+  ) {
+    throw safeError('LIVE_PROVIDER_INDEX_WRITE_PROHIBITED');
+  }
+}
+
+function requireInput(input) {
+  if (!input || typeof input.input !== 'string' || input.input.trim() === '') {
+    throw safeError('LIVE_PROVIDER_INDEX_WRITE_PROHIBITED');
+  }
+  for (const field of IDENTITY_FIELDS) {
+    if (typeof input[field] !== 'string' || input[field].trim() === '') {
+      throw safeError('LIVE_PROVIDER_INDEX_WRITE_PROHIBITED');
+    }
+  }
+}
+
+function safeError(category) {
+  const error = new Error(category);
+  error.category = category;
+  return error;
+}
+
+function channelForObjectType(objectType) {
+  if (objectType === 'ArchitectureRelationship') {
+    return 'relationships';
+  }
+  if (objectType === 'View') {
+    return 'views';
+  }
+  return 'elements';
+}
+
+function incrementVersion(value) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    return 'index-v1';
+  }
+  const numericSuffix = value.match(/^(.*?)(\d+)$/);
+  if (!numericSuffix) {
+    return `${value}-indexed`;
+  }
+  return `${numericSuffix[1]}${Number(numericSuffix[2]) + 1}`;
+}
+
+module.exports = {
+  buildSemanticIndexEvidenceRecord,
+  createLiveEmbeddingIndexGate,
+};

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

@@ -0,0 +1,137 @@
+async function createApprovedNeo4jBoundary({ configuration, neo4j, logger }) {
+  if (
+    !configuration
+    || !neo4j
+    || !neo4j.auth
+    || typeof neo4j.auth.basic !== 'function'
+    || typeof neo4j.driver !== 'function'
+  ) {
+    throw safeError('LIVE_PROVIDER_NEO4J_BOUNDARY_MISSING');
+  }
+  const uri = requireValue(configuration, 'neo4jDatabaseUrl');
+  const username = requireValue(configuration, 'neo4jDatabaseUsername');
+  const password = requireValue(configuration, 'neo4jDatabasePassword');
+  let driver;
+  try {
+    const authentication = neo4j.auth.basic(username, password);
+    driver = neo4j.driver(uri, authentication);
+    await driver.verifyConnectivity();
+  } catch {
+    if (driver && typeof driver.close === 'function') {
+      try { await driver.close(); } catch {}
+    }
+    throw safeError('LIVE_PROVIDER_OPERATION_FAILED');
+  }
+
+  let closed = false;
+  async function query(cypher, parameters) {
+    if (closed) throw safeError('LIVE_PROVIDER_OPERATION_FAILED');
+    const session = driver.session();
+    try {
+      return await session.run(cypher, parameters);
+    } catch {
+      throw safeError('LIVE_PROVIDER_OPERATION_FAILED');
+    } finally {
+      try { await session.close(); } catch {}
+    }
+  }
+
+  return Object.freeze({
+    async countWrites(runId) {
+      const result = await query(
+        'MATCH (e:ArgoLiveEmbeddingEvidence { runId: $runId }) RETURN count(e) AS count',
+        { runId },
+      );
+      const count = result.records[0].get('count');
+      return count && typeof count.toNumber === 'function' ? count.toNumber() : Number(count);
+    },
+    async writeEvidence(runId, evidence) {
+      if (evidence === undefined) {
+        evidence = runId;
+        runId = evidence.runId;
+      }
+      const normalized = normalizeEvidence(evidence);
+      await query(
+        'CREATE (e:ArgoLiveEmbeddingEvidence { runId: $runId, vector: $vector, provider: $provider, model: $model, qualificationVersion: $qualificationVersion, dimensions: $dimensions, canonicalIdentity: $canonicalIdentity, canonicalVersion: $canonicalVersion, contentIdentity: $contentIdentity, contentVersion: $contentVersion, indexIdentity: $indexIdentity, indexVersion: $indexVersion })',
+        { runId, ...normalized },
+      );
+    },
+    async readEvidence(runId) {
+      const result = await query(
+        'MATCH (e:ArgoLiveEmbeddingEvidence { runId: $runId }) RETURN e { .runId, .provider, .model, .qualificationVersion, .dimensions, .canonicalIdentity, .canonicalVersion, .contentIdentity, .contentVersion, .indexIdentity, .indexVersion, .vector } AS evidence',
+        { runId },
+      );
+      return result.records.map(record => normalizeNeo4jValue(record.get('evidence')));
+    },
+    async queryVectorEvidence(runId, vector, canonicalIdentities) {
+      if (!Array.isArray(vector) || vector.length !== 1024 || !Array.isArray(canonicalIdentities)) {
+        throw safeError('LIVE_PROVIDER_OPERATION_FAILED');
+      }
+      await query(
+        'CREATE VECTOR INDEX argo_live_embedding_vector IF NOT EXISTS FOR (e:ArgoLiveEmbeddingEvidence) ON (e.vector) OPTIONS { indexConfig: { `vector.dimensions`: 1024, `vector.similarity_function`: "cosine" } }',
+        {},
+      );
+      const result = await query(
+        'CALL db.index.vector.queryNodes("argo_live_embedding_vector", $limit, $vector) YIELD node, score WHERE node.runId = $runId AND node.canonicalIdentity IN $canonicalIdentities RETURN node { .canonicalIdentity, .canonicalVersion, .contentVersion, .indexVersion, .provider, .model, .qualificationVersion, .dimensions, .vector } AS evidence, score',
+        {
+          runId,
+          vector,
+          canonicalIdentities,
+          limit: Math.max(1, canonicalIdentities.length * 4),
+        },
+      );
+      return result.records.map(record => normalizeNeo4jValue(record.get('evidence')));
+    },
+    async cleanup(runId) {
+      await query('MATCH (e:ArgoLiveEmbeddingEvidence { runId: $runId }) DELETE e', { runId });
+      return this.countWrites(runId);
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      try {
+        await driver.close();
+      } catch {
+        throw safeError('LIVE_PROVIDER_OPERATION_FAILED');
+      }
+    },
+  });
+}
+
+function normalizeEvidence(evidence) {
+  const fields = [
+    'provider', 'model', 'qualificationVersion', 'dimensions', 'canonicalIdentity',
+    'canonicalVersion', 'contentIdentity', 'contentVersion', 'indexIdentity', 'indexVersion', 'vector',
+  ];
+  if (!evidence || fields.some(field => evidence[field] === undefined)) {
+    throw safeError('LIVE_PROVIDER_OPERATION_FAILED');
+  }
+  return Object.fromEntries(fields.map(field => [field, evidence[field]]));
+}
+
+function normalizeNeo4jValue(evidence) {
+  if (!evidence) return evidence;
+  const dimensions = evidence.dimensions;
+  return {
+    ...evidence,
+    dimensions: dimensions && typeof dimensions.toNumber === 'function'
+      ? dimensions.toNumber()
+      : dimensions,
+  };
+}
+
+function requireValue(configuration, field) {
+  const value = configuration[field];
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw safeError('LIVE_PROVIDER_NEO4J_BOUNDARY_MISSING');
+  }
+  return value;
+}
+
+function safeError(category) {
+  const error = new Error(category);
+  error.category = category;
+  return error;
+}
+
+module.exports = { createApprovedNeo4jBoundary };

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

@@ -0,0 +1,49 @@
+function createLiveEmbeddingProviderClient({ configuration, transport }) {
+  if (!configuration || !transport || typeof transport.request !== 'function') {
+    throw safeError('LIVE_PROVIDER_CONFIGURATION_REQUIRED');
+  }
+  return Object.freeze({
+    async embed(input) {
+      let response;
+      try {
+        response = await transport.request(
+          `${configuration.embeddingBaseUrl}/embeddings`,
+          {
+            method: 'POST',
+            headers: {
+              Authorization: `Bearer ${configuration.qwenKey}`,
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+              input,
+              model: configuration.embeddingModel,
+              dimensions: configuration.embeddingDimensions,
+            }),
+          },
+        );
+      } catch {
+        throw safeError('LIVE_PROVIDER_REQUEST_FAILED');
+      }
+      if (!response || response.ok !== true || typeof response.json !== 'function') {
+        throw safeError('LIVE_PROVIDER_REQUEST_FAILED');
+      }
+      let payload;
+      try {
+        payload = await response.json();
+      } catch {
+        throw safeError('LIVE_PROVIDER_RESPONSE_INVALID');
+      }
+      const vector = payload && payload.data && payload.data[0] && payload.data[0].embedding;
+      if (!Array.isArray(vector)) throw safeError('LIVE_PROVIDER_RESPONSE_INVALID');
+      return vector;
+    },
+  });
+}
+
+function safeError(category) {
+  const error = new Error(category);
+  error.category = category;
+  return error;
+}
+
+module.exports = { createLiveEmbeddingProviderClient };