feat(normalizer): real store-backed regeneration + working normalize endpoint

- verisim-api regenerator module: StoreRegenerator implements the
  normalizer's ModalityRegenerator against the live octad store.
  Supported repairs (all real write-backs through OctadStore::update,
  so WAL-logged, versioned, and recorded on the provenance chain as
  'normalized' events):
    Graph -> Document  (rebuild relations section from actual edges)
    Document -> Vector (deterministic feature-hashing embedding)
    Document/Vector -> Tensor (1-D feature tensor)
  Unsupported pairs return honest errors instead of fake success.
  measure_drift re-reads persisted state and scores via drift_compute.
- AppState gains a RegenerationEngine wired to StoreRegenerator, with a
  content-modality authority order (provenance/temporal excluded as
  regeneration sources: audit records, not content).
- POST /normalizer/trigger/{id} replaces the 202 no-op: measures drift,
  picks the worst repairable component, runs the engine, re-measures
  from persisted state, feeds the aggregates, and returns
  action/before/after + the full post-repair component report.
- Tests: hash-embedding determinism, relations-section idempotency, and
  an end-to-end integration test (drift 0.5 -> repaired -> 0.0,
  provenance chain extended, second call no_action_needed).
  Workspace: 620 passed / 0 failed; clippy clean under -D warnings.

Closes Week-1 items 3-4 of docs/reviews/2026-06-11-deep-review-and-july-1-plan.adoc

https://claude.ai/code/session_01E8BpV19yxhf67UrCrvkfTr

Author: claude

Cargo.lock

@@ -25,6 +25,7 @@ verisim-planner = { path = "../verisim-planner" }
 
 axum.workspace = true
 tokio.workspace = true
+async-trait.workspace = true
 tower.workspace = true
 hyper.workspace = true
 serde.workspace = true

rust-core/verisim-api/Cargo.toml

@@ -11,6 +11,7 @@ pub mod federation;
 pub mod graphql;
 pub mod grpc;
 pub mod rbac;
+pub mod regenerator;
 pub mod transaction;
 pub mod vql;
 
@@ -36,6 +37,9 @@ use verisim_drift::{DriftDetector, DriftMetrics, DriftThresholds, DriftType};
 use verisim_graph::RedbGraphStore;
 #[cfg(not(feature = "persistent"))]
 use verisim_graph::SimpleGraphStore;
