# controlplane9

controlplane9 is the session-scoped dogfood and dev integration environment for
TiDB Cloud product surfaces. A cp9 session may run locally or on a cloud host;
old-dev replacement acceptance uses the cloud-hosted substrate. This language
file defines project terms used by cp9 persona design and review.

## Language

**Persona**:
A named cp9 product-surface environment with an accepted proof boundary and a
concrete service graph.
_Avoid_: profile, mode

**Persona Tiltfile**:
A persona-owned Tiltfile example that users copy before starting a cp9 session.
It defines the persona's expected runtime graph shape.
_Avoid_: generated Tiltfile, service graph in `cp9.yaml`

**Session Tiltfile**:
The copied, user-editable Tiltfile for one cp9 session; it is the session's
runtime graph source of truth.
_Avoid_: generated Tiltfile, separate service override file

**Starter PD topology contract**:
The create-time, substrate-immutable choice between the Staging-compatible PD
microservice topology and three monolithic PD replicas. It is resolved in
`starter.activation.pdms.enabled` before AWS mutation and fingerprinted with
the Starter EKS substrate. This narrow topology contract does not select
service source/image ownership; the Session Tiltfile remains the runtime graph
source of truth.
_Avoid_: Persona mode, image source mode, mutable service graph override

**Image source mode**:
The Session Tiltfile choice for whether a service runs from a staging-aligned
image or is built from local source for development.
_Avoid_: service role, source/live/stub

**Fast-start mode**:
The Dev full Session Tiltfile default where most product services run from
staging-aligned images, while only explicit development targets are source-built.
Fast-start proof uses a selected host architecture that can run those
staging-aligned images; source-build services and always-local stubs are built
for the selected host architecture.
_Avoid_: all-source-build default, staging runtime dependency

**Source build services**:
The Session Tiltfile list of services that a user intentionally builds from
source in a fast-start cp9 session.
_Avoid_: service role override, cp9.yaml service mode

**Staging-aligned image pin**:
An explicit image reference in the Session Tiltfile that runs the same service
artifact line as staging without reading staging at session runtime.
_Avoid_: dynamic staging lookup, implicit latest image

**Staging-image service**:
A product service in Fast-start mode that runs from a Staging-aligned image pin
instead of declaring a local image build in the Session Tiltfile.
_Avoid_: disabled source service, manual image resource

**CP9 UI image**:
An immutable static-server image that CP9 builds and publishes from a pinned
`dbaas-ui` production-line source commit for Remote Dev full Fast-start use. It
is a CP9 packaging artifact, not an upstream UI release or a Source build service.
_Avoid_: dbaas-ui staging image, frontend source image

**CP9 UI image candidate**:
A CP9 UI image built from a resolved upstream `master` commit but not yet
selected by the checked-in Remote Dev full image pin.
_Avoid_: latest UI image, automatically deployed UI

**CP9 UI candidate command**:
The single maintainer entry point, `make dbaas-ui-candidate`, that resolves an
exact upstream `master` commit through the maintainer's local `gh` identity,
applies and validates the source overlay, builds and tests the image contract,
and optionally publishes after explicit AWS profile selection. Local validation
is the default. Future automation calls this same
Make target instead of owning a second build implementation.
_Avoid_: Actions-only build, duplicated release script, implicit publication

**CP9 UI image promotion**:
The human-approved change that selects a validated CP9 UI image candidate by
its immutable digest for new Remote cp9 sessions.
_Avoid_: master tracking, automatic promotion

**CP9 UI image registry**:
The durable ECR publication boundary in AWS account `385595570414` for CP9 UI
image candidates. The runtime account's `cp9-developer` role publishes directly
through the repository policy, while consumer principals in that account pull
the shared digest through cross-account authorization. The registry is not
session-owned or destroyed by `cp9 destroy`.
_Avoid_: per-session UI registry, account-local UI image copy

**CP9 UI source overlay**:
The minimal, versioned patch that CP9 applies to a pinned `dbaas-ui` source
commit before building a UI image candidate. It introduces the CP9 runtime
configuration contract and must fail closed when the upstream source is no
longer compatible.
_Avoid_: fork, patched bundle, post-build replacement

**CP9 UI runtime config**:
The per-session public configuration loaded before the main UI application. It
selects session API and browser-integration settings without rebuilding the CP9
UI image.
_Avoid_: build-time environment, localStorage override

**CP9 UI dev profile**:
The isolated default runtime configuration for a CP9 UI. It enables the current
session API and `tidb-dev` Auth0, disables every other external integration when
its explicit runtime settings are absent, and never falls back to upstream
staging or production hosts. External o11y remains an optional runtime extension
for the near-term follow-up rather than a compile-time image variant.
_Avoid_: copied PRO config, staging fallback, implicit external egress

**CP9 UI same-origin contract**:
The rule that a CP9 UI sends every main API request to the same cp9 session
origin that served the page, where the Dev full route layer selects the target.
The v1 contract does not accept an arbitrary backend URL.
_Avoid_: configurable dbaasUrl, cross-session UI backend

