KB orphan heal

ADMINISTRATOR Re-maps quarantined cl_knowledge_base rows whose target_code no longer exists in the active Master, against the active Master, at Jaccard ≥ 0.72.

Why orphans exist

Two paths:

1. The active Master changed (cascade) and some KB target codes vanished
2. Migration 0089 quarantined the historical 2,419 / 2,952 orphan rows

Endpoints

GET  /api/admin/kb-orphan-count
POST /api/admin/kb-orphan-heal       { dryRun?: boolean = true }

Algorithm

SELECT cl_knowledge_base WHERE quarantined=1
For each orphan:
  candidates = SELECT FROM ucs_master_list
               WHERE component_name LIKE '%<token>%'
                 AND version_id IN (SELECT id FROM ucs_foundation_versions WHERE is_active=1)
  best = argmax(jaccard(orphan.target_code_text, candidate.component_name))
  if best.score >= 0.72:
    UPDATE cl_knowledge_base SET target_code = best.code, quarantined = 0
    sampleHeals.push (cap 10)
  else:
    sampleUnhealed.push (cap 10)
  on D1 error:
    errorSamples.push (cap 10) with raw e?.message

Response shape

{
  "scanned": 2419,
  "healed": 1873,
  "unhealed": 532,
  "errors": 14,
  "sampleHeals": [...],
  "sampleUnhealed": [...],
  "errorSamples": [...]
}

Operator workflow

1. Always dryRun first. POST /api/admin/kb-orphan-heal { "dryRun": true }
2. Inspect sampleHeals — does the Jaccard match make sense?
3. Inspect errorSamples — any SQLITE schema-drift errors? If so, fix the heal SQL before live run (see incident playbook for v2.31.0.20)
4. Live run: { "dryRun": false }
5. The completion posts an ai-status messenger thread (no dedupe — admin-triggered).