Struct RequiredSpec 

pub struct RequiredSpec {
    pub regions: Vec<String>,
    pub zones: Vec<String>,
    pub providers: Vec<String>,
    pub mesh_tags: Vec<String>,
    pub nodes: Vec<String>,
    pub memory_mb: u32,
    pub cpu_millis: u32,
    pub tolerates: Vec<String>,
    pub requires_taint: Option<String>,
    pub replicas: Option<u32>,
}

F16 placement constraints declared on a MirrorProviderSlot, lives under [providers.<role>] required = { regions = [...], mesh_tags = [...] } in mirrors/<env>.toml.

Hard (must-satisfy) axes, all AND-ed together:

• regions / zones / providers — membership: the machine’s region / zone / provider must be one of the listed values.
• mesh_tags — superset: the machine’s mesh_tags must contain every listed tag.
• memory_mb / cpu_millis — capacity floor (R572-F5): the machine’s allocatable budget must cover the demand. 0 = no constraint.
• taint repulsion — unconditional (R876-B7): the machine must not carry any taint that taint_effect classifies as TaintEffect::Repels, unless that exact key is listed in Self::tolerates. This axis is not declared; it applies to every spec.
• requires_taint — taint affinity (R572-F5): the machine must carry this taint key (in taints or mesh_tags). None = no affinity.

These are the only readers of MachineConfig::taints, which is what makes taint_effect’s closed vocabulary well-founded.

MachineConfig::sovereign_group is deliberately not an axis here and must not become one (W305/R742-F1). A sovereign group is a blast radius, not a filter: which quorum a box votes in says nothing about whether a workload may run on it, and a dev-group node exists precisely so dev-mode services — stateful ones included — can be scheduled onto it. Filtering on it would re-make the mistake W305 exists to undo, where one mechanism silently carried three unrelated properties.

An empty / zero / None on every axis means “no constraint on that axis”. A fully-unconstrained RequiredSpec matches every machine (see RequiredSpec::is_unconstrained).

Fields

regions: Vec<String>

zones: Vec<String>

providers: Vec<String>

mesh_tags: Vec<String>

nodes: Vec<String>

R833-F8: imperative placement — the machine must be one of these by name. Empty (the default) = no constraint, which is every pre-R833-F8 caller.

This is the one axis that is not a capability the scheduler infers. The operator typed --where=node:us-west-003, so it composes with the other axes exactly like the rest — a named node that fails the capacity floor or carries a repelling taint still does not match, and the refusal names why rather than silently placing the work somewhere else.

memory_mb: u32

R572-F5: minimum memory (MiB) the target node must have in its declared allocatable budget. 0 = no constraint. Filled by CloudConfig::admit_workload from the workload’s memory_request_mb() — its placement request, which is not the same number as the resources.memory_mb cgroup ceiling.

cpu_millis: u32

R572-F5: minimum CPU (millicores) the target node must have in its declared allocatable budget. 0 = no constraint. Filled by CloudConfig::admit_workload from the workload’s resources.cpu_millis.

tolerates: Vec<String>

R876-B7: repelling node taints this placement opts back in to. Each entry is a machine taint key spelled exactly as it appears in MachineConfig::taints — "no-appliance", not "appliance" — so the node side and the workload side share one vocabulary and nothing has to translate between them.

Why this replaced repel_archetypes

Repulsion used to be opt-in-to-be-repelled: the spec named the archetypes it was, and only a no-<that archetype> taint blocked it. That field was #[serde(skip)], so a slot declared as required = { ... } in a mirror TOML always deserialized with it empty and Self::matches never read MachineConfig::taints at all. Node taints were therefore structurally inert for every mirror-declared placement, and inert silently — no-server is a legal key, so yah cloud validate passed and an operator draining a node before maintenance got a green run and a workload that never moved (R876-S2’s drill measured exactly this against the real tree).

The sense is now inverted, which is the only shape that can survive a field the wire does not carry: repulsion is unconditional and toleration is declared. A spec that says nothing is repelled by every repelling taint — the reading an operator writing taints = ["no-server"] on a machine already assumed they were getting.

