Managed custom-domain connections — platform-owned verification and cert status

Date: 2026-08-27 · Status: approved (design approved in conversation 2026-08-27) · Requested by: the Tito Go team, via Paul

Closes: #299 (managed custom-domain connections). Folds in: #287 (attached custom domains are not published to edges files).

Builds on: #151 (the global claim + route_aliases + the domains door), #82 / 2026-08-12-domain-attach-design.md (first-route attach, the DNS-pointing-as-evidence ruling this spec keeps), 2026-08-20-multi-region-ingress-design.md (the edges files, the elected issuer, control/certs/ and the mirror), #300 / PR #301 (the per-host class mark this spec's alias mark follows), #291 / PR #297 (the cert backfill that makes control/certs/ complete), #289 (the housekeeper gating this spec narrows), #207, #180 and #277 (the exact-only cert admission bound this spec must not widen).

0. How this spec was arrived at

Four adversarial review rounds (one per stage, then a whole-plan pass) ran against earlier revisions. Five blockers were found and folded in; the findings that changed the design are kept inline as rationale rather than stripped, because in each case the wrong answer is the one a reader would otherwise reach again — the deploymentHosts/deploymentHost confusion and the Generation staleness bound especially.

Scope rulings (Paul, 2026-08-26/27):

• Status + structured records + capability discovery. NOT TXT ownership proof — claim authz stays first-writer-wins + DNS-pointing-as-evidence (2026-08-12-domain-attach-design.md §2).
• #287 folded in as stage 1.
• Cert provisioning becomes proactive on the elected issuer.

---

Stage 1 — make the inputs true

1a. Aliases reach the edges files, with a class mark (#287)

edgesFilePass (internal/host/edgesfile.go:101) folds reg.ListAliases() alongside reg.List().

Wire: edgeHost gains Alias bool \json:"alias"\` — additive, ALWAYS emitted, the convention #300's Platform mark set (a file with no alias` key is a pre-mark publisher, not a box publishing no aliases).

Per alias: join to the primary via RouteAlias.Host against the reg.List() map already in hand; skip unless the primary is Status == "ready"; emit edgeHost{Role:"home", Platform:false, Alias:true}. Platform:false keeps customer domains out of wildcard-parent derivation (parentInput, homemap.go:343). Routes are written first; an alias never overwrites a route key on the same box.

The fold rule — the security fix. foldHomes (homemap.go:446-465) today resolves a duplicate host by "first box in sorted order wins". New rule: a non-alias entry beats an alias entry; among equals, sorted order still decides.

Why: ReconcileAliases' "a real route owns that host" refusal is per-box (byHost is this box's routes — aliases.go:41,66), and the attach door deliberately does not verify a route exists, because operator-minted routes have no instance record (apidomains.go:106-113). So an account can claim a hostname that is a real, UNCLAIMED route on another box. Today inert. Once both boxes publish role:"home", sorted-order-wins hands the victim's hostname to the claimant on every other edge — under steering, most traffic. The vulnerable set is exactly the claimless routes: operator carlos add rows, go.tito.io, every route on a self-hosted box.

The mark must reach the reader, not just the writer. The fold rule alone is not enough: edgesHostView (homemap.go:134-141) and homeEntry (homemap.go:143-149) carry only Role/Platform. Stage 1 must carry alias into both, plus an accessor enumerating fold entries — all of them, not only alias-marked ones, since 3a's corrected warm set is "not under the apps domain" rather than "alias". Without this accessor stage 3 is unimplementable.

Note: the always-emit choice (never omitempty) matches what #300 actually shipped — Platform bool \json:"platform"\` with the comment "always emitted (never omitempty), so a file with no key at all is definitely a pre-mark publisher" (edgesfile.go:37-46). A review claimed #301 used omitempty`; the code says otherwise, and the always-emit reasoning is what makes "old publisher" distinguishable from "nothing to declare".

The fold rule alone is NOT the whole fix. It corrects what REMOTE edges answer. It does nothing on the claimant's own box: ReconcileAliases materializes the alias whenever the claim's primary exists locally and the victim's host is not a LOCAL route, and request routing consults the local upstream map before Home() — an exact local alias match wins regardless of the fold. So for a pre-existing or door-race claim, any traffic landing on the claimant's box serves the claimant's content over valid TLS (the mirror hands every box the victim's cert). That is reachable: an operator route outside the apps domain (the go.tito.io class — apps-domain hosts are door-denied) whose owner followed our own steering guidance (CNAME to edge.<apps-domain>) steers a share of traffic to every edge, the claimant's included.

