manifest

type App struct {
	// Name identifies the app in logs, names its socket, and is the stem of
	// both its env overrides and its sibling binary.
	Name string

	// Prefixes are the absolute paths it answers. zip mounts each path AND its
	// subtree, and the router takes the first match — so a shallower prefix
	// registered earlier wins, exactly as it does when everything is linked into
	// one binary.
	Prefixes []string

	// Coresident means the app is NOT prefix-routed: it mounts as middleware on
	// another app's router and decides per request whether to serve or call Next.
	// The light host must not Load it, because Load's whole job is to claim a
	// prefix and hand matching requests to a process — a contract a middleware
	// cannot express, since a proxied request never falls through to the next
	// candidate.
	//
	// The row still exists, because every plugin/<name> binary needs one (the
	// gen-app-cmds bijection). What it must not do is state a Prefix it does not
	// route: zen said "/v1", the same prefix ai serves, so the manifest carried a
	// duplicate claim that only worked because nothing checked. zip now refuses
	// two owners for one prefix at compose time, which is how this surfaced.
	// Naming the property is the fix; tolerating the duplicate would have been a
	// second way to say one thing.
	Coresident bool

	// Eager starts the child WITH the host instead of on the first request
	// reaching one of its prefixes. It is for a subsystem whose work is not
	// request-driven — one that owns a listener or a background loop, where
	// deferring the start means it silently does nothing and the symptom is an
	// empty dashboard rather than an error.
	Eager bool

	// Required means the HOST must not serve without this app. A required app
	// that will not start aborts the process; every other app degrades to being
	// absent — its prefixes answer 503 and the rest of the fleet serves.
	//
	// It is deliberately a property of the app rather than of start order,
	// because start order is where it lived by accident and that cost a 25-minute
	// outage of the whole API: pubsub is Apps[0] and Eager, so when its child
	// could not open a store, the single `return err` in the host's mount loop
	// took down the API, IAM validation, billing and the team backend with it.
	// Being first in a list is not a claim on everyone else's availability.
	//
	// The default is false, and NOTHING in Apps sets it — see
	// manifest/required_test.go for the argument and for what would justify an
	// entry. The host is a router: it opens no store, validates no token, and
	// holds no state whose absence corrupts anything. Every child enforces its
	// own auth in its own process, so one child's absence cannot silently weaken
	// another's plane — the planes ARE processes. Against that, aborting buys
	// exactly one thing (a pod that never goes Ready) and destroys the console,
	// the health surface, the log stream an operator needs, and every healthy
	// sibling. CrashLoopBackOff is the state in which a process cannot tell you
	// why it is unhappy.
	Required bool

	// Vital means the host is not fit to RECEIVE TRAFFIC without this app: its
	// absence is reported on /readyz as a 503, so Kubernetes takes the pod out of
	// the Service and a rollout that breaks it stalls against the old pods instead
	// of replacing them.
	//
	// It is the other half of Required, and the two are deliberately separate
	// because they answer different questions. Required asks "may this process
	// run at all", and the answer is argued above: aborting destroys the console,
	// the health surface, the log stream and every healthy sibling, so nothing
	// sets it. Vital asks "should this process be sent requests", and the pod that
	// answers no is still up, still serving its siblings, and still able to say
	// why. Required's own doc names "a pod that never goes Ready" as the one thing
	// aborting buys; Vital buys exactly that and nothing else.
	//
	// The bar is NOT "serving without it is unsafe" — that is Required's bar. It
	// is "serving without it is pointless": traffic that arrives will not be
	// answered, so routing it here helps nobody. That is a strictly narrower claim
	// and it is why `ai` qualifies where the credz broker does not.
	//
	// Written against 2026-08-01, ~30 minutes of api.hanzo.ai/v1/models and
	// /v1/chat/completions answering 503 {"error":"mount /v1: no instance
	// running"} while the pod stayed Ready with 0 restarts. o11y v1.5.41 seized
	// :4317-:4319 from the `ai` child, the child's listen failed, and mount()
	// correctly degraded it to absent — but absence went into a map that only
	// /healthz reported, in a FIELD, and the probe reads the STATUS CODE. Every
	// specifically-mounted prefix (/v1/sentry, /v1/o11y, /v1/commerce/tenant,
	// /v1/admin/*) kept answering from its own subsystem, so only a path falling
	// THROUGH to `ai` showed it. A health check that returns 200 while the entire
	// product API is absent is not a health check.
	Vital bool
}