// The CLI's instance provisioning API: the verbs that turn "place an
// instance" into a data write in the deployment bucket, so a signup path
// holding no AWS credentials and no box access can provision one in
// seconds. The record it writes is the whole authorization; the agent's
// reconcile pass (internal/provision) is what turns it into a route, on its
// own box only.
//
// This was the FIRST console family a non-human principal could speak to,
// and for a while it carried its own resolver (apiInstancePrincipal) to do
// it. That resolver is gone: service principals are a platform-wide idea now
// (svcprincipal.go, spec 2026-08-18), and its rules — the sqid-only match,
// the exact app binding, the `app:<sqid>/<app>` audit actor — live in the
// shared path (apiAccountApp) where every family gets them. What is left
// here is the same gate with the instance BUDGET bound to it.
//
// Two shapes of bearer reach it: a person's token, resolved through exactly
// the same membership-proving lookup every other CLI verb uses, or a service
// credential bound to one account and — for the legacy app tokens this
// family minted — one app, which must match the path it is used on EXACTLY.
// Every refusal before that proof is the family's byte-identical 404 — an
// unknown account, someone else's account, an unclaimed app and a service
// credential probing a foreign path are all one answer, so probing teaches
// nothing.
//
// Spec: docs/superpowers/specs/2026-08-04-instance-provisioning-design.md
// §7 (the verbs), §8 (the credential), §10 (the DNS seam), §11 (security).
package console

import (
	"context"
	"encoding/json"
	"errors"
	"log"
	"net/http"
	"os"
	"slices"
	"strconv"
	"strings"
	"time"

	"github.com/carlosframework/platform/internal/gate"
	"github.com/carlosframework/platform/internal/hostops"
	"github.com/carlosframework/platform/internal/provision"
	"github.com/carlosframework/platform/internal/registry"
	"github.com/carlosframework/platform/internal/release"
	"github.com/carlosframework/platform/internal/status"
)

// instanceStoreTimeout bounds every store round trip these handlers make,
// the same 15s the rest of the CLI API uses: a wedged bucket costs one
// request 15 seconds, not a console goroutine forever.
const instanceStoreTimeout = 15 * time.Second

// instanceListMax caps one list answer (spec §7): instance fleets can be
// large, and a caller that needs more than 500 is not using this door for
// what it is. The response says so with `truncated` rather than silently
// serving a prefix.
const instanceListMax = 500

// instanceGate is the preamble every instance verb shares, in the order the
// family fixed (handleAPIPromote): principal FIRST, budget second, then the
// deployment's own readiness. The order is load-bearing — a rate limit
// answered before the principal is proven would be a 429 where a 404
// belongs, and "this path is rate limited" is itself the answer that an app
// exists here.
//
// The principal proof is apiAccountApp's, which is to say the general one:
// this family no longer resolves its own callers. The string it returns is
// the audit actor either way — an address for a person, app:<sqid>/<app> for
// a legacy app token exactly as before, service:<sqid>/<name> for a named
// service credential.
func (s *Server) instanceGate(w http.ResponseWriter, r *http.Request) (string, *Account, string, bool) {
	return s.instanceGateFor(w, r, "instance")
}

// instanceGateFor is instanceGate with the noun its 429 uses. The BUDGET is
// deliberately shared across every family that gates here — one credential
// doing one kind of work, and one place for the ordering to live — but a
// member creating sidecars should not be told they made too many "instance
// requests" when they hit it. Only the sentence varies; nothing about the
// order, the key or the limiter does.
func (s *Server) instanceGateFor(w http.ResponseWriter, r *http.Request, noun string) (string, *Account, string, bool) {
	return s.instanceGateSaying(w, r, noun, mainGateCopy())
}

// instanceGateSaying is instanceGateFor with the sentences of c.
func (s *Server) instanceGateSaying(w http.ResponseWriter, r *http.Request, noun string, c gateCopy) (string, *Account, string, bool) {
	principal, acct, app, ok := s.apiAccountAppSaying(w, r, s.store.HasAppIn, c)
	if !ok {
		return "", nil, "", false
	}
	// Keyed on the TOKEN, not the address (see cliInstanceBurst): the
	// principal here is frequently an app, which has no address of its own,
	// and a signup burst is the workload rather than the abuse.
	if !s.cli.instances.allow(hashToken(bearer(r)), time.Now()) {
		jsonError(w, http.StatusTooManyRequests, c.tooMany(noun))
		return "", nil, "", false
	}
	// A console with no deployment bucket configured can answer none of
	// these. Same shape as promote's signing-key check, and in the same
	// place: after the gate, before anything reaches for the store.
	if s.cfg.Releases == nil {
		jsonError(w, http.StatusServiceUnavailable, c.noBucket)
		return "", nil, "", false
	}
	return principal, acct, app, true
}

// instanceManifest reads the app's instances manifest and answers the
// caller itself when it cannot be had. ok=false means a response has
// already been written.
//
// CREATE is its only caller, and deliberately so: the manifest is policy
// about what may be BROUGHT INTO existence (which domain, which pool, which
// regions, which channel). Reads and deletes are about what already exists,
// which no version of this manifest can retract.
//
// The two failures are kept apart on purpose: ABSENCE is an answer — the
// feature does not exist for this app — while a read failure is the bucket
// being unreachable. Reporting a hiccup as "instances are not enabled"
// would tell an app its feature had been switched off.
func (s *Server) instanceManifest(ctx context.Context, w http.ResponseWriter, acct *Account, app string) (*provision.Manifest, bool) {
	m, err := provision.GetManifest(ctx, s.cfg.Releases, acct.Sqid, app)
	switch {
	case err == nil:
		return m, true
	case errors.Is(err, os.ErrNotExist):
		// Membership (or binding) is already proven, so this may name its
		// cause and the operator act that fixes it.
		jsonError(w, http.StatusConflict,
			"instances are not enabled for "+app+" — an operator writes apps/"+
				acct.Sqid+"/"+app+"/instances.json (carlos instances enable)")
		return nil, false
	default:
		log.Printf("console: api instances manifest %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not read instance settings")
		return nil, false
	}
}

// instanceListRecord wraps provision.Record with the console's own
// staged_version join (Task 8, issue #78) rather than adding the field to
// Record itself: Record is the wire shape CreateRecord persists to the
// bucket, and staged_version is never written there — it is computed fresh
// at every list call from status/boxes/*.json, so giving Record the field
// would risk a future write path serializing a stale or zero value into a
// stored record that this join was never meant to touch.
type instanceListRecord struct {
	provision.Record
	// StagedVersion is registry.Route.Version as last reported by whichever
	// box's adopt pass claimed this host, read from that box's own
	// status/boxes/<label>.json (internal/status's bucket-private Metrics
	// block — see its package doc). Empty both for a host no box has ever
	// reported AND for one whose last-reporting box has gone stale (see
	// loadBoxJoin below, which asks status.BoxStale the same question
	// the operator fleet page does): fresh-ish for as long as some box keeps
	// reporting it, but a box that has gone silent drops OUT of the join
	// rather than going on serving that box's last-known version as if it
	// were current. The deploy watch does NOT read this field.
	StagedVersion string `json:"staged_version"`
	// Upstreams is the per-upstream probe state the box's edge currently
	// believes for this host (status.BoxMetrics.Upstreams), joined from the
	// same snapshots and under the same staleness rule as StagedVersion — a
	// box that has gone silent drops out rather than going on answering for
	// upstreams it may no longer be probing. It is what lets `carlos
	// instances` say WHICH upstream is down without a box session, and it is
	// omitempty because that is the honest shape for the overwhelming
	// majority of records: only a route with more than one addr (or an
	// explicit probe block) is probed at all, so every single-upstream record
	// in production carries no such key and parses exactly as it always did.
	Upstreams []status.UpstreamState `json:"upstreams,omitempty"`
	// Health is the same one-word state the Running tab's column shows,
	// computed by instanceHealth below from the registry row joined with the
	// metrics sweep. Additive on the wire (a client that never heard of it
	// keeps parsing the record it always parsed) and annotation-grade: a
	// record whose health could not be computed still lists, reading
	// "Setting up" rather than failing the call.
	Health string `json:"health"`
	// ServedBy is where this host is OBSERVED to be served (issue #337):
	// every box whose control/edges/<box>.json names it, with that box's AWS
	// region — the same files the edges backhaul on, so this is what the
	// platform itself routes by, not a guess. A list, not a scalar: an
	// everywhere-class route is genuinely served on every box. Distinct from
	// Record.Region, which is the REQUESTED placement code ("" =
	// unconstrained, "fleet/<name>"), and absent for a host no file names.
	ServedBy []servedBy `json:"served_by,omitempty"`
	// HiddenGate shadows Record.Gate for encoding/json (a shallower field of
	// the same name wins), so the bcrypt hash never leaves the console; it
	// is always "" and omitted. Gated is what a member may know.
	HiddenGate string `json:"gate,omitempty"`
	Gated      bool   `json:"gated"`
	// DBBytes is the on-disk size of this instance's SQLite database (file
	// plus -wal) as its box last measured it (status.BoxMetrics.RouteDBBytes),
	// under the same staleness rule as StagedVersion. Absent when no fresh
	// box has sized it: not minted yet, no database file yet, or a route
	// whose database lives somewhere the platform does not know about.
	DBBytes *int64 `json:"db_bytes,omitempty"`
	// Rollout is this host's rollout as its box last reported it
	// (zero-downtime spec §9.1), joined under StagedVersion's staleness rule.
	// Absent when no fresh box reports one: a box from before plan 5, one
	// with CARLOS_SWAP off, or one gone dark. The deploy watch reads it.
	Rollout *rolloutView `json:"rollout,omitempty"`
	// UpdateReport is this host's update report as its box last gave it
	// (status.BoxMetrics.Updates and UpdateSettings), joined under the same
	// staleness and tenant rules as Rollout. It is named update_report
	// because the embedded record already owns "updates" (its own setting).
	UpdateReport *updatesJoinView `json:"update_report,omitempty"`
	// SettingsDefault says the record and the app's policy together ask for
	// today's behaviour (provision.EffectiveUpdates(...).Default()), so the
	// CLI can tell an instance on a box that ignores settings from one that
	// never asked for any.
	SettingsDefault bool `json:"settings_default"`
}

// instanceHealth computes each record host's health word the same way the
// Running tab does — registry row joined with the metrics sweep — so the
// API, the CLI and the page can never disagree about an instance's state.
// A record with no registry row yet is still provisioning: "Setting up".
// Failures degrade to that same word rather than erroring the list: health
// here is an annotation on the record, not the record.
//
// The tenant boundary is the recs slice and nothing else. recs arrives
// already scoped to one account+app (provision.ListRecords under that app's
// own prefix), and every lookup below is keyed on a host drawn FROM recs —
// the registry read returns the whole box's routes, including other tenants',
// and none of them can enter hosts, unitByHost or the answer. That matters
// twice over: OwnerAppMetrics' allowlist is exactly the hosts and stamped
// units it is handed, so a foreign unit name reaching unitByHost would widen
// the metrics view past the caller's own app.
func (s *Server) instanceHealth(ctx context.Context, recs []provision.Record) map[string]string {
	out := make(map[string]string, len(recs))
	for _, rec := range recs {
		out[rec.Host] = "Setting up"
	}
	if s.cfg.Registry == "" {
		// A console with no registry configured cannot know any route's
		// state; opening "" would hand sqlite a throwaway temp DB and answer
		// the same "Setting up" a page later, having created a file for it.
		return out
	}
	reg, err := openRegistry(s.cfg.Registry)
	if err != nil {
		log.Printf("console: api instances health: registry %s: %v", s.cfg.Registry, err)
		return out
	}
	routes, err := reg.List()
	if err != nil {
		log.Printf("console: api instances health: registry list: %v", err)
		return out
	}
	byHost := make(map[string]registry.Route, len(routes))
	for _, rt := range routes {
		byHost[rt.Host] = rt
	}
	// routeFor is the join reduced to the routes that ANSWER for these
	// records, built once and used by both loops so the two can never drift.
	routeFor := make(map[string]registry.Route, len(recs))
	var hosts []string
	unitByHost := map[string]string{}
	for _, rec := range recs {
		rt, ok := byHost[rec.Host]
		if !ok {
			continue // no route minted yet: the record stays "Setting up"
		}
		// A row stamped to another app or account is not this record's route.
		// The box's own reconcile pass says so — it refuses to converge such
		// a row ("exists but was not minted by this pass — leaving it
		// alone", reconcile.go) — and reporting it here would be worse than
		// useless twice: the caller would read a neighbour's health word as
		// its own instance's, and the neighbour's stamped Unit would enter
		// unitByHost, widening OwnerAppMetrics' allowlist past this app's own
		// units. An UNSTAMPED row (either column empty: hand-added, or minted
		// before the column existed) still joins — refusing those would read
		// live instances as forever "Setting up".
		if (rt.App != "" && rt.App != rec.App) || (rt.Account != "" && rt.Account != rec.Account) {
			continue
		}
		routeFor[rec.Host] = rt
		hosts = append(hosts, rec.Host)
		if rt.Unit != "" {
			unitByHost[rec.Host] = rt.Unit
		}
	}
	for h, word := range s.healthByHost(ctx, routeFor) {
		out[h] = word
	}
	return out
}

