Control Plane Baseline Resolution

The control plane baseline resolution flow lets the CLI use a typed Harness API source for baseline metadata without making the backend a hard dependency for current scaffold behavior.

Trigger

An operator runs a CLI command that needs the stable scaffold baseline and DP_CONTROL_PLANE_URL is set.

Actors

• Harness operator
• apps/cli
• packages/contract
• apps/api
• GitHub stable baseline release fallback
• Bundled baseline fallback

Steps

1. Keep --baseline bundled and DP_BASELINE=bundled as immediate bundled-baseline exits.
2. Check DP_BASELINE_URL=file://... before remote sources.
3. Use the typed Effect client when DP_CONTROL_PLANE_URL is set.
4. Download, verify, extract, and cache the archive when artifact metadata is usable.
5. Continue to GitHub stable release lookup when the control plane fails.
6. Return bundled baseline only after all stable remote sources fail.

Outcome

The CLI can adopt backend-provided baseline metadata when it exists, while preserving the pre-IP-97 GitHub and bundled fallback guarantees.

Closeout Signal

The implementation is healthy when the typed client path is covered by tests and a failing control-plane request still reaches the GitHub stable release fallback before bundled fallback.