archgraph-argo 0.1.0

package/argo/scripts/graph-rag/semantic-persistence/ARCHITECTURE.md

@@ -0,0 +1,51 @@
+# Production Semantic Persistence Contract
+
+This local contract refines `OVERALL_ARCHITECTURE.md` and the parent `.argo/scripts/graph-rag/ARCHITECTURE.md`.
+
+## Responsibilities
+
+- `productionSemanticBackfill.js` owns the explicit WP-P1 backfill use case through `createProductionSemanticBackfill(dependencies).execute({ explicitOptIn })`.
+- Backfill begins only after the injected structural-projection boundary proves the same canonical version complete. Structural projection is a prerequisite, not semantic readiness.
+- Backfill reads one immutable canonical snapshot and independently enumerates every Element, ArchitectureRelationship, and View. It never fabricates a canonical mutation to trigger embedding generation.
+- Work is bounded by an explicit positive batch size. Every channel has durable totals, completed counts, cursor, canonical version, retry, and isolated-failure checkpoints.
+- Resume starts from durable channel checkpoints and does not repeat completed work. Acceptance independently compares provider and durable-upsert canonical identities before and after interruption; an implementation-reported resume flag is not evidence. Rerun performs stable-identity upserts and is idempotent for unchanged canonical/content/index/provider/model/version/dimensions/vector evidence.
+- A record failure is observable and isolated from other records. Partial or failed channels remain non-Aligned. Alignment may become `Aligned` only after Element, ArchitectureRelationship, and View channels all report complete for the same canonical version.
+- `productionSemanticProjectionStore.js` owns `createProductionSemanticProjectionStore(dependencies)` and exposes only `upsertRecords(records)`, `deleteTombstones(tombstones)`, `readRecords()`, and `close()`.
+- `productionSemanticNeo4jAdapter.js` owns `createProductionSemanticNeo4jAdapter(dependencies)` as the concrete durable production projection adapter. `productionSemanticCheckpointStore.js` owns `createProductionSemanticCheckpointStore(dependencies)` as the concrete durable per-channel checkpoint adapter. Deterministic tests inject only a recording raw Neo4j driver beneath these production factories; they do not substitute an in-memory projection or checkpoint implementation.
+- The production store validates stable canonical identity and complete channel, canonical/content/index, provider/model/model-version/dimensions, and vector metadata before persistence.
+- The production store depends inward on a durable Neo4j persistence adapter. It must MERGE/upsert changed records by stable canonical identity and delete tombstones by that identity.
+- Production records have no `runId`; a `runId`-bearing record is rejected before persistence. The store's complete callable public surface is exactly `upsertRecords`, `deleteTombstones`, `readRecords`, and `close`: no cleanup, runId-delete, truncate, clear, or reset API is permitted. Production never imports or delegates to `liveEmbeddingNeo4jBoundary.js`.
+- Existing live E2E runId cleanup remains test-only and unchanged. It cannot select or delete production semantic projection labels or identities.
+- The same four-method production store is the only durable target for automatic incremental indexing. Successful batch and focused Element, ArchitectureRelationship, and View add/update/remove writes provide exact touched identities: add/update records use `upsertRecords`, removed identities use `deleteTombstones`, and unrelated records remain unchanged across restart. Incremental records carry the same complete canonical/content/index/provider/model/model-version/dimensions/vector contract as full reconciliation.
+- Readiness invalidation belongs to the canonical-write orchestration boundary and occurs before this store or provider is called. This directory may report persistence success/failure but cannot mark Aligned; queryability and global coherence are later outer checks.
+- External Neo4j and provider credentials use the existing approved external configuration and qualification boundaries. Missing configuration or provider qualification blocks before provider, projection, checkpoint, or index side effects. Missing `neo4jUri` blocks startup; tests never invent synchronization evidence.
+- Canonical JSON remains authority at `design/KG/SystemArchitecture.json`. The durable Neo4j records are subordinate projection/index state and have no API that writes canonical JSON.
+
+## Public interface
+
+- `createProductionSemanticBackfill(dependencies)` requires canonical-source, structural-projection, qualified-provider, durable projection-store, checkpoint-store, external configuration, qualification, and bounded-batch dependencies; it returns `execute({ explicitOptIn })`.
+- `createProductionSemanticProjectionStore(dependencies)` requires the concrete durable adapter, canonical-authority policy, external configuration, and qualified-provider evidence; it returns exactly the four store methods listed above.
+- `createProductionSemanticNeo4jAdapter(dependencies)` and `createProductionSemanticCheckpointStore(dependencies)` translate store/checkpoint operations to the configured durable Neo4j driver boundary.
+- The parent runtime exposes `runSemanticBackfill(request)` and composes the concrete adapter, store, checkpoint store, and backfill from `semanticPersistence` production dependencies.
+- The parent durable incremental lifecycle composes the existing projection store directly for exact touched upsert/tombstone operations. It does not reuse live-E2E `writeEvidence(runId, ...)` or cleanup APIs.
+- Canonical argo init privately delegates to `runtime.runSemanticBackfill(request)` after its exact enabled/valid gate decision. No standalone MCP backfill route is exposed. The private composition must exist without Harness injection; missing internal consent fails `SP01_EXPLICIT_OPT_IN_REQUIRED`, and structural/canonical mismatch fails `SP01_STRUCTURAL_VERSION_MISMATCH`, both before provider or durable effects. Structural mutation uses the incremental lifecycle and never fakes a full-backfill trigger.
+
+## Local dependencies
+
+- MCP gateway → production Graph RAG composition → semantic backfill → canonical/structural/provider/store/checkpoint ports.
+- Semantic backfill may depend on provider and projection interfaces; provider and store adapters must not depend outward on backfill orchestration.
+- Production semantic persistence may depend on the approved Neo4j JavaScript driver adapter and existing external configuration/qualification modules.
+- No file in this directory may depend on `tests/`, Python, Neo4j GenAI procedures, the live-E2E evidence boundary, or mutable canonical-write internals.
+- Checkpoint persistence and semantic projection persistence are durable production state. Neither is a process-local map in production composition.
+
+## Owned tests
+
+- `tests/harness/productionSemanticPersistenceHarness.js`
+- `tests/explicit/entries/runProductionSemanticBackfill.js` — SP-01 control point: shipped non-injected JSON-RPC `tools/call` plus explicit backfill after structural projection. Observation: the default MCP path owns production composition and fails closed before secrets/Neo4j, while the deterministic injected raw-driver scenario proves independent complete channels, bounded checkpoints, interruption/resume, isolated failure, idempotent rerun, complete metadata, no fake mutation, and alignment only after all channels complete.
+- `tests/explicit/entries/runPersistentSemanticProjectionLifecycle.js` — SP-02 control point: durable projection across restart, changed-record upsert, tombstone deletion, and unrelated live-E2E cleanup. Observation: stable identity and metadata survive, production has no runId cleanup, canonical authority remains intact, and Neo4j remains subordinate.
+- `tests/architecture/production-semantic-persistence/architecture-boundary.guard.js` — `ArchitectureBoundaryGuard`.
+- `tests/architecture/production-semantic-persistence/dependency-direction.guard.js` — `DependencyDirectionGuard`.
+- `tests/architecture/production-semantic-persistence/explicit-entrypoint-correctness.guard.js` — `ExplicitEntrypointCorrectnessGuard`.
+- `tests/architecture/production-semantic-persistence/implementation-traceability.guard.js` — `KeyImplementationTraceabilityGuard`.
+
+All owned Harness, explicit entrypoints, guards, this contract, the root and parent contracts, incoming intent handoff, runner failure records, and canonical graph are frozen during Coding/Repair. The protected fixture is `canonicalThreeChannelFixture`; the protected baseline is the committed WP-P1 pre-coding full-run result in `design/KG/test-failure-records.json`.

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

