// Package status is the fleet status page's writer half: per-box snapshots
// that carry only what the public commitments allow — aggregate counts and
// band words, never ratios, hostnames, or machine ids. Privacy is enforced
// HERE, in the process that does the counting and banding, not downstream —
// a merge step or a page template can only leak what this package already
// let through.
//
// Box.Metrics is the one deliberate exception to that rule, not a hole in
// it: a raw, unbanded block (real byte counts, a load average, the running
// build, tunnel state) that CollectBox attaches to the Box it returns, which
// WriteBox lands in status/boxes/<label>.json alongside everything else this
// package computes. That file is bucket-private — the deployment bucket
// blocks all public access (infra/modules/deployment-buckets), and the edge
// process's fixed three-object menu (internal/edge/status.go) only ever
// serves "/", "/fleet.json", and "/status.css"; a request for
// status/boxes/<label>.json 404s the same as any other unlisted path. Only
// fleet-status machinery (loadBoxes in fleet.go) and operators with bucket
// credentials ever read it. The public merge step, fleet.go's BuildFleet,
// copies Box's fields into FleetBox one at a time by field name and simply
// never names Metrics — so the banded-words-only commitment on fleet.json
// holds by construction, not by a filter that could be forgotten. See
// dryrun.go's leak fixtures, which assert a raw metric value survives into
// the box object but never into fleet.json or index.html.
package status

import (
	"context"
	"crypto/sha256"
	"encoding/binary"
	"encoding/json"
	"errors"
	"os"
	"time"

	"github.com/carlosframework/platform/internal/registry"
	"github.com/carlosframework/platform/internal/release"
)

// Probes carries everything CollectBox may not read from the registry —
// each nil means "unknown", and unknown publishes as null, never a guess.
type Probes struct {
	ConsoleProcesses        []ConsoleProcess
	ActivationID            string
	ActivationComplete      bool
	Enrollment              string
	MovesProtocol           int
	ReleaseTag              string
	BinarySHA256            string
	BootID                  string
	FloorSHA256             string
	FloorGuardReady         bool
	HostClaimEnabled        bool
	RetirementReceiptSHA256 string

	MachineID string // hashed into the label; never serialized
	// InstanceID is the cloud machine this box runs on (status.InstanceID),
	// or "" for hardware no cloud owns. It is the console architecture
	// page's join key — see BoxMetrics.InstanceID.
	InstanceID string
	Region     string                  // operator-set, coarse; "" omits the field
	MemFrac    *float64                // 0..1 memory utilization
	DiskFrac   *float64                // 0..1 proximity to the disk floor
	Listening  func(sock string) *bool // kernel socket table read; nil fn = unknown
	LagSecs    *int64                  // seconds since litestream last progressed
	// AdoptRunning is whether release adoption is actually armed on this box
	// — the carlos-adopt.timer being ACTIVE, not merely enabled. nil is
	// "never asked / couldn't tell", and like every other nil here it must
	// publish as null: a box that can't answer is not a box that is fine.
	AdoptRunning *bool
	// ConfigPathRunning is whether this box's config-sync trigger unit
	// (carlos-adopt.path) is ACTIVE — the issue #44 sibling of AdoptRunning,
	// with the identical failure mode behind it: enabled writes a symlink,
	// only started arms the watch. An unarmed path unit degrades silently
	// (the agent writes its marker, nothing reads it, unit-backed config
	// waits out the hourly floor), which is precisely the class of quiet
	// half-working this field exists to end. nil is "never asked / couldn't
	// tell" and publishes as null, same as every other probe here.
	ConfigPathRunning *bool
	// RestartPathRunning is whether this box's restart trigger unit
	// (carlos-restart.path) is ACTIVE — ConfigPathRunning's issue #113 sibling,
	// same failure mode, sharper consequence: with it unarmed, a member who
	// runs `carlos restart` against a wedged instance is told "requested" and
	// waits out the hourly pass for a cycle they were led to expect in
	// seconds. nil is "never asked / couldn't tell" and publishes as null.
	RestartPathRunning *bool
	// ExpiredCanaries is how many of this box's own canary/* routes have
	// passed release.CanaryTTL (pipelines spec §5 "Canaries expire"),
	// pre-computed by the caller against the release store — CollectBox
	// stays pure and never resolves a channel pointer itself, the same
	// reason every other field here arrives pre-resolved. nil means this
	// box could not determine the answer (no deployment store configured,
	// or a channel pointer it needed wouldn't verify), never a guessed
	// zero; 0 is itself a real, confident answer when every canary route on
	// the box is fresh, or there are none at all.
	ExpiredCanaries *int
	// Alerts is the box's alert-sink answer (see AlertDelivery), carried
	// into Box.Metrics. nil means "never asked".
	Alerts *AlertDelivery

	// MemTotalBytes, MemAvailBytes, Load1, and DiskFreeBytes are the raw
	// numbers MemFrac/DiskFrac above are already computed FROM — CollectBox
	// still bands MemFrac/DiskFrac into Load/Capacity as always, but also
	// carries these through unbanded into Box.Metrics, the package's one
	// documented private exception (see the package doc comment). nil means
	// unknown, same as every other pointer field here.
	MemTotalBytes *int64
	MemAvailBytes *int64
	Load1         *float64
	DiskFreeBytes *int64
	// Release is the running binary's version.Build (a short sha or similar),
	// and Tunnel is one of ""|"connected"|"reconnecting" — both land in
	// Box.Metrics unbanded, like the four numeric fields above. "" means
	// unknown/not-applicable for both, never a guess.
	Release string
	Tunnel  string
	// GeoIP is the edge's GeoIP mirror state (geoip spec §5.5); nil when
	// the edge has not published one (no edge yet, or an older binary).
	GeoIP *GeoIPState
	// Platform is runtime.GOOS-runtime.GOARCH, so the console knows which
	// artifacts a platform promote must mirror. SystemChannel is the box's
	// CARLOS_SYSTEM_CHANNEL, so the console knows which boxes a promote
	// reaches. System is root's last self-update outcome (spec §5, §6).
	Platform      string
	SystemChannel string
	System        *SystemState
	// Upstreams is this box's edge probe table — route host -> per-upstream
	// state — read WHOLE from the prober on every tick (internal/edge's
	// Edge.UpstreamStates), never accumulated across ticks. That rebuild is
	// the field's staleness contract: a route the box has stopped probing
	// (deleted, or its addrs cleared) simply isn't in the next tick's map, so
	// no ghost entry can outlive the route that produced it. Empty/nil means
	// this box probes nothing — the shape of every box with no multi-upstream
	// route, which is most of them — and publishes as an absent key, not an
	// empty object.
	Upstreams map[string][]UpstreamState

	// Aliases is this box's route_aliases rows (registry.RouteAlias), the
	// agent's reg.ListAliases() read at statusTick — carried through raw so
	// CollectBox can fold each row's DNS/cert stamp into Box.Metrics.Aliases
	// alongside RouteVersions above. A failed read is the caller's problem
	// (log-and-continue, see agent.go's statusTick), never CollectBox's: nil
	// here means "no aliases known this tick," identical on the wire to "no
	// alias rows exist."
	Aliases []registry.RouteAlias

	// DBBytes sizes one route's SQLite database on local disk: the file at
	// registry.Route.DBPath plus its -wal. CollectBox calls it for every
	// non-platform, non-static route with a DBPath. A nil func, or a nil
	// answer (no file yet, stat failed), means unknown and the host is left
	// out of Metrics.RouteDBBytes rather than published as 0.
	DBBytes func(dbPath string) *int64

	// Layout is the box's layout report (isolated-exec design §8.4): which
	// mode the box last converged to and, per instance-kind route, the word
	// the layout pass's own Classify gave it. The caller (internal/host's
	// statusLoop) builds it from the armed layout.Pass and the routes it
	// already listed; nil means no pass is armed on this box, which
	// CollectBox carries straight through as "nothing to report" rather
	// than guess at a mode. Hostname-keyed, like Aliases and RouteVersions
	// above, which is why it lands in Box.Metrics and nowhere else.
	Layout *LayoutReport
	// ConfigRefusals is the instances this box is CURRENTLY refusing to take
	// because it cannot provide their config (amadan #213), as the host's
	// config guard reports them; nil when it refuses nothing. They land in
	// the private Metrics block only: they name hosts. ConfigRefusalsTotal is
	// how many are refused in all when the guard capped the list.
	ConfigRefusals      []ConfigRefusal
	ConfigRefusalsTotal int
	// ReleaseRefusals is the builds this box rolled back and is now refusing
	// to re-adopt (D1); nil when there are none. Private Metrics only.
	ReleaseRefusals []ReleaseRefusal
	// ProofWaits is the hosts held on their current build waiting for a dev
	// proof (D3). Private Metrics only: they name hosts.
	ProofWaits []ProofWait
	// Rollout is the rollout scheduler's report (zero-downtime spec §8.4,
	// §9.1); nil with CARLOS_SWAP off. Private Metrics only: it names hosts.
	Rollout *RolloutReport
	// ConfigGuard is "" in the normal mode and a words-only note when the
	// config guard's explicit bypass is in effect on this box (amadan #213).
	ConfigGuard string
	// BuildStates is the build-state builds of the instances this box hosts
	// (settings spec rev 11 §4.4), and BuildStatesErr says the box could not
	// collect them. Private Metrics only: they name hosts.
	BuildStates    map[string]BuildStatePins
	BuildStatesErr string
	// UpdateSettings is the update-settings protocol this box enforces
	// (BoxMetrics.UpdateSettings): UpdateSettingsProtocol, or 0 when the box
	// cannot honour pin, manual and major. Updates is root's last decision per
	// host. Private Metrics only: Updates names hosts and builds.
	UpdateSettings int
	Updates        map[string]HostUpdates
}

