feat(dns): exposure: internal can no longer publish a public record

docs/09 R-DNS-03 and schemas/renderer-contract.md both said an `internal`
service renders no public DNS record. Nothing enforced either sentence.
ExternalDNS's `gateway-httproute` source admitted EVERY HTTPRoute on the shared
Gateway, so six `exposure: internal` services — jackett, pihole, qbittorrent,
radarr, semaphore, sonarr — published `<name>.home.keithjackson.dev` into the
public authoritative Cloudflare zone answering with the Gateway VIP
192.168.2.20. That published the internal subnet, the Gateway VIP and a full
service inventory to anyone who could guess a label, and made each of those
names a DNS-rebind primitive — which is why the SOHO router strips RFC1918
answers and LAN clients need per-client dnsmasq overrides to reach their own
services.

THE MECHANISM, established against the DEPLOYED version rather than from
memory. The live prod Deployment runs
registry.k8s.io/external-dns/external-dns:v0.21.0. In v0.21.0,
source/annotations/processors.go IsControllerMismatch() skips a source object
whose `external-dns.alpha.kubernetes.io/controller` annotation is present and
!= its own `dns-controller`, and source/gateway.go applies that check inside
Endpoints() BEFORE any hostname is resolved; source/service.go applies the
identical check, covering the second configured source. catalog/render.py now
emits that annotation on every HTTPRoute it renders for an `internal` service,
derived from `exposure` alone — no per-service list — so a service that omits
`exposure` inherits the internal default and is unpublishable too. Verified
LIVE on prod on a throwaway hostname with no existing record at risk: the
annotated route published nothing, and adding the annotation to a route that
already had a record produced action=DELETE for both its A record and its `a-`
TXT registry entry one ~60s reconcile later, moving nothing else in the zone.

WHY PER-RESOURCE AND NOT A CLUSTER-WIDE OPT-IN FILTER. `labelFilter` is the
stronger default posture and v0.21.0 supports it for both configured sources,
but nine publishing objects here are hand-authored platform/apps manifests with
no `exposure` field, seven of which hold live records (auth, crafty, crafty-mc,
grafana, headlamp, the apex, unifi). An opt-in filter deletes all seven at
once, and whether each should be publicly resolvable is an operator decision
per name. Per-resource exclusion has exactly the blast radius of the defect;
the seven are enumerated in a shrink-only register so the unadjudicated set
cannot grow silently, and the filter stays available as hardening afterwards.

`policy: sync`, `txtOwnerId` and `domainFilters` are UNTOUCHED. Per-resource
exclusion only ever removes an object from this instance's view, so nothing
here makes prod capable of deleting a record it does not own.

WHAT THIS DELETES, and it is not reversible by a revert alone: 12 records — the
A record and the `a-`-prefixed TXT registry entry for each of jackett, pihole,
qbittorrent, radarr, semaphore and sonarr. The zone has no
`*.home.keithjackson.dev` wildcard and `*.keithjackson.dev` does not match two
labels, so each becomes a public NXDOMAIN with no fallback. The complete
pre-state is captured at the authority and committed as a recovery baseline
(.standup-dns/dns-20260914-pre-externaldns-scope.txt), with the restore
procedure for both halves of a record.

MERGE ORDER IS NOT OPTIONAL: feat/pihole-lan-dns-authority must land and be
verified first. Removing these records while the LAN still depends on them,
with the router stripping RFC1918 and no internal authority yet, breaks name
resolution outright.

The five `exposure: public` services are LEFT UNCHANGED and still answer with
the Gateway VIP, so they remain publicly unreachable. That is two open operator
decisions, both written up in platform/externaldns/helmrelease.yaml: what
address they should answer with (136.51.115.252 is the legacy non-k3s stack
serving a placeholder cert, not established as correct for this cluster), and
how to separate them from the non-public names that share the Gateway —
because in v0.21.0 the target annotation is read only from the GATEWAY and a
ListenerSet, never from an HTTPRoute, so a per-service override is not
expressible while they all attach to `shared`. No knob is added for it yet: one
that cannot take effect invites someone to set it and expect one.