@@ -0,0 +1,241 @@
+const crypto = require('node:crypto');
+const {
+  evaluateEmbeddingQualification,
+} = require('../embeddingQualificationGate.js');
+
+const CHANNELS = Object.freeze(['Element', 'ArchitectureRelationship', 'View']);
+const CHANNEL_SOURCES = Object.freeze({
+  Element: Object.freeze({ property: 'elements', identity: record => record.id }),
+  ArchitectureRelationship: Object.freeze({ property: 'relationships', identity: record => record.id }),
+  View: Object.freeze({ property: 'views', identity: record => record.view_id }),
+});
+
+function createProductionSemanticBackfill(dependencies = {}) {
+  requireBoundary(dependencies.canonicalSource, 'readSnapshot', 'canonicalSource');
+  requireBoundary(dependencies.structuralProjection, 'requireComplete', 'structuralProjection');
+  requireBoundary(dependencies.embeddingProvider, 'embedBatch', 'embeddingProvider');
+  requireBoundary(dependencies.projectionStore, 'upsertRecords', 'projectionStore');
+  requireBoundary(dependencies.checkpointStore, 'readCheckpoint', 'checkpointStore');
+  requireBoundary(dependencies.checkpointStore, 'writeCheckpoint', 'checkpointStore');
+  const batchSize = dependencies.batchSize;
+  if (!Number.isInteger(batchSize) || batchSize <= 0) {
+    throw categoryError('SP01_POSITIVE_BATCH_SIZE_REQUIRED', 'batchSize');
+  }
+
+  return Object.freeze({
+    async execute(request = {}) {
+      if (request.explicitOptIn !== true) {
+        throw categoryError('SP01_EXPLICIT_OPT_IN_REQUIRED', 'explicitOptIn');
+      }
+      requireExternalConfiguration(dependencies.configuration);
+      const qualification = evaluateEmbeddingQualification(dependencies.qualification);
+
+      const structural = await dependencies.structuralProjection.requireComplete();
+      const snapshot = await dependencies.canonicalSource.readSnapshot();
+      const canonicalVersion = snapshot && snapshot.version;
+      if (
+        !structural
+        || structural.status !== 'complete'
+        || !isNonBlankString(structural.canonicalVersion)
+        || structural.canonicalVersion !== canonicalVersion
+      ) {
+        throw categoryError('SP01_STRUCTURAL_VERSION_MISMATCH', 'canonicalVersion');
+      }
+
+      const channels = {};
+      for (const channel of CHANNELS) {
+        channels[channel] = await processChannel({
+          channel,
+          snapshot,
+          canonicalVersion,
+          qualification,
+          batchSize,
+          embeddingProvider: dependencies.embeddingProvider,
+          projectionStore: dependencies.projectionStore,
+          checkpointStore: dependencies.checkpointStore,
+        });
+      }
+      const aligned = CHANNELS.every(channel => (
+        channels[channel].status === 'complete'
+        && channels[channel].canonicalVersion === canonicalVersion
+      ));
+      return Object.freeze({
+        status: aligned ? 'passed' : 'partial',
+        canonicalVersion,
+        alignmentState: aligned ? 'Aligned' : 'Updating',
+        channels: Object.freeze(channels),
+      });
+    },
+  });
+}
+
+async function processChannel(options) {
+  const source = CHANNEL_SOURCES[options.channel];
+  const canonicalRecords = (options.snapshot[source.property] || []).map(record => Object.freeze({
+    canonicalIdentity: `${options.channel}:${source.identity(record)}`,
+    channel: options.channel,
+    canonicalObject: record,
+  }));
+  const stored = await options.checkpointStore.readCheckpoint(options.channel);
+  const checkpoint = stored && stored.canonicalVersion === options.canonicalVersion
+    ? mutableCheckpoint(stored, canonicalRecords.length)
+    : emptyCheckpoint(options.channel, options.canonicalVersion, canonicalRecords.length);
+  const attempts = new Map();
+
+  while (checkpoint.completedCanonicalIdentities.length < canonicalRecords.length) {
+    const completed = new Set(checkpoint.completedCanonicalIdentities);
+    const pending = canonicalRecords.filter(record => (
+      !completed.has(record.canonicalIdentity)
+      && (attempts.get(record.canonicalIdentity) || 0) < 2
+    ));
+    if (pending.length === 0) {
+      break;
+    }
+    const batch = pending.slice(0, options.batchSize);
+    for (const record of batch) {
+      attempts.set(record.canonicalIdentity, (attempts.get(record.canonicalIdentity) || 0) + 1);
+    }
+
+    const providerResult = await options.embeddingProvider.embedBatch(Object.freeze(batch));
+    const vectors = new Map((providerResult && providerResult.vectors ? providerResult.vectors : [])
+      .map(result => [result.canonicalIdentity, result.vector]));
+    const providerFailures = providerResult && Array.isArray(providerResult.failures)
+      ? providerResult.failures
+      : [];
+    const successfulRecords = [];
+    const currentFailures = [];
+
+    for (const record of batch) {
+      const vector = vectors.get(record.canonicalIdentity);
+      if (Array.isArray(vector)) {
+        successfulRecords.push(buildSemanticRecord(record, vector, options));
+        completed.add(record.canonicalIdentity);
+        continue;
+      }
+      const observed = providerFailures.find(failure => failure.canonicalIdentity === record.canonicalIdentity);
+      currentFailures.push(Object.freeze({
+        canonicalIdentity: record.canonicalIdentity,
+        category: observed && observed.category ? observed.category : 'PROVIDER_RECORD_FAILED',
+      }));
+    }
+
+    if (successfulRecords.length > 0) {
+      await options.projectionStore.upsertRecords(successfulRecords);
+    }
+    checkpoint.completedCanonicalIdentities = [...completed];
+    checkpoint.completedCount = completed.size;
+    checkpoint.cursor = completed.size;
+    checkpoint.retries += currentFailures.length;
+    checkpoint.isolatedFailures = mergeFailures(checkpoint.isolatedFailures, currentFailures);
+    checkpoint.status = completed.size === canonicalRecords.length ? 'complete' : 'partial';
+    await options.checkpointStore.writeCheckpoint(freezeCheckpoint(checkpoint));
+  }
+
+  return Object.freeze({
+    status: checkpoint.completedCanonicalIdentities.length === canonicalRecords.length ? 'complete' : 'partial',
+    canonicalVersion: options.canonicalVersion,
+    total: canonicalRecords.length,
+    completedCount: checkpoint.completedCanonicalIdentities.length,
+    cursor: checkpoint.cursor,
+    retries: checkpoint.retries,
+    isolatedFailures: Object.freeze(checkpoint.isolatedFailures.map(failure => Object.freeze({ ...failure }))),
+  });
+}
+
+function buildSemanticRecord(record, vector, options) {
+  const contentHash = crypto.createHash('sha256')
+    .update(JSON.stringify(record.canonicalObject))
+    .digest('hex');
+  return Object.freeze({
+    canonicalIdentity: record.canonicalIdentity,
+    channel: record.channel,
+    canonicalVersion: options.canonicalVersion,
+    contentVersion: `content:${contentHash}`,
+    indexVersion: `index:${contentHash}`,
+    provider: options.qualification.provider,
+    model: options.qualification.model,
+    modelVersion: options.qualification.version,
+    dimensions: options.qualification.dimensions,
+    vector: Object.freeze([...vector]),
+  });
+}
+
+function emptyCheckpoint(channel, canonicalVersion, total) {
+  return {
+    channel,
+    canonicalVersion,
+    total,
+    completedCount: 0,
+    cursor: 0,
+    retries: 0,
+    completedCanonicalIdentities: [],
+    isolatedFailures: [],
+    status: total === 0 ? 'complete' : 'pending',
+  };
+}
+
+function mutableCheckpoint(checkpoint, total) {
+  return {
+    channel: checkpoint.channel,
+    canonicalVersion: checkpoint.canonicalVersion,
+    total,
+    completedCount: checkpoint.completedCount || 0,
+    cursor: checkpoint.cursor || 0,
+    retries: checkpoint.retries || 0,
+    completedCanonicalIdentities: [...(checkpoint.completedCanonicalIdentities || [])],
+    isolatedFailures: [...(checkpoint.isolatedFailures || [])],
+    status: checkpoint.status || 'pending',
+  };
+}
+
+function freezeCheckpoint(checkpoint) {
+  return Object.freeze({
+    ...checkpoint,
+    completedCanonicalIdentities: Object.freeze([...checkpoint.completedCanonicalIdentities]),
+    isolatedFailures: Object.freeze(checkpoint.isolatedFailures.map(failure => Object.freeze({ ...failure }))),
+  });
+}
+
+function mergeFailures(existing, current) {
+  const merged = new Map(existing.map(failure => [failure.canonicalIdentity, failure]));
+  for (const failure of current) {
+    merged.set(failure.canonicalIdentity, failure);
+  }
+  return [...merged.values()];
+}
+
+function requireBoundary(boundary, method, name) {
+  if (!boundary || typeof boundary[method] !== 'function') {
+    throw new TypeError(`${name}.${method} is required`);
+  }
+}
+
+function requireExternalConfiguration(configuration) {
+  const supplied = configuration && typeof configuration === 'object' ? configuration : {};
+  const required = [
+    ['neo4jDatabaseUrl', 'neo4jUri'],
+    ['neo4jDatabaseUsername', 'neo4jUsername'],
+    ['neo4jDatabasePassword', 'neo4jPassword'],
+    ['embeddingCredential'],
+  ];
+  for (const alternatives of required) {
+    if (alternatives.map(field => supplied[field]).find(isNonBlankString) === undefined) {
+      throw categoryError('EXTERNAL_CREDENTIALS_REQUIRED', alternatives[0]);
+    }
+  }
+}
+
+function isNonBlankString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function categoryError(category, field) {
+  const error = new Error(category);
+  error.category = category;
+  error.field = field;
+  return error;
+}
+
+module.exports = {
+  createProductionSemanticBackfill,
+};

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