// HostUpdates is root's last update decision for one instance, for the
// console's list and instance page (settings spec §4.3). Everything is
// omitempty: a field root has nothing to say about is absent.
type HostUpdates struct {
	// Desired is the build root last chose for the instance, and Reason why
	// it differs from the channel head (a release.TargetReason word). Detail
	// is a build version when root names one (the major hold's head).
	Desired string `json:"desired,omitempty"`
	Reason  string `json:"reason,omitempty"`
	Detail  string `json:"detail,omitempty"`
	// Baking is the head a pending request waits on, reported beside Reason.
	Baking string `json:"baking,omitempty"`
	// Major is the instance's effective major hold, so a list can name one
	// the instance inherits.
	Major *int `json:"major,omitempty"`
	// Pending is the install request not yet completed; Completed is the
	// highest completed request; CompletedFailed says that one failed.
	Pending         uint64 `json:"pending,omitempty"`
	Completed       uint64 `json:"completed,omitempty"`
	CompletedFailed bool   `json:"completed_failed,omitempty"`
	// Account and App are the instance's tenant as the box's route names it
	// (HostRollout.Account and .App's rule), so the console can join the
	// report to a tenant without the rollout report (Astra r1, R18). Absent
	// from a box that predates them: the console then joins only whether the
	// box enforces settings, nothing the report says about the instance.
	Account string `json:"account,omitempty"`
	App     string `json:"app,omitempty"`
}

// RowLayout is one instance-kind route's layout, as the box's layout pass
// classified it (activator.Classify): Layout is one of flat, nested,
// fenced, conflict, foreign or external, and Reason carries the detail for
// anything but flat and nested — a path, or another row's host — which is
// why it is never shown on the console's instance page (see
// instancepage.go's handleAppInstance): a member sees the word, an operator
// reading status/boxes/<label>.json sees the reason too.
type RowLayout struct {
	Layout string `json:"layout"`
	Reason string `json:"reason,omitempty"`
	// Note is the last event the pass recorded for the host that was not
	// a refusal: what a move quarantined out of the instance directory or
	// kept aside, and when. Paths, so private like Reason.
	Note string `json:"note,omitempty"`
}

// LayoutReport is one box's whole layout picture: Mode is the intent the
// box last converged to ("none" before any is recorded, "unreadable" when
// the last read of it failed or named a mode this binary does not know,
// otherwise "flat" or "nested"), and Rows is every instance-kind route on
// the box, keyed by host. It carries real hostnames, so — like RowLayout
// above — it is private: BoxMetrics.Layout, never a field on Box itself.
type LayoutReport struct {
	Mode string               `json:"mode"`
	Rows map[string]RowLayout `json:"rows"`
	// Default is set when Mode is nested by the deployment's default
	// rather than by a recorded intent (design §8.6, "Nested by
	// default"); DefaultBlocked is why the default is not in force on a
	// box whose Mode is none. Both additive; an old reader ignores them.
	Default        bool   `json:"default,omitempty"`
	DefaultBlocked string `json:"default_blocked,omitempty"`
}

// ConfigRefusal is one host this box is refusing to take because it cannot
// provide that instance's config: no CARLOS_SECRETS_KEY, one that does not
// parse, one that does not open the sealed config, or a store read it could
// not complete (a box that cannot tell refuses). Reason is a closed word
// (no_key, key_unparseable, cannot_open, store_error), never error text, so
// nothing from the store or the crypto reaches a snapshot. Since is when the
// host was first refused in this stretch, Last the most recent refusal, and
// Count how many wake or admission attempts were refused.
//
// PRIVATE, like everything under Box.Metrics: the host is a real route name.
// It is declared here, with the other wire types of the snapshot, so the
// readers (console, operators) need not import the host agent to decode it.
type ConfigRefusal struct {
	Host   string    `json:"host"`
	Reason string    `json:"reason"`
	Since  time.Time `json:"since"`
	Last   time.Time `json:"last"`
	Count  int       `json:"count"`
}

// ReleaseRefusal is a build this box rolled back because its unit did not
// come up (D1, release.Refusal). PRIVATE like the rest of Box.Metrics: Host
// is a real route name.
type ReleaseRefusal struct {
	Host      string    `json:"host"`
	Version   string    `json:"version"`
	Reason    string    `json:"reason"`
	RefusedAt time.Time `json:"refused_at"`
	// Kind is release.Refusal's: "" for a unit that did not come up,
	// "wrong-program" for a build refused before it was ever pointed live.
	Kind string `json:"kind,omitempty"`
	// RecoveryError is set when the rollback itself did not come up (the
	// record's Recovered is false): why. "" is a recovered rollback.
	RecoveryError string `json:"recovery_error,omitempty"`
}