The authoritative refusal therefore belongs in ReconcileAliases, using the same shared reader: refuse to materialize an alias whose host any live box publishes as a non-alias home entry. That also retro-cleans pre-existing claims on the next pass, which neither the fold rule nor a door check can do.

Defence in depth at the door. The attach door additionally refuses such a host at attach time. Best-effort (it races a concurrent mint), so it shortens the window but is not the fix. Its refusal must be byte-identical to the existing 409 "hostname unavailable" (apidomains.go:26-31), or it becomes an existence oracle for operator routes.

Roll order: readers before publishers — the INVERSE of #301's rule. #301's mark failed CLOSED in an old reader (no mark → derive no parent), so publishers could lead. This one fails OPEN: an old reader sees no alias key and falls back to sorted-order-wins. Both halves are in one binary, so a box-by-box roll would have an early-rolled box publishing into un-rolled readers. Stage 1 therefore ships as TWO releases:

1. Reader release — fold preference + alias carried into edgesHostView/homeEntry. Inert while nothing publishes the mark.
2. Writer release — alias publication, plus 1b–1e below.

1b. #289 fixed the wrong thing — return the pass to every box

The per-box divergence #289 saw was ONE INPUT (cfg.EdgeIPs, judged per-box), not the pass. Gating the whole pass silenced N-1 writers instead of fixing the input. Every section except the auto-purge writes only the box's own registry, derived deterministically from shared bucket state:

• §1a account materialization (reg.PutAccount/DeleteAccount, reconcile.go:127-137) — gated, non-housekeeper account tables are frozen, so carlos accounts list on those boxes lies.
• §1b route-account stamping (reg.SetAccount) — local.
• §1c trashed-route removal (reg.Delete, reconcile.go:244-258) — gated, a trashed app's routes on non-housekeeper boxes keep serving until the purge cooloff deletes the records, against the code's own "Trashed apps stop routing NOW" and its "the worse betrayal" rationale.
• §2/§3 minting — mints into the LOCAL registry from firstReadyUpstream over LOCAL routes. Per-box is CORRECT (it is how an everywhere-class app gets its platform host on every box that serves it); housekeeper-only means an app served only on non-housekeeper boxes never gets a platform domain.
• §3 canary-route removal — local, deterministic from the bucket pointer.
• §4/§5 DNS + cert stamps — local; the original Finding A.

Only §1d auto-purge is deployment-global — it DESTROYS bucket objects, so it stays a housekeeper duty, lifted into domains.PurgeTrashed.

1c. pointing judged against the deployment, not the box

• domains.Config.EdgeIPs []string becomes EdgeIPs func() []string. domainsTickConfig is read ONCE at arm (agent.go:1619) while the edge set moves at runtime; a boot-frozen list is the bug being fixed.
• The parser needs a home both the agent and the console can import. 1c originally put the fold in internal/host — but the console is a separate process (cmd/console) that does not import internal/host at all, and stage 2's records/edge_ips need the same fold. Putting a reader in the console would make it the FOURTH parser of the shape, which is the rule 1c invokes against itself. So: extract one exported reader (package internal/edgesfile, or exported from internal/steering) and have internal/host, the console, and internal/edge share it. Also: internal/edge needs the EIP set too (stage 3's DNS gate), and host imports edge, never the reverse — a shared low-level package is the only shape that serves all three.
• Semantics: UNION the fold with PLATFORM_EDGE_IPS. The fold can only widen, so a short or failed fold degrades to today's behaviour, never below. (Contrast internal/steering, which fails CLOSED on a short fold because a short fold there DELETES records; nothing is deleted here.)
• Liveness bound — NOT Generation. An earlier revision proposed ignoring an edges file whose Generation is older than a few publish cadences. That cannot work: Generation is stamped ONLY when a write happens (edgesfile.go:145), the change gate suppresses writes for unchanged content (bytes.Equal(gate, *last)), and seedEdgesFileGate exists precisely so an unchanged file is never republished across restarts. On a stable fleet every HEALTHY box's Generation is arbitrarily old, so that bound would ignore every healthy box and silently degrade the fold to env-only — defeating its own purpose, in all three stages that share it.