**CP9 UI Auth0 contract**:
The normal interactive login contract for a CP9 UI. The browser uses the
existing `tidb-dev` Auth0 domain and client that match the session account
service, returns to the current session's `/auth_redirect`, and completes login
without a pre-seeded browser token. Upstream production Auth0 defaults are not
valid CP9 runtime configuration. The existing shared development application
contains exact CP9 callback, logout, and web-origin entries with one wildcard
hostname label under the CP9-owned dev session zone and fixed
`/auth_redirect`/`/` paths. CP9 requires those exact entries but does not claim
ownership of, reject, or remove broader entries used by the application's other
development consumers; session lifecycle only preflights the configuration and
never mutates the Auth0 client.
_Avoid_: production Auth0 fallback, pre-seeded-token acceptance, per-session Auth0 registration, shared-client isolation claim

**CP9 UI seed user**:
The designated identity for the primary browser proof. Its email/password
identity already exists in the shared tidb-dev/us Auth0 tenant, while the same
email is prepared as an ACTIVE user with an org role in the current Session
Account data. Auth0 owns the password; CP9 never stores it, creates it during
session startup, infers it from the session owner, or grants arbitrary users
just-in-time Account access. Remote Dev full defaults to the shared CP9 test
identity; an explicit email is only an override for another identity already
prepared by an Auth0 administrator.
_Avoid_: browser-token seed, session-owner inference, unrestricted JIT user

**CP9 UI registration slice**:
The next identity browser journey: use the preserved registration UI and routes
to create the required Auth0 and Account state, then log in. The current delivery
keeps those entrypoints conformant but gates only the prepared seed user's normal
login and authenticated shell.
_Avoid_: current must-pass, removed signup route, implicit JIT

**CP9 UI browser acceptance**:
The v1 live finish line: a real browser on the cp9 CLI machine opens the public
session URL as the prepared seed user, completes normal Auth0 callback and
same-origin login confirmation, renders the authenticated shell, and survives a
direct history-path refresh. Cluster create, registration-to-login, and other
product journeys are later proof phases.
_Avoid_: curl-only UI proof, pre-seeded login, cluster-create v1 gate

**Remote Dev full UI slice**:
The mandatory UI workload, per-session runtime configuration, complete main-host
route layer, and routing-placeholder Services in every Remote Dev full
Fast-start session. The slice is part of the persona contract and has no
enablement or disablement setting.
_Avoid_: optional UI add-on, `ui.enabled`, backend-only Remote Dev full

**CP9 UI host scope**:
The built-in CP9 UI has one supported browser origin: the Remote Dev full HTTPS
session hostname.
_Avoid_: localhost UI, dual exposure contract

**CP9 UI readiness**:
The layered status of the Remote Dev full UI slice. Session-owned file serving
participates in `session_ready`; the shared Auth0 preflight and prepared seed
Account binding participate in `ui_ready` and browser acceptance but cannot
revoke readiness from an otherwise-valid backend session.
_Avoid_: one undifferentiated ready bit, Auth0-blocked backend session

**Routing-placeholder Service**:
A Kubernetes Service with the exact staging target name and declared port,
but no selector or endpoints. It lets Kong materialize an absent target without
a fake workload or response. A later real backend supplies endpoints behind the
same Service contract and removes the placeholder marker.
_Avoid_: response stub, generic unavailable backend, route-only target

**Source-capable staging service**:
A product service that defaults to a Staging-image service in Fast-start mode,
but also has an intentional Source build service path and, where the service can
support it, a live-update inner loop.
_Avoid_: staging-only service, deferred source service

**Source-backed service contract registry**:
The checked-in `internal/sourcebacked/contracts.json` registry that describes
each service's family, staging image, source entrypoint, backend kind, image
writer, rollout/readiness target, and proof/status evidence target. Premium,
BYOC regional, imported Starter/Essential v1, and imported Dedicated services
use this shared registry and the `premium-image-source-summary.json` schema
instead of product-specific source-build models.
_Avoid_: per-product live-update list, inferred rollout target, duplicated
status/proof contract

**Image source summary**:
Run evidence that records which services were Staging-image services, Source
build services, or always-local stubs for one cp9 session.
_Avoid_: manual image report, source coverage guess

**Fast-start proof**:
Acceptance evidence from fast-start mode; it proves staging-image services
participate in the cp9 product flow, and proves local source behavior only for
Source build services.
_Avoid_: source proof, all-source proof

**All-source proof**:
Acceptance evidence from a Dev full Session Tiltfile where every product service
is listed as a Source build service.
_Avoid_: default proof, fast-start proof

**Full persona**:
A persona whose acceptance proves the user-visible product workflow end to end,
including product API, returned endpoint, database connectivity, and cleanup.
_Avoid_: create-only persona

**cp9 session**:
A temporary, isolated cp9 environment for one owner and one product-surface
proof.
_Avoid_: shared dev environment

**Shared cp9-global**:
The common global control-plane layer reused by the Premium and BYOC regional
control planes within one Dev full session.
_Avoid_: BYOC global control plane, per-persona global control plane

**BYOC Region**:
A session-scoped BYOC product environment composed of the BYOC regional control
plane and a validated customer-account contract, attached to Shared cp9-global.
A ready BYOC Region does not imply that a customer dataplane VPC/EKS or TiDB
cluster exists; those are created by the later product cluster lifecycle.
Imported Dedicated state that may coexist in the shared Dev full baseline is
not part of the BYOC Region and cannot gate its cleanup or lease release.
_Avoid_: BYOC cluster, BYOC account