// RolloutReport is this box's rollout scheduler state (zero-downtime spec
// §8.4, §9.1), published only with CARLOS_SWAP=overlap. It names hosts, so
// it lives in the private Metrics block alone.
type RolloutReport struct {
	Hosts    map[string]HostRollout `json:"hosts,omitempty"`
	Apps     map[string]AppRollout  `json:"apps,omitempty"` // keyed "<acct>/<app>"
	Failures []RolloutFailure       `json:"failures,omitempty"`
	// Unavailable, when set, is a reason code (not member-facing text) for
	// why CARLOS_SWAP=overlap is on but the scheduler could not arm. Either
	// the box cannot contain generations ("no-cgroup-delegation",
	// "no-generation-control", "generations-off"), has host claims on
	// ("host-claims-on"), or failed its arm-time test placement
	// ("cgroup-placement-failed"), and stays on today's
	// paths, or its required state is unavailable ("no-deploy-store",
	// "no-release-key", "failure-book-unreadable"), and every managed start
	// is refused meanwhile (Task 14, internal/host's swapArming and
	// refuseManaged). The rest of the report is then empty. Plan 6 words it.
	Unavailable string `json:"unavailable,omitempty"`
	// FailureBook is set only beside a decline code (the first five): what a
	// box that cannot contain generations does with the failure records an
	// earlier armed run left (final review F6). "honoured": a managed wake,
	// or a bounce, onto a build they hold for that instance is refused.
	// "failure-book-unreadable": every managed start is refused and the
	// bounce legs stand down. Empty: there are no records, and the box is on
	// today's paths. A code, like Unavailable.
	FailureBook string `json:"failure_book,omitempty"`
}

// HostRollout is one managed instance. Attempt and Reason are the closed
// words below; plan 6 renders them.
type HostRollout struct {
	Account       string `json:"account"`
	App           string `json:"app"`
	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"`
	// ConfigError is a reason word (Reason*), never raw error text.
	ConfigError string `json:"config_error,omitempty"`
	// HeldEpoch is the generation of HeldBy's restriction of this instance
	// as published (rollout.FailureBook.PublishedEpoch): the console signs
	// it into a `carlos instances retry` grant, which the box honours only
	// while the app's restrictions are unchanged. 0 on a held instance means
	// the box's failure book is not saved yet; absent from an older box,
	// which is 0 too.
	HeldEpoch uint64 `json:"held_epoch,omitempty"`
	// HeldBook is the identity of the failure book HeldEpoch counts in
	// (rollout.FailureBook.ID): epochs are a counter every book starts
	// alike, so the console signs both into its grant and the box clears
	// only for its own book (final review round 1, finding 3). Absent from
	// an older box: a grant signed without it clears nothing.
	HeldBook string `json:"held_book,omitempty"`
	// RetryV is the `carlos instances retry` protocol this box takes, set
	// beside HeldBook: HostRetryV is a root-signed, book-bound grant in the
	// host-retry log (release.HostRetryKey). Absent (0) from a box built
	// before that log, which reads no grant there, so the console writes
	// it none and says the box is too old (readiness round 2, Task 3).
	RetryV int `json:"retry_v,omitempty"`
	// Transient is set when the activator owns the host's process but has no
	// current generation for it: the process is starting or stopping, so the
	// instance is neither asleep nor awake and no serving build is reported.
	// The deploy watch keeps such a host pending (Astra R3 section 5 item 10).
	// Absent from an older box, which is false. A reader that ignores the
	// field sees a transient host as Serving "" and Awake false, that is,
	// asleep.
	Transient bool `json:"transient,omitempty"`
}

// AppRollout counts one app's attempts. Settling is canary settles and
// first-wake observations under way.
type AppRollout struct {
	Queued   int `json:"queued"`
	Running  int `json:"running"`
	Settling int `json:"settling"`
}

// RolloutFailure is one failure record (spec §8.4). Reason is a reason word.
type RolloutFailure struct {
	Account    string    `json:"account"`
	App        string    `json:"app"`
	Build      string    `json:"build"`
	Host       string    `json:"host"`
	Mode       string    `json:"mode,omitempty"`
	Reason     string    `json:"reason"`
	PromotedAt time.Time `json:"promoted_at"`
	At         time.Time `json:"at"`
	HeldDown   []string  `json:"held_down,omitempty"`
}

// The attempt words.
const (
	AttemptQueued   = "queued"
	AttemptRunning  = "running"
	AttemptSettling = "settling"
	AttemptFailed   = "failed"
	AttemptDown     = "down"
)

// HostRetryV is HostRollout.RetryV for a box that reads root-signed,
// book-bound retry grants from the host-retry log and honours a legacy
// signed one in the restart-scope log with the same checks.
const HostRetryV = 1

// The reason words: the closed vocabulary a member-facing event or status
// line may give for a failure. internal/rollout maps every diagnostic text
// onto one of them (reasonWord).
const (
	ReasonHealth  = "health"
	ReasonSettle  = "settle"
	ReasonExit    = "exit"
	ReasonStaging = "staging"
	ReasonReused  = "reused"
)

// ProofWait is a host this box is holding on its current build because its
// channel head has no dev proof yet (D3, release.ProofGate), or because the
// box's proof policy file does not load. PRIVATE like the rest of
// Box.Metrics: Host is a real route name. With no Prover the wait is about
// the policy, and Reason is the policy's own load error.
type ProofWait struct {
	Host    string    `json:"host"`
	Version string    `json:"version"`
	SHA256  string    `json:"sha256,omitempty"`
	Prover  string    `json:"prover,omitempty"`
	Reason  string    `json:"reason"`
	Since   time.Time `json:"since"`
}

// UpstreamState is one upstream's health as the edge's prober currently sees
// it: what it believes, when that belief last changed, and why.
//
// It lives HERE, in the writer of the snapshot, rather than in internal/edge
// where the prober that fills it lives, for one reason: this is a WIRE type on
// status/boxes/<label>.json, and its readers are the console
// (internal/console's box-detail views, which already parse BoxMetrics) and
// operators. Declaring it in internal/edge would force every one of those
// readers to import the edge — the whole ACME/DNS/proxy stack — just to name
// the shape of a struct it decodes. internal/edge aliases this type instead
// (type UpstreamState = status.UpstreamState), so the prober keeps writing
// UpstreamState in its own package with no conversion at the boundary, and the
// dependency runs edge -> status, the direction that leaves internal/status a
// leaf over registry/release.
//
// Like everything else under Box.Metrics this is PRIVATE: Addr is a real
// backend address and the map key is a real route host, safe here only because
// BuildFleet never copies Metrics into the public fleet.json (see the package
// doc comment).
type UpstreamState struct {
	Addr      string    `json:"addr"`
	Up        bool      `json:"up"`
	Since     time.Time `json:"since"`                // last transition (or the sync that started this prober)
	Fails     int       `json:"fails"`                // consecutive probe failures
	LastError string    `json:"last_error,omitempty"` // dial vs status, for the log/dashboard
}

