fix(deploy): allocate site ports per box, so a second attach cannot collide

docs/config.mdmodified+50-0

Changes to docs/config.md

		⋯383 linesShow the 383 lines above this hunk@@ -384,6 +384,56 @@ regenerates the route config and restarts the gateway — so new
384	384	server-app/server-static sites appear automatically. Leaving `proxy` unset
385	385	keeps the prior behavior (no gateway installed; you run your own).
386	386
	387	+### Ports on a shared box
	388	+
	389	+Each project's deploy writes only its own route fragment,
	390	+`/etc/rpx/sites.d/<slug>.json`, and the gateway merges them at startup. That is
	391	+what lets several independent projects share one box: routes are keyed by host, so
	392	+they compose.
	393	+
	394	+Ports do not compose. Every `server-app` route resolves to `from:
	395	+'localhost:<port>'` on one shared loopback namespace, and apps generated from the
	396	+same template declare the same ports. `validateDeploymentConfig` only ever sees
	397	+one project's `sites`, so a second project attaching to an occupied box passes
	398	+validation.
	399	+
	400	+What happens next is worse than a failure. ts-cloud's units do not set exclusive
	401	+binding, so both listeners bind and the kernel load-balances between them: nothing
	402	+errors, both services look healthy, and each domain answers with the other
	403	+project's site for roughly half its requests. `buddy deploy` catches this late via
	404	+`assertPortsAreFree`, which compares wanted ports against the box's live listeners
	405	+and stops the deploy, but its only remedy is to tell you to pick free ports by
	406	+hand.
	407	+
	408	+The fragments already answer this, since every one of them records its upstream
	409	+port. `site-ports.ts` reads them:
	410	+
	411	+```typescript
	412	+import { allocateSitePorts, buildHostSitePortsScript, occupiedHostPorts, parseHostSiteFragments } from './deploy/site-ports'
	413	+import { validateDeploymentConfig } from './deploy/site-target'
	414	+
	415	+// `stdout` is the output of buildHostSitePortsScript() run on the box.
	416	+const occupiedPorts = occupiedHostPorts(parseHostSiteFragments(stdout), { ignoreSlug: config.project.slug })
	417	+
	418	+// Reports a collision at plan time, naming the project that holds the port.
	419	+const { errors } = validateDeploymentConfig(config, { occupiedPorts })
	420	+
	421	+// Or allocate around it, so no app has to hand-pick a globally unique port.
	422	+const { allocations } = allocateSitePorts(config, occupiedPorts)
	423	+```
	424	+
	425	+Two details matter:
	426	+
	427	+- **`ignoreSlug` is required.** This project's own fragment is already on the box
	428	+ from its last deploy, so counting it makes every redeploy conflict with itself.
	429	+- **A declared port is kept whenever it is free.** A box with no co-tenants
	430	+ allocates nothing and ports stay stable across deploys; only a site that
	431	+ actually collides moves, and it moves to the next free port rather than
	432	+ somewhere arbitrary.
	433	+
	434	+Omitting `occupiedPorts` validates exactly as before, so this is additive for any
	435	+single-project box.
	436	+
387	437	## Preset Configuration
388	438
389	439	### Static Site Preset