+use verisim_normalizer::regeneration::{
+    Modality as RegenModality, RegenerationConfig, RegenerationEngine, RegenerationResult,
+};
 use verisim_normalizer::{create_default_normalizer, Normalizer, NormalizerStatus};
 use verisim_octad::{
     BoundingBox, Coordinates, InMemoryOctadStore, OctadConfig, OctadDocumentInput, OctadGraphInput,
@@ -501,6 +505,7 @@ pub struct AppState {
     pub octad_store: Arc<ConcreteOctadStore>,
     pub drift_detector: Arc<DriftDetector>,
     pub normalizer: Arc<Normalizer>,
+    pub regeneration_engine: Arc<RegenerationEngine>,
     pub planner: Arc<Mutex<Planner>>,
     pub plan_cache: Arc<PlanCache>,
     pub slow_query_log: Arc<SlowQueryLog>,
@@ -666,6 +671,27 @@ impl AppState {
 
         let drift_detector = Arc::new(DriftDetector::new(DriftThresholds::default()));
         let normalizer = Arc::new(create_default_normalizer(drift_detector.clone()).await);
+        // Authority order restricted to content modalities: provenance and
+        // temporal are audit/history records, not content a modality can be
+        // regenerated FROM (under the default order, the ever-present
+        // provenance chain would win source selection for every repair).
+        let regeneration_engine = Arc::new(RegenerationEngine::with_regenerator(
+            RegenerationConfig {
+                authority_order: vec![
+                    RegenModality::Document,
+                    RegenModality::Semantic,
+                    RegenModality::Graph,
+                    RegenModality::Vector,
+                    RegenModality::Tensor,
+                    RegenModality::Spatial,
+                ],
+                ..Default::default()
+            },
+            Arc::new(regenerator::StoreRegenerator::new(
+                octad_store.clone(),
+                config.vector_dimension,
+            )),
+        ));
 
         let planner = Arc::new(Mutex::new(Planner::new(PlannerConfig::default())));
         let plan_cache = Arc::new(PlanCache::new(CacheConfig::default()));
@@ -688,6 +714,7 @@ impl AppState {
             octad_store,
             drift_detector,
             normalizer,
+            regeneration_engine,
             planner,
             plan_cache,
             slow_query_log,
@@ -1250,28 +1277,141 @@ async fn normalizer_status_handler(
     Ok(Json(status))
 }
 
-/// Trigger normalization handler
+/// Outcome of a normalization request: measured drift before/after plus
+/// what the regeneration engine actually did.
+#[derive(Debug, Serialize, Deserialize)]
+pub struct NormalizeResponse {
+    pub entity_id: String,
+    /// "repaired" | "no_action_needed" | "pending_resolution" | "failed"
+    pub action: String,
+    /// The modality that was regenerated, when a repair was attempted.
+    pub modality: Option<String>,
+    /// Source modality used for the repair, when known.
+    pub source_modality: Option<String>,
+    pub reason: Option<String>,
+    pub before_score: f64,
+    pub after_score: Option<f64>,
+    /// Full per-component drift report measured after the action.
+    pub report_after: drift_compute::EntityDriftReport,
+}
+
+/// Modality targeted for repair, derived from the worst measured component.
+fn repair_target(report: &drift_compute::EntityDriftReport) -> Option<(RegenModality, f64)> {
+    report
+        .components
+        .iter()
+        .filter(|c| c.computable && c.score > 0.0)
+        .filter_map(|c| {
+            // Only components with an implemented regeneration path map to
+            // a repair target; the rest are detect-only for now.
+            let modality = match c.drift_type.as_str() {
+                "graph_document_drift" => Some(RegenModality::Document),
+                "tensor_drift" => Some(RegenModality::Tensor),
+                "semantic_vector_drift" => Some(RegenModality::Vector),
+                _ => None,
+            };
+            modality.map(|m| (m, c.score))
+        })
+        .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal))
+}
+
+/// Trigger normalization: measure the entity's drift, pick the worst
+/// repairable component, run the regeneration engine (which writes the
+/// repair back through the store), and report measured before/after scores.
 #[instrument(skip(state))]
 async fn trigger_normalization_handler(
     State(state): State<AppState>,
     Path(id): Path<String>,
-) -> Result<StatusCode, ApiError> {
+) -> Result<(StatusCode, Json<NormalizeResponse>), ApiError> {
     validate_octad_id(&id)?;
     let octad_id = OctadId::new(&id);
 
-    // Check if octad exists
-    let _octad = state
+    let octad = state
         .octad_store
         .get(&octad_id)
         .await
         .map_err(|e| ApiError::Internal(e.to_string()))?
         .ok_or_else(|| ApiError::NotFound(format!("Octad {} not found", id)))?;
 
-    // In a full implementation, this would trigger actual normalization
-    // For now, we just verify the octad exists and return accepted
-    info!(id = %id, "Normalization triggered for octad");
+    let before = drift_compute::compute_entity_drift(&state.octad_store, &octad, None).await;
 
-    Ok(StatusCode::ACCEPTED)
+    let Some((target, score)) = repair_target(&before) else {
+        return Ok((
+            StatusCode::OK,
+            Json(NormalizeResponse {
+                entity_id: id,
+                action: "no_action_needed".to_string(),
+                modality: None,
+                source_modality: None,
+                reason: Some("no repairable drift component above zero".to_string()),
+                before_score: before.overall_score,
+                after_score: None,
+                report_after: before,
+            }),
+        ));
+    };
+
+    info!(id = %id, modality = %target, score, "Normalization triggered for octad");
+    let result = state
+        .regeneration_engine
+        .regenerate(&octad, target, score)
+        .await;
+
+    // Re-measure from the persisted state and feed the aggregates, so
+    // /drift/status reflects the post-repair reality.
+    let fresh = state
+        .octad_store
+        .get(&octad_id)
+        .await
+        .map_err(|e| ApiError::Internal(e.to_string()))?
+        .ok_or_else(|| ApiError::NotFound(format!("Octad {} not found", id)))?;
+    let after = drift_compute::compute_entity_drift(&state.octad_store, &fresh, None).await;
+    drift_compute::record_entity_drift(&state.drift_detector, &after).await;
+
+    let response = match result {
+        RegenerationResult::Repaired { event } => NormalizeResponse {
+            entity_id: id,
+            action: "repaired".to_string(),
+            modality: Some(event.drifted_modality.to_string()),
+            source_modality: event.source_modality.map(|m| m.to_string()),
+            reason: None,
+            before_score: score,
+            after_score: event.post_drift_score,
+            report_after: after,
+        },
+        RegenerationResult::NoActionNeeded => NormalizeResponse {
+            entity_id: id,
+            action: "no_action_needed".to_string(),
+            modality: Some(target.to_string()),
+            source_modality: None,
+            reason: Some("drift score at or below the engine threshold".to_string()),
+            before_score: score,
+            after_score: None,
+            report_after: after,
+        },
+        RegenerationResult::PendingResolution { reason, .. } => NormalizeResponse {
+            entity_id: id,
+            action: "pending_resolution".to_string(),
+            modality: Some(target.to_string()),
+            source_modality: None,
+            reason: Some(reason),
+            before_score: score,
+            after_score: None,
+            report_after: after,
+        },
+        RegenerationResult::Failed { error } => NormalizeResponse {
+            entity_id: id,
+            action: "failed".to_string(),
+            modality: Some(target.to_string()),
+            source_modality: None,
+            reason: Some(error),
+            before_score: score,
+            after_score: None,
+            report_after: after,
+        },
+    };
+
+    Ok((StatusCode::OK, Json(response)))
 }
 
 // --- Query Planner Handlers ---
@@ -2746,4 +2886,93 @@ mod tests {
         );
         assert_eq!(after, 0.0);
     }
+
+    /// The full loop: measured drift -> normalize -> regeneration engine
+    /// repairs the document from the graph -> re-measured drift falls to
+    /// zero -> the repair is recorded in the provenance chain.
+    #[tokio::test]
+    async fn test_normalize_repairs_dissonant_entity() {
+        let state = create_test_state().await;
+        let app = build_router(state);
+
+        let created = post_octad(&app, &dissonant_octad_request()).await;
+        assert_eq!(created.provenance_chain_length, 1);
+
+        let response = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri(format!("/normalizer/trigger/{}", created.id))
+                    .body(Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::OK);
+        let body = axum::body::to_bytes(response.into_body(), 1024 * 1024)
+            .await
+            .unwrap();
+        let normalized: NormalizeResponse = serde_json::from_slice(&body).unwrap();
+
+        assert_eq!(
+            normalized.action, "repaired",
+            "reason: {:?}",
+            normalized.reason
+        );
+        assert_eq!(normalized.modality.as_deref(), Some("document"));
+        assert_eq!(normalized.source_modality.as_deref(), Some("graph"));
+        assert!(normalized.before_score > 0.0);
+        assert_eq!(
+            normalized.after_score,
+            Some(0.0),
+            "regenerated document must fully restore graph-document consonance"
+        );
+        let graph_doc_after = normalized
+            .report_after
+            .components
+            .iter()
+            .find(|c| c.drift_type == "graph_document_drift")
+            .expect("graph_document_drift component missing");
+        assert_eq!(graph_doc_after.score, 0.0);
+
+        // The repair itself must be on the provenance chain.
+        let response = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .uri(format!("/octads/{}", created.id))
+                    .body(Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::OK);
+        let body = axum::body::to_bytes(response.into_body(), 1024 * 1024)
+            .await
+            .unwrap();
+        let fetched: OctadResponse = serde_json::from_slice(&body).unwrap();
+        assert_eq!(
+            fetched.provenance_chain_length, 2,
+            "the normalized event must extend the provenance chain"
+        );
+
+        // A consonant entity has nothing to repair.
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri(format!("/normalizer/trigger/{}", created.id))
+                    .body(Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::OK);
+        let body = axum::body::to_bytes(response.into_body(), 1024 * 1024)
+            .await
+            .unwrap();
+        let second: NormalizeResponse = serde_json::from_slice(&body).unwrap();
+        assert_eq!(second.action, "no_action_needed");
+    }
 }