// SystemState is the last platform self-update outcome root recorded on the
// box, published so `carlos system status` can show a rolled-back box with
// its reason within one heartbeat.
type SystemState struct {
	Channel    string    `json:"channel"`
	Version    string    `json:"version"`
	PromotedAt time.Time `json:"promoted_at"`
	Outcome    string    `json:"outcome"`
	Reason     string    `json:"reason,omitempty"`
	At         time.Time `json:"at"`
}

// BoxMetrics is the raw, PRIVATE block: real numbers, never banded. It lives
// in status/boxes/<label>.json — which only fleet-status machinery and
// operators read — and is deliberately NOT copied into FleetBox, so the
// publicly served fleet.json keeps the banded-words-only commitment. See the
// package doc comment for why this block is safe to exist at all.
type BoxMetrics struct {
	ConsoleProcesses        []ConsoleProcess `json:"console_processes,omitempty"`
	ActivationID            string           `json:"activation_id,omitempty"`
	ActivationComplete      bool             `json:"activation_complete,omitempty"`
	Enrollment              string           `json:"enrollment,omitempty"`
	MovesProtocol           int              `json:"moves_protocol,omitempty"`
	ReleaseTag              string           `json:"release_tag,omitempty"`
	BinarySHA256            string           `json:"binary_sha256,omitempty"`
	BootID                  string           `json:"boot_id,omitempty"`
	FloorSHA256             string           `json:"floor_sha256,omitempty"`
	FloorGuardReady         bool             `json:"floor_guard_ready,omitempty"`
	HostClaimEnabled        bool             `json:"host_claim_enabled,omitempty"`
	RetirementReceiptSHA256 string           `json:"retirement_receipt_sha256,omitempty"`

	MemTotalBytes *int64       `json:"mem_total_bytes,omitempty"`
	MemAvailBytes *int64       `json:"mem_avail_bytes,omitempty"`
	Load1         *float64     `json:"load1,omitempty"`
	DiskFreeBytes *int64       `json:"disk_free_bytes,omitempty"`
	Release       string       `json:"release,omitempty"`        // running binary's version.Build
	Platform      string       `json:"platform,omitempty"`       // runtime.GOOS-runtime.GOARCH
	SystemChannel string       `json:"system_channel,omitempty"` // CARLOS_SYSTEM_CHANNEL
	System        *SystemState `json:"system,omitempty"`         // last self-update outcome
	// Alerts is where this box's own alert rules (metrics.Evaluate) can send
	// a fire or clear, and how many sends have failed since the agent
	// started. nil means the box did not say (a snapshot from before the
	// field existed), which is not the same as an AlertDelivery whose sinks
	// are both off: that is a box that says it has nowhere to deliver.
	// Private, like the rest of this block: BuildFleet never copies Metrics.
	Alerts *AlertDelivery `json:"alerts,omitempty"`
	// InstanceID is the cloud machine this box IS — read from the instance
	// metadata service by the box itself (status.InstanceID). "" means no
	// cloud machine owns it: a Pi, a laptop, someone else's hardware.
	//
	// It lives here, in the private per-box block, for the reason every
	// hostname-bearing field here does: status/boxes/<label>.json is
	// bucket-private and BuildFleet never copies Metrics into the public
	// feed, so an instance id cannot reach fleet.json.
	//
	// The console's architecture page joins boxes to machines on this and
	// nothing else matters as much: the first version matched an instance's
	// Name tag against the box label, and on the flagship those namespaces
	// are disjoint (carlos-flagship-ie versus annie-welding), so the join
	// found nothing at all and every box read as bring-your-own. A box
	// asking the metadata service which machine it is cannot drift from a
	// naming convention, because it is not using one.
	InstanceID string `json:"instance_id,omitempty"`
	Tunnel     string `json:"tunnel,omitempty"` // ""|"connected"|"reconnecting"
	// GeoIP is present on every box running a GeoIP-aware binary (geoip
	// spec §5.5); its absence is how the rollout verdict tells an older
	// binary, which does not strip forged geo headers.
	GeoIP *GeoIPState `json:"geoip,omitempty"`
	// UpdateSettings is the instance-update-settings protocol this binary
	// implements: it applies pin, manual and major, and its retention
	// protects the builds they name (settings spec §4.4). Absent (0) is a
	// binary that ignores them; the console refuses those settings until
	// every box reports UpdateSettingsProtocol.
	UpdateSettings int `json:"update_settings,omitempty"`
	// BuildStates is, per instance this box hosts that keeps a build state,
	// the builds that build state names: last_executed and a resolved
	// request's target (settings spec rev 11 §4.4). The housekeeper protects
	// them, because it cannot read the regional data buckets the objects
	// live in. Host-keyed and private like RouteVersions; omitted when empty.
	BuildStates map[string]BuildStatePins `json:"build_states,omitempty"`
	// BuildStatesErr is set when this box could not collect BuildStates at
	// all (its registry list failed). The housekeeper prunes nothing while a
	// fresh report says so (Astra I2 #5): an absent map is never "nothing to
	// protect".
	BuildStatesErr string `json:"build_states_err,omitempty"`
	// Updates is, per instance this box hosts that has non-default settings
	// or a decision of root's, root's last decision (settings spec §4.3).
	// Host-keyed and private like RouteVersions: it names hosts and builds,
	// so it lives in this block and never reaches the public feed. Omitted
	// when empty.
	Updates map[string]HostUpdates `json:"updates,omitempty"`
	// RouteVersions is host -> registry.Route.Version for every non-platform
	// route this box carries with a Version the adopt pass has stamped
	// (issue #78's staged_version chip) — a hostname-keyed map, which is
	// exactly why it lives here and nowhere else: BuildFleet copies Box's
	// fields into FleetBox one at a time by name and never names Metrics, so
	// this map can carry real hostnames without the public fleet.json ever
	// seeing one. It is the box's OWN routes only (CollectBox is called
	// per-box), never a fleet-wide join. Omitted entirely when this box has
	// no versioned route, same "absent, not empty" rule as the rest of this
	// block.
	RouteVersions map[string]string `json:"route_versions,omitempty"`
	// RouteServing is host -> the build the agent last started for that
	// route (registry ServingVersion, zero-downtime plan 5), for this box's
	// own non-platform routes that have one. RouteVersions is root's install
	// stamp and can name a build nothing runs yet; this is what runs. Private
	// and omitted when empty, for RouteVersions' reasons.
	RouteServing map[string]string `json:"route_serving,omitempty"`
	// Upstreams is the box's per-upstream probe table, route host -> the
	// UpstreamState of each addr behind it (multi-upstream routes only; a
	// single-addr route with no health config is never probed and never
	// appears). It is RouteVersions' twin in every way that matters here: a
	// hostname-keyed map that belongs in this block and nowhere else, carried
	// straight through from Probes.Upstreams with no banding, and omitted
	// entirely — not present-and-empty — on a box that probes nothing, so
	// every consumer written before this field parses such a box unchanged.
	//
	// Size is bounded by (probed routes × addrs per route) — a handful of
	// entries on the busiest box today, and self-limiting: only routes an
	// operator gave an addr list AND a health block are in it at all.
	Upstreams map[string][]UpstreamState `json:"upstreams,omitempty"`
	// Aliases is issue #151's per-hostname DNS/cert status, keyed by the
	// alias hostname — the box's own route_aliases rows only (CollectBox is
	// called per-box, same scope as RouteVersions above), never a fleet-wide
	// join. It lives here for the identical reason RouteVersions does:
	// status/boxes/<label>.json is bucket-private (this package's own doc
	// comment, and dryrun.go's leak-scan self-check, which guards the PUBLIC
	// feed only — fleet.json, index.html, status.css — and deliberately
	// EXPECTS raw values inside status/boxes/*.json). BuildFleet copies Box's
	// fields into FleetBox one at a time by name and never names Metrics, so
	// these hostnames can never reach the public aggregation. Task 9's
	// console list door is the intended reader. Omitted entirely (not a
	// present-but-empty map) when this box has no alias rows, same
	// "absent, not empty" rule as RouteVersions.
	Aliases map[string]AliasReading `json:"aliases,omitempty"`
	// RouteDBBytes is host -> on-disk size of that route's SQLite database
	// (file plus -wal), for this box's own routes with a DBPath. It is
	// RouteVersions' twin: hostname-keyed, so it lives in this private block
	// and nowhere else. The console's instance and route listings are the
	// readers. A host whose file could not be sized is absent, never 0; the
	// whole map is omitted when no route could be sized.
	RouteDBBytes map[string]int64 `json:"route_db_bytes,omitempty"`
	// Layout is Probes.Layout carried straight through — the box's layout
	// report, hostname-keyed like RouteVersions and RouteDBBytes above, and
	// private for the identical reason: BuildFleet copies Box's fields into
	// FleetBox one at a time by name and never names Metrics, so this can
	// never reach the public fleet.json. nil (the field absent) means the
	// box has no layout pass armed, not "every route reports flat".
	Layout *LayoutReport `json:"layout,omitempty"`
	// ConfigRefusals is the hosts this box is refusing to take because it
	// cannot provide their config (amadan #213). It is how an operator sees
	// that a box is keyless, or holds the wrong key, without reading its
	// journal: a keyed sibling takes these instances, and this list says why
	// this box did not. Hostname-bearing, so it lives in this private block
	// and nowhere else (BuildFleet never names Metrics). Omitted when empty.
	ConfigRefusals []ConfigRefusal `json:"config_refusals,omitempty"`
	// ConfigRefusalsTotal is the count of refused hosts when ConfigRefusals
	// was capped, so a long list reads as long. Omitted when zero.
	ConfigRefusalsTotal int `json:"config_refusals_total,omitempty"`
	// ReleaseRefusals is the builds this box rolled back because their unit
	// did not come up (D1), one per host. Hostname-bearing, so private like
	// ConfigRefusals. Omitted when empty.
	ReleaseRefusals []ReleaseRefusal `json:"release_refusals,omitempty"`
	// ProofWaits is the hosts this box is holding on their current build
	// until a dev proof for the new head arrives (D3). Hostname-bearing, so
	// it lives in this private block only. Omitted when empty.
	ProofWaits []ProofWait `json:"proof_waits,omitempty"`
	// Rollout is the rollout scheduler's report (zero-downtime spec §8.4,
	// §9.1). Hostname-bearing, so it lives in this private block only.
	// Omitted when the scheduler is off.
	Rollout *RolloutReport `json:"rollout,omitempty"`
	// ConfigGuard says the box's admission guard is bypassed, e.g.
	// "bypassed (CARLOS_NO_SEALED_CONFIG)": it admits placed exec instances
	// without checking their sealed config. Omitted in the normal mode, so an
	// operator scanning snapshots sees only the boxes that are exposed. A
	// fixed phrase, never a value from the environment.
	ConfigGuard string `json:"config_guard,omitempty"`
}

