# Design: cp9 Starter Full Persona

Slock task: `#cp9:df920499`

Related product surface: Starter/Essential v1.

Related decision:
[`20260608-adr-starter-full-remote-eks-o11y.md`](./20260608-adr-starter-full-remote-eks-o11y.md)

## Summary

`starter-full` is the cp9 persona for the Starter/Essential v1 product family.
It is not the legacy `tidb-cloud-starter` DB provider helper. It is a full
product-line dogfood persona that must prove the shared Starter/Essential v1
regional architecture.

Final acceptance is a full product proof:

1. `cp9 setup`, `cp9 doctor`, and `cp9 up` prepare the session.
2. TiDB Cloud OpenAPI creates a Starter cluster and an Essential v1 cluster.
3. The Starter train proves autoscale-critical behavior from deterministic
   o11y metric responses.
4. Both trains return an endpoint.
5. A host mysql client proves `select 1`.
6. `cp9 destroy` cleans the local and cloud session resources with owner/session
   evidence.

## Current cp9 Baseline

The current shipped core product persona is Premium full on AWS. Premium runs
the global and regional control-plane services in local k3d while the customer
dataplane EKS is created later by service code through normal OpenAPI flows.

Starter/Essential v1 does not fit that Premium invariant. The historical
Starter/Essential v1 architecture is two-layer:

- global control-plane services dispatch product work;
- the regional control plane is also the shared dataplane;
- regional shared pools, keyspace pools, gateway services, and TiDB components
  are already part of the product runtime rather than a per-cluster EKS side
  effect.

Because of that, `starter-full` intentionally extends cp9 beyond the Premium
local-k3d-only substrate model.

## Accepted Decisions

1. Final `starter-full` acceptance is a full product proof, not create-only.
2. Global CP runs in the local cp9 k3d host.
3. Regional CP/DP runs in cp9-owned ephemeral remote EKS.
4. cp9 owns the remote EKS lifecycle end-to-end. `cp9 setup/up` must create or
   reuse session-scoped EKS state, and `cp9 destroy` must clean it.
5. Shared staging EKS is not the runtime substrate. Staging manifests and
   historical docs are source material only.
6. The first regional stack is a staging-faithful regional stack, not a
   minimal curated subset.
7. Staging-faithful means faithful topology and contracts, not reuse of shared
   staging secrets. Secrets and config are cp9-owned generated or stubbed by
   default.
8. Narrow upstream config hooks are allowed when needed. They must be
   configuration-only hooks with tests, not product behavior changes.
9. The o11y stub is AWS-hosted, cp9-owned, public HTTPS, and session-scoped.
   Both local k3d global CP and remote EKS regional CP/DP call the same stub.
10. The o11y stub must implement Prometheus-compatible `/api/v1/query` and
    `/api/v1/query_range` surfaces needed by Starter/Essential v1 services.
11. Autoscale proof uses deterministic scripted o11y responses, not
    workload-generated live metrics in the first train.
12. The first acceptance includes both a Starter train and an Essential v1
    train. Starter carries the autoscale-critical assertion. Essential v1 must
    at least prove same-substrate create, endpoint, host mysql `select 1`, and
    cleanup; add Essential-specific assertions if code research shows a
    separate critical path.
13. The implementation train must add Starter-family skills after the persona
    design is accepted: `persona-starter-full-aws` for setup/proof/cleanup and
    `starter-openapi` for Starter/Essential v1 OpenAPI trains.

## Runtime Shape

### Local k3d

Local k3d hosts the global CP side of the proof:

- source-built or live global services needed to accept OpenAPI requests;
- local stubs for off-path dependencies;
- generated config that points regional dependencies at the remote EKS and the
  AWS-hosted o11y stub.

Local k3d must not rely on staging as a runtime success path.

### Remote EKS

Remote EKS hosts the regional CP/DP stack:

- regional serverless control-plane components;
- shared-pool and keyspace-pool runtime components;
- gateway and dataplane entry components needed for the returned endpoint;
- staging-faithful app-delivery/aws-shared-provider service graph;
- generated or stubbed secrets/config unless a live dependency is explicitly
  approved.

Remote EKS resources must be tagged or otherwise scoped by cp9 owner/session so
destroy can prove cleanup.

### AWS-hosted o11y stub

The o11y stub is a session-scoped AWS service reachable by:

- local k3d global CP services over public HTTPS;
- remote EKS regional CP/DP components over public HTTPS or normal VPC egress.

The stub must:

- serve Prometheus-compatible `/api/v1/query`;
- serve Prometheus-compatible `/api/v1/query_range`;
- require a session token or equivalent cp9 session credential;
- record each query, response fixture, and request identity;
- support scripted response sequences for autoscale-critical proof;
- include its evidence in the final proof report.

The design does not require real o11y metrics in the first train. Real workload
metrics can become a later confidence train after the product proof is stable.

## Secrets And Config