@@ -0,0 +1,99 @@
+const CHECKPOINT_LABEL = 'ArgoProductionSemanticCheckpoint';
+
+function createProductionSemanticCheckpointStore(dependencies = {}) {
+  const { driver } = dependencies;
+  if (!driver || (typeof driver.execute !== 'function' && typeof driver.session !== 'function')) {
+    throw new TypeError('driver.execute or driver.session is required');
+  }
+
+  return Object.freeze({
+    async readCheckpoint(channel) {
+      if (typeof driver.execute === 'function') {
+        const result = await driver.execute(Object.freeze({
+          kind: 'semantic-checkpoint-read',
+          channel,
+        }));
+        return result && result.checkpoint ? cloneCheckpoint(result.checkpoint) : undefined;
+      }
+      return withSession(driver, dependencies.configuration, async session => {
+        const result = await executeRead(
+          session,
+          `MATCH (checkpoint:${CHECKPOINT_LABEL} {channel: $channel}) RETURN checkpoint.payload AS payload`,
+          { channel },
+        );
+        const record = result.records && result.records[0];
+        const payload = record && typeof record.get === 'function' ? record.get('payload') : record && record.payload;
+        return typeof payload === 'string' ? cloneCheckpoint(JSON.parse(payload)) : undefined;
+      });
+    },
+
+    async writeCheckpoint(checkpoint) {
+      const durableCheckpoint = cloneCheckpoint(checkpoint);
+      if (typeof driver.execute === 'function') {
+        const result = await driver.execute(Object.freeze({
+          kind: 'semantic-checkpoint-write',
+          checkpoint: durableCheckpoint,
+        }));
+        return result && result.checkpoint ? cloneCheckpoint(result.checkpoint) : durableCheckpoint;
+      }
+      await withSession(driver, dependencies.configuration, session => executeWrite(
+        session,
+        [
+          `MERGE (checkpoint:${CHECKPOINT_LABEL} {channel: $channel})`,
+          'SET checkpoint.canonicalVersion = $canonicalVersion, checkpoint.payload = $payload',
+          'RETURN checkpoint.payload AS payload',
+        ].join('\n'),
+        {
+          channel: durableCheckpoint.channel,
+          canonicalVersion: durableCheckpoint.canonicalVersion,
+          payload: JSON.stringify(durableCheckpoint),
+        },
+      ));
+      return durableCheckpoint;
+    },
+
+    async close() {
+      if (typeof driver.close === 'function') {
+        await driver.close();
+      }
+    },
+  });
+}
+
+async function withSession(driver, configuration, action) {
+  const database = configuration && configuration.neo4jDatabase;
+  const session = driver.session(database === undefined ? undefined : { database });
+  try {
+    return await action(session);
+  } finally {
+    if (session && typeof session.close === 'function') {
+      await session.close();
+    }
+  }
+}
+
+function executeWrite(session, query, parameters) {
+  if (typeof session.executeWrite === 'function') {
+    return session.executeWrite(transaction => transaction.run(query, parameters));
+  }
+  return session.run(query, parameters);
+}
+
+function executeRead(session, query, parameters) {
+  if (typeof session.executeRead === 'function') {
+    return session.executeRead(transaction => transaction.run(query, parameters));
+  }
+  return session.run(query, parameters);
+}
+
+function cloneCheckpoint(checkpoint) {
+  return Object.freeze({
+    ...checkpoint,
+    completedCanonicalIdentities: Object.freeze([...(checkpoint.completedCanonicalIdentities || [])]),
+    isolatedFailures: Object.freeze((checkpoint.isolatedFailures || []).map(failure => Object.freeze({ ...failure }))),
+  });
+}
+
+module.exports = {
+  createProductionSemanticCheckpointStore,
+};

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