// healthByHost is the metrics half of a health answer, shared by
// instanceHealth (records joined to routes) and handleAPIRoutes (routes
// directly, issue #64) so the two — and the Running tab, which uses the
// same healthWord — can never disagree about an instance's state.
//
// routeFor arrives ALREADY SCOPED to the caller's own account and app.
// This function performs no tenant check of its own and must never be
// handed an unfiltered registry listing: OwnerAppMetrics' allowlist is
// exactly the hosts and stamped units it is given, so a foreign unit name
// reaching unitByHost below would widen the metrics view past the caller's
// own app. The scoping lives in each caller, beside the reason that
// caller's rows are the caller's to see.
func (s *Server) healthByHost(ctx context.Context, routeFor map[string]registry.Route) map[string]string {
	out := make(map[string]string, len(routeFor))
	hosts := make([]string, 0, len(routeFor))
	unitByHost := map[string]string{}
	for h, rt := range routeFor {
		hosts = append(hosts, h)
		if rt.Unit != "" {
			unitByHost[h] = rt.Unit
		}
	}
	am, err := s.OwnerAppMetrics(ctx, hosts, unitByHost)
	if err != nil {
		// An unreadable sweep is not knowledge that these instances are
		// down: every host reads as not-reporting below, which healthWord
		// turns into "No readings" or "Not responding" per expectsReadings —
		// the same answer the page gives when the sweep is unavailable.
		log.Printf("console: health by host: metrics: %v", err)
		am = nil
	}
	rep := make(map[string]bool, len(am))
	for _, m := range am {
		if m.Reporting() {
			rep[m.Host] = true
		}
	}
	for h, rt := range routeFor {
		status := rt.Status
		if status == "" {
			status = "ready" // registry contract: empty status means ready
		}
		out[h] = healthWord(rt.Kind, status, rt.Hibernate, rep[h],
			expectsReadings(rt.Provisioned, rt.Unit, rt.Backing))
	}
	return out
}

// boxJoin is everything the list annotates a record with from the FLEET's own
// snapshots, gathered in one pass: the staged version and the per-upstream
// probe table, both host-keyed.
//
// One struct and one loader rather than two functions, because the two joins
// must vote on staleness with the same reading of the same objects: a second
// LoadBoxes call could see a box go stale between them and answer a record's
// version from a box whose upstream table it had just refused, which is a
// disagreement no reader could diagnose.
type boxJoin struct {
	versions  map[string]string
	serving   map[string]string
	upstreams map[string][]status.UpstreamState
	dbBytes   map[string]int64
	rollouts  map[string]rolloutView
	updates   map[string]updatesJoinView
}

// updatesJoinView is one host's update report as a member sees it. account
// and app are the report's tenant: the entry's own (status.HostUpdates.Account
// and .App) when it names one, else the one the SAME box's rollout report
// gives for the host (status.HostRollout.Account and .App), else none. They
// decide whether the report may be joined (update).
type updatesJoinView struct {
	Desired         string `json:"desired,omitempty"`
	Reason          string `json:"reason,omitempty"`
	Detail          string `json:"detail,omitempty"`
	Baking          string `json:"baking,omitempty"`
	Major           *int   `json:"major,omitempty"`
	Pending         uint64 `json:"pending,omitempty"`
	Completed       uint64 `json:"completed,omitempty"`
	CompletedFailed bool   `json:"completed_failed,omitempty"`
	// Enforced says the box applies update settings at all
	// (status.BoxMetrics.UpdateSettings); a box from before them reports
	// nothing, and an empty view must not read as "following its channel".
	Enforced     bool `json:"enforced"`
	account, app string
}

// update is the join's answer for host, or nil when the box has nothing on
// it or names another tenant for it. The cross-tenant rule is rollout's: a
// box's report about a host never surfaces on another tenant's list or page.
// A report is this account's and this app's only when its tenant is known
// and is this one (Astra r1, R18). Owning the hostname now is not enough: a
// snapshot stays fresh for minutes, and the host may have been another
// tenant's when the box wrote it, on a platform box as on a fleet box. A
// report with no known tenant yields whether the box enforces settings and
// nothing else, so an old box still reads "settings not enforced" and nothing
// about any instance crosses.
func (j boxJoin) update(host, acct, app string) *updatesJoinView {
	v, ok := j.updates[host]
	if !ok {
		return nil
	}
	if v.account == "" && v.app == "" {
		return &updatesJoinView{Enforced: v.Enforced}
	}
	if v.account != acct || v.app != app {
		return nil
	}
	return &v
}

// rolloutView is one host's rollout as a member sees it. account and app are
// the report's own, kept so the join can refuse to cross tenants (rollout).
type rolloutView struct {
	Box           string `json:"box"`
	Installed     string `json:"installed"`
	Serving       string `json:"serving,omitempty"`
	Good          string `json:"good,omitempty"`
	Awake         bool   `json:"awake"`
	Attempt       string `json:"attempt,omitempty"`
	AttemptBuild  string `json:"attempt_build,omitempty"`
	HeldBy        string `json:"held_by,omitempty"`
	Reason        string `json:"reason,omitempty"`
	ConfigPending bool   `json:"config_pending,omitempty"`
	// Transient is the box's word that the host's process is starting or
	// stopping (status.HostRollout.Transient): neither asleep nor awake.
	Transient bool `json:"transient,omitempty"`
	// SchedulerIdle is the box's scheduler for this app: nothing queued,
	// running or settling, first-wake observations included (spec §9.1's
	// "a box is done" half).
	SchedulerIdle bool `json:"scheduler_idle"`
	// Unavailable is the reason code a box gives for being unable to arm its
	// rollout scheduler (RolloutReport.Unavailable). When set, the view is
	// only Box, Installed and this: the box reports no per-host state. The
	// one exception is a host a box that declined the flag reports held by
	// the failure book it honours (Task 10), whose view also carries Good,
	// the attempt, HeldBy and its epoch.
	Unavailable  string `json:"unavailable,omitempty"`
	account, app string
	// heldEpoch is the box's epoch for HeldBy's restriction
	// (status.HostRollout.HeldEpoch), and heldBook the failure book it
	// counts in (HeldBook, final review round 1, finding 3). Neither is
	// shown: the retry doors sign both into their grant (retryHostBuild).
	heldEpoch uint64
	heldBook  string
	// retryV is the retry protocol the box takes (status.HostRollout.RetryV):
	// 0 is a box built before the host-retry log, which reads no grant
	// there, so the retry doors write it none (retryHostBuild).
	retryV int
	// refused marks a view built from an Unavailable box, which has no
	// account or app to check (hosts are unique; the caller filtered by app).
	refused bool
}

// rollout is the join's answer for host, or nil unless the report is this
// account's and this app's: a report is the box's word about a route, and a
// route stamped to another app is not this record's (instanceHealth's rule).
func (j boxJoin) rollout(host, acct, app string) *rolloutView {
	v, ok := j.rollouts[host]
	if !ok || (!v.refused && (v.account != acct || v.app != app)) {
		return nil
	}
	return &v
}

// dbSize is the join's database size for host, nil when no fresh box
// reported one — so the wire field is absent rather than a 0 that reads as
// an empty database.
func (j boxJoin) dbSize(host string) *int64 {
	n, ok := j.dbBytes[host]
	if !ok {
		return nil
	}
	return &n
}

// loadBoxJoin builds boxJoin from every NON-STALE box's own
// private Metrics block (status/boxes/*.json), through status.LoadBoxes —
// the same loader the operator fleet page's HostRows reads through
// (internal/console/view.go) — and status.BoxStale, the fleet's one
// staleness rule (internal/status/fleet.go: "Every caller ... asks this
// function, never its own subtraction"). A box that stopped reporting is
// EXCLUDED from the join entirely rather than contributing its last-known
// reading: the alternative would let a route adopted a week ago on a now-
// dark box keep answering staged_version queries as if it were as current
// as a box that reported thirty seconds ago, which is exactly the kind of
// reassuring-but-wrong answer internal/status's whole design refuses to
// give (see BoxStale's own doc). now is passed in, not read internally, so
// this and BuildFleet/HostRows always vote on staleness using the request's
// own clock rather than three independent time.Now() calls that could
// disagree at a period boundary.
//
// A store that cannot be listed at all — not one corrupt object, the whole
// read failing — degrades to "no staged versions known" rather than
// answering a 500: this join is best-effort observability on top of the
// list, never load-bearing for it. A nil store (a console with no
// deployment bucket configured) is not reachable via handleAPIInstanceList
// today — instanceGate already refuses those with a 503 before this ever
// runs — but the nil check is kept here too so this helper degrades safely
// for any future caller that reaches it before that gate.
func loadBoxJoin(ctx context.Context, s release.Store, now time.Time) boxJoin {
	j, _ := loadBoxJoinComplete(ctx, s, now)
	return j
}

// loadBoxJoinComplete is loadBoxJoin that also says whether every box's
// snapshot was read (status.LoadBoxesComplete): false when the listing
// failed, was capped, or skipped an object it could not read. The join is
// still best-effort; completeness is what lets a reader tell "no box reports
// this host" from "the report may be the one that was not read" (Astra plan
// 6 R1 #4: the deploy watch must not URL-poll on the second).
func loadBoxJoinComplete(ctx context.Context, s release.Store, now time.Time) (boxJoin, bool) {
	if s == nil {
		return boxJoin{}, false
	}
	boxes, complete, err := status.LoadBoxesComplete(ctx, s)
	if err != nil {
		log.Printf("console: api instances: could not load status boxes for the list join: %v", err)
		return boxJoin{}, false
	}
	return joinBoxes(boxes, now), complete
}

// loadRolloutJoin is the box join the instance list, the instance page and
// the host-retry door share (Astra plan 6 R1 #6), so the three never
// disagree about a host's rollout: the platform's boxes (status/boxes/),
// then the rollout reports of the customer-fleet boxes of THIS account's
// fleets (fleets/<name>/status/boxes/, the prefix systemBoxes reads). A
// fleet another account owns is never read: fleet names are one flat
// namespace across accounts, and its boxes are written by machines this
// account does not control. boxJoin.rollout still checks the report's own
// account and app.
//
// Hosts are assumed unique to one box. When two boxes name the same host (a
// move in flight, a report not yet stale), the last platform box read wins,
// as loadBoxJoin always did, and a platform box wins over any fleet box,
// then the first fleet box read wins: the operator's boxes are the ones this
// console trusts most.
//
// complete is false when a read failed on a source that could hold the
// reports in question: any platform box snapshot, and the fleets relevant
// names (Astra plan 6 R2: an unreadable snapshot on a fleet none of the
// app's instances is placed on says nothing about the app, and must not
// block its deploy watch's fallback). relevant nil counts every fleet of the
// account. A registry that cannot be read counts only when relevant names
// some fleet. A console with no route registry, or none yet, has no fleets
// and is complete on its platform boxes alone. Every fleet of the account is
// still READ, whatever relevant says: completeness is scoped, the join's
// content is not.
func (s *Server) loadRolloutJoin(ctx context.Context, acct string, now time.Time, relevant map[string]bool) (boxJoin, bool) {
	j, complete := loadBoxJoinComplete(ctx, s.cfg.Releases, now)
	if s.cfg.Releases == nil || s.cfg.Registry == "" {
		return j, complete
	}
	counts := func(fleet string) bool { return relevant == nil || relevant[fleet] }
	unreadable := relevant == nil || len(relevant) > 0
	reg, err := s.openPassRegistry()
	switch {
	case errors.Is(err, os.ErrNotExist):
		return j, complete // no registry file yet: no fleets
	case err != nil:
		log.Printf("console: rollout join %s: open registry: %v", acct, err)
		return j, complete && !unreadable
	}
	fleets, err := reg.ListFleets()
	if err != nil {
		log.Printf("console: rollout join %s: list fleets: %v", acct, err)
		return j, complete && !unreadable
	}
	for _, f := range fleets {
		if f.Account != acct {
			continue
		}
		boxes, fleetComplete, err := status.LoadBoxesComplete(ctx, release.NewPrefixStore(s.cfg.Releases, "fleets/"+f.Name+"/"))
		if err != nil {
			log.Printf("console: rollout join %s: fleet %s boxes: %v", acct, f.Name, err)
			complete = complete && !counts(f.Name)
			continue
		}
		complete = complete && (fleetComplete || !counts(f.Name))
		j.joinFleetRollouts(boxes, now)
	}
	return j, complete
}

// recordFleets is the set of customer fleets that could hold reports for
// recs: the fleet each record is placed on (its Region, "fleet/<name>"),
// and either end of a move in flight. Never nil, so an app with no
// fleet-placed record counts no fleet at all.
func recordFleets(recs []provision.Record) map[string]bool {
	out := map[string]bool{}
	for _, rec := range recs {
		places := []string{rec.Region}
		if rec.Move != nil {
			places = append(places, rec.Move.From, rec.Move.To)
		}
		for _, p := range places {
			if f, ok := registry.FleetPlacement(p); ok {
				out[f] = true
			}
		}
	}
	return out
}

// joinBoxes is loadBoxJoin's fold over snapshots already read, so a page that
// has its boxes reads them once.
func joinBoxes(boxes []status.Box, now time.Time) boxJoin {
	j := boxJoin{versions: map[string]string{}, serving: map[string]string{}, upstreams: map[string][]status.UpstreamState{},
		dbBytes: map[string]int64{}, rollouts: map[string]rolloutView{}}
	for _, b := range boxes {
		if b.Metrics == nil || status.BoxStale(b, now, status.SnapshotPeriod) {
			continue
		}
		for host, v := range b.Metrics.RouteVersions {
			j.versions[host] = v
		}
		for host, v := range b.Metrics.RouteServing {
			j.serving[host] = v
		}
		for host, ups := range b.Metrics.Upstreams {
			j.upstreams[host] = ups
		}
		for host, n := range b.Metrics.RouteDBBytes {
			j.dbBytes[host] = n
		}
		j.foldRollout(b, true)
		j.foldUpdates(b, true)
	}
	return j
}

// foldUpdates adds box b's update report to the join, under foldRollout's
// override rule (a fleet box never replaces a host a platform box already
// reported). Every host the box serves gets a view saying whether the box
// enforces settings; the hosts it reports on carry the report. The tenant is
// the report's own, else whatever the same box's rollout report names for
// the host (updatesJoinView).
func (j *boxJoin) foldUpdates(b status.Box, override bool) {
	m := b.Metrics
	enforced := m.UpdateSettings >= status.UpdateSettingsProtocol
	if j.updates == nil {
		j.updates = map[string]updatesJoinView{}
	}
	put := func(host string) {
		if _, had := j.updates[host]; had && !override {
			return
		}
		v := updatesJoinView{Enforced: enforced}
		if m.Rollout != nil {
			if hr, ok := m.Rollout.Hosts[host]; ok {
				v.account, v.app = hr.Account, hr.App
			}
		}
		if u, ok := m.Updates[host]; ok {
			v.Desired, v.Reason, v.Detail, v.Baking, v.Major = u.Desired, u.Reason, u.Detail, u.Baking, u.Major
			v.Pending, v.Completed, v.CompletedFailed = u.Pending, u.Completed, u.CompletedFailed
			if u.Account != "" || u.App != "" {
				v.account, v.app = u.Account, u.App
			}
		}
		j.updates[host] = v
	}
	for host := range m.RouteVersions {
		put(host)
	}
	for host := range m.Updates {
		put(host)
	}
}

