UCS Foundation cascade

ADMINISTRATOR When you activate a new Master version, the cascade re-aligns every dependent table. The two-step preview-then-apply UX shipped in v2.31.0.34 (preview) and v2.31.0.35 (apply).

Step 1 — Preview (read-only)

POST /api/admin/ucs-foundation/cascade-preview
Body:
  {
    "fromVersionId": 12,        // optional, defaults to current active
    "toVersionId":   13,
    "dryRun": true              // default
  }

Classifies each Master code as one of:

Class	Meaning
kept	Code unchanged
renamed	Same code, new component_name
moved	New L3 / dept
split	Old code → 2+ new codes (ambiguous; quarantine for operator pick)
merged	2+ old codes → 1 new code
deleted	Old code has no successor
new	New code with no predecessor

Returns per-table impact counts and sample rows that would be touched.

Step 2 — Apply (writes)

POST /api/admin/ucs-foundation/cascade-apply
Body:
  {
    "toVersionId":  13,
    "dryRun":       false,        // explicit
    "confirmApply": true          // REQUIRED when dryRun:false
  }

Three-way safety:

• dryRun defaults to true
• dryRun: false requires confirmApply: true
• toVersionId must satisfy is_active=1

Atomic D1 batch write across:

vessel_components.code
source_documents.g1_ucs_code
cl_builds.code references
cl_knowledge_base.target_code
vessel_particulars_provenance.field_path (when path includes a code)
pms_jobs.code
audit_log entries (one row per touched cell)

Quarantine guard: ambiguous splits route to operator quarantine pick (F-6 milestone — v2.31.0.36+).

Step 3 — RAG cascade (F-5 milestone, not yet shipped)

Reads audit_log details, rewrites rag_chunks.code in the RAG_DB binding. Until F-5 ships, RAG retrieval still has the old codes; reads via code_history redirect to the new code with a code_history_via=N annotation.

Step 4 — Post-cascade ops

In order, after a successful apply:

1. POST /api/admin/kb-orphan-heal { dryRun: true } — identify orphans
2. POST /api/admin/kb-orphan-heal { dryRun: false } — heal at Jaccard ≥ 0.72
3. POST /api/admin/backfill/rag-chunks-mandatory-class {} — re-classify chunks
4. (Optional) POST /api/admin/backfill/vessel-particulars-provenance {} if the cascade touched field_path