Installer V2 Takes Shape: OMOP CDM Phase Skeleton, Docker Secrets, and i18n Crossing the 90% Line

A heavy day on the Parthenon installer front — 81 commits landed across the repo, pushing installer-v2 from "wired up" to "genuinely trustworthy." We added Docker secrets support, closed a handful of correctness bugs surfaced in post-review, scaffolded the omop_cdm phase for existing-CDM deployments, and nudged Finnish, Japanese, and Chinese localizations well into the mid-90s. Here's a full breakdown.

Installer V2: From Skeleton to Load-Bearing Structure

The headline work today was on the redesigned installer engine, which is now far enough along that the legacy cli.py shim has been fully wired to the new StepRunner. Critically, the wire-up preserves backward compatibility — --defaults-file and --resume both pass through cleanly, so existing automation scripts and deployment runbooks don't need to change. That matters a lot for our early adopters who have CI pipelines built around the v1 interface.

Docker Secrets Integration

The most architecturally significant addition is proper Docker secrets support (feat(installer-v2): add Docker secrets integration). The implementation ships two artifacts:

• secrets-entrypoint — a small entrypoint wrapper that reads Docker secret files at container startup and injects them into the environment before the installer process begins.
• compose override — a Docker Compose override fragment that wires the secrets volume mounts into the service definition without touching the primary compose.yaml.

This keeps credential material out of environment variables and away from docker inspect exposure, which is the right posture for any installation that touches a production OMOP CDM. Future work will extend this to support Vault and AWS Secrets Manager backends, but the Docker-native path covers the majority of on-premises deployments we're targeting in the near term.

Correctness Fixes from Post-Review

The post-review pass (fix(installer-engine): apply post-review correctness fixes) addressed several subtle issues that wouldn't have been caught by unit tests alone:

• exec_php now correctly wraps invocations through sh -c, fixing a quoting edge case that caused failures when PHP binary paths contained spaces.
• Solr health checks now use > 0 comparisons instead of truthy string checks, preventing false positives when Solr returns an empty-but-valid response body.
• The Eunomia skip logic in the check function was corrected to actually short-circuit — previously, the skip flag was read but the check still executed, which caused spurious failures in environments that intentionally omit Eunomia.

Integration Tests for Preflight Idempotency and Event Contract

Good infrastructure code needs tests that prove behavior across runs, not just in isolation. Today's test additions (test(installer-v2): add integration tests for preflight idempotency and event contract) do exactly that:

• Idempotency tests run the preflight phase twice in sequence and assert that the second run produces identical output and leaves the system in the same state — essential for --resume correctness.
• Event contract tests assert that the StepRunner emits the expected lifecycle events (step.started, step.completed, step.failed) in the right order and with the right payloads. This is the foundation for the progress-reporting UI we'll build on top of the installer in a future sprint.

Installer Sub-Project C: Existing OMOP CDM Support

A new design spec landed today (docs: add installer sub-project C design spec), formalizing the approach for deploying Parthenon against an already-existing OMOP CDM — the "bring your own data" path that many academic medical centers will use. Alongside the spec, the omop_cdm phase skeleton was committed (feat(installer-c): omop_cdm phase skeleton with mode 3 guards and source key utility).

Two details worth calling out:

• Mode 3 guards — the phase is gated so it only executes when the installer is running in mode 3 (existing CDM attachment), preventing accidental execution during fresh-install or upgrade flows.
• Source key utility — a small helper that normalizes the CDM source key into the format Parthenon's metadata layer expects. This sounds minor but it's the kind of thing that causes hard-to-debug mapping failures six months later if it isn't standardized early.

The design spec lives in .claude/specs/ and is written to be executable by Claude Code — consistent with our emerging pattern of using specs as both documentation and AI-assisted implementation prompts.

Internationalization: Finnish, Japanese, Chinese Crossing into the Mid-90s

Two consecutive i18n pushes today moved fi, ja, and zh from the low-80s to the mid-to-upper 90s in translation coverage. This isn't just string-count progress — the commits specifically targeted UI surfaces that are visible during installation and initial configuration, which means international users will now have a fully localized experience through the most critical part of onboarding.

Design fixtures were auto-exported alongside the i18n work (the [skip ci] chore commit), keeping the visual regression baselines in sync with the updated string tables.

Hypertension Study Protocol: V2 Spec in Review

Separately from the installer push, the Hypertension Characterization Study protocol reached V2 this week (PI: Dr. Glenn Bock; study coordination: Dr. Sanjay Udoshi). The revision tightens the cohort definition to require two consecutive readings above threshold (SBP > 130 or DBP > 80), adds serum aldosterone to the baseline lab panel, and anchors the primary hypothesis to the Lu et al. 2025 diagnostic-delay benchmark. The V2 spec is staged for Claude Code execution against the Parthenon repo — implementation work is expected to begin next week.

What's Next

• Installer-C phase completion — flesh out the omop_cdm phase beyond the skeleton, implementing the actual CDM version detection and schema validation logic.
• Progress-reporting UI — now that the event contract is tested and stable, we can start building the real-time installer progress view in the frontend.
• Hypertension study implementation — translate the V2 protocol spec into Circe cohort definitions, concept sets (labs_aldosterone, htn_primary_aldosteronism), and characterization queries.
• i18n to 100% — the remaining gaps in fi, ja, and zh are concentrated in the advanced analytics UI; targeting full coverage before the next release candidate.