// foldRollout adds box b's rollout report to the join. override false keeps
// a host the join already has: the caller folds platform boxes first, and a
// fleet box's word about a host never replaces a platform box's.
func (j *boxJoin) foldRollout(b status.Box, override bool) {
	ro := b.Metrics.Rollout
	if ro == nil {
		return
	}
	if j.rollouts == nil {
		j.rollouts = map[string]rolloutView{}
	}
	put := func(host string, v rolloutView) {
		if _, had := j.rollouts[host]; had && !override {
			return
		}
		j.rollouts[host] = v
	}
	if ro.Unavailable != "" {
		// The scheduler could not arm. Say so for every host this box
		// serves, from the version it reports for it. A box that declined
		// the flag but honours its failure book also reports the hosts the
		// book holds (Task 10, plan review #5): those keep the code, and
		// carry the hold and its epoch so a retry can be signed for them
		// (retryHostBuild), under the report's own account and app.
		for host, v := range b.Metrics.RouteVersions {
			if _, held := ro.Hosts[host]; held {
				continue
			}
			put(host, rolloutView{Box: b.Label, Installed: v, Unavailable: ro.Unavailable, refused: true})
		}
		for host, hr := range ro.Hosts {
			put(host, rolloutView{Box: b.Label, Installed: hr.Installed, Good: hr.Good, Attempt: hr.Attempt, AttemptBuild: hr.AttemptBuild,
				HeldBy: hr.HeldBy, Reason: hr.Reason, Unavailable: ro.Unavailable, account: hr.Account, app: hr.App, heldEpoch: hr.HeldEpoch, heldBook: hr.HeldBook, retryV: hr.RetryV})
		}
		return
	}
	// Plan 5 marks every host a failure record holds as failed. The
	// record's own Host is the one the build failed on; the rest are held
	// by it (spec §9.1), so their attempt is cleared and HeldBy kept. A
	// hold-mode host left down (AttemptDown) stays as it is.
	failedOn := map[[4]string]bool{}
	for _, f := range ro.Failures {
		failedOn[[4]string{f.Account, f.App, f.Build, f.Host}] = true
	}
	for host, hr := range ro.Hosts {
		if hr.Attempt == status.AttemptFailed && !failedOn[[4]string{hr.Account, hr.App, hr.AttemptBuild, host}] {
			hr.Attempt, hr.AttemptBuild = "", ""
		}
		a := ro.Apps[hr.Account+"/"+hr.App]
		put(host, rolloutView{
			Box: b.Label, Installed: hr.Installed, Serving: hr.Serving, Good: hr.Good, Awake: hr.Awake,
			Attempt: hr.Attempt, AttemptBuild: hr.AttemptBuild, HeldBy: hr.HeldBy, Reason: hr.Reason,
			ConfigPending: hr.ConfigPending, Transient: hr.Transient, SchedulerIdle: a.Queued == 0 && a.Running == 0 && a.Settling == 0,
			account: hr.Account, app: hr.App, heldEpoch: hr.HeldEpoch, heldBook: hr.HeldBook, retryV: hr.RetryV,
		})
	}
}

// joinFleetRollouts folds customer-fleet boxes into the join: their rollout
// reports only, and never over a host a platform box already reported. Their
// route versions, upstreams and database sizes stay out, so the list's other
// columns are the platform join's, as before. Staleness is the platform's
// rule (status.BoxStale).
func (j *boxJoin) joinFleetRollouts(boxes []status.Box, now time.Time) {
	for _, b := range boxes {
		if b.Metrics == nil || status.BoxStale(b, now, status.SnapshotPeriod) {
			continue
		}
		j.foldRollout(b, false)
		j.foldUpdates(b, false)
	}
}

