Port allocation order within a resource is unspecified

The reference is precise about how one port is chosen:

The allocated port is the first one from start upward that is neither promised to another instance nor unbindable right now.

It does not say in what order a resource's own ports are allocated, and [ports.<name>] is a TOML table — a map, not a sequence. That matters as soon as two ports in one resource have ranges that can reach each other, which is the normal case for a tool whose defaults are consecutive:

[ports]
api    = { start = 54321, env = "SUPABASE_API_PORT" }
db     = { start = 54322, env = "SUPABASE_DB_PORT" }
shadow = { start = 54320 }
studio = { start = 54323, env = "SUPABASE_STUDIO_PORT" }
smtp   = { start = 54324, env = "SUPABASE_SMTP_PORT" }

Writing that, I could not tell from the docs whether shadow scanning up from 54320 might take 54321 before api ever got a look at it, or whether api is allocated first and shadow then skips past it. Both are reasonable implementations and they produce different assignments. I reasoned it was fine either way here (every start is distinct, so whichever order is used, each port lands on its own default for the first instance) and moved on, and the result was what I hoped:

resource:  `supabase` ports: analytics=54327 api=54321 db=54322 shadow=54320 smtp=54324 studio=54323

But "I convinced myself it works out for my particular numbers" is a worse place to be than "the docs told me," especially for a thing recorded once at spawn and fixed for the life of the instance. The [exports] section makes a point of saying you never have to think about declaration order because siblings resolve in two passes; [ports] leaves the equivalent question open.

One line in the [ports.<name>] section would close it — whatever the answer is, including "sorted by name, and do not rely on it."

While in there: the output above is sorted by name, which is reasonable, but if allocation order and display order are the same thing it is worth saying so, and if they are not, worth not implying it.

Found while setting up newgit in an Expo + Supabase monorepo (one Supabase stack per branch instance), newgit 0.2.0 (203dbaf884e6) on macOS.

Start with the [ports.] documentation and compare its wording with the existing allocation behavior for a resource's ports. Document the defined allocation order, whether declaration or display order is relevant, and make the result clear enough that the example's assignments are predictable.