**BYOC regional control plane**:
The regional control-plane sibling of the Premium regional control plane. In a
Dev full session it owns independent region-scoped process and state in the
`cp-byoc` namespace, reuses Shared cp9-global and shared cluster foundations,
and never reuses live `cp-premium` workloads.
_Avoid_: BYOC seed cluster, separate BYOC persona

**BYOC dataplane substrate**:
The isolated customer-side network and management capacity on which BYOC TiDB
clusters are created. It runs in a BYOC customer account that is distinct from
the cp9 control-plane account, is created on demand by the product
shared-pool/dataplane workflow rather than BYOC Region activation, and is never
treated as Premium dataplane capacity.
_Avoid_: BYOC regional control plane, shared dataplane

**BYOC control-plane account**:
The cp9 target AWS account that hosts the remote session, the BYOC regional
control plane, its VPC, and the control-plane side of PrivateLink.
_Avoid_: BYOC customer account, shared BYOC account

**BYOC customer account**:
The separate AWS account that hosts the CP9 BYOC session bootstrap, customer
ECR, DNS, PCA, IAM, and the BYOC dataplane substrate. A BYOC session must not
resolve this account to the BYOC control-plane account. In CP9 dogfood, one
customer account may belong to only one active BYOC session at a time; it may
be reused sequentially only after the prior session completes destroy and
zero-residual proof.
_Avoid_: cp9 target account, simulated customer account

**Exclusive BYOC dogfood account**:
The single-active-session ownership rule for a BYOC customer account. It gives
account-global production CloudFormation stacks and fixed IAM role names one
unambiguous CP9 lifecycle owner. It does not mean the AWS account can never be
reused; it means reuse is serialized behind completed teardown and absence
proof.
_Avoid_: permanently disposable account, concurrently shared customer account

**BYOC dogfood account pool**:
A pre-provisioned set of customer AWS accounts available to concurrent CP9
users. Each simultaneous BYOC session selects a different account and local
profile; the control-plane account may remain shared. Because the current
public product path selects a BYOC Region by tenant, provider, physical Region,
and service plan, parallel sessions must also use different tenants or physical
Regions; account separation alone cannot disambiguate same-tenant/same-Region
creates. The first slice does not create AWS Organizations accounts or
automatically broker pool selection.
_Avoid_: shared customer account, CP9-created AWS account, control-plane account pool

**BYOC catalog selector slot**:
The product routing key `tenant + cloud provider + physical Region + service
plan` used to resolve a public-API `regionId` to one logical BYOC Region. A
first-slice activation must be the only active BYOC Region in that slot. The
read-only catalog preflight checks existing Regions; an atomic, cross-machine
SSM reservation in the control-plane account then serializes simultaneous
empty-slot observations before either session touches its customer account.
The reservation binds the full selector, both accounts, owner, session, server,
and fingerprint, and exact destroy releases it only after catalog/customer
teardown. Customer account identity and logical Region name are not selector
dimensions in the current service.
_Avoid_: customer-account selector, logical-Region selector, last-writer-wins routing

**Canonical BYOC tenant ID**:
The one positive base-10 spelling of a numeric tenant ID, with no leading
zeros. CP9 rejects numeric aliases before fingerprint, selector-slot, quota,
or catalog identity derivation so one product tenant cannot split across two
coordination keys.
_Avoid_: tenant alias, zero-padded tenant ID

**BYOC tenant quota**:
The single RCU quota row keyed by `tenant + BYOC` in the shared global catalog.
It is intentionally shared by distinct physical Regions for the same tenant,
not owned by one session. CP9 uses one deterministic tenant-global identity;
destroy removes it only after the tenant has no active BYOC Region and proves
that a retained row is either still referenced or absent, never orphaned.
_Avoid_: per-session quota, per-Region quota, unconditional quota deletion

**BYOC account lease**:
An atomic, account-global, cross-machine ownership record acquired before any
customer-account mutation. It binds one customer account to the CP9 owner,
session, server, and activation fingerprint. Its fixed SSM parameter lives in
one partition-wide anchor Region (`us-east-1` in commercial AWS), not the target
Region, so different target Regions still contend on one account lease. A
second claimant fails before CloudFormation and reports the holder. Destroy
refuses every mutation unless the live lease still matches owner, session,
server, and fingerprint, proves the owned closure absent while retaining only
that lease, releases it, then proves lease/tag absence again. An interrupted
session remains recoverable instead of making a dirty account appear free.
_Avoid_: local lock file, stack-name collision, TTL-only lease release

**Session lifecycle operation lock**:
The local, session-keyed advisory lock shared by V1alpha2 `up` and `destroy`.
It lives outside the removable session root and is held from pending-intent
inspection/publication through cleanup, session-root removal, and final intent
removal. This makes divergent no-root destroy contracts mutually exclusive and
prevents `up` from reopening a session with pending cleanup. Its hashed lock
file and the external reaper intent live below `.cp9/.internal/`, whose leading
dot makes it an invalid session name, and the lock file is retained so
unlinking cannot create two independently locked inodes.
`reaper`, `destroy-summaries`, and `lifecycle-operation-locks` remain reserved
while their pre-`.internal` artifacts are read for compatibility. A current
process acquires both the previous and new operation-lock files in that order,
so it serializes with both older and current CP9 processes. It is process
serialization for one local state root, never a substitute for
the cross-machine selector reservation or customer-account lease.
_Avoid_: check-then-overwrite intent, removable advisory lock, cloud lease

