docs(consul-postgres-ha): rewrite "Adapting to your own workload" + retire design brief

README's adaptation guide now walks a worked example (add a fictional
billing:9090 service) end-to-end. ARCHITECTURE notes the allowlist is
platform-generated. design/declarative-services.md is deleted per the
hand-off section — the code + updated README are the surviving
artifacts; the index entry comes out too.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: h4x3rotab

consul-postgres-ha/ARCHITECTURE.md

@@ -78,9 +78,10 @@ above. Two carved-out loopback `/24`s, allocated cluster-wide:
   worker consumes (e.g. webdemo, postgres-master, postgres-replica).
   Identifies *what service* an app is calling.
 
-mesh-conn binds a small **static infra-port allowlist** on every
+mesh-conn binds a small **platform-supplied allowlist** on every
 *other* peer's VIP and forwards each accepted connection to the right
-remote peer over the QUIC link:
+remote peer over the QUIC link. With the 3-service example
+(webdemo + postgres-master/-replica) the allowlist is:
 
 | Port  | Used by                                               | Proto       |
 |-------|-------------------------------------------------------|-------------|
@@ -89,11 +90,16 @@ remote peer over the QUIC link:
 | 8300  | Consul server RPC (server-to-server, client-to-server)| TCP         |
 | 8301  | Consul serf-LAN gossip                                | UDP + TCP   |
 
-The allowlist is static and small by design — mesh-conn knows
-**peers, not services**. Apps never dial peer VIPs; only Envoy and
-Consul-agent do, and both speak well-known platform ports. Adding a
-port to the allowlist is a code change in `mesh-conn/main.go`, not
-a runtime catalog watch.
+The allowlist is intentionally minimal — mesh-conn knows **peers,
+not services**. Apps never dial peer VIPs; only Envoy and Consul-agent
+do, and both speak well-known platform ports.
+
+The allowlist is **platform-generated, not Go-const**: per-service
+Connect-sidecar ports come from `local.services` in `cluster.tf`, get
+collapsed into per-backend `sidecar_port`s, and the platform sidecar
+emits `MESH_CONN_ALLOWLIST` env (JSON `[{port, udp}, …]`) at startup.
+mesh-conn reads it once and binds accordingly. Adding a service is an
+HCL edit in `cluster.tf`; mesh-conn never has to be rebuilt.
 
 ```
                   inside worker-3 CVM (network_mode: host)

consul-postgres-ha/README.md

@@ -122,20 +122,81 @@ consul-postgres-ha/
 
 ## Adapting to your own workload
 
-Three things make this opinionated for Patroni; everything else is
-generic platform plumbing.
+The mesh is **declarative**: `local.services` in `cluster.tf` is the
+single source of truth, and the platform sidecar generates Consul
+registrations, Envoy supervise loops, loopback aliases, `/etc/hosts`
+entries, and `mesh-conn`'s peer-VIP allowlist from it. Adding a
+microservice is one HCL block plus an image; no edits to `mesh-conn`,
+the sidecar entrypoint, your app's source, or the CI workflow.
+
+### Add a service: worked example
+
+Say you want a billing service on port 9090 that the existing
+`webdemo` calls into. End-to-end:
+
+1. **Declare it in `cluster.tf`** — append one entry to
+   `local.services`:
+
+   ```hcl
+   services_raw = [
+     { name = "webdemo",          port = 8080, subset = null    },
+     { name = "postgres-master",  port = 5432, subset = "master" },
+     { name = "postgres-replica", port = 5432, subset = "replica" },
+     { name = "billing",          port = 9090, subset = null    },  # ← new
+   ]
+   ```
+
+   This is the only edit to the platform.
+
+2. **Add the image** to `terraform.tfvars` (`billing_image = "..."`),
+   wire a `BILLING_IMAGE` variable + env entry on `phala_app.worker`,
+   and add a `billing` service to `compose/worker.yaml` (modelled on
+   `webdemo` — it just binds `127.0.0.1:9090` and serves).
+
+3. **`terraform apply`**. The provider's in-place env update pushes
+   the new `SERVICES_JSON` to every CVM:
+
+   - `mesh-conn`'s allowlist extends to `{21000, 21001, 21002,
+     8300, 8301}` automatically — `MESH_CONN_ALLOWLIST` is computed
+     from `SERVICES_JSON` in `mesh-sidecar/entrypoint.sh`.
+   - Workers provision `127.10.0.13/32 dev lo`, append
+     `127.10.0.13 billing` to `/etc/hosts`, and start a third Envoy
+     supervise loop with `--base-id 3 -admin-bind 127.0.0.1:19002`.
+   - Coordinator-0 writes a default-allow intention for `billing`
+     and any subset/redirect resolvers implied by the declaration.
+
+4. **From any container on any peer**, `curl http://billing:9090/...`
+   load-balances across all peers' `billing` instances over Connect
+   mTLS. No application-side service-discovery code.
+
+### What the convention does for you
+
+| Field on each entry | What it controls |
+|---|---|
+| `name` | Consul service name + `/etc/hosts` alias. Apps dial `${name}:${port}`. |
+| `port` | Canonical app port. App binds `127.0.0.1:port`. Two entries sharing a port collapse onto one **backend** (one Envoy supervise loop, one `sidecar_port`, one Connect-mTLS endpoint) — that's how `postgres-master` and `postgres-replica` ride the same Patroni instance. |
+| `subset` | Optional Consul service-subset filter (matches `Service.Tags`). Each subset-bearing entry generates a redirect resolver to the parent backend. Patroni's role-watcher (in `patroni/entrypoint.sh`) updates those tags on role flips. |
+
+VIP octets and `sidecar_port` numbers are computed in HCL from
+declaration order — first service gets `vip=10 sidecar_port=21000`,
+second `vip=11 sidecar_port=21001`, and so on. Plan-time validation
+catches duplicate `(name, subset)` tuples.
+
+### Workload-specific pieces remaining
+
+Only two files contain workload-specific logic after this refactor:
 
