feat: cBioPortal→OMOP showcase — slice-0 concept mapping + slice-1 FK-closed OMOP shape with cross-study identity

[deanban]

Summary

Delivers the cBioPortal → OMOP mapping showcase end to end, in two vertical slices, keeping the SEMA core domain-generic (R29):

• Slice-0 — concept mapping. Deterministic OncoTree → standard OMOP Condition concept resolution, staged with provenance, gated by Gate-D-lite + contract conformance. Target contract is OMOP-standard-Condition (SNOMED and ICDO3 oncology extension), not SNOMED-only (bug-369).
• Slice-1 — FK-closed OMOP table shape + full identity. Materializes production-shaped omop.person + omop.condition_occurrence, FK-closed, with a two-level identity registry and deterministic cross-study person dedup (Stage B). All OMOP/cBio specifics live in showcase/cbioportal_to_omop/; the FK-closed harness, identity registry, and collapse engine stay generic in core.

Live results (Databricks workspace.omop_stage_a)

Two MSK studies materialized and de-duplicated on the shared MSK-DMP P- key:

• person: 53,562 (= chord 24,950 + impact 48,179 − 19,567 cross-study duplicates retired)
• condition_occurrence: 79,371 (chord 25,040 + impact 54,331), FK-closed, 0 orphans
• Concept coverage: chord 100%, impact 99.9% real concepts (66 rows → OMOP 0 sentinel)
• Both studies pass Gate-D-lite (FK closure, required-not-null, missing-key disposition); collapse is idempotent

Dedup was verified against an adjudication set: 19,567 merges, 0 sex mismatches across 19,437 corroborable pairs, all over-collapse guards clean (P- namespace only, 0 blank keys, 0 cross-namespace TCGA collision, patient key a true PK in both studies), 0 residual keys split across >1 person_id.

Key design points

• Two-level identity registry ((source_namespace, key) → uid → person_id) so Stage B can revise identity without rewriting surrogate PKs. person_id is registry-assigned, never a hash — a hash would be incompatible with dedup.
• Ordered FK-closed write (person before condition); Databricks has no multi-table transaction, so the guarantee is write-order + FK-valid-at-rest, not atomicity.
• Deterministic same-namespace collapse only. Probabilistic/cross-namespace dedup is deliberately deferred — de-identified cBio has no cross-namespace signal to judge on.
• No fabricated data. condition_start_date is nullable (cBio carries only relative day-offsets, no absolute date); missing patient keys route to review; unmapped concepts use the standard OMOP 0 sentinel.

Testing

• Engine work is TDD (identity registry, resolver, FK-closed compiler, Stage B collapse, Gate-D-lite); last full suite was green (2263 unit tests, mypy strict, R29 guard) as of the S1-10 engine commit.
• This branch's final commits are the live Databricks runs + the durable plan record; no core src/ change since the last green suite.

Follow-ups

Filed as separate issues:

• feat: collapse-omop-identities pre-flight check for unregistered studies #117 — collapse pre-flight check for unregistered studies (from bug-421)
• chore: decouple core unit tests from showcase.cbioportal_to_omop.omop_policy #118 — decouple core unit tests from the showcase omop_policy
• feat: stage cBioPortal relative day-offset as condition_start_offset_days provenance #119 — stage relative day-offset as condition_start_offset_days provenance (D4)
• feat: deferred probabilistic cross-namespace person dedup (Stage B producer #2) #120 — deferred probabilistic cross-namespace dedup (Stage B producer chore: add Apache 2.0 license #2)

Also advances #79 (extract cBioPortal to its own package) via the showcase/cbioportal_to_omop/ relocation.