// UpdateSettingsProtocol is the BoxMetrics.UpdateSettings a binary reports
// once it applies update settings and protects the builds they name.
const UpdateSettingsProtocol = 1

// BuildStatePins is one instance's build-state builds in a box report.
// Complete is false when this box could not read the instance's build state
// (never read, a failed refresh, an unparseable copy): the housekeeper then
// prunes nothing for the app (Astra I1 #6).
type BuildStatePins struct {
	Account  string   `json:"account"`
	App      string   `json:"app"`
	Builds   []string `json:"builds"`
	Complete bool     `json:"complete"`
}

// AliasReading is one alias hostname's status as CollectBox saw it this
// tick: Route is the route it points at (registry.RouteAlias.Host), DNSStatus
// and CertExpiresAt are the box-stamped health columns (Task 2/5), carried
// through unbanded like the rest of BoxMetrics. Route has no omitempty — an
// alias with no route would be a data bug worth seeing, not a field worth
// hiding; DNSStatus/CertExpiresAt omit when unstamped ("" / 0), same
// unknown-stays-absent convention as every other Metrics field.
type AliasReading struct {
	Route     string `json:"route"`
	DNSStatus string `json:"dns_status,omitempty"`
	// DNSCheckedAt is when this box last RESOLVED the hostname (registry
	// dns_checked_at). Carried because a stamp without its age cannot be
	// judged: a box that has stopped stamping keeps publishing fresh
	// SNAPSHOTS full of frozen readings, and BoxStale — which measures the
	// snapshot, not the stamp — cannot see it. Omitempty: unstamped stays
	// absent, never a zero that reads as 1970.
	DNSCheckedAt  int64 `json:"dns_checked_at,omitempty"`
	CertExpiresAt int64 `json:"cert_expires_at,omitempty"`
}

// AlertDelivery is the box's own answer to "if a rule fires, does anyone
// hear it": which sinks the agent has, and how many sends to them have
// failed. It exists because an unset CARLOS_ALERT_WEBHOOK used to be
// silent, and the flagship's disk, memory and cpu alerts went nowhere for
// weeks (discussion #192). Webhook is CARLOS_ALERT_WEBHOOK set. SNS is
// CARLOS_ALERT_SNS_TOPIC_ARN set to a topic ARN the agent can use; a
// malformed value reads false, because it is not a sink. SNS is the state
// of the sink the agent actually built, not of the env: when a topic ARN is
// set but the agent could not build its SNS client (no region, a missing
// profile), SNS is false and SNSUnavailable is true, so the box never reads
// as having a sink it cannot use. Failures count sends (and that failed
// build) since the agent process started, so a role without sns:Publish
// shows up here and not only in the journal.
type AlertDelivery struct {
	Webhook         bool  `json:"webhook"`
	SNS             bool  `json:"sns"`
	SNSUnavailable  bool  `json:"sns_unavailable,omitempty"`
	WebhookFailures int64 `json:"webhook_failures,omitempty"`
	SNSFailures     int64 `json:"sns_failures,omitempty"`
}

// Delivered is whether at least one sink is configured.
func (a AlertDelivery) Delivered() bool { return a.Webhook || a.SNS }