**BYOC lifecycle lock**:
The session-local exclusive lock shared by activation and destroy. It prevents
closeout from proving absence and releasing cross-account reservations while
an in-flight activation apply can still create resources, and prevents
activation from reopening a closeout in progress. Destroy acquires it before
the authoritative journal read and keeps it through terminal publication; an
absent journal is fenced as a terminal empty lifecycle before the lock is
released. That empty-lifecycle closeout does not require a selected host; a
nonterminal journal still requires the persisted remote host to reconstruct
its exact mutation contract. If a config-scoped enclosing cleanup fails after
publishing the fence, or stops while the lock/temp journal shell is being
created, its retry rebuilds the reaper from the supplied config only when an
external pre-root destroy intent binds the same cleanup contract digest.
That config-scoped intent cannot be reused as ordinary persisted lifecycle
state, and its completed local cleanup or workflow handoff checkpoint is kept
until the terminal shell is removed. Activated/unknown shells, missing intents,
concurrent divergent contracts, and config drift fail closed.
_Avoid_: activation-only lock, reservation-only concurrency guard

**Foreign BYOC setup stack**:
Any fixed-name `tidbcloud-byoc-setup-{deploy,dataplane,o11y}` stack that a fresh
activation did not prove absent and later bind to its own pre-call journal
intent and immutable stack ID. CP9 never updates, adopts, or deletes a foreign
setup stack. The first slice has no `--adopt` escape hatch.
_Avoid_: resumable CP9 stack, same-name proof, implicitly managed prerequisite

**BYOC zero-residual proof**:
Evidence that no CP9-created setup stack, session marker, runtime role/resource,
dataplane, cluster, or other session-owned object remains in either AWS account.
Explicit customer-owned BYOC prerequisites named in the immutable handoff are
reported but excluded; the retained BYOC account image cache and shared inert
control-plane account-setup principal are also explicit account-level
exclusions. Their continued existence is not a cleanup survivor.
_Avoid_: empty customer account, deleting customer prerequisites

**BYOC customer handoff**:
The product contract a customer prepares and shares with TiDB Cloud: tenant ID,
dedicated AWS account ID, region, Availability Zone names and IDs, TiDB hosted
zone name/ID, PCA ARN or explicit POC certificate alternative, TiDB CIDR, image
sync region, and quota readiness. O11Y hosted-zone/CIDR fields belong to the
later O11Y runtime slice, although the unmodified account-setup script still
requires the O11Y hosted-zone prerequisite.
_Avoid_: AWS CLI profile, cp9 bootstrap credential, DPM runtime role

**Customer-owned BYOC prerequisite**:
A long-lived TiDB or O11Y public hosted zone, its verified parent DNS
delegation, or the customer PCA consumed by account setup. CP9 validates its
identity, account/region, state, and required public contract before mutation,
but never adopts, modifies, or deletes it. These explicit foreign resources are
outside session zero-residual accounting and may be reused by the next
serialized session.
_Avoid_: CP9-owned setup stack, cleanup survivor, session resource

**BYOC customer image mirror**:
The exact set of core-lifecycle container images copied into the ECR registry
derived from the configured customer account and image-sync region after
account setup and before BYOC Region readiness. Each required source digest
must exist under the customer registry at the same digest. Customer dataplane
workloads may not fall back to a control-plane account registry.
_Avoid_: registry hostname placeholder, best-effort image copy, CP ECR fallback

**BYOC account image cache**:
The production-shaped, `ManagedBy=PingCAP` ECR repositories and images retained
in the customer account across serialized CP9 sessions. They are scoped to the
customer account and image-sync region rather than one BYOC Region/session.
Normal destroy reports but does not delete them; full account retirement is a
separate explicitly authorized cleanup operation. Activation and status require
the exact account/Region/repository ARN and exactly the production
`ManagedBy=PingCAP` tag before trusting any cached image digest.
_Avoid_: session image repository, cleanup survivor, disposable mirror

**Shared inert BYOC account-setup principal**:
The exact control-plane role
`arn:aws:iam::<control-plane-account>:role/auto-deploy-cli` required to exist
before AWS can validate the pinned official customer setup template's trust.
`terraform/cp9-developer/SKILL.md` owns it as an account-level compatibility
resource with deny-only trust, zero policies, no permissions boundary or
instance profile, a durable non-empty `cp9-owner`, and exact CP9 component tags
but no `cp9-session`. CP9 validates it read-only before customer mutation and
never uses it for runtime credentials or session cleanup; the session-prefixed
two-hop DPM chain remains the runtime identity.
_Avoid_: session DPM role, customer auto-deploy role, cleanup survivor