-| Patroni-specific | Lives in |
+| Workload-specific | Lives in |
 |---|---|
-| The Patroni image itself | `patroni/` |
-| Patroni env block + REST/Postgres port choices | `compose/worker.yaml` |
-| Postgres service VIPs + Connect upstreams | `cluster-example/cluster.tf` (`local.service_vips`) |
-| Postgres Connect sidecar registration + Envoy launch | `mesh-sidecar/entrypoint.sh` |
-
-To run something else (a Redis cluster, a Kafka broker, your own
-stateful service): swap those three pieces, leave `mesh-conn`,
-`bootstrap-secrets`, `consul`, `sidecar`, the coordinator topology,
-and the Terraform structure as-is.
+| The Patroni image itself + role-watcher loop | `patroni/` |
+| Patroni env block (`CLUSTER_NAME`, replication passwords, etc.) | `compose/worker.yaml` |
+
+`mesh-sidecar/entrypoint.sh` contains zero per-workload code paths —
+grep it for `patroni` or `webdemo` and you get nothing. To run
+something other than Patroni (Redis, Kafka, your own service): replace
+the `patroni` compose service and image with your own, edit
+`local.services` to declare its names + ports, and leave the rest of
+the platform plumbing untouched.
 
 ## Key operational properties
 

consul-postgres-ha/design/README.md

@@ -12,7 +12,6 @@ in their face.
 
 | Doc | What |
 |---|---|
-| [`declarative-services.md`](declarative-services.md) | Adding a microservice should be one HCL block in `cluster.tf`. Today's `mesh-conn` allowlist is hardcoded Go; sidecar registration lives in app binaries; Envoy supervise loops are copy-pasted. This pass makes the service list declarative and generates the rest. |
 | [`attestation-admission.md`](attestation-admission.md) | Use dstack TEE attestation as the mesh-conn admission credential, replacing/augmenting the shared TURN HMAC. Phased plan: per-app-id first, Consul-KV-rooted policy later. |
 
 Each doc includes: