# Use First-Class Starter Substrate Activation Command

The merged Premium proof should expose Starter regional substrate activation as a first-class Starter-scoped cp9 command with a status/readiness surface, rather than as a `cp9.yaml` edit followed by re-running `cp9 up` or an overload of the now-removed Premium `prewarm` command. This makes the proof phases explicit: baseline `cp9 up` starts the k3d-side Premium and imported Starter services, the activation command brings up and registers the session-scoped real EKS Starter substrate, and the Starter train runs only after that substrate reports ready.

Starter Train A must fail fast with an activation/status prerequisite if the substrate is missing, rather than implicitly creating or registering the EKS substrate itself. The activation command owns only environment activation and registration; it must stop before any Starter product lifecycle operation such as create/delete cluster, leaving create, poll, endpoint/mysql proof, delete, and cleanup assertions to the Starter train. It also must not own the long-lived source-backed inner loop. Control-plane k3d source-build stays on the existing ADR 0011 Session Tiltfile path; data-plane EKS source-backed resources also belong to the Session Tiltfile surface, with an ECR-backed delivery path for remote EKS workloads. In CP9 product language, selecting a service for source-build means CP9 watches, builds, publishes, and applies source changes for that service; live-update is not a separate product mode or second user opt-in. The implementation derives update behavior from source-build selection plus a capability gate: `_contains(source_build_services, service) && _live_update_supported(service)`, where supported means CP9 ships a pre-tested internal rollout/readiness contract for that service. That contract records namespace, Deployment, container, image writer, rollout/readiness check, and status/proof image target; it is not supplied by the end user. The contract must have one canonical source of truth reused by the Session Tiltfile source-backed writer, `cp9 starter status`, and Starter proof, not duplicated Tilt-vs-proof target definitions. Session graph validation fails before build, push, summary write, or activation if a selected remote-EKS service lacks the contract. Remote-EKS source-backed updates already-activated workloads by patching Deployment images and waiting for rollout; they do not rerun activation as part of the edit loop. If activation sees a selected remote-EKS source-backed service without a first built/pushed/recorded session image, it fails fast instead of activating the service with its staging image.

The session image-source summary at `.cp9/<session>/tilt/reports/evidence/premium-image-source-summary.json` is the lockfile-like source of selected-image truth for activation, status, and proof evidence. Activation and status consume the summary-selected image for source-backed services; proof closeout records checks against that same summary as advisory evidence. None of those surfaces rederive or override selection from live Tilt state, ECR latest tags, or other mutable external state. External registry checks only validate that the summary-selected image exists and is pullable.

Remote-EKS source-backed resource flow is split by target existence, not by a new durable state machine. Before activation creates a workload, the Session Tiltfile source-backed resource can build, push, and record the selected session image in the image-source summary without patching any Deployment. Activation then reads that summary; selected source-backed services without a first recorded source image fail fast, while services with a recorded image use it to create the workload. After activation, the same source-backed resource patches the existing Deployment image and waits for rollout. No separate `preActivationBuilt`, `rolloutPending`, or similar persisted phase marker is introduced.

First selected-image production for remote-EKS source-backed services belongs to `cp9 up` / Session Tiltfile readiness. The Session Tiltfile waits until the selected image is built, pushed, and recorded, then can report the source-backed resource ready before activation with rollout pending activation. `cp9 starter activate` does not wait for, poll, or trigger source builds; it only consumes the summary and fails fast when a selected service lacks the recorded first image.

Before mutating remote workload resources, activation preflights all selected source-backed service images from the summary. It validates that each selected image is present, pullable through the planned registry/pull-secret contract, and has the required workload image replacement data. This all-before-mutation check happens before namespace, secret, or workload apply. Activation does not intentionally leave a partially applied remote workload because one selected source-backed service image was missing or invalid.

Activation uses one selected-image summary snapshot per run. It captures the summary-selected image set during preflight and applies remote workloads from that stable input, even if the Session Tiltfile builds, pushes, and records a newer source image while activation is running. Activation does not chase a moving summary; after activation, status compares the running workload to the latest selected image, proof closeout records that comparison as advisory evidence, and the Session Tiltfile source-backed resource owns the patch/rollout catch-up.