**BYOC core image closure**:
The transitive set of TiDB, TiKV, PD, TiFlash, operator, sidecar, and other
customer-dataplane images selected by the pinned DPM/cluster product config for
the first-slice acceptance train. Activation mirrors and verifies this set;
the later running-pod proof confirms the selected customer ECR digests. An
unpinned/malformed source or conflicting customer target blocks discovery;
tag- and digest-form pinned sources are both explicit closure members.
_Avoid_: all company images, control-plane service images, mutable tag list

**BYOC bootstrap credential**:
An operator-local AWS profile that resolves directly to the BYOC customer
account and has permission to prepare that account and verify its identity. It
is a cp9 execution input, not a field supplied in the BYOC customer handoff,
and it is never copied to the remote host or Kubernetes. It is distinct from
the control-plane source profile because the two profiles must resolve to
different account IDs, although both may reuse one underlying SSO session. In
a CP9 dogfood run, the local CP9 operator uses this profile to act in the role
that the customer performs in production; CP9 wraps the customer-side setup
procedure but does not turn the credential into a TiDB Cloud runtime secret.
_Avoid_: customer contract, control-plane source profile, cross-account runtime identity

**CP9 control-plane source profile**:
The existing `target.aws.iam.source_profile` used before the generated daily
`target.aws.iam.profile` exists. Current cp9 requires this source profile to
resolve to the BYOC control-plane account; it then assumes that account's
configured `cp9-developer` role and creates the remote session substrate.
_Avoid_: generated daily cp9 profile, BYOC bootstrap credential

**BYOC control-plane DPM role**:
The session-scoped `<session>-byoc-dataplane-manager` role in the BYOC
control-plane account. The remote instance profile may assume it, and the
production customer-account DPM role trusts it through the existing
`*-dataplane-manager` principal contract. It is distinct from the Premium DPM
role so the two regional control planes do not share a provider identity.
_Avoid_: Premium dataplane-manager role, remote instance profile, customer role

**BYOC runtime role**:
The fixed `tidbcloud-dataplane-manager-assumed-role` in the BYOC customer
account, created by Production BYOC account bootstrap. DPM/Crossplane reaches
it only through the BYOC control-plane DPM role; it is a resolved setup output,
not an optional handoff input or a local bootstrap credential.
_Avoid_: BYOC control-plane DPM role, local AWS profile, customer administrator identity

**BYOC runtime assume-role chain**:
The runtime path from the remote EC2 instance profile to the BYOC control-plane
DPM role and then to the BYOC runtime role. No bootstrap profile or static AWS
key is copied to the remote host. Proof records both successful assumed-role
identities and confirms that the remote instance profile cannot bypass the
control-plane DPM role to assume the customer role directly.
_Avoid_: direct host-to-customer assume, one-hop provider identity, remote bootstrap profile

**Production BYOC account bootstrap**:
The customer-account CloudFormation contract that prepares the fixed IAM roles,
image-sync registry access, and permissions used by a production BYOC Region.
It consumes pre-existing TiDB/O11Y hosted-zone IDs and a PCA ARN; it does not
create those customer prerequisites. CP9 runs its official fixed-name setup
contract in the exclusive customer account rather than replacing it with
session-derived roles. The script also creates O11Y IAM prerequisites, but
those roles do not imply that an O11Y runtime has been deployed. Its
account-global fixed names are not safe for concurrent cp9 sessions. The
customer template also names the shared inert control-plane account-setup
principal; that distinct control-plane prerequisite is Terraform-owned and
retained across sessions.
_Avoid_: BYOC dataplane, cp9 prerequisite

**BYOC account-setup bundle**:
The byte-for-byte vendored execution closure of the official AWS account-setup
script and its three CloudFormation templates. Its manifest records the
upstream repository, full commit, every file digest, and a whole-bundle digest.
CP9 materializes it into a session-owned staging directory and runs the original
script with the local BYOC bootstrap credential; it never executes a floating
branch, arbitrary operator checkout, or runtime clone. A pass-through AWS CLI
wrapper appends the mandatory CP9 owner/session tags only to the script's three
CloudFormation deploys without changing any vendored byte. Under the selector
reservation and account lease it also rechecks the exact stack boundary
immediately before each deploy, rejecting a stack created or replaced after
preflight. Before invoking the official script, CP9 durably records each
stack's observed absence plus the exact account, Region, pinned-template
digest, and parameter digest. Completed
stages re-read the bound ID, creation time, template, parameters, and tags.
_Avoid_: reimplemented CloudFormation, mutable upstream checkout, patched setup script

**BYOC setup contract pin**:
The reviewed upstream commit and bundle digest that select one BYOC
account-setup bundle. They participate in the activation fingerprint and appear
in status and evidence. Moving the pin is an explicit bundle-bump change with
provenance and closure tests, not an activation-time update.
_Avoid_: latest main, implicit upgrade, local source override

**CP9 BYOC session bootstrap**:
A withdrawn same-account design that replaced production fixed-name
CloudFormation/IAM resources with session-derived equivalents. It is retained
only as historical vocabulary after the distinct, exclusive customer-account
model allowed CP9 to run the official production setup contract.
_Avoid_: current BYOC bootstrap, production CloudFormation stack