@@ -0,0 +1,149 @@
+const SEMANTIC_LABEL = 'ArgoProductionSemanticRecord';
+const CHANNEL_INDEXES = Object.freeze({
+  Element: Object.freeze({
+    label: 'ArgoProductionSemanticElement',
+    indexName: 'argo_production_semantic_element_vector',
+  }),
+  ArchitectureRelationship: Object.freeze({
+    label: 'ArgoProductionSemanticRelationship',
+    indexName: 'argo_production_semantic_relationship_vector',
+  }),
+  View: Object.freeze({
+    label: 'ArgoProductionSemanticView',
+    indexName: 'argo_production_semantic_view_vector',
+  }),
+});
+
+function createProductionSemanticNeo4jAdapter(dependencies = {}) {
+  const { driver } = dependencies;
+  if (!driver || (typeof driver.execute !== 'function' && typeof driver.session !== 'function')) {
+    throw new TypeError('driver.execute or driver.session is required');
+  }
+
+  return Object.freeze({
+    async upsertRecords(records) {
+      if (typeof driver.execute === 'function') {
+        return driver.execute(Object.freeze({
+          kind: 'semantic-record-upsert',
+          records: Object.freeze(records.map(cloneRecord)),
+        }));
+      }
+      return withSession(driver, dependencies.configuration, async session => {
+        await ensureVectorIndexes(session);
+        const results = [];
+        for (const [channel, definition] of Object.entries(CHANNEL_INDEXES)) {
+          const channelRecords = records.filter(record => record.channel === channel).map(cloneRecord);
+          if (channelRecords.length === 0) continue;
+          const query = [
+            'UNWIND $records AS record',
+            `MERGE (semantic:${SEMANTIC_LABEL} {canonicalIdentity: record.canonicalIdentity})`,
+            'SET semantic = record',
+            `SET semantic:${definition.label}`,
+            'RETURN count(semantic) AS count',
+          ].join('\n');
+          results.push(await executeWrite(session, query, { records: channelRecords }));
+        }
+        return results[results.length - 1] || { records: [] };
+      });
+    },
+
+    async deleteTombstones(tombstones) {
+      if (typeof driver.execute === 'function') {
+        return driver.execute(Object.freeze({
+          kind: 'semantic-record-delete-tombstones',
+          tombstones: Object.freeze(tombstones.map(cloneRecord)),
+        }));
+      }
+      return withSession(driver, dependencies.configuration, async session => {
+        const query = [
+          'UNWIND $canonicalIdentities AS canonicalIdentity',
+          `MATCH (semantic:${SEMANTIC_LABEL} {canonicalIdentity: canonicalIdentity})`,
+          'DETACH DELETE semantic',
+          'RETURN count(*) AS count',
+        ].join('\n');
+        return executeWrite(session, query, {
+          canonicalIdentities: tombstones.map(item => item.canonicalIdentity),
+        });
+      });
+    },
+
+    async readRecords() {
+      if (typeof driver.execute === 'function') {
+        const result = await driver.execute(Object.freeze({ kind: 'semantic-record-read-all' }));
+        return Object.freeze((result && result.records ? result.records : []).map(cloneRecord));
+      }
+      return withSession(driver, dependencies.configuration, async session => {
+        const result = await executeRead(
+          session,
+          `MATCH (semantic:${SEMANTIC_LABEL}) RETURN properties(semantic) AS record ORDER BY semantic.canonicalIdentity`,
+          {},
+        );
+        return Object.freeze((result.records || []).map(resultRecord).map(cloneRecord));
+      });
+    },
+
+    async close() {
+      if (typeof driver.close === 'function') {
+        await driver.close();
+      }
+    },
+  });
+}
+
+async function ensureVectorIndexes(session) {
+  for (const definition of Object.values(CHANNEL_INDEXES)) {
+    await executeWrite(
+      session,
+      [
+        `CREATE VECTOR INDEX ${definition.indexName} IF NOT EXISTS`,
+        `FOR (semantic:${definition.label}) ON (semantic.vector)`,
+        'OPTIONS { indexConfig: { `vector.dimensions`: 1024, `vector.similarity_function`: "cosine" } }',
+      ].join('\n'),
+      {},
+    );
+  }
+}
+
+async function withSession(driver, configuration, action) {
+  const database = configuration && configuration.neo4jDatabase;
+  const session = driver.session(database === undefined ? undefined : { database });
+  try {
+    return await action(session);
+  } finally {
+    if (session && typeof session.close === 'function') {
+      await session.close();
+    }
+  }
+}
+
+function executeWrite(session, query, parameters) {
+  if (typeof session.executeWrite === 'function') {
+    return session.executeWrite(transaction => transaction.run(query, parameters));
+  }
+  return session.run(query, parameters);
+}
+
+function executeRead(session, query, parameters) {
+  if (typeof session.executeRead === 'function') {
+    return session.executeRead(transaction => transaction.run(query, parameters));
+  }
+  return session.run(query, parameters);
+}
+
+function resultRecord(record) {
+  if (record && typeof record.get === 'function') {
+    return record.get('record');
+  }
+  return record && record.record ? record.record : record;
+}
+
+function cloneRecord(record) {
+  return Object.freeze({
+    ...record,
+    ...(Array.isArray(record && record.vector) ? { vector: Object.freeze([...record.vector]) } : {}),
+  });
+}
+
+module.exports = {
+  createProductionSemanticNeo4jAdapter,
+};