Resource Broker Metadata

1. Owned problem

A broker cannot place work defensibly from a resource name, provider label, or green health flag. The real question is whether one resource is eligible and allocatable for this workload, this quantity, this tenant, and this decision time. ARC-003 owns the metadata and rejection evidence for that decision; Versioned Shared Interfaces and Quota/Reservation remain separate outcomes.

2. Deliverable

Build Resource Broker Capability & Allocation Metadata Sheet v1. Keep demand separate from supply and record Resource ID/Type/Provider, Total and Allocatable capacity, Request Quantity and Unit, Capabilities, Locality, Tenant Scope, Reservation, Health, Availability, Cost Basis, Candidate State, Rejection Reason, Observed At, and Provenance.

3. Mental model: demand → gates → rank

Normalize workload demand first. Pass each resource through hard eligibility gates. Only ELIGIBLE candidates enter ranking. The flow is normalized demand → resource metadata → hard eligibility filters → eligible set → ranking → decision + rejection evidence. Cost is an advisory preference after eligibility, not a substitute for it.

4. Evidence contract

request_quantity, capacity_allocatable, and unit must be comparable. Capability, locality, tenant scope, reservation, and health remain independent. observed_at and provenance_ref identify the snapshot behind the decision. If decisive metadata is unknown, weaken the state; never invent fields merely to complete the sheet.

5. Request is not the same as limit

Kubernetes distinguishes requests from limits and uses requests in scheduling decisions. The transferable lesson is that a broker must carry the workload's placement demand explicitly; a resource name or theoretical maximum does not replace the workload request.

6. Total capacity is not allocatable capacity

capacity_total is nominal capacity; capacity_allocatable is the amount usable for the decision snapshot. A resource can be large and healthy while allocatable capacity is below the request. Green health cannot turn that candidate into ELIGIBLE.

7. Capability and unit are hard gates

If the workload needs a GPU/CUDA or another hard feature, a candidate missing that capability is rejected. Quantity without unit is not comparable: “24” without GiB/GB or “1” without a device unit is not defensible. Missing decisive unit or capability metadata produces UNKNOWN, not an invented conversion or label.

8. Worked baseline

The workload needs one GPU, at least 24 GiB memory, locality eu-central or eu-west, and Tenant A. The local CPU node fails capability. The shared GPU worker has enough capacity and is healthy, but it is reserved for Tenant B, so it is INELIGIBLE. The cloud GPU worker exposes two allocatable GPU units, matching capability, allowed locality, and no conflicting reservation; it becomes ELIGIBLE and is selected after ranking.

9. Why green health is not enough

A tempting shortcut treats health_state=GREEN as availability. In the mutation, the cloud GPU remains GREEN but capacity_allocatable=0.5 GPU while the request is 1 GPU. It must be INELIGIBLE. Health is one gate; it does not erase capacity, reservation, tenant, or locality constraints.

10. Reservation and tenant scope

A resource can be shared while an active reservation belongs to another tenant. Physical capacity exists, but the resource is not eligible for the current request. If reservation ownership and broker ownership evidence conflict, DISPUTED is stronger than guessing an owner.

11. Locality and availability window

Locality must satisfy the workload constraint, not merely name a region. Availability windows can also exclude a candidate temporarily. A locality or reservation change after ranking is a material change; do not copy the old decision. Keep it PARTIAL until recomputed.

12. Staleness, provenance, and non-success states

Resource metadata changes quickly. Old decisive evidence for a scarce resource can become STALE. Missing quantity/unit/capability can be UNKNOWN. Ownership conflict is DISPUTED, an explicit policy prohibition is BLOCKED, and an unrecomputed material change is PARTIAL. These states prevent overclaiming.

13. Transfer: healthy GPU, changed reservation and locality

In the transfer case, the same shared GPU remains healthy, its Tenant B reservation is released, and locality changes from eu-central to eu-west; the workload already allows both localities. With the same request, eligibility is recomputed. The shared GPU is now ELIGIBLE and, with a lower cost basis than the cloud worker, can become the new selected candidate. The baseline decision is not reused as an oracle.

14. Lab execution

Open lab/ARC-003-LAB1/learner/ and run python run_checks.py offline. Eight fixtures cover baseline, green-but-under-capacity, missing unit, tenant-scope change, stale evidence, reservation conflict, missing capability, and transfer. Do not memorize verdicts; explain the first controlling hard gate or evidence state.

15. Assessment, freshness, and claim boundary

Assessment covers boundary retrieval, baseline sheet construction, shortcut diagnosis, and transfer. Kubernetes documentation bounds FACT semantics for requests, capacity, and extended-resource scheduling. The schema, state vocabulary, and ranking policy remain MAKNOW DESIGN. Material source or broker-policy changes require a newly qualified package version rather than silent mutation of this Golden.