**O11Y bootstrap prerequisite**:
The O11Y hosted-zone input and fixed IAM roles created by the unmodified
production customer account-setup script. They are accepted in the first core
lifecycle slice solely to preserve the real customer setup contract. They do
not authorize CP9 to create the O11Y shoot, VPC/EKS, services, ACS integration,
or metrics/logging/alerts proof; status must report that runtime as not
deployed.
_Avoid_: O11Y runtime, O11Y ready

**Empty BYOC dataplane**:
One active, session-owned BYOC dataplane created on the first product
shared-pool/cluster path through the BYOC-configured DPM. It includes the
isolated customer VPC, management EKS/AppBox, and cross-account PrivateLink path
but contains no customer TiDB cluster after the cluster is deleted.
_Avoid_: BYOC cluster, hand-created VPC/EKS fixture, DPM E2E fixture

**BYOC management PrivateLink**:
The private management path owned by an Empty BYOC dataplane: a customer-account
endpoint service backed by the cluster-gateway NLB, an interface endpoint in the
BYOC control-plane account, and the `/k8s-apiserver` ingress carried through that
endpoint. Its allowed principal is exactly the BYOC control-plane DPM role. The
interface endpoint uses the remote host VPC and a physical-AZ-compatible subnet,
plus a dedicated session-owned endpoint security group that admits TCP/443 only
from the remote host security group.
_Avoid_: public EKS API, customer-facing cluster endpoint, VPC peering

**BYOC PrivateLink proof**:
Later first-dataplane/cluster-train evidence that the customer endpoint service
and its exact allowed principal are ready, the control-plane interface endpoint
is Available, `/k8s-apiserver` is reachable through the endpoint DNS, and the
public EKS API path is simultaneously unreachable. Activation performs only the
immutable network preflight because no dataplane exists yet. The Empty BYOC
dataplane retains this proof boundary until session destroy removes the
dataplane and both accounts pass absence checks.
_Avoid_: activation readiness, resource-exists check, public fallback

**BYOC activation journal**:
The durable, credential-free stage record for `cp9 byoc activate`. It binds an
immutable input fingerprint to each stage's pending, running, done, failed, or
interrupted state, attempt count, timestamps, resolved non-secret outputs, and
last error. It retains the activation's bundle/image provenance so later code
pin changes still permit exact destroy while requiring recreate for activation.
A done stage is live-revalidated before a rerun skips it; the journal is
evidence for reconciliation, not a substitute for observed truth. Account
setup stores a separate durable create intent for each official stack before
the script can deploy it. Role-chain readiness re-reads both live IAM hops,
including the customer role trust, as well as the sanitized runtime proof.
_Avoid_: transaction log, credential cache, blind done marker

**Terminal BYOC destroy checkpoint**:
Journal state `destroyed`, persisted only after session-owned absence is proved,
exact owned reservations are released, and absence is proved again. A retry is
an idempotent local checkpoint operation with no external calls, so later host
or runtime teardown cannot make enclosing destroy non-retryable. If the process
stops before checkpoint publication, exact zero-state recovery handles foreign
winners without touching them. Activation cannot resume a terminal journal.
_Avoid_: delete-complete in memory, reopen-after-destroy, global-slot absence

**BYOC activation resume**:
Reconciliation performed by rerunning `cp9 byoc activate` with the same immutable
fingerprint after failure or interruption. CloudFormation retains its normal
per-stack rollback, while CP9 preserves successful stages and resumes the wider
cross-system workflow. Changing an immutable input requires session destroy and
recreate; only explicit destroy performs broad cross-account teardown.
_Avoid_: whole-activation rollback, best-effort retry, mutable resume

**Cross-account BYOC proof**:
Acceptance evidence that the BYOC regional control plane assumes the customer
account role, reconciles customer resources through that identity, authorizes
the control-plane principal on the customer PrivateLink service, and creates
the endpoint in the control-plane account. It requires distinct resolved AWS
account IDs.
_Avoid_: same-account approximation, resource-isolation-only proof

**BYOC Region activation**:
The lifecycle that makes the BYOC regional control plane, catalog, customer
bootstrap, images, and cross-account configuration ready. Matching the
auto-deploy AWS BYOC Terraform boundary, it does not call DPM `CreateDataPlane`
or create the customer TiDB dataplane VPC/EKS.
_Avoid_: BYOC cluster creation, BYOC proof train

**Opt-in BYOC activation**:
The user-authorized transition that may prepare a customer account and make a
BYOC Region ready. `byoc.enabled: true` runs it after the Dev full baseline in
`cp9 up`; false/omitted leaves it to day-2 `cp9 byoc activate`. Both entry
points use the same resumable journal, while `cp9 byoc status` only observes.
_Avoid_: implicit customer-account mutation, separate eager activation engine

**BYOC-A**:
The first-slice public-product-API acceptance train for a ready BYOC Region. It
creates the first cluster and BYOC dataplane substrate, proves private
cross-account operation and customer-image use through SQL readiness, then
deletes the cluster and leaves an Empty BYOC dataplane for final closeout. It
binds the Region and CP role to a fully done activation journal before mutation,
includes the reviewed project label, and exact-deletes its returned TiDB id on
any later failure.
_Avoid_: DPM fixture, direct DPM train, BYOC Region activation proof

**BYOC cluster lifecycle proof**:
Acceptance evidence that a ready BYOC Region can create a customer TiDB
cluster, reach its SQL endpoint, delete it, and prove exact absence.
_Avoid_: BYOC Region activation, infrastructure-ready proof