// handleAPIInstanceList answers `carlos instances list`: this app's records,
// capped and honest about the cap, each carrying its best-effort
// staged_version (Task 8, issue #78) — fresh-ish while some box keeps
// reporting the host, dropped rather than stale once none does — and its
// health word, plus the same q/health/limit/cursor controls the Running tab
// has, applied SERVER-side so the CLI and the page filter identically.
//
// Every addition is additive on the wire and defaults to today's answer: no
// params means the full `instanceListMax` page, `instances` and `truncated`
// exactly as before, with `health` on each record and `total`/`counts`/
// `next_cursor` alongside. Counts cover every record regardless of the
// filter — they are the whole app's health story, and a filtered count could
// not lead anywhere.
func (s *Server) handleAPIInstanceList(w http.ResponseWriter, r *http.Request) {
	_, acct, app, ok := s.instanceGate(w, r)
	if !ok {
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	recs, truncated, skipped, err := provision.ListRecordsComplete(ctx, s.cfg.Releases, acct.Sqid, app, instanceListMax)
	if err != nil {
		log.Printf("console: api instances list %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not list instances")
		return
	}
	relevant := recordFleets(recs)
	if len(skipped) > 0 {
		// A skipped record's placement is unknown, so every fleet the account
		// has, and the platform, counts toward completeness (nil means all).
		// Astra plan 6 R3: an unreadable record must not drop its fleet.
		log.Printf("console: api instances list %s/%s: %d record(s) unreadable %v; every fleet counts toward the rollout join",
			acct.Sqid, app, len(skipped), skipped)
		relevant = nil
	}
	join, joinComplete := s.loadRolloutJoin(ctx, acct.Sqid, time.Now(), relevant)
	served := loadEdgesJoin(ctx, s.cfg.Releases)
	// The app's update policy, read once: an absent manifest is no policy,
	// and a read error is logged and treated the same. The list never fails
	// for it; SettingsDefault is then computed from the record alone.
	var policy *provision.UpdatePolicy
	if m, err := provision.GetManifest(ctx, s.cfg.Releases, acct.Sqid, app); err == nil {
		policy = m.Updates
	} else if !errors.Is(err, os.ErrNotExist) {
		log.Printf("console: api instances list %s/%s: update policy: %v; settings_default computed from the records alone", acct.Sqid, app, err)
	}
	params := r.URL.Query()
	q := parseInstanceQuery(params)
	// The default stays the whole cap, so a client that sends no limit gets
	// the answer it always got. A limit outside (0, instanceListMax) is
	// ignored rather than refused — a bad page size is not worth an error
	// where the honest full page is right there.
	limit := instanceListMax
	if raw := params.Get("limit"); raw != "" {
		if n, err := strconv.Atoi(raw); err == nil && n > 0 && n < instanceListMax {
			limit = n
		}
	}
	health := s.instanceHealth(ctx, recs)
	counts := map[string]int{}
	matched := make([]instanceListRecord, 0, len(recs))
	for _, rec := range recs {
		h := health[rec.Host]
		counts[h]++
		if q.Q != "" && !strings.Contains(rec.Host, q.Q) {
			continue
		}
		if q.Channel != "" && rec.Channel != q.Channel {
			continue
		}
		if q.Health != "" && h != q.Health {
			continue
		}
		matched = append(matched, instanceListRecord{Record: rec,
			StagedVersion: join.versions[rec.Host], Health: h, Upstreams: join.upstreams[rec.Host],
			ServedBy: served[rec.Host], Gated: rec.Gate != "", DBBytes: join.dbSize(rec.Host),
			Rollout:         join.rollout(rec.Host, acct.Sqid, app),
			UpdateReport:    join.update(rec.Host, acct.Sqid, app),
			SettingsDefault: provision.EffectiveUpdates(rec, policy).Default()})
	}
	total := len(matched)
	// provision.ListRecords returns records host-sorted and nothing above
	// re-orders them, which is the whole basis of the cursor: "resume after
	// this host" only means one page in a stable order.
	start := 0
	if after, ok := decodeInstanceCursor(q.Cursor); ok {
		for i, rec := range matched {
			if rec.Host > after {
				start = i
				break
			}
			start = i + 1
		}
	}
	next := ""
	end := start + limit
	if end < total {
		next = encodeInstanceCursor(matched[end-1].Host)
	} else {
		end = total
	}
	answer := map[string]any{
		"instances": matched[start:end], "truncated": truncated,
		"total": total, "counts": counts, "next_cursor": next,
	}
	// Additive and only when true, so a complete join's answer is the bytes
	// it always was: the box join behind the rollout views could not read
	// every box's report, so a record with no rollout may yet have one.
	if !joinComplete {
		answer["rollout_incomplete"] = true
	}
	if s.cfg.HostClaim {
		pending, err := s.claimPendingViews(ctx, acct.Sqid, app, "instance")
		if err != nil {
			writeClaimResponseError(w, err)
			return
		}
		answer["operations"] = pending
	}
	writeJSON(w, http.StatusOK, answer)
}

// handleAPIInstanceGet answers one record. A host with no record is the
// byte-identical 404 — a record's existence is not a thing to probe for
// either, and this way "no such instance" and "no such app" read alike.
func (s *Server) handleAPIInstanceGet(w http.ResponseWriter, r *http.Request) {
	_, acct, app, ok := s.instanceGate(w, r)
	if !ok {
		return
	}
	host := r.PathValue("host")
	// Shape-checked before the key builder, not after. A {host} segment
	// arrives percent-decoded, so "..%2f..%2fchannels" reaches this handler
	// as a path with separators in it; RecordKey would happily join it. A
	// host that cannot name a record is simply not found — the same answer
	// a host that names no record gets.
	if !provision.ValidHostShape(host) {
		http.NotFound(w, r)
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	rec, err := provision.GetRecord(ctx, s.cfg.Releases, acct.Sqid, app, host)
	if errors.Is(err, os.ErrNotExist) {
		http.NotFound(w, r)
		return
	}
	if err != nil {
		log.Printf("console: api instances get %s/%s/%s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not read the instance")
		return
	}
	writeJSON(w, http.StatusOK, instanceGetRecord{Record: *rec,
		ServedBy: loadEdgesJoin(ctx, s.cfg.Releases)[host], Gated: rec.Gate != ""})
}

// instanceGetRecord is the single-record answer: the stored record plus the
// same observed-placement join the list carries (issue #337). Only that —
// the get has never carried staged_version/health, and growing it to the
// list's full row is a separate decision from telling a consumer where one
// instance lives.
type instanceGetRecord struct {
	provision.Record
	ServedBy []servedBy `json:"served_by,omitempty"`
	// HiddenGate shadows Record.Gate for encoding/json (a shallower field of
	// the same name wins), so the bcrypt hash never leaves the console; it
	// is always "" and omitted. Gated is what a member may know.
	HiddenGate string `json:"gate,omitempty"`
	Gated      bool   `json:"gated"`
}

// apiRecordView is a record as the write doors answer it: the whole record
// with the gate hash shadowed and a gated flag in its place. Every handler
// that used to writeJSON a bare record answers through this, so there is one
// place — not five — where "the hash never leaves" has to hold.
type apiRecordView struct {
	provision.Record
	HiddenGate string `json:"gate,omitempty"`
	Gated      bool   `json:"gated"`
	// PrivateStoreBucket is the bucket the create door provisioned for this
	// instance under the app's private-storage policy (issue #412), empty on
	// every other record and every other door. Not part of the record: it is
	// a fact about what this one request did, and the record's own
	// Environment is what names the store afterwards.
	PrivateStoreBucket string `json:"private_store_bucket,omitempty"`
	// RegionFrom and RegionName say how this create chose its region and
	// what the place is called (spec §7): facts about this request, not
	// part of the record.
	RegionFrom string `json:"region_from,omitempty"`
	RegionName string `json:"region_name,omitempty"`
}

func recordView(rec provision.Record) apiRecordView {
	return apiRecordView{Record: rec, Gated: rec.Gate != ""}
}

// replicaFields is the #162 slice of the instance-create body. Role and
// placement travel together or not at all — "a replica without a placement"
// and "a placement without a replica role" are both half a decision, and
// each half alone produces a record some other box will act on while the
// writer thinks they asked for nothing. Replicas (the home's own placement
// set) rides the same body so one call can provision the replica AND publish
// where the account's replicas live.
type replicaFields struct {
	Role     string   `json:"role,omitempty"`
	Replicas []string `json:"replicas,omitempty"`
}

// checkReplicaCreate is the create door's replica rails (#162). Returns nil
// when the request carries no replica fields at all — the overwhelmingly
// common shape, byte-identical to every create before this door existed —
// and a refusal when it carries half of one. The home's own placement set is
// canonicalized (sorted, deduped, ValidRegion-checked) in place, so the wire
// column never carries a non-canonical order and the reconciler's converge
// has nothing to re-canonicalize on the next pass.
func checkReplicaCreate(req replicaFields, rec *provision.Record) *doorRefusal {
	if req.Role == "" && len(req.Replicas) == 0 {
		return nil
	}
	// A replica's placement IS its region — one placement, the create's own
	// --region — so an empty one is half a replica: a mirror with nowhere to
	// live. (The armed-placement gate below refuses one that names no real
	// box; this refuses one that names nothing at all.)
	if req.Role != "" && rec.Region == "" {
		return &doorRefusal{http.StatusBadRequest,
			"role replica needs a placement — pass the placement code the replica lives in as the create's region"}
	}
	// A replica does not carry a replica set of its own: the set is the
	// HOME's opt-in naming where its replicas live, and a replica of a
	// replica is not a shape the platform carries.
	if req.Role != "" && len(req.Replicas) > 0 {
		return &doorRefusal{http.StatusBadRequest,
			"role replica with replicas: the placement set is the HOME record's opt-in — a replica does not carry one"}
	}
	// The home's own placement set is canonicalized (sorted, deduped,
	// ValidRegion-checked) in place, so the wire column never carries a
	// non-canonical order and the reconciler's converge has nothing to
	// re-canonicalize on the next pass.
	if len(req.Replicas) > 0 {
		norm, err := provision.ValidReplicas(req.Replicas)
		if err != nil {
			return &doorRefusal{http.StatusBadRequest, err.Error()}
		}
		rec.Replicas = norm
	}
	return nil
}

// handleAPIInstanceCreate is the point of the feature: one create-only
// write to the bucket, in spec §7's refusal order — gate, budget, manifest,
// host, region, channel, write. Every field the record carries that policy
// governs (pool, and the channel default) is stamped from the MANIFEST, not
// from the request: the body below has no pool field to lie in at all.
func (s *Server) handleAPIInstanceCreate(w http.ResponseWriter, r *http.Request) {
	principal, acct, app, ok := s.instanceGate(w, r)
	if !ok {
		return
	}
	// A PERSON must be able to write the control plane's own instance
	// record — that is the act that makes `carlos deploy -app console`
	// resolve a host at all, and refusing it here would close the door this
	// family exists to open. A SERVICE credential must not: the record it
	// would write is the thing the reconciler then owns, and ownership of
	// the console's route is not a CI token's to acquire (controlplane.go).
	//
	// Straight after instanceGate, which is to say after the family's
	// byte-identical 404 and before the manifest read: a non-member must
	// never learn from this door that an app here carries the flag.
	// principalFrom's ok is discarded for the reason handleAPIPromote's
	// comment gives — cliRoute stashed the principal before the handler
	// started, so it is already present.
	p, _ := principalFrom(r.Context())
	if s.refuseServiceControlPlane(w, p, acct.ID, app, "create its instance records") {
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	m, ok := s.instanceManifest(ctx, w, acct, app)
	if !ok {
		return
	}
	var req struct {
		Host    string `json:"host"`
		Region  string `json:"region"`
		Channel string `json:"channel"`
		Message string `json:"message"`
		// The route SHAPE fields (route-records design §3, HA design §II).
		// All optional, all defaulting to the exact route this door minted
		// before they existed, and all gated by provision.ValidateShape
		// below — the same door the reconcile pass re-checks them at, because
		// neither side trusts the other about what is in the bucket.
		//
		// What is deliberately NOT here: pool (manifest policy), hibernate
		// and unit (operator columns with their own verbs), and anything
		// that could widen which HOST this app may claim — the suffix check
		// below is unchanged, so a "kind":"static" body cannot reach for a
		// hostname outside the app's own domain.
		//
		// Environment WAS on that list until 2026-09-04, and the omission
		// had a cost worth recording. Config in CARLOS is per-app, so a
		// second instance standing alongside a live one inherits the
		// default bundle — including whatever single origin the app's
		// framework compares the request's Origin header against. That
		// makes every POST to the new host fail closed: sign-in, magic
		// links, WebAuthn RP ID, the cookie Secure flag, all keyed off a
		// scalar that names the OTHER host. `carlos canary` mints exactly
		// such a route, so without this field the verb hands you a live
		// hostname that cannot accept a form submission for any app that
		// carries config, which is most of them.
		//
		// It is not an operator column in the way pool and unit are. Those
		// govern host resources the member has no standing over; a config
		// bundle is the app's own, written by the app's own `carlos env
		// --environment`, and binding one of an app's routes to one of its
		// own bundles is squarely inside what a member already controls.
		// ValidateShape (provision.go) checks the name, and the same
		// control-plane guard the PATCH door applies is applied above.
		Kind        string            `json:"kind"`
		Environment string            `json:"environment"`
		Addrs       []string          `json:"addrs"`
		Health      *provision.Health `json:"probe"`
		// The replica fields (#162), embedded so their wire keys sit beside
		// kind/environment's — one flat body, no nesting for the caller to
		// discover.
		replicaFields
		// The seed doors (seeded-instances spec §4, §5.1): a create that
		// starts from a sibling's replica or an uploaded snapshot. Both run
		// every check below, then leave this handler (apiinstanceseed.go,
		// apiinstanceimport.go).
		From   *seedFromReq   `json:"from,omitempty"`
		Import *seedImportReq `json:"import,omitempty"`
	}
	if !readJSON(w, r, &req) {
		return
	}
	message, ok := checkedActivityMessage(w, req.Message)
	if !ok {
		return
	}
	seeded := req.From != nil || req.Import != nil
	if seeded {
		if ref := seedOneDoorRefusal(req.From != nil, req.Import != nil); ref != nil {
			jsonError(w, ref.Status, ref.Msg)
			return
		}
		if ref := seedCommonRefusal(strings.TrimSpace(req.Kind), req.Addrs, strings.TrimSpace(req.Role), req.Replicas); ref != nil {
			jsonError(w, ref.Status, ref.Msg)
			return
		}
	}
	host := strings.TrimSpace(req.Host)
	// Path-traversal defence stated as such (spec §11): this host becomes a
	// bucket key segment here and, on the box, the <host>.sock and
	// <host>.db path segments. Nothing below runs until it is one label
	// plus the app's own domain.
	if !provision.ValidHost(host, m.Domain) {
		jsonError(w, http.StatusBadRequest,
			"invalid host — an instance host is one DNS label followed by ."+m.Domain)
		return
	}
	// A temporary app serves one static site at its own platform address
	// (spec §4, ruling 5): anything else is estate an automatic purge would
	// have to tear down, or a host outside what its expiry drops.
	if apex := s.apexHost(acct.Sqid, app); strings.TrimSpace(req.Kind) != "static" || apex == "" || host != apex {
		if s.refuseTemporary(w, acct, app, "serve anything but a static site at "+app+"'s own platform address") {
			return
		}
	}
	// The account's platform subdomain is a SHARED namespace: every app's
	// apex lives at <app>.<sqid>.<AppsDomain>, and a manifest pinned there
	// (the member-facing enable door) makes every sibling's apex a valid
	// host shape for THIS app. A record at a sibling's apex would mint a
	// real route there first, and the domains pass would then skip the
	// sibling's own apex mint forever (byHost) — one app quietly serving
	// another's public URL (review 2026-08-06 #1). Within-account only, but
	// reachable by an app token, so it is refused rather than trusted to
	// membership: a label naming another claimed app in the account belongs
	// to that app. Custom-domain manifests never enter apex space (ValidHost
	// pinned the suffix above), so this check cannot touch them.
	//
	// "Claimed" includes an app in the TRASH. A trashed app's name is
	// reserved until purge — CreateAppIn and RenameAppIn both refuse it — and
	// so is its apex: were the check live apps only, a sibling could take the
	// apex while the app sat in the trash and keep it across a restore, with
	// the domains pass deferring to the sibling's route for ever. That is
	// also where `carlos email events push` sends the restored app's
	// recipients' addresses (discussion 153). Only a purge frees the apex.
	// The name arriving after the instance — a create, rename or move — is
	// the other way in, and apex.go closes it.
	//
	// The same question answers a second one further down (the steering
	// default), so it is asked once, here, and named: is this manifest
	// pinned to the account's platform subdomain, or to a domain of the
	// app's own?
	platformNamespace := s.cfg.AppsDomain != "" && m.Domain == acct.Sqid+"."+s.cfg.AppsDomain
	// siblingLabel is set when this host sits at a label that is not the
	// app's own — the case re-checked after the record is written, below.
	siblingLabel := ""
	if platformNamespace {
		if label := strings.TrimSuffix(host, "."+m.Domain); label != app {
			siblingLabel = label
			live, trashed, err := s.store.AppNameState(acct.ID, label)
			if err != nil {
				log.Printf("console: api instances create sibling check %s/%s: %v", acct.Sqid, label, err)
				jsonError(w, http.StatusInternalServerError, "could not check the host — try again")
				return
			}
			switch {
			case live:
				jsonError(w, http.StatusConflict,
					host+" is app "+label+"'s platform apex — create it as an instance of "+label+" instead")
				return
			case trashed:
				jsonError(w, http.StatusConflict,
					host+" is app "+label+"'s platform apex, and "+label+" is in the trash — its apex stays reserved until it is purged")
				return
			}
		}
	}
	// The sibling check above names apps; this one names HOSTS. Records are
	// keyed per app, so another app of this account may already hold the very
	// host this one is asking for without being called by its label: canary
	// "a" of app "b-c" and canary "a-b" of app "c" are both a-b-c (the flat
	// canary host, discussion 207). The provisioning pass would keep one
	// record and skip the other, so the loser would look created and serve
	// nothing. Refused here, for every host, on the same fail-closed terms as
	// the apex checks; a host this app already holds falls through to the
	// create's own "already exists".
	//
	// KNOWN LIMIT, filed as amadan discussion 232: this is a check, then a
	// write, and CreateRecord's conditional write protects only this app's
	// own account/app/host key. Two creates for one host from two different
	// apps, racing, can both pass and both be written; the provisioning pass
	// then keeps one and skips the other ("duplicate host"). Closing that
	// needs host-scoped atomic ownership, which is a gap in the instance door
	// that predates the flat canary host and is not built here. The
	// sequential case, the common one, is closed.
	switch hold, err := s.hostHolder(ctx, acct, host, app); {
	case err != nil:
		log.Printf("console: api instances create %s/%s: host holder check %s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusInternalServerError, "could not check the host — try again")
		return
	case hold != nil:
		jsonError(w, http.StatusConflict, hostHeldSentence(host, hold))
		return
	}
	// An attached alias has no record and may have no route yet, so the
	// holder check cannot see it; its authoritative claim is one read.
	switch hold, err := s.hostClaimHolder(ctx, acct, host, app); {
	case err != nil:
		log.Printf("console: api instances create %s/%s: host claim check %s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusInternalServerError, "could not check the host — try again")
		return
	case hold != nil:
		jsonError(w, http.StatusConflict, claimHeldSentence(host, hold))
		return
	}
	// A fleet-placed app (customer-fleets plan, `carlos apps place`) governs
	// every one of its instances' Region uniformly — spec's "one flag on the
	// app, all its instances follow" (appPlacement, fleets.go) — so when a
	// placement exists it OVERRIDES whatever the request body sent, and the
	// ordinary region/allow-list validation below never runs at all: a
	// "fleet/<name>" value would fail provision.ValidRegion's shape anyway
	// (no "/"), which is exactly why this has to be a check made BEFORE
	// that validation, not alongside it.
	reg, err := openRegistry(s.cfg.Registry)
	if err != nil {
		log.Printf("console: api instances create %s/%s: open registry: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not check this app's placement")
		return
	}
	placed, err := s.appPlacement(reg, acct, app)
	if err != nil {
		log.Printf("console: api instances create %s/%s: check placement: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not check this app's placement")
		return
	}
	// The app's region is the default for a create that names none
	// (nearest-region spec §7, R2). It runs BEFORE every check an explicit
	// region meets, and never for a fleet-placed app, a pooled manifest, a
	// replica, or anything but a socket-backed instance.
	raw := strings.TrimSpace(req.Region)
	regionFrom := ""
	if raw != "" {
		regionFrom = "request"
	}
	if raw == "" && placed == "" && m.Pool == "" && strings.TrimSpace(req.Role) == "" &&
		(provision.Record{Kind: strings.TrimSpace(req.Kind), Addrs: req.Addrs}).DerivesPaths() {
		appRegion, _, err := s.appRegion(acct.ID, app)
		if err != nil {
			log.Printf("console: api instances create %s/%s: read app region: %v", acct.Sqid, app, err)
			jsonError(w, http.StatusBadGateway, msgAppRegionUnreadable)
			return
		}
		if appRegion != "" {
			raw, regionFrom = appRegion, "app"
		}
	}
	if placed != "" {
		regionFrom = "fleet"
	}
	// The home region's NAME normalizes to the record's "" before any
	// validation (issue #346): pickers speak the code, records keep the
	// unconstrained value reconcile has always scoped by.
	region := s.homeRegionIn(raw)
	// An APP-DERIVED region needs positive eligibility — the secrets key
	// included (R9) — and never rides the dormant gate (codex R2-2).
	if regionFrom == "app" {
		snap, err := s.liveEdges(ctx)
		if err != nil {
			log.Printf("console: api instances create %s/%s: read edges: %v", acct.Sqid, app, err)
			jsonError(w, http.StatusServiceUnavailable, msgAppRegionUnconfirmed(s.homeRegionOut(region)))
			return
		}
		// Incomplete evidence for a non-home region is "could not confirm"
		// (C28, the same answer as a failed listing), not C16: the region
		// may well be fine, and a box that could not be read is the one
		// that may not be (re-review r1). The home needs no evidence.
		if region != "" && !snap.EvidenceComplete() {
			log.Printf("console: api instances create %s/%s: incomplete edges or snapshot read, region %s unconfirmed", acct.Sqid, app, region)
			jsonError(w, http.StatusServiceUnavailable, msgAppRegionUnconfirmed(s.homeRegionOut(region)))
			return
		}
		cands := s.regionCands(snap)
		reason := "absent"
		if c, ok := findCandidate(cands, region); ok {
			reason = c.unavailableReason()
		}
		// Region HA (spec 2 §7, H27): the region is judged by the eligible
		// set the create door's chooser will choose from, never by every
		// sibling's own answer, and an empty set is the door's no-room
		// refusal, alert included.
		if x := s.placementChooser(""); x != nil {
			switch boxes, err := x.PlaceableBoxes(ctx, s.cfg.claimPlacementRegion(region)); {
			case errors.Is(err, hostops.ErrContract):
				reason = "absent"
			case err != nil:
				log.Printf("console: api instances create %s/%s: region %s placeable boxes: %v", acct.Sqid, app, region, err)
				jsonError(w, http.StatusServiceUnavailable, msgAppRegionUnconfirmed(s.homeRegionOut(region)))
				return
			case len(boxes) == 0:
				writeClaimResponseError(w, s.noRoom(ctx, region))
				return
			default:
				reason = ""
			}
		}
		// Each list names only what an explicit request for this same
		// instance would pass (codex plan-R4 2): instanceChoices.
		if reason != "" {
			jsonError(w, http.StatusBadRequest, msgAppRegionUnavailable(s.homeRegionOut(region), reason, s.instanceChoices(ctx, m.Regions, cands, region)))
			return
		}
		if !instanceRegionAllowed(m.Regions, region) {
			jsonError(w, http.StatusBadRequest, msgAppRegionNotAllowed(s.homeRegionOut(region), s.instanceChoices(ctx, m.Regions, cands, region)))
			return
		}
		for _, rep := range req.Replicas {
			if s.homeRegionIn(strings.TrimSpace(rep)) == region {
				jsonError(w, http.StatusBadRequest, msgReplicaOverlap(s.homeRegionOut(region)))
				return
			}
		}
	}
	// The replica rails (#162) run BEFORE the region allow-list, because
	// half a decision is a different refusal from "wrong region": a role
	// with no placement, or a set on a replica, is a shape error the
	// caller can fix from the message alone, and the record must not
	// carry either into the shape validation below. The rails also
	// canonicalize the placement set, so the record ValidateShape sees —
	// and the bucket receives — is the canonical form.
	probeRec := provision.Record{Kind: strings.TrimSpace(req.Kind), Region: region, Role: strings.TrimSpace(req.Role)}
	if ref := checkReplicaCreate(req.replicaFields, &probeRec); ref != nil {
		jsonError(w, ref.Status, ref.Msg)
		return
	}
	if placed != "" {
		// A fleet-placed app governs every instance's Region uniformly, and
		// the armed/hosting gate below is skipped for it — the fleet is the
		// placement, validated by its own rail. A replica under that regime
		// would land wherever the fleet says, unchecked by anything that
		// knows what a replica placement means (#162): refused, not guessed.
		// Delete the app's placement first, or place the replica's account
		// on a fleet that spans the placement you want.
		if probeRec.Role == "replica" {
			jsonError(w, http.StatusBadRequest,
				"role replica on a fleet-placed app: the app's fleet placement ("+placed+") governs every instance's region, and a replica's placement must be an armed, hosting platform region — remove the app's placement first")
			return
		}
		region = placed
	} else if !provision.ValidRegion(region) || !instanceRegionAllowed(m.Regions, region) {
		msg := "invalid region"
		if len(m.Regions) > 0 {
			msg = "region " + region + " is not one this app runs in — allowed: " + strings.Join(m.Regions, ", ")
		}
		jsonError(w, http.StatusBadRequest, msg)
		return
	}
	// The armed-placement gate (issue #329): a non-empty region that names
	// no armed box is an instance NOTHING will ever mint — the record would
	// sit dark forever, which is worse than a refusal that lists the real
	// choices. Placed apps skipped (their value is a fleet, validated by its
	// own rail above); the unconstrained "" region skipped (it means "the
	// deployment's home", which always exists); and the whole gate is
	// dormant until some box publishes a placement code, so a console rolled
	// ahead of its fleet changes nothing.
	//
	// The gate has TWO bars, and which one applies depends on what is being
	// created. Every kind needs the region to be REACHABLE — a box nothing
	// can dial homes nothing. Only a socket-backed instance additionally
	// needs the region to HOST, because only that kind is spawned by an
	// activator: a static route is served from bucket bytes by every armed
	// edge with no process at all, and an addr-backed service proxies to a
	// process the platform never starts. Gating those two on hosting would
	// refuse a perfectly serveable static site in a region for want of a
	// hibernation bucket it would never have used. The predicate is
	// provision.Record's own (DerivesPaths), asked of a probe record rather
	// than restated here, so it cannot drift from what reconcile will mint.
	if placed == "" && region != "" {
		// Region HA (spec 2 §7, H27): a region with no box that has room is
		// the no-room refusal, before this gate answers it as a 400.
		if err := s.roomIn(ctx, region, m.Pool); err != nil {
			writeClaimResponseError(w, err)
			return
		}
		probe := provision.Record{Kind: strings.TrimSpace(req.Kind), Addrs: req.Addrs, Role: probeRec.Role}
		caps, published := placements(ctx, s.cfg.Releases)
		// The replica placement rides the same gate as the record's own
		// region (#162): a replica named into a placement no box announces
		// is a mirror nothing will ever provision — an order ledger in a
		// region that does not exist. Dormant with the rest of the gate
		// until a box publishes a placement code.
		if published && probe.Role == "replica" {
			switch {
			case !caps[region].Reachable:
				jsonError(w, http.StatusBadRequest,
					"replica placement "+region+" is not armed in this deployment — armed: "+armedCodes(reachableSet(caps)))
				return
			case !caps[region].Hosting:
				jsonError(w, http.StatusBadRequest,
					"replica placement "+region+" is reachable but cannot host an instance — no box there has its hibernation activator configured. Regions that can: "+armedCodes(hostingSet(caps)))
				return
			}
		}
		switch {
		case !published:
			// Dormant: the fleet predates the placement field.
		case !caps[region].Reachable:
			jsonError(w, http.StatusBadRequest,
				"region "+region+" is not armed in this deployment — armed: "+armedCodes(reachableSet(caps)))
			return
		case probe.DerivesPaths() && !caps[region].Hosting:
			jsonError(w, http.StatusBadRequest,
				"region "+region+" is reachable but cannot host an instance — no box there has its hibernation activator configured. Regions that can: "+armedCodes(hostingSet(caps)))
			return
		}
		// R9: a socket-backed instance or a replica needs its config,
		// secrets and store binding rendered on the box, which only a box
		// holding the deployment's secrets key can do. Refused only when a
		// CURRENT writer proves the region keyless; unknown keeps today's
		// behaviour, so roll order never refuses a working region.
		if probe.DerivesPaths() || probe.Role == "replica" {
			if snap, err := s.liveEdges(ctx); err == nil {
				if c, ok := findCandidate(s.regionCands(snap), region); ok && c.NoKeyProven {
					jsonError(w, http.StatusBadRequest, msgNoSecretsKey(s.homeRegionOut(region)))
					return
				}
			}
		}
	}
	channel := strings.TrimSpace(req.Channel)
	if channel == "" {
		resolved, ref := s.instanceChannel(ctx, acct.Sqid, app, m)
		if ref != nil {
			jsonError(w, ref.Status, ref.Msg)
			return
		}
		channel = resolved
	}
	if !release.ValidChannel(channel) {
		jsonError(w, http.StatusBadRequest, "invalid channel name")
		return
	}
	if ref := s.staticHeadRefusal(ctx, acct.Sqid, app, channel, strings.TrimSpace(req.Kind), host); ref != nil {
		jsonError(w, ref.Status, ref.Msg)
		return
	}
	rec := provision.Record{
		Schema:  1,
		Host:    host,
		Slug:    strings.TrimSuffix(host, "."+m.Domain),
		App:     app,
		Account: acct.Sqid,
		Pool:    m.Pool,
		Region:  region,
		Channel: channel,
		// UTC, like every other timestamp written to the bucket: these
		// records are read on boxes in other regions.
		CreatedAt:   time.Now().UTC(),
		CreatedBy:   principal,
		Kind:        strings.TrimSpace(req.Kind),
		Environment: strings.TrimSpace(req.Environment),
		Addrs:       req.Addrs,
		Health:      req.Health,
	}
	// The replica rails already ran above (before the region allow-list),
	// on a probe record; the canonicalized answers carry onto the real one
	// here. The role lands only as "replica" — checkReplicaCreate refused
	// everything else before this point.
	rec.Role = probeRec.Role
	rec.Replicas = probeRec.Replicas
	// A static platform host is HA by default. Static is the one serving
	// class every platform box materializes unconditionally
	// (provision.everywhereClass): no unit, no process, content read from
	// the bucket channel pointer, so a far edge serves it with no home box
	// and no backhaul. The content half of that is already true — every
	// armed edge holds the site and its account wildcard cert. What was
	// missing is DNS: with no opt-in the host resolves to one edge, so
	// several healthy boxes hold the site and every visitor is sent to one
	// of them.
	//
	// Scoped to the platform namespace deliberately. internal/steering's
	// steeredHosts only ever builds latency records for hosts under the
	// apps domain, so defaulting a custom domain's record to "latency"
	// would write an opt-in no pass will ever honour (#306's shape); a
	// custom domain reaches the edges by its owner's own DNS, and the
	// console's attach guidance already tells them to CNAME the steering
	// hostname.
	//
	// Scoped to static deliberately too: a home-boxed route reaches a far
	// edge by backhaul, a different trade with a different cost, not one to
	// make silently for every app on the deployment.
	//
	// And it honours v1's pool rail, the same one the PATCH door enforces
	// with a 409 (steering needs the shared pool, because a pool's own
	// edges are not the deployment's). A default that quietly wrote what
	// the update door refuses would be the worse kind of inconsistency: the
	// record would carry an opt-in nobody could have asked for through the
	// front door, and the converger would skip it anyway.
	//
	// This is a value at MINT, never a converge: `carlos steering --app x
	// --host y off` is the escape hatch, and nothing re-stamps a record
	// that already exists. The opt-in is inert on a deployment that has not
	// set CARLOS_STEERING_ZONE_ID, so a single-box deployment states the
	// intent harmlessly and becomes HA the day it arms a second edge.
	if rec.Kind == "static" && platformNamespace && rec.Pool == "" {
		rec.Steering = "latency"
	}
	// The app's private-storage policy (issue #412, spec §6): every instance
	// gets a config environment of its own, named for the host's first
	// label, with an object store bound to it.
	//
	// An EXPLICIT environment in the request wins, and the policy still
	// applies to it. The policy fills a blank; it does not seize the axis.
	// What it promises is that this record's bundle carries the store
	// coordinates — not that the bundle has any particular name — so
	// honouring the caller's own name keeps `carlos canary` working on such
	// an app, and two instances naming one environment share its store
	// exactly as they already share its config (#408 §5: sharing is
	// visible, not refused).
	//
	// Stamped BEFORE ValidateShape so the shape rail sees the same
	// environment the box will, and before the ceiling and the walk below so
	// neither can be asked about a record that was never legal.
	//
	// A seeded instance takes no explicit environment under the policy: its
	// store must be new and empty, and a named one may be shared (spec §4).
	if seeded && m.PrivateStorage && strings.TrimSpace(req.Environment) != "" {
		s.refuseSeededEnvironment(w)
		return
	}
	if m.PrivateStorage {
		env, derived := rec.Environment, false
		if env == "" {
			env, derived = rec.Slug, true
		}
		if ref := s.instanceStoreNames(acct, app, env, derived); ref != nil {
			jsonError(w, ref.Status, ref.Msg)
			return
		}
		rec.Environment = env
	}
	// The shape rails, at the door — kind vocabulary, one upstream shape per
	// record, addr syntax, and the combinations that would wedge a host (a
	// static route with an upstream, a hibernating addr-backed one). The
	// message is ValidateShape's own: it names WHICH upstream is wrong, which
	// is the only thing the caller can act on, and it is the identical
	// sentence the box's reconcile pass would print if a record carrying this
	// shape ever reached it from another writer.
	if err := provision.ValidateShape(rec); err != nil {
		jsonError(w, http.StatusBadRequest, err.Error())
		return
	}
	if s.refuseMemberUpstreams(w, p, rec.Addrs, nil) {
		return
	}
	// THE STORE IS PROVISIONED BEFORE THE RECORD IS WRITTEN, and a failure
	// here means no record at all (issue #412, spec §7). This ordering is
	// the load-bearing decision of the feature, so it is argued here rather
	// than assumed:
	//
	// Record first, and a failed walk leaves an instance whose bundle has no
	// store coordinates. It wakes, finds none, and runs on local disk — the
	// exact outcome the policy was declared to prevent, arrived at silently,
	// with no verb to repair it (there is no `instances create --resume`).
	//
	// Store first, and a failed record write leaves a store for an
	// environment no instance is bound to. That is visible — `store status`
	// lists every store of the app — and, because the environment is DERIVED
	// FROM THE HOST, a retry of the same host reuses it exactly: GrantIn is
	// idempotent, so the second attempt short-circuits and costs nothing.
	//
	// So: no instance record is ever created under this policy without its
	// store already provisioned and delivered.
	privateBucket := ""
	if m.PrivateStorage {
		if ref := s.storeCeiling(ctx, acct, app, rec.Environment); ref != nil {
			jsonError(w, ref.Status, ref.Msg)
			return
		}
	}
	// The leftover-replica rail (#199, createleftovers.go): a host still
	// holding a deleted instance's replica or move staging is refused, so
	// the new record cannot inherit that database. Last of the checks, after
	// every validation above, and BEFORE the store walk below, so a refused
	// create never provisions a bucket either.
	if ref := s.leftoverReplicaRefusal(r.Context(), leftoverCreate{
		logTag: "api instances create " + acct.Sqid + "/" + app,
		host:   host, region: region, pool: rec.Pool,
		exists: func(ctx context.Context) (bool, error) {
			_, err := provision.GetRecord(ctx, s.cfg.Releases, acct.Sqid, app, host)
			if errors.Is(err, os.ErrNotExist) {
				return false, nil
			}
			return err == nil, err
		},
		// The same two answers the CreateRecord call below gives.
		duplicate:  doorRefusal{http.StatusConflict, "instance " + host + " already exists"},
		readFailed: doorRefusal{http.StatusBadGateway, "could not create the instance — try again"},
		taken:      host + " still holds data from a deleted instance. Choose another address, or ask an operator to purge it.",
		unsure:     "could not check whether " + host + " is free. Try again.",
	}); ref != nil {
		jsonError(w, ref.Status, ref.Msg)
		return
	}
	// Plans 3a: an instance is a running thing. Checked once here, so plain,
	// seeded and imported creates all meet the cap, under the account lock.
	defer s.planLock(acct)()
	if err := s.checkRunningThings(r.Context(), acct, 1); err != nil {
		if isPlanCap(err) {
			writeJSON(w, http.StatusConflict, map[string]any{"error": err.Error(), "code": "cap"})
			return
		}
		log.Printf("console: api instances create %s/%s: plan cap: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not create the instance — try again")
		return
	}
	// Every ordinary check has passed: a seed door takes over from here, and
	// writes its own record (apiinstanceseed.go).
	if req.From != nil {
		s.createFrom(w, r, seedCreate{acct: acct, app: app, principal: principal, message: message, m: m,
			rec: rec, placed: placed, regionFrom: regionFrom, siblingLabel: siblingLabel}, *req.From)
		return
	}
	if req.Import != nil {
		s.createImport(w, r, seedCreate{acct: acct, app: app, principal: principal, message: message, m: m,
			rec: rec, placed: placed, regionFrom: regionFrom, siblingLabel: siblingLabel}, *req.Import)
		return
	}
	// A fresh budget for the write and its rollback: validation and the
	// rail's listings may have spent most of the original one.
	cancel()
	ctx, cancel = context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	buildClaim := func(now time.Time, acquisition string) (hostops.Record, error) {
		rec.CreatedAt = time.Time{}
		rec.Acquisition = acquisition
		region := s.cfg.claimPlacementRegion(rec.Region)
		prepared, err := hostops.PrepareInstance(rec, now, region)
		if err == nil {
			rec.CreatedAt = now
		}
		return prepared, err
	}
	// Region HA (spec 2 §7, H27): the box is chosen before the door's first
	// write, the environment binding below, so a create refused for want of
	// room changes nothing. beginClaimCreate keeps this choice.
	createContext := r.Context()
	if s.cfg.HostClaim {
		var chooseErr error
		if createContext, chooseErr = s.chooseCreateFirst(createContext, host, buildClaim); chooseErr != nil {
			writeClaimResponseError(w, chooseErr)
			return
		}
	}
	// An environment named without a store walk of its own takes the store
	// from a seed that made it (final review F3, seedenvbind.go).
	if !m.PrivateStorage && !s.bindEnvironmentCreate(ctx, w, rec) {
		return
	}
	var claimRequest *claimCreateRequest
	if s.cfg.HostClaim {
		var createErr error
		claimRequest, createErr = s.beginClaimCreate(createContext, acct, app, host, principal, buildClaim)
		if createErr != nil {
			writeClaimResponseError(w, createErr)
			return
		}
		defer claimRequest.Close()
		createContext = claimRequest.Context
	}
	if m.PrivateStorage {
		// r.Context(), not ctx: the walk takes storeGrantTimeout, which is
		// longer than this handler's own deadline.
		var storeResponse http.ResponseWriter = w
		if claimRequest != nil {
			storeResponse = &claimPrivateResponse{header: make(http.Header)}
		}
		storeRec, ok := s.instanceStoreProvision(createContext, storeResponse, acct, app, rec.Environment, principal)
		if !ok {
			if claimRequest != nil {
				writeJSON(w, http.StatusAccepted, map[string]string{"host": host, "operation_id": claimRequest.Observed.Claim.Op.ID, "phase": claimRequest.Observed.Claim.Op.Kind})
			}
			return
		}
		privateBucket = storeBucketName(storeRec)
		// And a fresh deadline for what is left. The walk can have consumed
		// every second of the handler's original budget, and the record
		// write below inheriting a spent context would fail immediately
		// after the bucket had already been paid for — the one shape of
		// failure this whole ordering exists to avoid.
		cancel()
		var recancel context.CancelFunc
		ctx, recancel = context.WithTimeout(r.Context(), instanceStoreTimeout)
		defer recancel()
	}
	var recordWriteErr error
	if claimRequest != nil {
		if !s.finishClaimCreate(w, claimRequest) {
			return
		}
	} else {
		recordWriteErr = provision.CreateRecord(ctx, s.cfg.Releases, rec)
	}
	if err := recordWriteErr; err != nil {
		if errors.Is(err, release.ErrCASConflict) {
			// A lost race against a second signup for the same host, or a
			// plain duplicate. Either way the winner's record stands.
			jsonError(w, http.StatusConflict, "instance "+host+" already exists")
			return
		}
		log.Printf("console: api instances create %s/%s/%s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not create the instance — try again")
		return
	}
	// The sibling check above and this write are two stores, so an app can be
	// created under the label between them (claimApp asked apexHolder before
	// the record existed). Re-read after writing, and on a hit take the record
	// back: the name that arrived owns its apex. The same after-the-commit
	// re-check a rename makes (appsettings.go).
	if siblingLabel != "" {
		if live, trashed, err := s.store.AppNameState(acct.ID, siblingLabel); err == nil && (live || trashed) {
			if derr := s.retireInstanceRecord(ctx, acct.Sqid, app, host, principal, mustCreateIncarnation(acct.Sqid, app, host, rec.CreatedAt)); derr != nil {
				log.Printf("console: api instances create %s/%s/%s: %s was claimed mid-create and UNDO FAILED: %v", acct.Sqid, app, host, siblingLabel, derr)
			}
			if privateBucket != "" {
				// The one window where this feature's ordering leaves
				// residue, logged in those words rather than papered over:
				// tearing the bucket down from a path nobody drove would
				// make this the platform's first automatic destroyer of
				// tenant data, which the per-environment store spec rules
				// out (#408 §3). It is listed by `carlos store status`.
				log.Printf("console: api instances create %s/%s/%s: %s was claimed mid-create; the record was withdrawn and its store %s WAS LEFT BEHIND", acct.Sqid, app, host, siblingLabel, privateBucket)
			}
			jsonError(w, http.StatusConflict,
				host+" is app "+siblingLabel+"'s platform apex — it was created while this instance was being written; the instance was not kept")
			return
		}
	}
	// DNS seam (spec §10): on a single-region deployment nothing writes
	// DNS — the app's wildcard already resolves every instance host to the
	// edge. Multi-region wants <slug>.<domain> CNAME -> <region>.<domain>
	// (TTL 60) written HERE, after the record write and before the
	// response, behind an interface the deployment configures (nil =
	// wildcard-covered). Recorded, not built.
	s.auditActivity(acct, app, principal, Activity{
		Action: "instance-create", TargetType: "instance", Target: host, Message: message,
		Detail: "created instance " + host + " (cli)",
	})
	// The record is what a box's reconcile leg mints a route from, so this is
	// a box-consumed write (carlos-deploy §3): announce it, and the instance
	// is serving seconds after signup instead of on the hour.
	s.bumpSerial(ctx)
	out := recordView(rec)
	out.PrivateStoreBucket = privateBucket
	out.RegionFrom = regionFrom
	// Every non-fleet placement is named, replicas included (codex
	// plan-R3 6); a fleet-placed record's Region is the fleet itself.
	if placed == "" {
		out.RegionName = s.placeOf(rec.Region, s.candsOrHome(ctx))
	}
	writeJSON(w, http.StatusCreated, out)
}

// instanceChannel answers "which channel is this record born on" for a
// create that named none — amadan carlos/platform#5, where a brand-new app's
// first instance landed on "stable" and the first deploy then met stable's
// passkey, as did the obvious repair of moving it to edge.
//
// The rungs, in order, and why each one is above the next:
//
//	manifest channel  app policy, written at `carlos instances enable
//	                  -channel`. An app that declared one is not re-decided
//	                  here, in either direction — this is what keeps tito's
//	                  per-customer creates landing where every sibling is.
//	sibling records   the channel this app's OTHER instances follow, when
//	                  they agree. A record per customer is the flagship's
//	                  shape, and a new one quietly landing on the pipeline
//	                  entry would serve that customer the edge build.
//	                  canary/* siblings do not vote: a canary instance is
//	                  made to verify a build and deleted after, so the
//	                  throwaway must not set policy for the real one.
//	pipeline entry    where this app's releases actually land
//	                  (release.Pipeline.Entry), which is what `carlos
//	                  deploy` resolves its own channel from. An app with no
//	                  pipeline.json falls to the starter pipeline's entry,
//	                  which is also the legacy ladder's: nothing is promoted
//	                  ONTO edge — merging is what puts a build there.
//
// Two cases refuse rather than guess, because a record's channel is chosen
// once and this door cannot take it back:
//
//	an unreadable pipeline is NOT an absent one (apipipeline.go's rule) — a
//	bucket hiccup must not mint a production route by falling through, and
//	instances that disagree have no default worth inventing (attachChannel's
//	refusal, same words, same reason).
//
// A caller who named a channel never reaches here: an explicit channel is
// the caller's decision, is shape-checked only, and costs no bucket reads.
func (s *Server) instanceChannel(ctx context.Context, sqid, app string, m *provision.Manifest) (string, *doorRefusal) {
	if m.Channel != "" {
		return m.Channel, nil
	}
	recs, _, err := provision.ListRecords(ctx, s.cfg.Releases, sqid, app, instanceListMax)
	if err != nil {
		log.Printf("console: api instances create %s/%s: list siblings: %v", sqid, app, err)
		return "", &doorRefusal{http.StatusBadGateway,
			"could not read this app's instances — try again, or pass -channel"}
	}
	var found []string
	for _, rec := range recs {
		if rung, ok := release.Rung(rec.Channel); rec.Channel == "" || (ok && rung == release.RungCanary) {
			continue
		}
		if !slices.Contains(found, rec.Channel) {
			found = append(found, rec.Channel)
		}
	}
	slices.Sort(found)
	if len(found) > 1 {
		return "", &doorRefusal{http.StatusUnprocessableEntity,
			"this app's instances follow several channels (" + strings.Join(found, ", ") +
				") — pass -channel to say which one this instance follows"}
	}
	if len(found) == 1 {
		return found[0], nil
	}
	p, err := release.GetPipeline(ctx, s.cfg.Releases, s.cfg.ReleasePub, sqid, app)
	if err != nil {
		log.Printf("console: api instances create %s/%s: pipeline read: %v", sqid, app, err)
		return "", &doorRefusal{http.StatusBadGateway,
			"could not read this app's pipeline — try again, or pass -channel"}
	}
	if p != nil {
		return p.Entry(), nil
	}
	return release.DefaultPipelineChannels()[0].Name, nil
}

// staticHeadRefusal refuses the one instance record that can never work: a
// process-backed route on a channel whose head is a STATIC release.
//
// The record would be created happily, provisioned into a real route, and
// then fail every wake forever — a static release's manifest carries a "site"
// tar and no build for any box's platform, so nothing is ever staged and no
// live symlink is ever written. What the member saw before this door existed
// was "nothing is promoted for this instance's channel" against a `carlos
// channels` that showed the promote plainly there, with no path from either
// to the real problem (skills#29). internal/release's noHeadReason now names
// that state honestly when a box is already in it; this is the door that
// stops it being reachable.
//
// Only the exec shapes are gated. A "service" record proxies to declared
// upstreams and a "static" record reads the channel pointer directly —
// neither stages a binary, so neither has anything to mismatch. An empty kind
// is the default, which IS "instance": that is precisely the request the
// reporter made.
//
// The check spends two bucket reads on a create, and only a create. Every
// failure to read degrades to nil — this is a guard against a shape mistake,
// not a rail against a hostile caller, and a bucket hiccup must not stop an
// ordinary member declaring an ordinary instance. A brand-new app with
// nothing promoted yet reads as nil too, which is the common first-instance
// case and stays exactly as fast as it was.
func (s *Server) staticHeadRefusal(ctx context.Context, sqid, app, channel, kind, host string) *doorRefusal {
	if kind != "" && kind != "instance" {
		return nil
	}
	ptr, err := release.Channel(ctx, s.cfg.Releases, s.cfg.ReleasePub, sqid, app, channel)
	if err != nil || ptr == nil || ptr.Version == "" {
		return nil
	}
	m, err := release.GetManifest(ctx, s.cfg.Releases, sqid, app, ptr.Version)
	if err != nil || m == nil || m.Kind != "static" {
		return nil
	}
	return &doorRefusal{http.StatusUnprocessableEntity,
		"channel " + channel + " serves a static release (" + ptr.Version + "), and an instance runs a process — " +
			"a static site is served straight off the channel pointer, so it needs no instance at all. " +
			"Pass --kind static, or let one command do the whole thing: carlos deploy --app " + app +
			" --kind static --host " + host + " <site-dir>"}
}

// refuseMemberUpstreams answers whether this caller may point a route at
// addrs, and writes the refusal when not. Stating an upstream is an
// operator's act: the edge dials these addresses from inside the platform,
// so a member's could reach the box's own services (the console on
// 127.0.0.1:8090) or another tenant's private upstream (discussion 214,
// item 4). Paul's ruling on discussion 50 (option a): members
// state none until the "own fleet" allowance exists, public addresses
// included, and operators keep today's rail.
//
// kept lists the addresses the record already carries. Those pass whoever
// sends them, so a member whose route an operator pointed somewhere can
// keep it, change its probe, or drop a dead upstream; only adding one is
// refused.
//
// "Operator" is a person holding the operator bit. A service credential
// never is one, whichever account it belongs to. A failed operator lookup
// refuses, so a database blip is not the way past it.
func (s *Server) refuseMemberUpstreams(w http.ResponseWriter, p Principal, addrs, kept []string) bool {
	added := false
	for _, a := range addrs {
		if !slices.Contains(kept, a) {
			added = true
			break
		}
	}
	if !added {
		return false
	}
	if p.Kind == PrincipalUser {
		op, err := s.store.IsOperator(p.Address)
		if err != nil {
			log.Printf("console: upstream rail: is-operator %s: %v", p.Address, err)
			jsonError(w, http.StatusServiceUnavailable, "could not check who may set these upstreams — nothing was changed. Try again.")
			return true
		}
		if op {
			return false
		}
	}
	jsonError(w, http.StatusForbidden, "only a platform operator can point an instance at its own backends")
	return true
}

// handleAPIInstanceUpdate repoints a live instance's UPSTREAM SET, probe
// config and (Task 3, multi-region-steering plan) DNS STEERING opt-in — the
// fields of a record that are meant to change while the instance keeps
// serving (HA design, issue #152; steering, 2026-08-20 multi-region ingress
// design Part 4). Everything else about a record stays where it is: identity
// (host/app/account) is checked at create and never touched again, policy
// (pool, domain) is the manifest's, and region has its own writer in
// placement.
//
// It is a PATCH, and the body's fields are independently optional, because
// "leave the probe alone while I add an upstream" is the ordinary request. A
// body carrying NONE of them is refused rather than treated as a no-op write:
// it would cost a bucket round trip and a fleet-wide serial bump to change
// nothing.
//
// The write is guarded by the etag the record was READ under
// (provision.UpdateRecord): the caller decided this upstream set (or this
// steering opt-in) given the record they were shown, so a concurrent writer
// means the decision was made about bytes that no longer exist, and the
// honest answer is 409 — the same answer the enable door gives for the same
// reason.
//
// Steering carries its own two rails, beyond the CAS guard every field here
// shares: an invalid value is ValidateShape's own 400 (ValidSteering is
// already one of its checks, so a bad vocabulary word needs no extra code
// here), and asking to turn latency ON for a record whose Pool != "" is a
// 409 naming the v1 constraint verbatim (plan-2 ledger: a steered
// pool-scoped route would get latency records pointing at edges that
// structurally cannot serve it — the per-pool-record-scoping alternative is
// a recorded future, not v1). The rail reads the FETCHED RECORD's Pool —
// stamped once at create and never touched by this door — not the app's
// manifest, which may have moved to a different pool since; the record is
// the source of truth this door edits, and the manifest's current value is
// not it. Turning steering OFF is never blocked by this rail: only the
// latency-on request needs the shared pool.
//
// Every refusal before the principal is proven is the family's byte-identical
// 404 (instanceGate), including a host that names no record: a record's
// existence is not a thing to probe for here any more than it is on GET.
func (s *Server) handleAPIInstanceUpdate(w http.ResponseWriter, r *http.Request) {
	principal, acct, app, ok := s.instanceGate(w, r)
	if !ok {
		return
	}
	// Same split as create, for a sharper reason: the provisioning
	// reconciler converges a route's Channel and Environment FROM this
	// record on every pass (AGENTS.md), so a PATCH here repoints the
	// control plane. An operator doing that deliberately is legitimate; a CI
	// credential doing it is the console being moved by something with no
	// standing to move it. Placed before the host shape check so that no
	// branch of this handler reaches a write without passing it.
	p, _ := principalFrom(r.Context())
	if s.refuseServiceControlPlane(w, p, acct.ID, app, "change its instance records") {
		return
	}
	host := r.PathValue("host")
	// Shape-checked before the key builder, exactly as GET does it and for
	// the same reason: a {host} segment arrives percent-decoded, so
	// "..%2f..%2fchannels" reaches this handler as a path with separators in
	// it and RecordKey would happily join it. The manifest's suffix rule is
	// deliberately NOT applied — that is create-time policy ("which hosts may
	// this app claim"), and an app that has since moved domains must still be
	// able to repoint the upstreams of the instances it already has.
	if !provision.ValidHostShape(host) {
		http.NotFound(w, r)
		return
	}
	// Addrs is a POINTER and Probe a RawMessage because absent, empty and
	// null are three different requests (the apiConfigApply precedent): an
	// omitted field leaves what the record carries, `"addrs":[]` clears the
	// upstream set, and `"probe":null` clears the probe while `"probe":{}`
	// asks for the platform defaults.
	//
	// The two are deliberately NOT symmetric about null, and the asymmetry is
	// worth stating because it is invisible from the types: `"probe":null`
	// CLEARS the probe (a RawMessage records that the key was present), while
	// `"addrs":null` is indistinguishable from an absent key to a *[]string
	// and therefore means "leave the upstream set alone". Clearing the set is
	// spelled `"addrs":[]`, which is also the only spelling that says what it
	// means.
	//
	// Steering is a *string, plainer than either: it is one scalar fact, not
	// a set or a block, so there is no empty-vs-null distinction to carry.
	// Absent (nil) leaves the record's steering alone; `"steering":""` turns
	// it off; `"steering":"latency"` turns it on (subject to the pool rail
	// below).
	// Environment is a *string for the same reason Steering is: one scalar
	// fact, so absent (nil) leaves the record's binding alone and
	// `"environment":""` returns the route to the app's default bundle.
	// Rebinding is exactly what the handler doc above describes as
	// legitimate-when-deliberate — this door repoints the control plane, and
	// refuseServiceControlPlane has already decided whether this caller may.
	var req struct {
		Addrs       *[]string       `json:"addrs"`
		Probe       json.RawMessage `json:"probe"`
		Steering    *string         `json:"steering"`
		Environment *string         `json:"environment"`
		// Gate is a *string like Steering: absent leaves the gate alone,
		// "" opens the host, anything else is the new password — hashed
		// here, never stored or echoed (spec §5.2). The plaintext crosses
		// the wire once, over TLS, the same as a sign-in.
		Gate *string `json:"gate"`
	}
	if !readJSON(w, r, &req) {
		return
	}
	if req.Addrs == nil && req.Probe == nil && req.Steering == nil && req.Environment == nil && req.Gate == nil {
		jsonError(w, http.StatusBadRequest,
			"nothing to update — send addrs, probe, steering, environment, gate, or a combination")
		return
	}
	var probe *provision.Health
	if req.Probe != nil {
		if err := json.Unmarshal(req.Probe, &probe); err != nil {
			jsonError(w, http.StatusBadRequest,
				`invalid probe — want an object like {"path":"/healthz","status":200} or null to stop probing`)
			return
		}
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	rec, etag, err := provision.GetRecordETag(ctx, s.cfg.Releases, acct.Sqid, app, host)
	if errors.Is(err, os.ErrNotExist) {
		http.NotFound(w, r)
		return
	}
	if err != nil {
		log.Printf("console: api instances update read %s/%s/%s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not read the instance")
		return
	}
	// The record as it stands, kept whole before anything below mutates it:
	// the shape rail past ValidateShape is a comparison BETWEEN the stored
	// route and the patched one, not a property of either alone.
	stored := *rec
	if req.Addrs != nil {
		// This door states the upstream set WHOLE, so it also retires the
		// legacy single-addr spelling of the same fact. Leaving Addr standing
		// would make every patch of a record minted before Addrs existed fail
		// provision.ValidateShape's "addr and addrs both set" rail — a refusal
		// about a field the caller never sent, on the exact records (kass,
		// keymail, the consoles) this feature exists to give a second upstream
		// to. Clearing it is not a widening: AddrsOrDefault already folds Addr
		// into the same one-element set this replaces.
		rec.Addrs, rec.Addr = *req.Addrs, ""
	}
	if req.Probe != nil {
		rec.Health = probe
	}
	if req.Steering != nil {
		rec.Steering = *req.Steering
	}
	if req.Environment != nil {
		rec.Environment = strings.TrimSpace(*req.Environment)
	}
	// The gate is the one field this door does not store as it was sent: the
	// record carries a bcrypt hash and nothing else, so the plaintext lives
	// only in this stack frame. Not trimmed either — a password's leading and
	// trailing spaces are part of it, and the login POST compares the bytes
	// the member typed.
	if req.Gate != nil {
		if *req.Gate == "" {
			rec.Gate = ""
		} else {
			// CheckPassword's sentences name the rule and never the value:
			// nothing below (and nothing logged) can echo the password back.
			if err := gate.CheckPassword(*req.Gate); err != nil {
				jsonError(w, http.StatusBadRequest, err.Error())
				return
			}
			h, err := gate.Hash(*req.Gate)
			if err != nil {
				log.Printf("console: api instances update %s/%s/%s: hash gate: %v", acct.Sqid, app, host, err)
				jsonError(w, http.StatusInternalServerError, "could not set the password — try again")
				return
			}
			rec.Gate = h
		}
	}
	// The same door the create path and the box's reconcile pass check
	// against, so a shape that could not have been created cannot be patched
	// into existence either — and the caller gets ValidateShape's own
	// sentence, which names the offending upstream. It is also this
	// door's own invalid-value 400 for steering: ValidSteering is already
	// one of ValidateShape's checks, so "geo" or "Latency" is refused here
	// with no code of this handler's own.
	if err := provision.ValidateShape(*rec); err != nil {
		jsonError(w, http.StatusBadRequest, err.Error())
		return
	}
	// An address the record already carries is not a new statement, so a
	// member may keep it: dropping one dead upstream from an operator-made
	// set is theirs to do.
	if req.Addrs != nil && s.refuseMemberUpstreams(w, p, *req.Addrs, stored.AddrsOrDefault()) {
		return
	}
	// v1's pool guardrail (multi-region-steering plan, plan-2 ledger):
	// latency steering needs the SHARED pool, because a pool's own edges are
	// the only ones that can serve a pool-scoped route — a steered
	// non-shared-pool route would advertise latency records pointing at
	// edges that structurally cannot answer for it. The per-pool-record
	// alternative is a recorded future, not v1.
	//
	// rec.Pool is read straight off the bytes GetRecordETag fetched moments
	// ago — this door never writes Pool and never re-derives it from the
	// app's manifest, which may have moved to a different pool since the
	// record was created. The record is the source of truth this door
	// edits; the manifest's CURRENT value is not it, and using it here would
	// let an operator's later `instances enable` silently flip what an
	// already-provisioned route is allowed to do. Turning steering OFF is
	// never blocked: only a request that leaves this record at "latency"
	// needs the shared pool.
	if rec.Steering == "latency" && rec.Pool != "" {
		jsonError(w, http.StatusConflict,
			"steering requires the shared pool — pool-scoped steering is a recorded future")
		return
	}
	// The rail this door needs beyond ValidateShape: a patch may repoint a
	// route's upstreams, never change what KIND of thing the route is.
	// DerivesPaths is that line exactly — it decides whether the route owns a
	// <host>.sock and a <host>.db — and the reconcile pass refuses to converge
	// a row across it in place (the "record describes a different route SHAPE"
	// log). Allowing the patch anyway would answer 200 for a change that can
	// never take effect: a socket-backed instance handed addrs would keep
	// serving its socket while the box logged the same complaint every pass,
	// and an addrs-backed route emptied to nothing would become a route that
	// serves nothing at all. Transitions go through delete + create, which
	// this API already supports, and which lets the box retire the old route's
	// derived paths honestly.
	if stored.DerivesPaths() != rec.DerivesPaths() {
		jsonError(w, http.StatusBadRequest,
			"that changes the instance's route SHAPE, not just its upstreams — a socket-backed instance "+
				"and an upstream-backed one are different routes, and a box cannot convert one into the other "+
				"in place; delete "+host+" and create it again with the shape you want")
		return
	}
	// A new environment binding is serialised with a seed's store teardown,
	// and takes the store from the seed (final review F3, seedenvbind.go).
	unlockEnv, ok := s.lockEnvironmentUpdate(ctx, w, stored, *rec)
	if !ok {
		return
	}
	defer unlockEnv()
	// provision.UpdateRecord marshals the whole record through the canonical
	// writer: nothing here hand-builds an object body, so upstream ORDER —
	// which the reconcile pass's shapeMismatch compares verbatim against the
	// registry's joined column — lands exactly as the caller stated it.
	if err := provision.UpdateRecord(ctx, s.cfg.Releases, *rec, etag); err != nil {
		if errors.Is(err, release.ErrCASConflict) {
			jsonError(w, http.StatusConflict,
				"instance "+host+" changed while this request was in flight — read it again and re-apply")
			return
		}
		log.Printf("console: api instances update %s/%s/%s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not update the instance — try again")
		return
	}
	// "upstreams" no longer names the whole of what this door can change
	// (steering joined it in Task 3), so the audit line names exactly the
	// fields THIS request carried rather than either overclaiming ("upstreams"
	// on a steering-only patch) or going field-agnostic ("updated instance
	// <host> (cli)" alone) — this is a security surface, and "did anyone turn
	// on steering for this host last week?" has to stay answerable from the
	// audit log. Built from the same req.* nil checks the mutation above
	// already made, so it can never drift from what was actually applied.
	var changed []string
	if req.Addrs != nil {
		changed = append(changed, "addrs")
	}
	if req.Probe != nil {
		changed = append(changed, "probe")
	}
	if req.Steering != nil {
		changed = append(changed, "steering")
	}
	if req.Environment != nil {
		changed = append(changed, "environment")
	}
	// "gate" names that the host's password was set or cleared, never which
	// it was: the audit log answers "did anyone change the gate on this host
	// last week?" without becoming a place a password can be read.
	if req.Gate != nil {
		changed = append(changed, "gate")
	}
	s.audit(acct, app, principal, "instance-update",
		"updated instance "+host+" ("+strings.Join(changed, ", ")+") (cli)")
	// Strictly after the write landed, and exactly once: the record is what a
	// box's reconcile leg converges upstreams from (provision.convergeOwned),
	// so this announcement is what makes the new set live in seconds instead
	// of on the hour.
	s.bumpSerial(ctx)
	writeJSON(w, http.StatusOK, recordView(*rec))
}

// handleAPIInstanceDelete retires an instance's route authorization. The
// record is deleted; the parked database and blobs are deliberately
// untouched (spec §3.2) — retiring a route is not destroying a customer's
// data. Idempotent: the caller's goal is "not there", and a second delete
// has reached it.
func (s *Server) handleAPIInstanceDelete(w http.ResponseWriter, r *http.Request) {
	principal, acct, app, ok := s.instanceGate(w, r)
	if !ok {
		return
	}
	message, ok := checkedActivityMessage(w, r.Header.Get(activityMessageHeader))
	if !ok {
		return
	}
	// The eighth destructive door, and the one with the shortest fuse:
	// deleting a control-plane app's record is how the provisioning
	// reconciler's removal phase is TOLD to retire the console's route, so a
	// single call here takes the control plane off the air. That is the same
	// class of act as trash, purge and store-destroy, and it wears their
	// refusal — outright, for anyone, service or person alike, until the
	// flag is cleared (controlplane.go).
	//
	// FIRST, ahead of the shape check and the store: the app is already
	// past instanceGate's byte-identical 404, and nothing below this line
	// may run for a flagged app.
	if s.refuseControlPlane(w, acct, app, "deleted") {
		return
	}
	host := r.PathValue("host")
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	// SHAPE ONLY, always — and the manifest is not read here at all. The
	// domain-suffix rule is CREATE-time policy ("which hosts may this app
	// claim"), and deletion has to outlive every version of it: a retired
	// manifest, an app that moved domains, a record written under a domain
	// the manifest no longer names. Any of those checked against today's
	// manifest would refuse to delete records that exist, stranding
	// provisioned routes with nothing left able to retire them. What
	// deletion actually needs from validation is the traversal defence: a
	// {host} arrives percent-decoded, so "..%2f..%2finstances.json" reaches
	// here with separators in it and RecordKey would happily join it.
	// ValidHostShape is exactly that check, and there is no path through
	// this handler on which an unvalidated host reaches RecordKey.
	if !provision.ValidHostShape(host) {
		jsonError(w, http.StatusBadRequest, "invalid host")
		return
	}
	// With CARLOS_MOVES_PHASE1 on, a host being moved is not deleted
	// (M-C19, apiinstancemove.go); with it off this is main's door.
	if s.refuseDeleteDuringMove(ctx, w, acct.Sqid, app, host) {
		return
	}
	if answered, finished := s.refuseImportDelete(w, r, acct, app, host); answered {
		if finished {
			s.auditActivity(acct, app, principal, Activity{
				Action: "instance-delete", TargetType: "instance", Target: host, Message: message,
				Detail: "deleted instance " + host + " (cli)",
			})
			s.bumpSerial(ctx)
			writeJSON(w, http.StatusOK, map[string]any{"result": "deleted"})
		}
		return
	}
	if err := s.retireInstanceRecord(ctx, acct.Sqid, app, host, principal, ""); err != nil {
		// An accepted delete is this principal's durable request: audit it
		// and announce it before answering 202 with the operation.
		if accepted, ok := claimRetireAcceptedOf(err); ok {
			s.auditActivity(acct, app, principal, Activity{
				Action: "instance-delete", TargetType: "instance", Target: host, Message: message,
				Detail: "delete of instance " + host + " accepted, operation " + accepted.operation + " (cli)",
			})
			s.bumpSerial(ctx)
		}
		if s.writeClaimPending(w, err) {
			return
		}
		log.Printf("console: api instances delete %s/%s/%s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not delete the instance — try again")
		return
	}
	// DNS seam (spec §10): a multi-region deployment retires the instance's
	// CNAME here, after the record is gone.
	//
	// Audited whether or not an object was actually there to remove:
	// idempotency makes "deleted" and "already gone" indistinguishable from
	// the store, and the fact worth recording is that this principal asked
	// for this host to stop existing.
	s.auditActivity(acct, app, principal, Activity{
		Action: "instance-delete", TargetType: "instance", Target: host, Message: message,
		Detail: "deleted instance " + host + " (cli)",
	})
	// Retiring a route is reconcile's work too, and the direction people want
	// FAST: the announcement is what takes the route down in seconds.
	s.bumpSerial(ctx)
	writeJSON(w, http.StatusOK, map[string]any{"result": "deleted"})
}

// handleAPIInstanceToken mints the app-held credential (spec §8). Gated by
// apiPerson and then apiAccountApp DIRECTLY, not by the instance gate:
// minting is a human act, and a credential may never mint a credential —
// including itself. A service principal meets the 401 a fabricated token
// meets, the same one it met when this door's only resolver was cliUser.
// Budgeted on the address-keyed write limiter for the same reason: the
// principal a mint belongs to is a person.
//
// That 401 is the INNER of two walls, and it is the one nothing can reach:
// the outer is cliRoute, where this door's zero Set refuses every role,
// admin included (TestNoRoleReachesAMintFleetOrPolicyDoor,
// TestAdminIsRefusedAtAClosedDoor). Both are kept, because the inner one
// used to be a side effect of resolving through cliUser and would otherwise
// have vanished the day that resolution became principal-aware.
func (s *Server) handleAPIInstanceToken(w http.ResponseWriter, r *http.Request) {
	if !s.apiPerson(w, r) {
		return
	}
	addr, acct, app, ok := s.apiAccountApp(w, r)
	if !ok {
		return
	}
	p, _ := principalFrom(r.Context())
	if !s.allowWrite(p, time.Now()) {
		jsonError(w, http.StatusTooManyRequests, "too many requests — wait a minute and try again")
		return
	}
	var req struct {
		Label string `json:"label"`
	}
	if !readJSON(w, r, &req) {
		return
	}
	// Same de-fanging every terminal label gets: this string is rendered on
	// the minter's tokens page, where it is the one field a human reads to
	// decide whether to revoke.
	label := cleanLabel(req.Label)
	if label == "" {
		label = app + " instance token"
	}
	raw, err := s.store.NewAppTokenContext(r.Context(), acct.ID, app, addr, label, time.Now())
	if err != nil {
		log.Printf("console: api instance token %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusInternalServerError, "could not mint the token — try again")
		return
	}
	s.audit(acct, app, addr, "instance-token", "minted an instance token for "+app+" (cli)")
	// Shown exactly once: only the hash is stored, so there is no second
	// copy to hand out and no way to recover this one. Delivery to the app
	// is the config-env layer, like any other app secret —
	// `carlos secrets set -app <app> CARLOS_INSTANCE_TOKEN=...`.
	writeJSON(w, http.StatusCreated, map[string]any{
		"token": raw, "account": acct.Sqid, "app": app,
	})
}

// instanceSeed bounds (issue #66). Seed becomes the argv the activator execs
// the app's OWN binary with on first wake — the caller already controls that
// binary via ship, so the bound here is manifest hygiene, not privilege: a
// manifest is read forever, and an unbounded argv written once would be
// permanent.
const (
	instanceSeedMaxArgs   = 16
	instanceSeedMaxArgLen = 256
)

// handleAPIInstanceEnable is the member-facing half of `carlos instances
// enable` (issue #66): the one bucket-only prerequisite that kept the
// otherwise-API path from "promoted" to "reachable" needing a box shell.
//
// The security line it holds: the manifest's DOMAIN is pinned server-side to
// <account-sqid>.<AppsDomain> — the account's own platform subdomain — and
// nothing the request carries can name another. Custom domains (tito's
// go.tito.io) stay an operator act in store mode, and an existing manifest
// under any other domain is refused with a 409, never overwritten: this door
// can hand an account keys only to hostnames that were already hers.
//
// Gated by apiPerson and then apiAccountApp DIRECTLY, not the instance gate:
// enabling is policy, a human act — a service credential meets the 401 here
// that it meets at the token mint, and for the same reason. The manifest
// this door writes is standing policy about what may ever be BROUGHT INTO
// existence for the app; a credential the app itself holds must not be able
// to rewrite the bounds it runs inside. Budgeted on the address-keyed write
// limiter for the same reason.
//
// The door is registered with the zero Set (authcli.go), so no role reaches
// it and a service credential is refused out at cliRoute with the same 403
// the mint door gives. That registration is the load-bearing wall; apiPerson
// is the second one, stated here because the person-only rule is a fact
// about the SUBJECT of this door rather than about any caller's role, and
// because it used to hold only as a side effect of resolving through
// cliUser. Pinned by TestAPIInstanceEnableRefusals, TestEnableStaysAHumanAct
// and TestApiPersonIsTheInnerWall.
func (s *Server) handleAPIInstanceEnable(w http.ResponseWriter, r *http.Request) {
	if !s.apiPerson(w, r) {
		return
	}
	addr, acct, app, ok := s.apiAccountApp(w, r)
	if !ok {
		return
	}
	p, _ := principalFrom(r.Context())
	if !s.allowWrite(p, time.Now()) {
		jsonError(w, http.StatusTooManyRequests, "too many requests — wait a minute and try again")
		return
	}
	if s.cfg.Releases == nil {
		jsonError(w, http.StatusServiceUnavailable,
			"no deployment bucket on this host — the console is running without one")
		return
	}
	if s.cfg.AppsDomain == "" {
		// Membership is proven, so this may name the operator act that fixes
		// it. 503, not 409: the missing piece is deployment configuration
		// (PLATFORM_APPS_DOMAIN on the console), not anything about this app.
		jsonError(w, http.StatusServiceUnavailable,
			"this console has no platform apps domain configured — an operator enables instances in store mode (carlos instances enable) or sets PLATFORM_APPS_DOMAIN on the console")
		return
	}
	// Channel and Seed are pointers because "absent" and "empty" are
	// different requests on the wire (the apiConfigApply precedent): an
	// omitted field preserves what the manifest already carries, an explicit
	// value replaces it — including seed's explicit [] meaning "clear".
	//
	// PrivateStorage joined them on 2026-09-22 (issue #412) as a pointer for
	// exactly the same reason: an app that already gives its instances their
	// own storage must not lose the policy to a `carlos instances enable
	// -channel beta` that never mentioned it.
	var req struct {
		Channel        *string   `json:"channel"`
		Seed           *[]string `json:"seed"`
		PrivateStorage *bool     `json:"private_storage"`
	}
	if !readJSON(w, r, &req) {
		return
	}
	if req.Channel != nil && !release.ValidChannel(*req.Channel) {
		jsonError(w, http.StatusBadRequest, "invalid channel name")
		return
	}
	if req.Seed != nil {
		if len(*req.Seed) > instanceSeedMaxArgs {
			jsonError(w, http.StatusBadRequest, "seed takes at most 16 arguments")
			return
		}
		for _, arg := range *req.Seed {
			if arg == "" || len(arg) > instanceSeedMaxArgLen {
				jsonError(w, http.StatusBadRequest, "each seed argument must be 1-256 bytes")
				return
			}
		}
	}
	domain := acct.Sqid + "." + s.cfg.AppsDomain
	// The domain is about to be stamped into a manifest every future host
	// gets checked against, and ValidHost only regex-checks the leading
	// label — the suffix rides into bucket keys verbatim. Store mode
	// validates its -domain for exactly this reason (instances_cli.go); a
	// misconfigured PLATFORM_APPS_DOMAIN ("*.oncarlos.com" copied off a DNS
	// record) must refuse here, not surface as records reconcile skips
	// forever. The console also refuses garbage at boot (cmd/console); this
	// guard covers embedders that build Config directly.
	if !provision.ValidHostShape(domain) {
		jsonError(w, http.StatusServiceUnavailable,
			"this console's PLATFORM_APPS_DOMAIN is not a valid domain — fix the console configuration")
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	// Read WITH the etag and write guarded by it below: the domain-conflict
	// refusal is only honest if nothing can land between this read and the
	// write. PutManifest's upsert re-reads inside, so an operator's
	// store-mode manifest written into that window would be silently
	// re-homed — the exact overwrite the 409 exists to prevent.
	m, etag, err := provision.GetManifestETag(ctx, s.cfg.Releases, acct.Sqid, app)
	switch {
	case errors.Is(err, os.ErrNotExist):
		m, etag = &provision.Manifest{Schema: 1, App: app, Domain: domain}, ""
	case err != nil:
		log.Printf("console: api instances enable read %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not read instance settings")
		return
	case m.Domain != domain:
		// Never overwritten from here: a manifest naming any other domain
		// was written by an operator in store mode, and re-homing every
		// FUTURE host check under the platform domain would be this door
		// rewriting operator policy. Membership is proven, so naming the
		// standing domain leaks nothing the caller cannot already read.
		jsonError(w, http.StatusConflict,
			"instances for "+app+" are managed under "+m.Domain+
				" — changing an app's instance domain is an operator act (carlos instances enable, store mode)")
		return
	}
	// Pool and Regions survive untouched on an update: they are operator
	// policy this door never speaks for, in either direction. (Recorded
	// debt: fields ADDED to schema 1 after this binary would be dropped by
	// this read-modify-write, the same property the store-mode upsert has —
	// an additive manifest field needs the console upgraded before members
	// enable through it.)
	if req.Channel != nil {
		m.Channel = *req.Channel
	}
	if req.Seed != nil {
		m.Seed = *req.Seed
	}
	// Turning the policy ON is checked against what this deployment and this
	// account can actually do; turning it OFF never is (spec §5). The
	// asymmetry is deliberate: a policy that cannot be honoured fails once
	// per signup in a door whose caller is a machine, so the person
	// declaring it is told now — but an account whose entitlement was later
	// declined must be able to get its create door working again without
	// waiting on an operator.
	if req.PrivateStorage != nil && *req.PrivateStorage &&
		s.refuseTemporary(w, acct, app, "give its instances private storage") {
		return
	}
	if req.PrivateStorage != nil && *req.PrivateStorage && !m.PrivateStorage {
		if !s.instancePrivateStorageAllowed(ctx, w, acct) {
			return
		}
	}
	if req.PrivateStorage != nil {
		m.PrivateStorage = *req.PrivateStorage
	}
	if err := provision.PutManifestIfMatch(ctx, s.cfg.Releases, acct.Sqid, app, *m, etag); err != nil {
		if errors.Is(err, release.ErrCASConflict) {
			jsonError(w, http.StatusConflict,
				"instance settings changed while this request was in flight — try again")
			return
		}
		log.Printf("console: api instances enable %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not enable instances — try again")
		return
	}
	s.audit(acct, app, addr, "instance-enable", "enabled instances under "+domain+privateStorageAuditSuffix(req.PrivateStorage)+" (cli)")
	// The manifest names the channel every minted route follows, so a change
	// here changes what boxes converge onto — reconcile reads it each pass.
	s.bumpSerial(ctx)
	writeJSON(w, http.StatusOK, map[string]any{
		"app": app, "domain": m.Domain, "pool": m.Pool, "channel": m.Channel,
		"regions": m.Regions, "seed": m.Seed, "private_storage": m.PrivateStorage,
	})
}

// privateStorageAuditSuffix names the policy in the audit line only when
// this request SPOKE to it. An enable that changed a channel says nothing
// about storage, and a row that restated the standing policy every time
// would make the one request that changed it impossible to find.
func privateStorageAuditSuffix(req *bool) string {
	switch {
	case req == nil:
		return ""
	case *req:
		return ", every instance with storage of its own"
	default:
		return ", instances sharing the app's storage"
	}
}

// instanceRegionAllowed applies the manifest's region allow-list. An empty
// list means any shape-valid region (spec §3.1) — including the empty,
// unconstrained one, which is what a single-region deployment uses.
func instanceRegionAllowed(allowed []string, region string) bool {
	return len(allowed) == 0 || slices.Contains(allowed, region)
}