Use box-snapshot freshness instead: statusTick's WriteBox is UNCONDITIONAL every tick (agent.go:1863) and BoxStale compares a moving GeneratedAt (status/fleet.go:137-139) — a real liveness signal. A box whose status snapshot is stale drops out of the EIP fold. This reuses the loader and the staleness rule the console already applies (apidomains.go:650-656), so there is one definition of "a box that still counts", not two.

Why it matters: nothing deletes a retired box's control/edges/<box>.json, so without a liveness bound a retired box's file keeps a DEAD customer domain reading pointing — a lying green.

• Guidance consistency: the console's dnsTargets (server.go:666) must read the same fold, or the platform tells a customer to point at an address its own checker will not credit.

1d. Carry the stamp's age, and give claim-backed ROUTES a reading

This is a stage-2 blocker discovered here. Metrics.Aliases is built exclusively from Probes.Aliases = route_aliases rows (snapshot.go:435-441), and RouteVersions carries Version only (snapshot.go:166). A first-route claim (Claim.Route == "") mints a real registry ROUTE, not an alias — so it never gets a reading, and carlos domains list shows it pending forever. That is live today for carlos deploy -kind static -host <site>, a shipped headline flow.

The fix is nearly free: CollectBox(routes []registry.Route, ...) (snapshot.go:376) already holds the routes, and registry.Route already carries the DNSStatus/CertExpiresAt columns §4/§5 stamp. Fold claim- backed route stamps into the same readings map in the loop already running, with Route: r.Host — which is exactly what claims.go means by "an empty route means this host is its own primary".

Also:

• Add DNSCheckedAt int64 \json:"dnscheckedat,omitempty"\` to status.AliasReading (additive). registry has dnscheckedat` (registry.go:198) and nothing downstream reads it.
• Make the console fold prefer the FRESHEST reading. Today it is last-box-wins by map iteration with no tie-break (apidomains.go:656-658), so a frozen stamp can deterministically overwrite a fresh one.

1e. pending-dns honesty

dnsStatus returns "" for ANY resolver error (reconcile.go:465-476) — NXDOMAIN and a box-side SERVFAIL are indistinguishable. Deriving pending-dns from that blames the customer's record for our outage, the failure the unknown state exists to prevent. Either add a third stamp value separating "authoritative no answer" from "lookup failed" (an additive registry + snapshot field, belonging in this release), or weaken the pending-dns description to what is actually derivable. Recommend the third value — it is small here and unpickable later.

1f. Repins

• internal/host/domains_duty_test.go, the domainsDuty doc comment, and the arm log (agent.go:1632) pin "only the lease holder may reconcile" for the WHOLE pass. Invert to the new boundary, or a future reader re-gates it citing the old test.
• New pins: an alias derives no wildcard parent; the fold prefers a route over an alias; a not-ready primary publishes nothing; the stamping half runs ungated on every box; a first-route claim gets a reading.

What stage 1 does NOT do

It does not make a latency-steered custom domain work end to end. The client's TLS terminates at the NEAREST edge, before any backhaul; that edge serves the alias's cert only from the mirror, and the mirror holds one only after the issuer has ordered — which today needs a hello AT the issuer. Stage 1 removes the structural blockers (challenge admission, challenge serving, backhaul, and the fact that an alias homed off the issuer cannot be ordered at all). The cert EXISTING is stage 3.

---

Stage 2 — one status, structured records, capability

Rollout: stage 2's console roll TRAILS stage 3's fleet roll. On the original order, every pointing-but-certless domain would report issuing-cert during the gap — naming platform activity that is structurally impossible until the warm ships — and would advertise a failed state nothing can produce. That is the same honesty test used to rename verifying, applied to my own state name and failed.

2a. Vocabulary

One state per domain, DERIVED on read, never stored:

| state | means | derived from | |---|---|---| | pending-dns | no record found for this host yet | fresh reading, authoritative no-answer | | misdirected | resolves, but not to this deployment | DNSStatus "elsewhere" | | issuing-cert | points; no usable cert yet | pointing + no cert covering the host | | live | points AND a current cert covers it | pointing + cert | | failed | the platform tried and stopped | warm attempts exhausted (stage 3) | | unknown | nothing fresh reports on this host | no non-stale reading, or lookup failed |

misdirected rather than the issue's verifying: verifying named titogo's ownership-proof phase, which Paul cut from scope, so the phase the word names does not exist here — and reusing it for "your record resolves elsewhere" would label a customer-side condition as platform activity. This must be said on #299 so titogo does not build against the proposed vocabulary.

Plus reason (stable machine slug) and detail (human sentence).