**BYOC session closeout**:
The final lifecycle boundary that deletes every session-owned BYOC object in
both AWS accounts, releases the account lease and then the selector reservation
after exact absence proof, and then removes the ordinary remote session.
Customer-owned prerequisites, the BYOC account image cache, and the shared
inert control-plane account-setup principal remain explicit exclusions; O11Y
runtime remains absent. Losing pre-mutation sessions close by
proving their own zero state and never delete or wait for a foreign selector or
account lease. Closeout is lifecycle-locked and terminally checkpointed so an
enclosing destroy retry remains safe. A pending config-scoped closeout blocks
session startup, and its cleanup/handoff checkpoint outlives the session root
until root removal succeeds.
_Avoid_: cluster delete, customer account retirement, prerequisite cleanup

**Session config**:
The user-editable cp9 YAML that selects the session identity, host/substrate,
target, and Tilt execution for a cp9 session.
_Avoid_: persona topology, service graph, `cp9.local.yaml`

**Session context**:
The read-only handoff from cp9 lifecycle to a persona Tiltfile for one cp9
session; it describes resolved session and substrate facts, not persona
topology, runtime status, or evidence.
_Avoid_: generated service graph, service manifest inputs, Tilt status

**Host mode**:
The runtime placement choice for a cp9 session, such as local laptop k3d or a
cloud-hosted k3d substrate.
_Avoid_: persona, profile

**Cloud-hosted substrate**:
The host mode used for old-dev replacement acceptance, where product runtime
executes in a cloud network while the laptop remains the command and editing
surface.
_Avoid_: local cp9

**Compressed staging**:
A cp9 session model that preserves staging product contracts while reducing
staging placement and multiplicity to a temporary session.
_Avoid_: staging clone, local dev

**api-gateway public entrypoint**:
The staging-like public entry path for public-facing UI APIs and OpenAPI
traffic: public load balancer, Kong ingress/proxy, `api-gateway` routes/plugins,
then persona services.
_Avoid_: direct service endpoint, generic cp9 ingress, raw service load balancer

**Dev full route layer**:
The single public Kong/api-gateway route layer for a Dev full runtime session.
Premium-plan, Dedicated, and imported Starter routes share this route layer
rather than creating a second Starter gateway or host.
_Avoid_: second Starter public gateway, separate Starter host

**Shared management services**:
The real shared `tidb-mgmt-portal` and `tidb-mgmt-service` instances used by
the Dev full runtime for both Premium-family and Starter/Essential v1
OpenAPI traffic. Imported Starter must reuse these instances instead of running
separate Starter-named management service copies.
_Avoid_: Starter-specific `tidb-mgmt-portal`, Starter-specific `tidb-mgmt-service`

**Shared account service**:
The real `premium-account-svc` account service used by the Dev full runtime for
Premium-family, Dedicated, and imported Starter/Essential v1 account
and ACL calls. Imported Starter must not bring forward the standalone
`account-local-stub`; it joins the staging-like single account service contract.
_Avoid_: Starter account stub, product-specific account service copy

**New-account substrate proof**:
Acceptance evidence gathered from the new AWS account `804837308162`, using
profile `dev-offline-afterworld`, with all resources recycled by `cp9 destroy`.
_Avoid_: legacy dev-account proof, unrecycled cost proof

**Persona end-to-end proof**:
Acceptance evidence that one persona creates a real cluster through the
api-gateway public entrypoint, reaches the returned endpoint, executes
`select 1`, and cleans up session resources.
_Avoid_: route-only proof, create-only proof, local-only proof

**Dev full closeout**:
The session-level status, train artifacts, and cleanup evidence for a Dev full
runtime session. Historical `proof-summary.json` artifacts may still be
read by `cp9 status`, but new closeouts should use status output plus the
product-specific train and destroy artifacts directly.
_Avoid_: separate Starter proof persona, folded Premium train

**Dynamic data-plane proof**:
Acceptance evidence that a Premium or Dedicated persona uses the product's real
create and destroy path for customer-visible data-plane behavior.
_Avoid_: DP fixture

**Dedicated source-backed integration point**:
The #670 planning and contract hook that keeps future Dedicated imports on PRD
#664's unified source-backed model. Imported Dedicated k3d/control-plane
services must use ADR 0011-style source-backed mechanics through the shared
contract registry and image-source summary. Any future real Dedicated data-plane
candidate defaults to an ADR 0014/0015 image-level backend unless a future PRD
approves another backend. Dedicated must not add a separate user-facing
`live_update_services` opt-in.
_Avoid_: Dedicated-specific source mode, direct Tilt-only target list, second
Dedicated live-update opt-in

**Shared pool**:
A real-EKS dataplane that hosts multiple Premium logical clusters, keyed by
`SharedPoolId` and persisting across cluster create/delete
(`enableCleanSharedPool: false`). One cp9 env uses one shared pool that all of
that env's creates reuse.
_Avoid_: per-cluster dataplane, dedicated EKS per cluster

**Logical cluster**:
A Premium TiDB cluster (a `TiDBGroup`) placed onto a Shared pool by `SharedPoolId`
rather than getting its own EKS. It is the unit an agent creates and deletes in a
loop.
_Avoid_: standalone cluster, own-EKS cluster