Toleration is per-key and absolute; there is no wildcard. Listing a key no machine declares is harmless and matches nothing.

[admission_spec] fills this from the placement group’s archetypes — every repelling key that is not the group’s own class — which is what makes the admit_workload path behave identically across this change (R860-T4 / W338 §Placement consequences 2 still hold: the group’s archetypes are the union over local requirement edges, so a Server bound to an Appliance tolerates neither no-server nor no-appliance).

requires_taint: Option<String>

R572-F5: taint the workload requires the target node to carry (annotation yah.placement.requires-taint). The node must have the key in its taints list or mesh_tags. None = no affinity constraint.

replicas: Option<u32>

R844-F8: how many machines this constraint places onto. None — the only shape on disk before this field — means one, so every mirror in the tree resolves byte-identically across the change.

This is not a match axis: it never appears in Self::matches and never changes whether a given machine qualifies. It is the cardinality of the answer, which is why it lives here rather than as another filter — the operator declares what is required and how many of it, and the scheduler picks which.

Declared, never inferred. The count is emphatically not “how many machines happen to match”: deriving it that way would make adding a box to the fleet silently scale a production front door. A constraint that matches four machines and asks for two places on two.

Fewer matches than asked is an error ([select_matching]), not a partial placement. Placing one of two and reporting success is the subset-that-looks-like-it-worked failure R844 exists to close.

Deliberately absent from Self::is_unconstrained, which answers “does every machine match” — a question about the predicate, not the count. A required = { replicas = 2 } with no axis is therefore still unconstrained, and the deploy side still refuses it as an underspecified placement.

Implementations

impl RequiredSpec

pub fn replica_count(&self) -> usize

How many machines this constraint places onto — Self::replicas, resolving the absent case to the pre-R844-F8 answer of one.

The single place that default is spelled, so the ingress planner and the deploy resolver cannot disagree about what “no replica count” means.

pub fn is_unconstrained(&self) -> bool

True when no declared axis carries a constraint — every untainted machine matches.

R876-B7: taint repulsion is deliberately absent from this conjunction, unlike the repel_archetypes it replaced. Repulsion is no longer an axis a spec declares — it applies to every spec — so including it would make the answer a property of the fleet rather than of the constraint. Nor does Self::tolerates belong here: a toleration widens the candidate set, and the callers of this predicate ask “did the operator narrow anything” in order to refuse an underspecified placement. A slot that declares only a toleration has still narrowed nothing.

pub fn matches(&self, machine: &MachineConfig) -> bool

Whether machine satisfies every hard axis.

• Membership axes (region/zone/provider): machine must carry the field and it must appear in the constraint list.
• mesh_tags: machine tags must be a superset of the required set.
• R572-F5 capacity floor: machine.allocatable.{memory,cpu} must cover self.{memory,cpu}. A machine with no allocatable block passes unconditionally (capacity unknown → no constraint enforced).
• Taint repulsion (R876-B7): machine must not carry any taint that taint_effect classifies as TaintEffect::Repels, unless that key is listed in Self::tolerates. Applied unconditionally — this is the axis no spec has to declare, and the one that makes a node drainable.
• R572-F5 taint affinity: if requires_taint is set, the machine must carry that key in its taints list or mesh_tags.

A TaintEffect::Attracts key (today just public-ip) does not repel: it is the affinity vocabulary, so reading it as repulsion would evict every workload from the three nodes that carry it. Only the no-<archetype> class repels, and taint_effect is the single authority on which is which — which is why crate::validate::check_inert_taints refuses to let an unclassifiable key be declared: it would read as a constraint and be none.

pub fn describe(&self) -> String

Human-readable summary of the constraints, for fail-loud error messages. Example: required.regions=[us-west] + required.mesh_tags=[tag:cloud-runner].

Trait Implementations

impl Clone for RequiredSpec

fn clone(&self) -> RequiredSpec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RequiredSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RequiredSpec

fn default() -> RequiredSpec

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for RequiredSpec

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for RequiredSpec

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.