archgraph-argo 0.10.43 → 0.10.44

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

@@ -1,45 +1,45 @@
-function enforceCanonicalProjectionAuthority(input) {
-  const canonicalGraph = input && input.canonicalGraph;
-  const projection = input && input.projection;
-  if (!canonicalGraph || !projection) {
-    throw projectionConflict('Canonical graph and projection evidence are required');
-  }
-
-  const canonicalIds = collectCanonicalIds(canonicalGraph);
-  const projectionIds = new Set(
-    Array.isArray(projection.seeds)
-      ? projection.seeds.map(seed => seed && seed.id).filter(Boolean)
-      : [],
-  );
-  const versionAligned = projection.canonicalVersion === canonicalGraph.version;
-  const identitiesAligned = [...projectionIds].every(id => canonicalIds.has(id));
-
-  if (!versionAligned || !identitiesAligned) {
-    throw projectionConflict('Neo4j projection conflicts with canonical intent');
-  }
-
-  return {
-    status: 'passed',
-    canonicalAuthority: 'canonical',
-    document: canonicalGraph,
-    projection,
-  };
-}
-
-function collectCanonicalIds(graph) {
-  return new Set([
-    ...(graph.elements || []).map(entry => entry.id),
-    ...(graph.relationships || []).map(entry => entry.id),
-    ...(graph.views || []).map(entry => entry.view_id),
-  ].filter(Boolean));
-}
-
-function projectionConflict(message) {
-  const error = new Error(message);
-  error.category = 'CANONICAL_PROJECTION_CONFLICT';
-  return error;
-}
-
-module.exports = {
-  enforceCanonicalProjectionAuthority,
-};
+function enforceCanonicalProjectionAuthority(input) {
+  const canonicalGraph = input && input.canonicalGraph;
+  const projection = input && input.projection;
+  if (!canonicalGraph || !projection) {
+    throw projectionConflict('Canonical graph and projection evidence are required');
+  }
+
+  const canonicalIds = collectCanonicalIds(canonicalGraph);
+  const projectionIds = new Set(
+    Array.isArray(projection.seeds)
+      ? projection.seeds.map(seed => seed && seed.id).filter(Boolean)
+      : [],
+  );
+  const versionAligned = projection.canonicalVersion === canonicalGraph.version;
+  const identitiesAligned = [...projectionIds].every(id => canonicalIds.has(id));
+
+  if (!versionAligned || !identitiesAligned) {
+    throw projectionConflict('Neo4j projection conflicts with canonical intent');
+  }
+
+  return {
+    status: 'passed',
+    canonicalAuthority: 'canonical',
+    document: canonicalGraph,
+    projection,
+  };
+}
+
+function collectCanonicalIds(graph) {
+  return new Set([
+    ...(graph.elements || []).map(entry => entry.id),
+    ...(graph.relationships || []).map(entry => entry.id),
+    ...(graph.views || []).map(entry => entry.view_id),
+  ].filter(Boolean));
+}
+
+function projectionConflict(message) {
+  const error = new Error(message);
+  error.category = 'CANONICAL_PROJECTION_CONFLICT';
+  return error;
+}
+
+module.exports = {
+  enforceCanonicalProjectionAuthority,
+};

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

@@ -1,59 +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,
-};
+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

@@ -1,74 +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,
-};
+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/liveEmbeddingProviderClient.js

@@ -1,49 +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 };
+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 };

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

@@ -1,37 +1,37 @@
-function createNeo4jNativeRetrieval(dependencies = {}) {
-  const queryBoundary = dependencies.queryBoundary;
-  if (!queryBoundary || typeof queryBoundary.query !== 'function') {
-    throw new TypeError('queryBoundary.query is required');
-  }
-
-  return {
-    async retrieve(request) {
-      return queryBoundary.query(request);
-    },
-
-    async retrieveThresholdCandidates(request) {
-      if (typeof queryBoundary.queryThresholdCandidates === 'function') {
-        return queryBoundary.queryThresholdCandidates(request);
-      }
-      const result = await queryBoundary.query(request);
-      if (Array.isArray(result)) {
-        return result;
-      }
-      if (Array.isArray(result && result.thresholdCandidates)) {
-        return result.thresholdCandidates;
-      }
-      if (Array.isArray(result && result.seeds)) {
-        return result.seeds.map(seed => ({
-          objectType: seed.objectType,
-          id: seed.id,
-          score: typeof seed.score === 'number' ? seed.score : 1,
-        }));
-      }
-      return [];
-    },
-  };
-}
-
-module.exports = {
-  createNeo4jNativeRetrieval,
-};
+function createNeo4jNativeRetrieval(dependencies = {}) {
+  const queryBoundary = dependencies.queryBoundary;
+  if (!queryBoundary || typeof queryBoundary.query !== 'function') {
+    throw new TypeError('queryBoundary.query is required');
+  }
+
+  return {
+    async retrieve(request) {
+      return queryBoundary.query(request);
+    },
+
+    async retrieveThresholdCandidates(request) {
+      if (typeof queryBoundary.queryThresholdCandidates === 'function') {
+        return queryBoundary.queryThresholdCandidates(request);
+      }
+      const result = await queryBoundary.query(request);
+      if (Array.isArray(result)) {
+        return result;
+      }
+      if (Array.isArray(result && result.thresholdCandidates)) {
+        return result.thresholdCandidates;
+      }
+      if (Array.isArray(result && result.seeds)) {
+        return result.seeds.map(seed => ({
+          objectType: seed.objectType,
+          id: seed.id,
+          score: typeof seed.score === 'number' ? seed.score : 1,
+        }));
+      }
+      return [];
+    },
+  };
+}
+
+module.exports = {
+  createNeo4jNativeRetrieval,
+};

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

@@ -1,51 +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`.
+# 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`.