**Pre-warmed pool**:
Withdrawn historical design for eagerly provisioning an env's Shared pool at
env-up. `cp9 prewarm` and `cp9 prewarm status` were removed in the 2026-07-06
command-surface cleanup; do not describe a pre-warmed pool as a current cp9
command or readiness surface. See ADR 0009 for historical context only.
_Avoid_: warm node pool, fleet pool, idle-node pool

**Session access summary**:
The read-only connection and login facts `cp9 status` reports for the current
session: local kubeconfig path/context, Tilt URL, Remote Dev full UI URL and
non-secret login guidance, plus persisted Starter EKS facts when present.
`cp9 share` and `cp9 share frontend` are retired; status never changes security
groups, Account data, CORS, or EKS access. See ADR 0012 for historical context.
_Avoid_: share bundle, cp9 join, credential dump

**Premium/Essential v2**:
The Premium-family product surface currently proven by cp9 Dev full AWS.
Essential v2 is a Premium-family variant, not the same architecture as
Starter/Essential v1.
_Avoid_: Essential

**Starter/Essential v1**:
The shared Starter-family product surface where the regional control plane is
also the shared dataplane. Starter and Essential v1 share the same architectural
family even when their product trains assert different behavior.
_Avoid_: Starter DB provider

**Imported Starter slice**:
The Starter/Essential v1 product surface accepted inside the Dev full persona
proof boundary. Dev full owns the session and proof surface; Starter owns
the Starter-family vocabulary and OpenAPI train semantics.
_Avoid_: Starter-as-Premium, Premium Starter skill, separate Starter proof persona

**Separated Starter skill entry**:
The Starter-owned `starter` skill entry (renamed from `starter-openapi` in the
2026-07-25 product-line skill restructure, and now also the home of Essential v1)
retargeted to guide Starter/Essential v1 proof work against the Dev full
runtime/session. It keeps Starter product semantics, review gates, artifacts, and
failure classification separate from Premium OpenAPI guidance.
_Avoid_: Premium Starter skill, folded Premium train, standalone persona proof,
separate Essential v1 skill directory

**Starter OpenAPI surfaces**:
The two logical Starter/Essential v1 API surfaces that a train must keep
distinct: cluster lifecycle and serverless data operations. Importing Starter
into Dev full gives them one public entrypoint, not one undifferentiated API
surface.
_Avoid_: single Starter base URL, generic Starter API

**starter-full**:
The standalone cp9 full persona inventory for Starter/Essential v1 used to
identify the import scope. It is distinct from the legacy direct
`tidb-cloud-starter` database provider helper and is not the target
user-facing proof persona after Starter is imported into Dev full; its files stay
as historical migration inventory.
_Avoid_: starter provider, create-only Starter, separate Starter proof persona

**Global CP**:
The global control-plane layer that accepts product requests and dispatches
Starter/Essential v1 work to a regional layer.
_Avoid_: base cluster

**Regional CP/DP**:
The Starter/Essential v1 regional layer that is both control plane and shared
dataplane for the product surface.
_Avoid_: customer dataplane

**Starter regional substrate**:
The standing Starter/Essential v1 regional CP/DP capacity that handles Starter
clusters. Starter create requests place work onto this existing substrate rather
than provisioning a new dataplane per request; cp9 keeps it as session-owned
real EKS capacity when staging dataplane fidelity is required.
_Avoid_: per-cluster dataplane provisioning, dynamic regional EKS

**Purge dry-run**:
A fully read-only `cp9 purge` run. It reports candidates, tag-assurance plans,
aws-nuke survivors, and blocked reasons without mutating tags or deleting
resources. A dry-run must never change the set a later destructive run would act
on.
_Avoid_: preview that tags, simulate-with-mutation

**Tag-assurance plan**:
The set of cp9 scope-tag repairs `cp9 purge` would apply to untagged children of
a trusted parent before aws-nuke. The whole plan is validated for a candidate
before any tag is applied, so a late conflict produces no partial repair.
_Avoid_: tag fixup, retag pass

**Trusted parent proof**:
Deterministic evidence that an untagged resource belongs to a cp9 scope because
it is contained by a verified cp9 parent — a tagged VPC, EKS cluster, IAM role,
or load-balancer-derived Route53 selector. It is the only basis on which tag
assurance may repair tags.
_Avoid_: ownership guess, relationship hint

**Name-only inference**:
Concluding a resource is cp9-owned solely because its name resembles a session.
It is rejected for tag assurance and deletion; a session-looking name is at most
a logged clue, never proof.
_Avoid_: name match cleanup, fuzzy session match

## Flagged Ambiguities

**Essential**:
Use `Essential v1` for the Starter-family shared regional architecture. Use
`Essential v2` for the Premium-family product surface.

## Example Dialogue

Developer: "Can we use the Starter provider for this proof?"

Domain expert: "No. `starter-full` is a full persona for Starter/Essential v1.
The legacy Starter DB provider is not the persona."

Developer: "Does regional mean customer dataplane like Premium?"

Domain expert: "No. In Starter/Essential v1, the regional CP/DP is both the
regional control plane and the shared dataplane."