Guard: conformance/tests/l0-static/internal-services-publish-no-public-dns, a
whole-repo-scoped L0 static check (no ci/l0.sh stage — the
whole-repo-invariants-wired meta-test forbids one). It asserts both directions
(present on internal, absent on public), the `service`-source half, that the
renderer DERIVES the annotation from `exposure` and cannot emit external-dns's
own claiming value, proves the shipped renderer end-to-end on
internal/public/omitted-field fixtures, and ratchets the non-catalog register.
Proven to fail on the pre-fix tree (9 of 53 assertions, naming all six
services) and pass after (56/56).

Schema 1.6.0 -> 1.7.0: no field changes, a mapping change to `exposure`.

Co-Authored-By: Claude Opus 5 <[email protected]>

schemas/renderer-contract.md

@@ -53,6 +53,41 @@ platform must render, and cites the requirement each mapping satisfies. Changing
   ExternalDNS record for `<name>.home.keithjackson.dev`.
 - `internal` renders **no public DNS record** and is never port-forwarded (PiHole resolves it to the
   internal Gateway VIP).
+- **HOW "no public DNS record" IS MADE TRUE, since it was prose only until 2026-09-14.** Every
+  HTTPRoute rendered for an `internal` service carries ExternalDNS's own controller annotation with
+  a value other than the one ExternalDNS claims:
+
+      external-dns.alpha.kubernetes.io/controller: none
+
+  ExternalDNS v0.21.0 (`source/annotations/processors.go`) skips any source object whose
+  `controller` annotation is present and `!= "dns-controller"`, and `source/gateway.go` applies that
+  check **inside `Endpoints()` before any hostname is resolved** — so the route never becomes an
+  endpoint for any name it declares. `source/service.go` applies the identical check, which covers
+  the second configured source. It is derived **from `exposure` and nothing else**
+  (`catalog/render.py` `_externaldns_route_annotations`), so the operator's one declaration decides,
+  a service that OMITS `exposure` inherits the `internal` default and is likewise unpublishable, and
+  there is no per-service list to forget to extend. `ci/render-golden.sh` proves `apps/` reproduces
+  from `catalog/`, so an `internal` service cannot exist in the applied tree without it, and
+  `conformance/tests/l0-static/internal-services-publish-no-public-dns` re-proves both directions
+  (present on internal, **absent** on public) on every gate run.
+  - The route itself, the wildcard TLS and LAN reachability are **unchanged** — only the public
+    record is withdrawn. The internal split-horizon answer is Pi-hole's job (R-DNS-03), which is why
+    withdrawing these records requires Pi-hole to be answering the LAN authoritatively first: the
+    zone has no `*.home.keithjackson.dev` wildcard, and `*.keithjackson.dev` does not match two
+    labels, so a withdrawn name is a public NXDOMAIN with no fallback.
+  - Why not a cluster-wide ExternalDNS opt-in filter (`labelFilter`, which v0.21.0 supports for
+    both configured sources): seven published names come from hand-authored `platform/`/`apps/`
+    manifests that carry no `exposure` field for a renderer to read, and an opt-in filter deletes
+    all seven the moment it is set. Per-resource exclusion has exactly the blast radius of the
+    defect. The filter stays available as hardening once those seven are adjudicated — see
+    `platform/externaldns/helmrelease.yaml` and the register in the L0 check.
+- `public` renders the record but the renderer does **not** yet set a target: the record still
+  resolves to the shared Gateway VIP, i.e. an RFC1918 address, so a `public` service is not in fact
+  publicly reachable. Fixing that is **not** a renderer change on v0.21.0 —
+  `source/gateway.go` reads `external-dns.alpha.kubernetes.io/target` only from the **Gateway** (and
+  a ListenerSet), never from an HTTPRoute, so a per-service target override is not expressible while
+  the public services share the `shared` Gateway. The open decision is recorded in
+  `platform/externaldns/helmrelease.yaml`.
 - Exposure does **not** relax east-west default-deny (docs/09 §"Interaction with default-deny").
 - **Requirements:** R-DNS-02/03 (docs/09), R-NET-04 (docs/03).
 