status becomes legacy-frozen. Today status:"live" means "some non-stale box reported ANY reading" — it reads live while dns_status is elsewhere and no cert exists. Post-change the same row can read status:"live", state:"misdirected". Keeping both is right (the wire rule; status's values are frozen), but the trap needs fencing: (a) a test freezing status's exact current semantics so nobody "fixes" it toward state; (b) every first-party surface — CLI STATUS column, console Settings, carlos deploy's exit — moves to state in the same change; (c) the door comment and the issue reply mark status legacy.

2b. Structured records

records: [...] — what the customer must create. Corrections:

• alias_target is emitted ONLY when steering is armed. edge.<apps-domain> exists only where the steering converger maintains it (server.go:525-534); on a non-steering deployment the draft's unconditional field named a hostname with no records.
• The array needs an alternative-set marker: with steering, the English guidance offers CNAME or A records (view.go:163-165), and a flat array cannot say "one of these two sets" — the records would contradict the sentence beside them.
• A wildcard-enabled claim needs its _acme-challenge CNAME in the array (apidomains.go:409-410) — the platform already instructs it and stamps delegation_status; omitting it makes "what you must create" incomplete against our own surface.
• TTL 300, with the reason stated: steering withdraws a dead edge in ~90s, and a customer A-record TTL of 3600 nullifies that.
• The English guidance sentence changes in LOCKSTEP (apex guidance never mentions ALIAS today), or 2d's one-story rule breaks on day one.

Source: the same shared fold as 1c, with the same Generation staleness bound.

2c. Capability discovery — folded into the list answer

No new endpoint. The original justification ("facts an app needs before it holds a claim") conflated no claim with no app binding: every caller is already app-bound, and GET .../domains answers fine with zero claims. Folding a capability block into the list answer's top level gives present-or-absent for free (an old console omits the keys; a console with no door at all 404s — the exact signal carlos deploy already uses, deploy.go:915-923), and needs no new role decision and no new limiter.

{"domains": [...],
 "deployment": {"managed_domains": true, "apps_domain": "...",
                "steering_host": "...", "edge_ips": [...],
                "apex_alias_target": "...", "delegation_zone": "...",
                "states": [...]}}

This also retires domainsDoorMissing's 404-sniff (deploy.go:915-931) — our own version of titogo's TITO_EDGE_ATTACH_URL guessing.

2d. Cert currency — an issuer-written index, not request-path reads

+The original 3d was wrong twice. control/certs/ entries are <private key PEM><chain> (certsync.go:741-744), so "read the cert from the bucket" means a Get and an x509 parse of a key-bearing blob per host per list call — strictly more expensive than the box stamp it replaces, on a door whose existing precedent caps eight DNS lookups per call (domainListCNAMELookupCap). And a custom domain served by a delegated wildcard parent has no per-host entry at all — its cert is wildcard-<parent>.pem — so presence-by-key would read issuing-cert forever for exactly the wildcard customers.

Instead the console reads a small index — host → NotAfter — with no private keys in it.

The index is WRITTEN BY STAGE 3, read by stage 2. An earlier revision described it inside stage 2, whose rollout entry is a console roll only — leaving the writer assigned to no release at all. It is issuer-side fleet code: it ships and rolls in stage 3 (§3h), and stage 2 merely consumes it. Stage 2 cannot land before stage 3 for this reason as well as the issuing-cert one.

Storage shape differs from 3e's warm records, deliberately: NotAfter is fully derivable from the mirrored cache on every pass, so a single rebuilt-every-pass object is safe under last-writer-wins — a second issuer recomputes the same answer. Attempt counts are NOT derivable, which is why 3e needs per-host CAS keys. Two shapes, two reasons, stated so neither is copied to the other.

The index must replicate hostCertExpiry's coverage logic (reconcile.go:744-755): per-host entry OR covering wildcard PEM — and check <host>+rsa, a gap hostCertExpiry itself has. Fix that gap at the source in stage 1, where the stamps are already being touched, so the box-stamped path and the index cannot disagree.

2e. Scale and the poller contract

The list door cannot carry the poller stage 2 invites.

• GET .../domains sits behind instanceGate — cliInstanceBurst 60/min, keyed on the token hash and shared with the instance verbs. A status poller would eat the budget its signups and instance-creates run on.
• Every list call is ListClaims = one List plus one Get per claim in the whole bucket, filtered in memory afterwards (claims.go:175-199).
• Required: rebuild the list on the #165 fast-path claims index (already referenced at apidomains.go:436-439) or add a per-host GET .../domains/{host} reading exactly one claim object; state a poll cadence; move the poller's budget off the shared instance ceiling.

2f. Detach

The issue names "detach-failed-still-remove". After a 200 the claim is gone and the host leaves the list while edges still serve it until reconcile and the cert mirror catch up — a poller cannot tell "draining" from "never existed". Ruling: detach stays fire-and-forget and the answer says so; the alternative (a draining state) would require a tombstone the claim shape deliberately does not keep.

2g. Surfaces

carlos domains list gains a State column; console Settings shows the same state and records; carlos deploy's DNS exit branches on state instead of DNSStatus == "pointing" (deploy.go:958-975), which currently cannot tell "your DNS is wrong" from "your DNS is right, the cert is coming". All read ONE derivation function.

---

Stage 3 — the platform provisions the cert

3a. The warm set — alias-derived

The draft cited the wrong symbol. deploymentHosts() (plural, edge.go:738-756) excludes aliases by design (!up.alias) and its doc comment says "Not to be confused with deploymentHost (singular)". The singular (edge.go:831-833) is the set meant — but it is a PREDICATE with no enumerator. Built naively it would also warm every canary host (three labels under the apps domain, no wildcard parent covers them, DNS gate passes) — a per-host cert and CT-log entry for names that are today lazily issued and rarely visited. That, not custom domains, is where a first-run burst would come from.

An earlier revision said "aliases only". That is also wrong — it drops first-route claims, which mint a real ROUTE, not an alias (1d). So carlos deploy -kind static -host <site>, the shipped headline flow this design itself cites, would never have its cert proactively ordered OR renewed, and stage 2's failed would be unreachable for that whole class.

The right predicate is simpler than either: exact hosts this deployment serves that are NOT under the apps domain. A custom domain is a foreign domain by definition — the attach door refuses apps-domain hosts outright (apidomains.go:63-69) — so this one test covers aliases and first-route claims alike, and excludes canary hosts, platform hosts and everything a wildcard covers without needing to reason about label depth.

• own box: keys of e.current() (routes AND aliases),
• remote: entries from the home-map fold (1a's accessor, which must therefore expose ALL entries, not only alias-marked ones),
• minus *. rows (Allowed refuses them; a keys-of-map walk includes them),
• minus anything under the apps domain,
• minus names covered by a CONFIGURED wildcard parent (CARLOS_WILDCARD_DOMAINS, e.g. go.tito.io) tested by SHAPE against currentParents(), NOT certFor: certFor returns nil for a parent whose cert is not yet obtained, so a new account's apps would all be warmed per-host in the window before their wildcard lands.

3b. The pass

A per-host sibling of wildcardManager (wildcard.go:416-495), with three deliberate departures:

• No holding-context claim. 3a originally copied "the order runs under the holding's context" — impossible here: the trigger is m.GetCertificate, which takes no context and builds its own context.Background() with a 5-minute timeout (autocert.go:273-275). The wildcard manager can honour the holding because it drives the ACME client itself. Instead: re-check the gate BETWEEN orders (the backfill's per-entry precedent, certsync.go:886) and accept a ≤5-minute overhang, inside the double-holder envelope issuerHostPolicy already documents. Consequence stated honestly: a finishing order's cachePut re-checks the gate, so the cert lands local-only and the new issuer re-orders it — bounded waste, not a hazard.
• The warm calls GetCertificate for every warm-set host EVERY pass, unconditionally — this is what owns renewal. autocert cannot renew through a skip-if-fresh check: m.cert returns any unexpired cached cert, so a cert 29 days from expiry is a cache hit and no order happens. Per-host renewal is exclusively domainRenewal timers, which die on every fleet roll and re-arm only via a GetCertificate that reaches m.cert. On a steering deployment a custom domain's visitors may NEVER land on the issuer, so after a roll nothing re-arms the timer and the cert expires at day 90 silently. An unconditional call is one cacheGet plus startRenew — cheap, and exactly the re-arm. Pin it with a test.
• No cache-load-before-gate step. Unlike the wildcard manager, the warm SERVES nothing (per-host serving is the mirror plus autocert), so a non-issuer scanning caches is pure waste. It stands down at the gate.

Retained: per-host hourly backoff on failure; a harder backoff on an ACME rateLimited error than on a validation failure, since hourly retries into a rate limit compound it; a per-pass order cap that returns a SHORT delay while capped work remains (the wildcard pass() precedent) so a backlog does not trickle out over days.

Arm only when e.staticStore != nil. An agent-less carlos edge is ungated (issuerGate nil → yes), and would otherwise start proactively ordering on hobbyist boxes.

3c. The DNS gate

Resolve each host against the deployment edge set and order only when it points. LE's failed-validation limit is 5 per account per hostname per hour and the ACME account is shared per issuer — ordering for a half-finished DNS is how one customer burns everyone's budget.

• Require ALL resolved answers in the set, not any: partial pointing passes an any-match gate and then fails validation from LE's vantage, burning exactly the budget the gate protects.
• The input does not exist in internal/edge yet. 1c's fold lands behind internal/host, and host imports edge, never the reverse. 1c's shared reader package is what makes this reachable; the edge also already parses EIP in edgesFileView (homemap.go:125-130), so the accessor can live on the home map with 1c's Generation bound and env union.

3d. The ECDSA trap — verified

m.GetCertificate(&tls.ClientHelloInfo{ServerName: host}) with an EMPTY hello: supportsECDSA returns false (nil SignatureSchemes and nil SupportedCurves skip their checks; the CipherSuites loop finds nothing) → certKey{isRSA:true} → the warm mints an RSA cert under <host>+rsa while browsers ask for <host>. The order is spent, nothing is satisfied, and the first visitor still triggers a second issuance.

Fix: advertise an ECDSA suite in the synthetic hello. Independently confirmed against x/crypto v0.52.0 (go.mod:17). Everything else checks out: ServerName must be non-empty and contain a dot; idna/lowercasing applied internally; nil SupportedProtos → wantsTokenCert false; no Conn dereference. The repo already ports supportsECDSA as helloSupportsECDSA (certsync.go:1285-1327) — pin PARITY between the two copies, plus the non-+rsa-key assertion.

3e. Where warm outcomes go

Per-host CAS keys, not one file. control/cert-warm/<host>.json, written with the putCert CAS idiom. A whole-file map has no per-host last-writer-wins safety: two transient holders, or a failover, overwrite each other wholesale, and a takeover issuer starting from empty in-memory state erases every attempt count. Each record carries a written-at stamp, and the console applies an age bound — a wedged issuer must not read as "warm quiet". The writer prunes records for detached hosts.

Verified: the fleet door is an allowlist (aclRead, storedoor.go:383-397), so any new control/ key is denied by default — but TestDoorNeverServesCertMaterial (storedoor_test.go:515-567) must gain the new keys. Cert writes bump no serial (certsync.go:25-28) — correct here too. The bucket-writer audit and the ingress spec's writer table need a new row ruled "issuer" before the write exists.

3f. Removal — expiry-bounded, never inference-driven

Nothing ever deletes control/certs/<host> for a detached domain (Delete fires only for spent tokens). The backfill will not re-publish it (ownsCertName refuses), but the object lingers, the mirror serves it to matching SNI until expiry, and the expired object then lingers forever.

The sweep's predicate must be EXPIRY, not detachment. A sweep keyed "no claim exists for this host" would delete every non-claim-backed cert in the deployment — every platform host, every wildcard PEM, the account keys. Worse, registry lag or a stale edges read could take down a live host's certs fleet-wide via the mirror. This repo's own rule is that inference never destroys owner property (reconcile.go §1c).

So: delete only entries whose LEAF IS ALREADY EXPIRED plus a margin. That also dissolves the "mirror serves it until expiry" concern by construction, and makes a wrong deletion harmless — the entry was already dead. Never "detached implies delete". Prune cert-warm records on the same pass, on the same terms. Issuer-side; #243's token-litter ruling is the precedent for assigning it, not for its predicate.

3h. The cert index (read by stage 2 §2d)

On every warm pass the issuer rebuilds control/cert-index.json: host → NotAfter, for every host in the warm set, resolved through hostCertExpiry's coverage rules (per-host entry, <host>+rsa, or a covering wildcard PEM). Whole-file and last-writer-wins is safe here because the content is fully derived — a second issuer recomputes the same answer (contrast 3e, whose attempt counts are not derivable and need per-host CAS). Carries a written-at stamp; the console applies an age bound so a wedged issuer does not read as "everything current". Added to TestDoorNeverServesCertMaterial's pinned list and to the bucket-writer audit's table, ruled "issuer", before the write exists.

3g. Observability

Failures are 3e. Add the success line (one per obtained host) and a per-pass summary, matching the wildcard manager's logging discipline.

---

The shared edges-file reader — the plan's load-bearing artifact

Six things stand on it: 1a's ReconcileAliases refusal and door check, 1c's EIP fold, 2b's records, 2c's edge_ips, and 3c's order gate. Earlier revisions gave the riskiest new surface the least design, so it gets its own contract:

• Where: one small exported package (internal/edgesfile) that owns the wire struct. internal/host (writer), internal/edge, the console and internal/domains all import it. internal/steering keeps its own deliberately narrow view (it reads no Hosts — steering.go:57-60) and is named here as a knowing exception rather than left unlisted, per the consumer-list rule.
• What it answers: the live edge-IP set (union with PLATFORM_EDGE_IPS), and per-host "is this published as a non-alias home by a live box".
• Liveness: the box-snapshot join above, never Generation.
• Failure: degrades to env-only, never to empty — nothing here deletes, so widening is always the safe direction.
• Cost: cached with a refresh cadence on the console side; the list door must not pay a per-request fold.

Rollout order

1. Stage 1 reader — fold preference + alias/full-entry accessor in the reader types. Inert no-op roll.
2. Stage 1 writer — split into independently green PRs rather than one: (i) alias publication + fold + ReconcileAliases refusal + door check; (ii) the #289 inversion + PurgeTrashed; (iii) the shared reader + live EIP set + dnsTargets; (iv) route readings + stamp age + resolver-error value + the +rsa fix. Fleet roll.
3. Stage 3 — the warm and the cert index. Fleet roll.
4. Stage 2 — the API, CLI and console. Console roll plus a CLI release (tap/apt/website, per the standing sync rule), LAST, so no state the deployment cannot yet produce is ever advertised.

Stage 1 ships real value alone (a live security gap, a live regression, a live false-negative). Stages 3 and 2 together are what make live mean what #299 asks it to mean.

Live checks owed before the first armed roll

• Count control/certs/ keys against the enumerated warm set on the flagship issuer — confirm the first pass orders nothing for the existing estate.
• Confirm which box currently holds the housekeeper lease on flagship and tito, to size 1b's live blast radius.

---

Addendum — what was built, and where it diverged (2026-08-27)

The spec above was written against main at da9a7ee. By the time it was implemented main had moved to 4235e9f and had independently built most of stage 1 (#287's alias publication, #303's per-box stamps, the Reconcile/StampHealth split). Stage 1 was therefore re-derived as a salvage — see .superpowers/sdd/salvage-onto-main/progress.md — and stages 2 and 3 were built against the newer base. The divergences below are decisions, not omissions, and each names what it would cost to be wrong.

The vocabulary gained checking and never gained failed

checking (attached; no edge has reported yet) was split out of unknown. Both mean "no verdict", but they are opposite news: one is the ordinary first few minutes after an attach, the other is a fault on our side. Collapsed, every successful attach opened with the word "unknown" — which an e2e test caught by asserting on the freshly-attached row.

failed is absent. It would mean "the platform tried and stopped", which requires §3e's per-host warm-outcome records — not built (below). The spec's own honesty test, the one that renamed verifying, applies to it directly: a state nothing can produce must not be advertised. A test now pins that the advertised set and the producible set are exactly equal, so failed returns with §3e and not before.

§2d's cert index (§3h) was NOT built; stamps are folded instead

The spec argued for an issuer-written host→NotAfter index because reading control/certs/ on the request path means a Get and an x509 parse of a key-bearing blob per host, and because a wildcard-covered domain has no per-host entry at all.

Both objections stand — against reading the BUCKET. They do not apply to the path actually taken: the boxes already stamp cert expiry into the registry, status.LoadBoxes already carries those stamps to the console, and the console already folds them across boxes (the freshest-stamp fold). Stage 2 reads that fold. The wildcard case is covered because hostCertExpiry already checks the covering wildcard PEM — and the <host>+rsa gap the spec flagged was fixed at the source, so the box-stamped path and any future index cannot disagree.

Cost if wrong: the fold is bounded by box staleness, so a deployment whose boxes all go stale reads checking rather than live. That is the correct failure direction, and §3h remains available if the fold proves too coarse.

Not building it also avoided a new bucket object, a new writer-table row, a new aclRead allowlist entry and an update to TestDoorNeverServesCertMaterial — none of which buy anything the existing stamps do not already carry.

§3e and §3f were follow-ups; §3e is now built

§3e (per-host control/cert-warm/<host>.json CAS records) and §3f (the expiry-bounded cert sweep) shipped after the first change, not with it. The warm worked without either: it ordered, it renewed, it backed off per host, and it logged. What was missing was durable observability of warm outcomes across a failover, and the pruning of certs for long-detached hosts.

§3e is built (2026-08-29). internal/certwarm owns the wire shape for both sides, the issuer writes a record through the same CAS loop putCert uses (extracted as putCAS), and the console folds it into domainState. Three decisions the spec did not settle, decided here:

• A record exists only while a host is FAILING. Success deletes it. That makes absence the healthy case, so the console's fold costs one object per BROKEN hostname rather than one per domain — which is what makes it safe to add to a list door that already pays one Get per claim (#173). The per-host door reads one key instead of listing, preserving the property #328 exists for.
• Freshness is judged against next_attempt_at, not written_at. A rate-limited host is deliberately not retried for twelve hours, and a bound on write time alone would call that healthy silence stale every time. The accepted limit: an issuer that wedges immediately after writing a rate-limited record is believed for up to fourteen hours. Closing that needs a per-pass heartbeat object — a second key and a second writer-table row for a sharper edge on an already rare case.
• failed fires at three consecutive failures, or immediately on a rate limit. Three is about three hours of trying. The rate-limit exception is because the retry is twelve hours away, and a member watching a "usually a minute or two" message for half a day is worse served than one told plainly what is happening.

failed never overrides a customer-side condition (misdirected, pending-dns) and never overrides a live certificate: it is only ever the alternative to issuing-cert. The vocabulary honesty test now produces it from an input the platform can actually produce, which is the same bar every other state clears.

§3f is built (2026-08-29), in internal/edge/certsweep.go, and it took #243's spent-token litter with it — one issuer-side pass over control/certs/, two predicates, because the two kinds of litter are not the same kind of thing:

• Spent challenge tokens (#243) go on AGE alone. A validation's whole life is seconds and autocert's order context is five minutes, so the one-hour TTL is generous by two orders of magnitude — deliberately, since deleting a token out from under a live validation burns the order.
• Certificates go only on their own leaf's expiry, plus a month. §3f's ruling is unchanged and is the reason the file opens with it: a sweep keyed "no claim exists for this host" would delete every platform host's cert, every wildcard PEM and the account keys, and a registry lag could take a live host down fleet-wide through the mirror.

Three bounds the spec did not name:

• A parse floor. Nothing younger than sixty days is read at all. autocert renews at ~30 days remaining on a 90-day certificate, so a healthy entry's object stamp never gets that old — which makes the steady-state cost one listing and zero reads, instead of the per-object N+1 this would otherwise be. An entry that IS that old is one nothing is renewing, which is exactly the population worth reading.
• Anything unreadable is left alone. A sweep that deletes what it cannot parse is a sweep that deletes tomorrow's format.
• Fifty deletions per pass. A bug in the predicate removes at most fifty objects before somebody reads the log.

The gate check moved above the empty-warm-set return in pass(): token litter and dead certs exist in a deployment with no custom domains at all, and the old ordering would have meant such a deployment never swept. A non-issuer still sweeps nothing.

The shared reader is a READER, not the wire-shape owner

internal/edgesfile reads the deployment-wide edges picture. It does not own the writer's struct: internal/host had developed that file substantially (wildcard parents, withheld-alias throttling, EIP-reuse-on-blank), and re-plumbing it onto a shared type would have fought a file under active development for no gain to #299. The two shapes are joined by a test instead, which also preserves the additive-wire property — the writer can add a field and roll before every reader understands it.

Rollout

The spec required stage 3's fleet roll to precede stage 2's console roll, so that issuing-cert never names activity that cannot happen. Both ship in one branch, so the constraint applies to the ROLL and not the merge: roll the fleet before the consoles. Rolled the other way, every pointing-but-certless domain reports issuing-cert while nothing is issuing.

Still owed

• §2e's poller contract: GET .../domains remains behind instanceGate's shared 60/min budget and still costs one Get per claim in the bucket. A status poller must not be pointed at it until the #165 claims index or a per-host door lands. This must be said on #299 — it is the one part of the issue's ask this change does not make safe.
• deploy.go's domainsDoorMissing 404-sniff could now be retired in favour of the capability block. Left in place: it still works, and retiring it is not free of risk against older consoles.
• The console Settings page still renders the pre-state wording. The CLI and the deploy exit moved; the page has not.