// RouteCounts is aggregate-only: no host, no socket path, just how many.
// Awake/Asleep stay null together whenever the socket table can't be read in
// full — partial knowledge published as a count would read as more certain
// than it is.
type RouteCounts struct {
	Static      int  `json:"static"`
	Resident    int  `json:"resident"`
	Hibernating int  `json:"hibernating"`
	Awake       *int `json:"awake"`  // null when the socket table is unreadable
	Asleep      *int `json:"asleep"` // null when the socket table is unreadable
}

// Replication summarizes litestream's furthest-behind lag across this box's
// routes, banded to a healthy bool rather than the raw seconds — the raw
// number is still carried for the console's private view, but the public
// commitment is only ever "healthy" or "not".
type Replication struct {
	Healthy *bool  `json:"healthy"`
	LagSecs *int64 `json:"lag_seconds"`
}

// Box is one box's self-report: what CollectBox produces and WriteBox
// serializes. Every field here has already had its needles pulled — there is
// no hostname, machine id, or raw ratio anywhere in this type — with two
// deliberate exceptions: Metrics, the raw/private block documented on the
// package comment and on BoxMetrics itself, and Sidecars, an aggregate count
// that is private for a different reason (a sidecar's existence is
// account-visible, not public, not because the number itself is sensitive).
// Every OTHER field on Box is still bound by the no-raw-numbers rule and IS
// meant for the public page; Metrics and Sidecars are the two places that
// default is intentionally suspended, gated by staying bucket-private (see
// the package doc) and excluded from FleetBox by construction (fleet.go's
// BuildFleet copies fields one at a time and never names either).
type Box struct {
	GeneratedAt time.Time   `json:"generated_at"`
	Label       string      `json:"label"`
	Region      string      `json:"region,omitempty"`
	Routes      RouteCounts `json:"routes"`
	Load        *string     `json:"load"`     // comfortable|busy|critical
	Capacity    *string     `json:"capacity"` // plenty|getting-full|at-capacity
	Replication Replication `json:"replication"`
	// AdoptionRunning is whether this box is actually picking up releases:
	// true = the adoption timer is armed and will fire, false = it is not and
	// nothing on this box will ever adopt on its own, null = unknown. It is a
	// bare bool rather than a band word because there is no spectrum here and
	// nothing private in the answer — a box either runs the platform's own
	// adoption pass or it doesn't, which says nothing about any tenant. The
	// flagship spent weeks in the false state with no way to see it; this
	// field is the way to see it.
	AdoptionRunning *bool `json:"adoption_running"`
	// ConfigPathRunning is whether config reaches this box's UNIT-BACKED
	// routes in seconds (carlos-adopt.path armed) or only on the hourly
	// carlos-adopt.timer floor: true = armed, false = the trigger is
	// installed but not watching, null = unknown. Published for the same
	// reason as AdoptionRunning above and with the same content — the
	// liveness of one of the platform's OWN units on an opaquely-labelled
	// box, which says nothing about any tenant. Snapshots written before
	// issue #44 carry no such key at all and decode to null, which is the
	// honest reading of a box that never reported it.
	ConfigPathRunning *bool `json:"config_path_running"`
	// RestartPathRunning is whether a member's `carlos restart` reaches this
	// box's units in seconds (carlos-restart.path armed) or only on the hourly
	// floor: true = armed, false = installed but not watching, null = unknown.
	// Same content and same privacy argument as ConfigPathRunning above — the
	// liveness of one of the platform's own units on an opaquely-labelled box.
	// Snapshots written before issue #113 carry no such key and decode to null,
	// which is the honest reading of a box that never reported it.
	RestartPathRunning *bool `json:"restart_path_running"`
	// ExpiredCanaries publishes Probes.ExpiredCanaries straight through — a
	// count, never hostnames (pipelines spec §5): which canary route expired
	// is exactly the kind of identifying detail this package's whole design
	// refuses to carry, but how many is aggregate and safe.
	ExpiredCanaries *int `json:"expired_canaries"`
	// Metrics is the raw/private exception documented above and on
	// BoxMetrics — omitted entirely (not a present-but-empty object) when
	// CollectBox has nothing to report, so an old parser reading a box this
	// package wrote before Metrics existed, and a box that genuinely can't
	// answer any of the six fields, produce the identical absent-key shape.
	Metrics *BoxMetrics `json:"metrics,omitempty"`
	// Sidecars is how many of this box's routes are standalone workers
	// (registry.Route.IsSidecar) — counted by CollectBox in their own
	// branch, never as Resident, Static or Hibernating (its Hibernate comes
	// from the app manifest, so a sidecar may legitimately be either, and
	// either way it does not belong in the public instance count). Present
	// in the private per-box snapshot (bucket-private, read only by
	// fleet-status machinery and credentialed operators) but — like
	// Metrics — deliberately NEVER copied into FleetBox: a sidecar's
	// existence is account-visible, not public, so even the aggregate count
	// must not reach fleet.json. omitempty keeps a box with no sidecars
	// byte-identical to one written before this field existed.
	Sidecars int `json:"sidecars,omitempty"`
}

// replHealthyWithin is the lag under which replication counts as healthy.
// 15 minutes: litestream's own replicate interval is seconds, so anything
// beyond a quarter hour behind means the replica loop has actually stalled
// (network partition, disk full, credential rot) rather than just being
// mid-batch — a threshold loose enough not to flap on ordinary jitter, tight
// enough to catch a real outage inside one on-call check-in.
const replHealthyWithin = 15 * time.Minute

// loadWords and capacityWords band a fraction into a public word — never a
// number, per the fleet status page's public commitments (see the plan's
// privacy rules). The three words are ordered low, medium, high.
var loadWords = [3]string{"comfortable", "busy", "critical"}
var capacityWords = [3]string{"plenty", "getting-full", "at-capacity"}

// bandBoundaryLow and bandBoundaryHigh are the two cut points shared by every
// banded fraction: below the low boundary is the first word, at-or-below the
// high boundary is the second, above it the third. Named constants so the
// 0.70/0.90 split — a decision the operator made once — isn't a magic number
// re-typed at each call site.
const (
	bandBoundaryLow  = 0.70
	bandBoundaryHigh = 0.90
)

// bandWord turns a possibly-unknown fraction into one of three words. nil in
// (unknown) means nil out — CollectBox must never invent a band for a
// quantity it never measured.
func bandWord(f *float64, words [3]string) *string {
	if f == nil {
		return nil
	}
	var w string
	switch {
	case *f < bandBoundaryLow:
		w = words[0]
	case *f <= bandBoundaryHigh:
		w = words[1]
	default:
		w = words[2]
	}
	return &w
}

// labelNames and labelActions are the two word lists Label indexes into —
// Eleven's "ada-stargazing" shape: a first name and a gerund action, picked
// to read as pleasant and give away nothing about the machine they name.
// Deliberately small const slices (not generated, not fetched) so the label
// space and its stability are auditable at a glance.
var labelNames = [40]string{
	"ada", "grace", "alan", "linus", "margaret", "dennis", "barbara", "ken",
	"radia", "vint", "tim", "hedy", "kathleen", "edsger", "donald", "john",
	"claude", "marvin", "shafi", "leslie", "whitfield", "adi", "ron", "sophie",
	"joan", "frances", "betty", "jean", "mary", "annie", "katherine", "dorothy",
	"nadia", "elena", "priya", "yuki", "noor", "amara", "leo", "iris",
}
var labelActions = [40]string{
	"stargazing", "birdwatching", "gardening", "sketching", "kayaking",
	"orienteering", "foraging", "woodworking", "beekeeping", "cycling",
	"origami", "brewing", "quilting", "hiking", "juggling", "puzzling",
	"weaving", "sailing", "climbing", "cartography", "fermenting", "welding",
	"knitting", "pottery", "birding", "spelunking", "kitesurfing", "canoeing",
	"tinkering", "letterpress", "printmaking", "bookbinding", "beachcombing",
	"fossicking", "aquascaping", "papermaking", "clockmaking", "lockpicking",
	"stenciling", "marquetry",
}

// Label derives a stable, opaque "name-gerund" label from a machine id — the
// same shape as Eleven's ada-stargazing box names. sha256 rather than a
// weaker hash: the machine id must never be recoverable from the label by
// brute force over any plausible id space (hostnames, instance ids), and the
// label is public.
//
// Each index is drawn from a 4-byte (32-bit) chunk of the digest rather than
// a single byte: 256 % 40 == 16, so indexing with one raw byte would leave
// names 0-15 roughly 1.4x likelier than names 16-39. A uint32 % 40 has a bias
// under 1 in 100 million — small enough to treat the label as uniform.
func Label(machineID string) string {
	sum := sha256.Sum256([]byte(machineID))
	nameIdx := binary.BigEndian.Uint32(sum[0:4]) % uint32(len(labelNames))
	actionIdx := binary.BigEndian.Uint32(sum[4:8]) % uint32(len(labelActions))
	return labelNames[nameIdx] + "-" + labelActions[actionIdx]
}

// CollectBox turns a box's live registry rows and probe results into the
// public Box for that box. It is the ONLY place fractions get banded to
// words, sockets get counted instead of named, and the machine id gets
// hashed instead of shipped — every value this function returns is already
// safe to publish as-is.
func CollectBox(routes []registry.Route, p Probes, now time.Time) Box {
	var counts RouteCounts
	var awakeKnown = true
	awake, asleep := 0, 0
	// sidecars counts standalone workers (registry.Route.IsSidecar) apart
	// from RouteCounts entirely — see Box.Sidecars' doc for why it is never
	// public.
	var sidecars int
	// routeVersions is issue #78's staged_version chip: host -> Version for
	// this box's own non-platform routes that have one stamped. Built
	// alongside the counts above rather than in a second pass over routes,
	// and nil (not an empty map) until the first entry, so an all-unversioned
	// box's Metrics attachment check below sees exactly "nothing to report"
	// rather than a present-but-empty map.
	var routeVersions map[string]string
	// routeServing is plan 5's ServingVersion: host -> the build the agent
	// last started, for this box's own non-platform routes that have one.
	// Same nil-until-first-entry convention as routeVersions.
	var routeServing map[string]string
	// aliasReadings is issue #151's Metrics.Aliases source. Declared here,
	// above the route loop, so the route loop below (a first-route claim's
	// ROUTE readings) and the p.Aliases loop after it (genuine alias rows)
	// both fold into the same map — nil (not an empty map) until the first
	// entry, same "nothing to report" convention as routeVersions.
	var aliasReadings map[string]AliasReading
	// routeDBBytes is Metrics.RouteDBBytes, built in the same loop and nil
	// until the first entry, like routeVersions.
	var routeDBBytes map[string]int64

	for _, r := range routes {
		// Platform-minted routes (internal/domains) are additional NAMES for
		// routes already counted below, not additional instances — counting
		// both would roughly double every fleet-wide number the moment a
		// deployment sets PLATFORM_APPS_DOMAIN, publishing a fleet larger
		// than the one that exists. Same reasoning as the opt-in and
		// null-propagation rules: the aggregate never overstates. It is also
		// why routeVersions skips them here: a platform alias's Version is
		// the same route's, under a second name, not a second instance's.
		if r.Platform {
			continue
		}
		if r.Version != "" {
			if routeVersions == nil {
				routeVersions = map[string]string{}
			}
			routeVersions[r.Host] = r.Version
		}
		if r.ServingVersion != "" {
			if routeServing == nil {
				routeServing = map[string]string{}
			}
			routeServing[r.Host] = r.ServingVersion
		}
		if r.Kind != "static" && r.DBPath != "" && p.DBBytes != nil {
			if n := p.DBBytes(r.DBPath); n != nil {
				if routeDBBytes == nil {
					routeDBBytes = map[string]int64{}
				}
				routeDBBytes[r.Host] = *n
			}
		}
		// Non-platform routes carry hostname readings too. A first-route
		// claim (claims.go: "an empty route means this host is its own
		// primary") materializes a ROUTE, not an alias row, so without this
		// the domains surface can never take it past "pending" — which is
		// exactly what a static app deployed to its own custom domain has
		// always shown. Route is the host itself, which is what the claim's
		// empty Route field means.
		if r.DNSStatus != "" || r.CertExpiresAt != 0 {
			if aliasReadings == nil {
				aliasReadings = map[string]AliasReading{}
			}
			aliasReadings[r.Host] = AliasReading{
				Route: r.Host, DNSStatus: r.DNSStatus,
				DNSCheckedAt: r.DNSCheckedAt, CertExpiresAt: r.CertExpiresAt,
			}
		}
		switch {
		case r.IsSidecar():
			// Checked first, ahead of Hibernate: a sidecar's Hibernate comes
			// from the app manifest and may legitimately be true, but
			// either way it is not the public Hibernating count — its own
			// Socket is empty by construction (no upstream to dial), so the
			// awake/asleep probe below would be meaningless for it too.
			sidecars++
		case r.Kind == "static":
			counts.Static++
		case r.Hibernate:
			counts.Hibernating++
			if p.Listening == nil {
				awakeKnown = false
				continue
			}
			isListening := p.Listening(r.Socket)
			if isListening == nil {
				awakeKnown = false
				continue
			}
			if *isListening {
				awake++
			} else {
				asleep++
			}
		default:
			counts.Resident++
		}
	}
	// p.Aliases (genuine route_aliases rows) runs AFTER the route loop above,
	// so a real alias wins its own key over the route-loop's fallback entry
	// for the same host.
	for _, a := range p.Aliases {
		if aliasReadings == nil {
			aliasReadings = map[string]AliasReading{}
		}
		aliasReadings[a.Alias] = AliasReading{
			Route: a.Host, DNSStatus: a.DNSStatus,
			DNSCheckedAt: a.DNSCheckedAt, CertExpiresAt: a.CertExpiresAt,
		}
	}

	if awakeKnown && p.Listening != nil {
		counts.Awake, counts.Asleep = &awake, &asleep
	}

	// Capacity is the worst-of DiskFrac/MemFrac — whichever known fraction is
	// closer to full drives the word, because a box that's fine on memory but
	// out of disk is still a box about to have a bad day.
	var worst *float64
	switch {
	case p.DiskFrac != nil && p.MemFrac != nil:
		if *p.DiskFrac >= *p.MemFrac {
			worst = p.DiskFrac
		} else {
			worst = p.MemFrac
		}
	case p.DiskFrac != nil:
		worst = p.DiskFrac
	case p.MemFrac != nil:
		worst = p.MemFrac
	}

	var healthy *bool
	if p.LagSecs != nil {
		h := *p.LagSecs < int64(replHealthyWithin.Seconds())
		healthy = &h
	}

	box := Box{
		GeneratedAt:        now,
		Label:              Label(p.MachineID),
		Region:             p.Region,
		Routes:             counts,
		Load:               bandWord(p.MemFrac, loadWords),
		Capacity:           bandWord(worst, capacityWords),
		Replication:        Replication{Healthy: healthy, LagSecs: p.LagSecs},
		AdoptionRunning:    p.AdoptRunning,
		ConfigPathRunning:  p.ConfigPathRunning,
		RestartPathRunning: p.RestartPathRunning,
		ExpiredCanaries:    p.ExpiredCanaries,
		Sidecars:           sidecars,
	}

	// Metrics attaches only when something is known — an all-unknown Probes,
	// no versioned route, no alias reading AND nothing probed publishes no
	// block at all, the same "unknown stays absent, never a guess" rule every
	// other field on Box follows, and it keeps a box that can't answer any of
	// the eight fields indistinguishable on the wire from a box running code
	// that predates Metrics entirely. An EMPTY (non-nil) probe or alias table
	// counts as nothing known for exactly the same reason an empty
	// routeVersions map does: a box with no multi-upstream route (or no
	// alias) has nothing to say, not something empty to say.
	if p.MemTotalBytes != nil || p.MemAvailBytes != nil || p.Load1 != nil ||
		p.DiskFreeBytes != nil || p.Release != "" || p.Tunnel != "" ||
		p.InstanceID != "" || p.Platform != "" || p.SystemChannel != "" || p.System != nil ||
		len(routeVersions) > 0 || len(routeServing) > 0 || len(aliasReadings) > 0 || len(p.Upstreams) > 0 ||
		len(routeDBBytes) > 0 || p.Layout != nil || len(p.ConfigRefusals) > 0 || len(p.ReleaseRefusals) > 0 || len(p.ProofWaits) > 0 || p.Rollout != nil || p.ConfigGuard != "" ||
		p.Alerts != nil || p.GeoIP != nil || len(p.BuildStates) > 0 || p.BuildStatesErr != "" ||
		p.UpdateSettings != 0 || len(p.Updates) > 0 {
		box.Metrics = &BoxMetrics{
			ConsoleProcesses: p.ConsoleProcesses,
			ActivationID:     p.ActivationID, ActivationComplete: p.ActivationComplete,
			Enrollment:              p.Enrollment,
			MovesProtocol:           p.MovesProtocol,
			ReleaseTag:              p.ReleaseTag,
			BinarySHA256:            p.BinarySHA256,
			BootID:                  p.BootID,
			FloorSHA256:             p.FloorSHA256,
			FloorGuardReady:         p.FloorGuardReady,
			HostClaimEnabled:        p.HostClaimEnabled,
			RetirementReceiptSHA256: p.RetirementReceiptSHA256,

			MemTotalBytes: p.MemTotalBytes, MemAvailBytes: p.MemAvailBytes,
			Load1: p.Load1, DiskFreeBytes: p.DiskFreeBytes,
			Release: p.Release, Tunnel: p.Tunnel, GeoIP: p.GeoIP,
			Platform: p.Platform, SystemChannel: p.SystemChannel, System: p.System,
			InstanceID:    p.InstanceID,
			Alerts:        p.Alerts,
			RouteVersions: routeVersions,
			RouteServing:  routeServing,
			Aliases:       aliasReadings,
			// Carried through as the prober handed it over: proberSet.State
			// already returns a fresh copy per call, so there is nothing here
			// for a later probe tick to mutate under the marshaller. An empty
			// map (rather than nil) reaching this line can only happen
			// alongside another known field above, and omitempty drops it.
			Upstreams:    p.Upstreams,
			RouteDBBytes: routeDBBytes,
			Layout:       p.Layout,
			// A fresh copy: the guard's own slice is its to mutate.
			ConfigRefusals:      append([]ConfigRefusal(nil), p.ConfigRefusals...),
			ConfigRefusalsTotal: p.ConfigRefusalsTotal,
			ReleaseRefusals:     append([]ReleaseRefusal(nil), p.ReleaseRefusals...),
			ProofWaits:          append([]ProofWait(nil), p.ProofWaits...),
			Rollout:             p.Rollout,
			ConfigGuard:         p.ConfigGuard,
			// The caller builds a fresh map every tick.
			BuildStates:    p.BuildStates,
			BuildStatesErr: p.BuildStatesErr,
			UpdateSettings: p.UpdateSettings,
			Updates:        p.Updates,
		}
	}

	return box
}