@@ -131,8 +166,12 @@ platform must render, and cites the requirement each mapping satisfies. Changing
   (Let's Encrypt via **DNS-01**, scoped Cloudflare token), so no per-service cert step — trusted,
   non-self-signed, auto-renewed, including for `internal` services. Per-service `Certificate` only
   where isolation warrants.
-- DNS: **ExternalDNS** watches the HTTPRoute and manages the `<host>` record (public IP for `public`,
-  internal Gateway VIP via PiHole split-horizon for `internal`).
+- DNS: **ExternalDNS** watches the HTTPRoute and manages the `<host>` record — but **only for a
+  `public` service**. An `internal` service's route is rendered with ExternalDNS's controller
+  annotation set to `none`, which removes it from ExternalDNS's view entirely (see §`exposure`), so
+  its `<host>` exists **only** in the internal split-horizon answer PiHole serves, never in the
+  public zone. A `public` record's TARGET is still the Gateway VIP, not a routable address — open
+  operator decision, see §`exposure`.
 - The `host` pattern is enforced to `<label>.home.keithjackson.dev` by the schema.
 - **Requirements:** **R-TLS-01/02/03** (docs/08), **R-DNS-01/02/03** (docs/09).
 
@@ -242,6 +281,11 @@ platform must render, and cites the requirement each mapping satisfies. Changing
 6. **irreplaceable ⇒ off-cluster backup:** DR-critical services must not carry `backup.policy:
    reacquirable` (R-STATE-03). *(Advisory: not enforced by the schema — an L0 policy check should
    assert it; see "Ambiguities / escalations" in schemas/README.md.)*
+7. **`exposure: internal` ⇒ no public DNS record, structurally.** Every HTTPRoute rendered for an
+   `internal` service (including one that omits `exposure` and takes the default) carries
+   `external-dns.alpha.kubernetes.io/controller: none`, and no `public` service's route carries it.
+   Derived from `exposure` alone; enforced on every gate run by
+   `conformance/tests/l0-static/internal-services-publish-no-public-dns` (R-DNS-03).
 
 ## Requirement traceability (contract-level)
 Primary **R-GITOPS-02** (single reviewable object wires every requirement). Field-level: R-NET-01/02

schemas/servicedefinition.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://home.keithjackson.dev/schemas/servicedefinition.schema.json",
   "title": "ServiceDefinition",
-  "description": "Operator-facing onboarding contract for the home k3s + Longhorn platform. One ServiceDefinition per file under catalog/. Captures INTENT; the platform compiles it into concrete resources (see schemas/renderer-contract.md). Canonical source of truth: spec docs/13-service-catalog.md. Serves R-GITOPS-02; ties into R-NET-*, R-STATE-*, R-TLS-*, R-DNS-*, R-OBS-*, R-UPD-*, R-IDP-*. Schema version: 1.6.0 (splits `observability.metrics` from WHERE metrics live: adds optional `metricsEndpoint` (port/name/path/interval) and optional `livenessWorkload` (kind/name). `metrics: true` previously rendered a ServiceMonitor hardcoded to a port named `metrics` that no rendered Service ever defined, so all twelve app monitors discovered ZERO targets and every `up{job=...}` SLI was structurally inert on prod; a monitor is now rendered only from a declared `metricsEndpoint`, which also renders the Service port and the monitoring-namespace ingress allow, and the `up` SLI is expressed against kube-state-metrics -- a signal that exists for every workload without a per-app exporter. `livenessWorkload` names the object whose readiness IS the service, for the case where the running workload is not the one this SD renders). 1.5.0 (adds optional `inClusterClients` — additional in-cluster clients, named by NAMESPACE, admitted to a declared port of this service DIRECTLY, bypassing the shared Gateway. `ingressRoutes` admits only the Gateway proxy identity and `dependencies` only links catalog services, so a PLATFORM controller dialling a Service ClusterIP had no authorable form at all; that gap is what deadlocked prod's GitOps when its GitRepository moved to the in-cluster Gitea Service. Renders one least-privilege ingress CiliumNetworkPolicy per entry — the named namespace and the declared port, nothing wider). 1.4.0 (makes the `bulk` tier REAL: a bulk storage entry now carries `export` (the absolute NFS export path on the ${BULK_NFS_SERVER} host) and renders a STATIC, pre-bound NFS PersistentVolume + PVC over data that already exists outside the cluster, plus optional `subPath` and `readOnly` on any entry. Resolves the OQ-2 bulk-backing stub for STATIC pre-existing datasets; dynamic bulk provisioning remains unimplemented and unneeded). 1.3.0 added optional pod-level podSecurityContext for the container kind — k8s PodSecurityContext emitted verbatim onto the pod spec; its fsGroup unblocks non-root images e.g. semaphore/UID-1001 writing a mounted Longhorn PVC). 1.2.0 added optional per-container env/envFrom/lifecycle for the container kind — k8s EnvVar/EnvFromSource/Lifecycle shapes emitted verbatim onto the app container; unblocks headless-install/DB-backed apps e.g. gitea/nextcloud/semaphore/unifi/minecraft. 1.1.0 added the shape invariant exposure:public => auth.mode!=none (docs/13 v1.1 / docs/15 / R-IDP-02).",
+  "description": "Operator-facing onboarding contract for the home k3s + Longhorn platform. One ServiceDefinition per file under catalog/. Captures INTENT; the platform compiles it into concrete resources (see schemas/renderer-contract.md). Canonical source of truth: spec docs/13-service-catalog.md. Serves R-GITOPS-02; ties into R-NET-*, R-STATE-*, R-TLS-*, R-DNS-*, R-OBS-*, R-UPD-*, R-IDP-*. Schema version: 1.7.0 (no field changes; a MAPPING change to `exposure`, which had never had an effect on DNS. `exposure: internal` now renders ExternalDNS's own controller annotation onto every HTTPRoute it emits, set to a value other than `dns-controller`, so external-dns (v0.21.0, source/gateway.go -> annotations.IsControllerMismatch) skips the route before resolving any hostname and the service is INCAPABLE of producing a public record. Both docs/09 R-DNS-03 and schemas/renderer-contract.md already said `internal` renders no public DNS record; nothing enforced it, and six internal services -- jackett, pihole, qbittorrent, radarr, semaphore, sonarr -- were publishing `<name>.home.keithjackson.dev` into the PUBLIC Cloudflare zone answering with the RFC1918 Gateway VIP, which published the internal subnet and a full service inventory and made each name a DNS-rebind primitive. Enforced on every gate run by conformance/tests/l0-static/internal-services-publish-no-public-dns). 1.6.0 (splits `observability.metrics` from WHERE metrics live: adds optional `metricsEndpoint` (port/name/path/interval) and optional `livenessWorkload` (kind/name). `metrics: true` previously rendered a ServiceMonitor hardcoded to a port named `metrics` that no rendered Service ever defined, so all twelve app monitors discovered ZERO targets and every `up{job=...}` SLI was structurally inert on prod; a monitor is now rendered only from a declared `metricsEndpoint`, which also renders the Service port and the monitoring-namespace ingress allow, and the `up` SLI is expressed against kube-state-metrics -- a signal that exists for every workload without a per-app exporter. `livenessWorkload` names the object whose readiness IS the service, for the case where the running workload is not the one this SD renders). 1.5.0 (adds optional `inClusterClients` — additional in-cluster clients, named by NAMESPACE, admitted to a declared port of this service DIRECTLY, bypassing the shared Gateway. `ingressRoutes` admits only the Gateway proxy identity and `dependencies` only links catalog services, so a PLATFORM controller dialling a Service ClusterIP had no authorable form at all; that gap is what deadlocked prod's GitOps when its GitRepository moved to the in-cluster Gitea Service. Renders one least-privilege ingress CiliumNetworkPolicy per entry — the named namespace and the declared port, nothing wider). 1.4.0 (makes the `bulk` tier REAL: a bulk storage entry now carries `export` (the absolute NFS export path on the ${BULK_NFS_SERVER} host) and renders a STATIC, pre-bound NFS PersistentVolume + PVC over data that already exists outside the cluster, plus optional `subPath` and `readOnly` on any entry. Resolves the OQ-2 bulk-backing stub for STATIC pre-existing datasets; dynamic bulk provisioning remains unimplemented and unneeded). 1.3.0 added optional pod-level podSecurityContext for the container kind — k8s PodSecurityContext emitted verbatim onto the pod spec; its fsGroup unblocks non-root images e.g. semaphore/UID-1001 writing a mounted Longhorn PVC). 1.2.0 added optional per-container env/envFrom/lifecycle for the container kind — k8s EnvVar/EnvFromSource/Lifecycle shapes emitted verbatim onto the app container; unblocks headless-install/DB-backed apps e.g. gitea/nextcloud/semaphore/unifi/minecraft. 1.1.0 added the shape invariant exposure:public => auth.mode!=none (docs/13 v1.1 / docs/15 / R-IDP-02).",
   "type": "object",
   "additionalProperties": false,
   "required": ["name", "source"],