UCS Master List & versioning

ADMINISTRATOR The Master List is the deterministic, code-perfect source of truth for every component code in the fleet. Owned by the administrator. Lives in ucs_master_list, indexed by (version_id, code).

Foundation versions

ucs_foundation_versions(id, label, is_active, created_at) — exactly one row has is_active=1. Inactive versions remain readable for code_history audit.

Imported files

ucs_foundation_files stores chunked base64 of the imported source files, keyed by (version_id, kind):

Kind	What
master_full	Full Master XLSX
master_slim	Trimmed Master
manifest	UCS Manifest
l4	L4 family file
source	Original source XLSX
hierarchy_atlas	L1/L2/L3 atlas (v2.31.0.23 task — adds as the sixth file kind)

Single bridge resolver

src/cl-skeleton/active-master-resolver.js (resolveActiveMaster, listActiveMasters) is the single bridge. It prefers ucs_foundation_versions(is_active=1) and falls back to legacy master_lists. Every consumer (CL Skeleton, status endpoints, master validator) reads through this resolver.

Activating a new version

1. Admin → Foundation → Import new version
2. Upload the Master XLSX, Manifest, L4, Hierarchy Atlas
3. The system stores the files (chunked base64 in ucs_foundation_files) and writes the leaves to ucs_master_list at the new version_id
4. Do not activate yet — first run a cascade preview
5. After preview clean, activate. The system flips is_active=1 and runs cascade-apply
6. Post-activation: KB orphan heal + RAG mandatory-class backfill + provenance backfill

Proposals

Code proposals (e.g. PR #3 added 6 new codes for FAM-CERT-INS "INSURANCE & LIABILITY CERTIFICATES"):

1. Admin → Foundation → Proposals → New proposal
2. Fill (code, component_name, dept, family, parent_code)
3. Save as draft
4. Promote to a new version, or apply directly to the active version (administrator only, audit-logged)

Recent proposals from PR #3 (master_rev 2.7 → 2.13):

• 1.0.3.004 MLC INSURANCE — REPATRIATION (MSI)
• 1.0.3.005 MLC INSURANCE — CONTRACTUAL CLAIMS (MSI)
• 1.0.5.001 BUNKER CIVIL LIABILITY BCLC (TSI)
• 1.0.5.002 WRECK REMOVAL WRC (TSI)
• 1.0.5.003 P&I CLUB ENTRY (MSI)
• 1.1.3.021 FOAM CONCENTRATE ANALYSIS (MSI)