Activation reports the selected-image summary snapshot it actually used. The report includes the summary location, a snapshot identity such as timestamp or content hash, and the selected source-backed service images that fed the workload apply. This report is operator-visible provenance for proof and debugging, not a new readiness prerequisite and not a second source of selected-image truth. Status still evaluates the live workload against the current image-source summary, and proof closeout records that evaluation as advisory evidence.

Starter Train A archives the same-session activation report as proof provenance when selected remote-EKS source-backed services are in scope. It validates that the report belongs to the current session and activation run, but absence or staleness of that provenance is advisory evidence rather than a direct proof-fail gate. The report does not decide workload readiness or image correctness; those still come from live status checks against the current image-source summary, with proof closeout recording the status result as evidence.

If a selected source-backed image is recorded but activation has not created or readied the workload, `cp9 starter status` fails the activation/readiness prerequisite instead of reporting image drift. Proof closeout records that status result as advisory environment evidence and still runs the Starter API train when requested; it must not fail proof directly or skip the train solely because the readiness check is not clean. Image mismatch is only meaningful after the status/proof target workload and container exist; before then, the operator-facing blocker is activation/substrate/workload readiness.

For the first implementation, summary freshness is based on the current session image contract, not on source revision or build-input fingerprint comparison. Activation and status require the selected image to be a current-session source-backed image, then rely on running image identity checks to prove the workload caught up to that selected image. Proof closeout records the same selected-image and running-image context without making it a direct proof-fail gate. These surfaces do not fail solely because the source checkout changed after the image was built; detecting and rebuilding for source changes remains the responsibility of the Session Tiltfile source-backed resource.

After activation, the Session Tiltfile source-backed resource updates the image-source summary as soon as a new session image is built, pushed, and recorded, before it patches the remote Deployment. This makes the summary the desired selected image. If patching or rollout fails, status fails because the running image has not caught up to the selected image. Proof closeout records that mismatch as advisory evidence and still runs the Starter API train; it does not continue to present the previous successfully rolled-out image as current selected-image proof.

The activation command is not a post-activation image drift reconciler. For an existing remote workload whose running image differs from the summary-selected image, the Session Tiltfile source-backed resource is the writer that patches the Deployment and waits for rollout, while status remains read-only and fails on mismatch. Proof closeout also remains read-only, but it reports the mismatch as advisory environment evidence instead of failing proof directly. Activation may still recreate a missing same-session workload from the current summary, but it does not patch image drift on an existing workload.

Switching a service back from source-backed mode to staging-image mode after activation is handled by that same Session Tiltfile writer. Removing the service from `source_build_services` updates the image-source summary to the staging pin, patches the existing Deployment back to staging, and waits for rollout. Activation remains out of existing-workload image patching, status validates the current selected mode, and proof closeout records the selected-mode context rather than requiring a session rebuild.

The activation command is idempotent within one cp9 session: it reports ready when the same-session substrate and registration already exist, resumes or repairs partial same-session resources, and fails closed rather than adopting shared, foreign, or unowned resources. To keep local session state simple, activation readiness is not a persisted prerequisite artifact; the status command and Starter Train A re-derive readiness from live cloud, kube, and registration checks each time. The first implementation PR includes the activation/status command because the agreed proof path depends on `cp9 up`, Starter substrate activation/status, and the retargeted Starter Train A in one runnable sequence.

The status surface should prove the activated workload slice, not only EKS reachability. It checks the key Starter remote rollouts in their real namespaces: `manager`, `serverless-regional-service`, and `tidb-gateway-inner` in `tidb-admin`, plus worker `scaler` in `tidb-worker`. Remote-EKS source-backed updates should reuse the same pre-tested rollout/readiness contract aligned with these status targets instead of inferring namespace, Deployment, or container from service name alone. Missing rollout contracts fail closed when a service is selected for source-build; they are not represented as a separate live-update opt-in. For selected source-backed services, status also verifies that the running Deployment container image matches the selected session source image from the image-source summary, starting with exact tag equality and tightening to digest equality later if stable. Image identity mismatch hard-fails status for source-backed services. Proof closeout may collect the same check before or after Starter Train A, but it records mismatch as advisory environment evidence and still runs the proof/train flow instead of failing proof directly. The status surface also re-reads the live `serverless-regional-service` LoadBalancer endpoint and re-derives the Premium control-plane registration by querying `premium-metadb` for active Starter and Essential `us-west-2` region rows that point at that exact regional service URL; proof closeout surfaces catalog drift as evidence rather than making the API train responsible for diagnosing it.