// WriteBox marshals a Box indented (human-diffable in the bucket) and writes
// it to its label-derived key, last-writer-wins. Each box republishes its own
// snapshot every 5 minutes to the SAME key, so a bare create-only Put (ifMatch
// "") would fail every tick after the first with ErrCASConflict — that's the
// bug this retry loop exists to avoid. The read-etag-then-Put dance is the
// only way to express "replace whatever is there, or create it" on top of
// release.Store's CAS-only Put: Get the current etag (a not-found just means
// "absent", so ifMatch stays "" for a create), Put with that etag, and if the
// Put itself loses the race (something else wrote in between), re-read once
// and retry with the fresh etag. A second conflict is NOT retried again and
// is returned to the caller: this box is the only writer that should ever be
// targeting its own label's key, so two conflicts in a row means something
// else collided on this label (clock-skewed duplicate machine id, a bug
// elsewhere) — that deserves a loud failure, not a silent third attempt.
func WriteBox(ctx context.Context, s release.Store, b Box) error {
	body, err := json.MarshalIndent(b, "", "  ")
	if err != nil {
		return err
	}
	key := "status/boxes/" + b.Label + ".json"

	etag, err := currentEtag(ctx, s, key)
	if err != nil {
		return err
	}
	if _, err := s.Put(ctx, key, body, etag); err != nil {
		if !errors.Is(err, release.ErrCASConflict) {
			return err
		}
		etag, err = currentEtag(ctx, s, key)
		if err != nil {
			return err
		}
		if _, err := s.Put(ctx, key, body, etag); err != nil {
			return err
		}
	}
	return nil
}

// currentEtag reads a key's etag for a replace-only Put, folding "doesn't
// exist yet" into "" (create-only) — the same absent-means-empty-ifMatch
// convention release.Store's own CAS contract uses.
func currentEtag(ctx context.Context, s release.Store, key string) (string, error) {
	_, etag, err := s.Get(ctx, key)
	if err != nil {
		if errors.Is(err, os.ErrNotExist) {
			return "", nil
		}
		return "", err
	}
	return etag, nil
}

// GeoIPState is one box's GeoIP mirror (geoip spec §5.5).
type GeoIPState struct {
	Mode   string `json:"mode"` // mirror | tunnel | none
	SHA256 string `json:"sha256,omitempty"`
	Type   string `json:"type,omitempty"`
	Error  string `json:"error,omitempty"`
}