The default rule is cp9-owned generated or stubbed values:

| Input class | Default behavior |
| --- | --- |
| Service credentials | generated per session |
| TLS certs and client certs | generated per session |
| Kubeconfigs | generated from cp9-owned local k3d and remote EKS state |
| O11y auth and URLs | generated for the cp9 AWS-hosted o11y stub |
| Dependency URLs | point to cp9 source/live/stub endpoints |
| Redis/etcd/API keys | generated or stubbed per session |

Real staging secrets or shared live dependencies are exceptions. Each exception
must name the dependency, owner, risk, and cleanup story in the implementation
issue before it can be used.

## Upstream Hooks

cp9 overlays should be the first tool. If a service lacks a safe way to replace
staging secrets, o11y endpoints, dependency URLs, or session identity, add a
narrow upstream config hook with tests in the owning repository.

Allowed upstream hooks:

- config keys for o11y base URL and token;
- config keys for dependency endpoint URLs;
- config keys for generated cert/secret names;
- config keys for session identity, owner, and region;
- manifest render hooks that expose those config keys.

Disallowed upstream changes:

- product behavior changes made only to satisfy cp9;
- bypassing Starter/Essential v1 control-plane logic;
- removing autoscale decisions from the first Starter train;
- hidden staging fallbacks.

## Acceptance Trains

### Starter Train

The Starter train must prove:

1. OpenAPI create is accepted from local k3d global CP.
2. Regional CP/DP in remote EKS receives and processes the request.
3. The AWS-hosted o11y stub serves deterministic scripted responses.
4. The Starter autoscale or pool-policy decision changes as expected from those
   responses.
5. The returned endpoint works from the host with mysql `select 1`.
6. Evidence records the OpenAPI request, o11y query sequence, autoscale decision,
   endpoint, SQL proof, and cleanup proof.

### Essential v1 Train

The Essential v1 train must prove:

1. OpenAPI create is accepted for an Essential v1 cluster.
2. The same remote EKS regional CP/DP substrate handles the request.
3. The returned endpoint works from the host with mysql `select 1`.
4. Cleanup removes both Starter and Essential v1 resources.

If Essential v1 uses a distinct autoscale, pool, or metering decision path, the
implementation issue must add a matching assertion instead of treating the smoke
train as sufficient.

## Skill Requirements

The persona is not fully shipped until the agent-facing skill layer can route
users into it without relying on this design doc.

Required new skills:

| Skill | Responsibility |
| --- | --- |
| `persona-starter-full-aws` | Guide `cp9 setup`, `doctor`, `up`, Starter/Essential v1 proof trains, AWS-hosted o11y stub evidence, remote EKS cleanup, and failure recovery for `starter-full`. |
| `starter-openapi` | Select and execute reviewed Starter/Essential v1 OpenAPI request trains after a `starter-full` environment exists. |

`starter-openapi` must use these OpenAPI sources as the first reference set:

- `tidbcloud/serverless-service`:
  `apidocs/v1beta1/branch.swagger.json`
- `tidbcloud/tidb-management-service`:
  `api/spec/tidb_cloud_open_api/serverless/v1beta1/services.swagger.json`

Required updates to existing skills:

- `skills/get-started/SKILL.md` must route Starter/Essential v1 AWS setup,
  diagnosis, endpoint, SQL proof, and cleanup questions to
  `persona-starter-full-aws` after the persona is proven.
- `skills/get-started/SKILL.md` must route Starter/Essential v1 OpenAPI request
  train work to `starter-openapi` after the environment exists.
- `skills/persona-config` must explain `starter-full` config fields once
  `cp9.starter-full.example.yaml` exists.
- `skills/shared` must document any new remote EKS cleanup and o11y stub evidence
  surfaces that become part of normal `cp9 destroy` closeout.

Until the persona is implemented and proven, existing skills should continue to
say Starter/Essential v1 is not yet a shipped proof path. They must not point
users at non-existent skills.

## Non-Goals

The first design does not:

- resurrect the legacy direct `tidb-cloud-starter` DB provider as the persona;
- depend on shared staging EKS as the runtime substrate;
- reuse real staging secrets by default;
- prove autoscale by waiting for real workload metrics;
- implement every later product train for Starter/Essential v1;
- support non-AWS Starter/Essential v1 clouds.

## First Implementation Train

Implementation should be split after this design is reviewed. Expected issue
families:

1. remote EKS substrate lifecycle and destroy evidence;
2. AWS-hosted o11y stub with scripted Prometheus query responses;
3. staging-faithful regional app graph import and config classification;
4. upstream config hooks needed to replace staging secrets/config safely;
5. local k3d global CP wiring to remote EKS and o11y stub;
6. Starter autoscale-critical train;
7. Essential v1 same-substrate train;
8. `persona-starter-full-aws` and `starter-openapi` skills, plus updates to
   `get-started`, `persona-config`, and `shared` after the persona is proven.