portal-mojo 0.2.19 → 0.2.21

package/docs/admin-edge.md

@@ -1,210 +1,214 @@
-# Edge Admin
+# Edge Admin · Serving
 
 ```ts
 import {
     EDGE_ADMIN_SECTION, VhostsPage, VhostDetail, VhostWizard, openVhostWizard,
     UpstreamsPage, BlocklistPage, EdgeVhostModel, EdgeRouteModel,
     EdgeUpstreamModel, EdgeBlocklistModel, buildVhostPayload,
-} from 'portal-mojo/admin';
+} from 'portal-mojo/admin'; // also portal-mojo/admin/infrastructure
 ```
 
-The same names are on `portal-mojo/admin/infrastructure`.
-
-`EDGE_ADMIN_SECTION` contributes Infrastructure routes at `edge/vhosts` and
-`edge/upstreams` (or the same paths under an embedded `/system` mount). The
-fleet blocklist is a route of Network Security, at
-`security/network/edge-blocklist`. There are no record routes: a vhost opens in
-`modal.detail`.
-
-Consumer contract: django-mojo `mojo/apps/edge/`. The mock in
-`client/mock.ts` returns the same graphs and the same refusals, word for word
-where the server has words.
-
-## Permissions
-
-- Vhosts, routes, upstreams — view: `sys.view_dns | sys.manage_dns | sys.security`.
-- Vhosts, routes — change or delete: `sys.manage_dns | sys.security`.
-- Upstreams — switch on or off: `sys.manage_dns | sys.security`.
-- Upstreams — declare or retire: `me.is_superuser === true`. The server gate
-  is `require_platform_admin`, which also refuses API keys.
-- Blocklist — view: `sys.view_security | sys.manage_security | sys.security`
-  (`EDGE_BLOCKLIST_VIEW_PERMS`). This is wider than `SECURITY_VIEW_PERMS`: the
-  server lets `manage_security` view, and manage does not imply view on the
-  client, so the clause is spelled out.
-- Blocklist — change or delete: `sys.manage_security | sys.security`.
-
-A section gate and a route gate both apply. A security-only operator is denied
-every DNS-gated section, which is why the blocklist does not live under Edge.
-The blocklist has no group: a member-scoped grant and `?group=` open nothing.
-
-**House rows.** A vhost on a group-less domain is platform property. It never
-appears in a non-superuser's list, even with a global grant, and its detail,
-its routes and creating one are refused to everyone else. The vhost graphs
-carry `domain: basic`, which has no `group`, so house-ness cannot be read off a
-vhost row. The wizard's domain picker passes `group__isnull: false` for
-non-superusers so a house domain is never offered to someone who would be
-refused at Finish.
+`EDGE_ADMIN_SECTION` contributes Infrastructure routes `edge/vhosts` and
+`edge/upstreams`, relative to the standalone or embedded `/system` mount.
+Network Security owns `security/network/edge-blocklist`. Records open in
+native modals, not record routes. Consumer source: django-mojo `mojo/apps/edge/`;
+`client/mock.ts` mirrors its graphs and refusals, with wording limits below.
+
+## Permissions and ownership
+
+All clauses are global; section and route gates both apply.
+
+| Resource/action | Authority |
+|---|---|
+| Vhost, route, upstream view | `sys.view_dns OR sys.manage_dns OR sys.security` |
+| Vhost/route change or delete; upstream enabled switch | `sys.manage_dns OR sys.security` |
+| Upstream declare/retire | Literal `me.is_superuser`; server `require_platform_admin` also refuses API keys |
+| Blocklist view | `sys.view_security OR sys.manage_security OR sys.security` |
+| Blocklist change/delete | `sys.manage_security OR sys.security` |
+
+`EDGE_BLOCKLIST_VIEW_PERMS` deliberately includes `manage_security`: manage does
+not imply view in the client. Security-only operators cannot enter DNS-gated
+Edge, hence the separate blocklist route. Member grants and `?group=` do not
+open the fleet-wide blocklist.
+
+A vhost on a group-less domain is a **house row**: non-superusers cannot list,
+inspect or create it or its routes, even with global DNS grants. Vhost graphs'
+`domain: basic` omits group, so never infer ownership there. Non-superuser domain
+choices use `group__isnull: false`. Resolve the domain's own graph before offering
+enabled upstreams: `group=<owner>` includes owned and shared rows; platform domains
+use `group__isnull: true`. Unresolved ownership disables selection.
 
 ## Endpoints
 
-| Address | Verbs | Notes |
-|---|---|---|
-| `/api/edge/vhost` (+`/<id>`) | list, read, create, update, delete | `list` graph for tables, `default` for one row |
-| `/api/edge/route` (+`/<id>`) | list, read, create, update, delete | `site_api` vhosts only; filter `vhost` |
-| `/api/edge/upstream` (+`/<id>`) | list, read, update | update writes `is_enabled` only; no create, no delete |
-| `/api/edge/upstream/declare` | POST | `{name, kind, host+port \| socket_path, group?}`; platform administrators |
-| `/api/edge/upstream/retire` | POST | `{upstream}`; disables, keeps the row; platform administrators |
-| `/api/edge/blocklist` (+`/<id>`) | list, read, create, update, delete | fleet-wide |
-
-## The four kinds
-
-The wizard never shows a kind dropdown over one long form. Its first step is
-four cards in plain words; the following steps show only that shape's settings.
-
-| Kind | Card | Needs | May carry | Refuses |
-|---|---|---|---|---|
-| `api` | API host | `upstream` | `quiet_paths`, `serve_static` | `spa`, `redirect_to` |
-| `site` | Static site or SPA | — | `spa` | `upstream`, `quiet_paths`, `serve_static`, `redirect_to` |
-| `site_api` | Site + API paths | routes | `spa`, `serve_static`, `quiet_paths` | whole-host `upstream`, `redirect_to` |
-| `redirect` | Redirect | `redirect_to` | — | everything else |
-
-`buildVhostPayload(draft, { create })` is the one place a draft becomes a
-request. It sends each knob the chosen kind does not carry as its empty value,
-so a draft that visited another shape cannot leak that shape's settings, and
-an edit that changes kind clears what the old kind held. It never sends
-`mojosec_policy`. A vhost that carries an edge evidence policy therefore cannot
-change kind, or its single-page-app switch on a `site`, from here: the server
-requires the policy's response class to match and refuses, and its message is
-shown.
-
-Shared rules, each mirrored by a validator in `edge/models.ts`:
-
-- `label`: empty serves the bare domain, `*` the wildcard, otherwise one DNS
-  label. The address (`server_name`) is derived, never typed.
-- `body_size_mb`: whole number, 1 to 4096, default 50. Not offered for a
-  redirect.
-- `pool`: must be one the deployment declares (`EDGE_POOLS`, default
-  `["default"]`). The refusal names the declared set.
-- `domain`: set once. An edit shows it read-only and never sends it.
-- `redirect_to`: a host name. No scheme, path, port or wildcard.
-- A route prefix or quiet path starts with `/`, uses letters, digits, `.`,
-  `_`, `-` and `/`, and has no `//` or `..`. A route prefix cannot be `/`.
-
-## What is checked when
-
-The server checks most things on every save. Two things are checked **only
-when the row is enabled**:
-
-- the certificate belongs to the vhost's domain and covers its address;
-- no other enabled row has the same domain and label.
-
-So a disabled row may hold a certificate that does not cover it yet, and may
-share a name with a live row. That is how a replacement is staged: create it
-disabled, then disable the old one and enable the new one. The wizard warns
-when the chosen certificate does not cover the address (`certificateCovers`,
-which knows that a wildcard covers exactly one label and never the apex) and
-still lets the row be saved disabled.
-
-## The create order for `site_api`
-
-A quiet path on a `site_api` vhost must sit under one of its route prefixes,
-and the server reads those prefixes from the stored row. A create that carries
-quiet paths is therefore always refused with "none declared". The only order
-that works is:
-
-1. create the vhost, **disabled** and without quiet paths;
-2. create its routes, one at a time;
-3. save the vhost once more with the quiet paths and the enablement the user
-   chose.
-
-The wizard does exactly this. Step 3 always runs, so the enable-time checks
-happen at the end and a failure part-way never leaves a live vhost with no
-routes. If a step is refused the wizard stays open and says which step and
-what already exists. Finishing again continues from there: it never posts the
-vhost a second time and never repeats a route that landed.
-
-The server will store an enabled `site_api` vhost with no routes. The wizard
-does not: at least one valid route is required at the settings step and again
-at review.
-
-In edit mode routes are read-only, with a pointer to the detail view, which
-owns adding, changing and deleting them. Changing a `site_api` vhost to
-another kind while it has routes is blocked with the count; the server refuses
-it too. Until the stored routes have been read, or if that read fails, the
-wizard does not judge quiet paths against them and leaves that to the server.
-
-## Vhost detail
-
-The detail follows the admin modal contract (`admin-modals.md`). The header
-switch enables and disables. Edit and Delete are in the header menu, shown
-only with the manage grant. Delete asks for confirmation, names the address,
-says its routes go with it, and points at Disable as the choice that can be
-undone. A refused enable shows the server's message in the overview. Routes
-are content: the Routes section lists them and owns add, change and delete.
-
-## Upstreams
-
-An upstream is a destination a vhost may proxy to. Only `is_enabled` can be
-written on one; its name and destination are fixed when it is declared. The
-list shows the active group's upstreams and the shared ones. Retiring disables
-the row and keeps it: vhosts and routes that reach it stop being served and
-are not repointed. The retire control names that consequence before it acts.
-The wizard's upstream pickers list enabled upstreams only.
-
-## Blocklist
-
-An entry matches an IP network or a user-agent pattern, in one of four modes:
-`log` (recorded, still served — the default), `enforce` (refused), `allow` (an
-exemption) and `off`. Create an entry in `log`, watch the edge watch log for
-it, then switch it to `enforce`. A change reaches the fleet in about ten
-minutes.
-
-An `ip` value is stored as its network: `10.1.2.3/8` is saved as `10.0.0.0/8`.
-The editor shows the saved value from the response.
-
-## Not built here
-
-- **Claim-reserved.** The plan for this page asked for a superuser control to
-  claim a reserved name. django-mojo removed the reserved-name mechanism, its
-  field and its action (commit `bc2c57b1`, in every release since v1.7.1), so
-  there is nothing for such a control to call.
-- **`mojosec_policy`.** Shown read-only on the vhost detail. It is set by the
-  platform and never sent from here.
-- **Web apps, releases and alias addresses.** An alias address appears in the
-  vhost list like any other row; `alias_of` is in no graph, so it cannot be
-  told apart, and a refused edit shows the server's message.
-
-## Pitfalls
-
-- Do not send `quiet_paths` on a `site_api` create. See the create order.
-- Do not treat a saved, enabled row as proof the certificate covers it from
-  the client check alone; the server's answer on save is the proof.
-- The mock's messages for database uniqueness (a second enabled vhost on one
-  name, a repeated route prefix, a repeated blocklist value, a repeated
-  upstream name) are the mock's own words. The server reports these from a
-  database constraint, and its wording was not measured.
-- The server parses a blocklist address with Python's `ipaddress` and compiles
-  a user-agent pattern with Python's `re`, and the mock follows Python, not
-  JavaScript: `010.1.2.3` and `\q` are refused, `10.0.0.0/255.0.0.0`,
-  `(?i)bot` and `a*+` are accepted. The reason after "does not compile" is the
-  mock's own wording. The editor's own check is only a first pass and never
-  compiles the pattern; the server's answer on save is the verdict.
-- A vhost update that names an upstream or certificate that does not exist is
-  refused by the mock with the same words as a missing one. The server's
-  wording for an unknown id was not measured.
-- The declare-upstream dialog and the blocklist editor refuse Escape and the
-  backdrop while their write is in flight, and the editor's save and delete
-  share one pending state. `npm run verify:admin-edge` holds each write open
-  and checks this.
+| `/api/edge/…` | Contract |
+|---|---|
+| `vhost`, `vhost/<id>` | list/read/create/update/delete; table graph `list`, record graph `default` |
+| `route`, `route/<id>` | list/read/create/update/delete; `site_api` only; filter `vhost` |
+| `upstream`, `upstream/<id>` | list/read/update `is_enabled`; no collection create/delete |
+| `upstream/declare` | POST `{name, kind, host+port OR socket_path, group?}` |
+| `upstream/retire` | POST `{upstream}`; disables and retains row |
+| `blocklist`, `blocklist/<id>` | list/read/create/update/delete; fleet-wide |
+
+Refused saves reject at the one client boundary. Public save/delete helpers
+accept an optional `beforeWrite` guard, invoked before **every** fresh-auth attempt.
+
+## Serving tasks
+
+The lean table shows hostname/domain, type and enabled intent. Pool and timestamps
+belong in inspection. The Domain picker writes URL filter state; search supports
+label/type/pool, not derived full hostnames. Persisted key remains
+`admin:edge:vhosts`; public `Vhost*` exports and `/edge/vhosts` remain compatible.
+
+- **Add hostname:** Hostname → Certificate → Review. Name, type and destination
+  belong to one Hostname task. Compact type choice,
+  only relevant destination controls, visible action footer. Other settings holds
+  pool/body/static/quiet paths without an accordion. Success opens the saved row.
+- **Edit:** Hostname / Certificate / Settings share one controlled draft.
+  Validation selects the relevant tab and focuses the invalid input. Saving retains
+  the active panel. Domain is immutable. Info-icon popovers carry secondary help.
+- **Inspect:** Overview / Routes / Settings; Routes only for Site + API.
+  Overview shows actual redirect/API destination first, followed by the certificate
+  name, stored status/expiry and direct Change certificate action. Settings holds other knobs, timestamps and
+  read-only platform policy. Header owns enable/disable, Edit and Delete.
+- **Routes:** paginated local table, focused Add/Edit dialogs and explicit removal
+  confirmation. Before rename/removal, inspect current quiet paths and complete
+  bounded routes. Block orphaning a quiet path and identify what to repair in
+  Settings first; no atomic multi-row operation is implied.
+
+Styles are scoped to these surfaces; shared Tabs/DetailView and Dashboard behavior
+are unchanged. See [presentation QA](admin-presentation.md).
+
+## Kinds, payloads and validation
+
+| Kind | Required | Supported options | Refused |
+|---|---|---|---|
+| `api` | `upstream` | quiet paths, static files | SPA, redirect |
+| `site` | — | SPA | upstream, quiet paths, static, redirect |
+| `site_api` | explicit routes on create | SPA, quiet paths, static | whole-host upstream, redirect |
+| `redirect` | `redirect_to` | — | other kind-specific knobs |
+
+`buildVhostPayload(draft, {create})` allowlists the chosen kind and sends empty
+values for its unsupported knobs, clearing values from a former kind. It never
+sends `mojosec_policy`. The server can refuse kind/SPA changes that conflict with
+that policy's response class; show its refusal.
+
+Client mirrors in `edge/models.ts`; server remains authoritative:
+
+- Label: empty apex, `*` wildcard or one lowercase DNS label. Derive `server_name`.
+- Body: integer 1–4096 MB, default 50; absent for redirect.
+- Pool: deployment-declared `EDGE_POOLS`, default `["default"]`; no client catalog.
+- Redirect: hostname only; no scheme/path/port/wildcard.
+- Route/quiet path: leading `/`, letters/digits/`._-/`, at most 128 characters,
+  no `//` or `..` segment. A route cannot be `/`.
+
+Only enabled rows require a certificate belonging to the domain and covering the
+address, and a unique enabled domain/label. Stage a replacement disabled, disable
+the old row, then enable the replacement. `certificateCovers` knows a wildcard
+covers one label and never the apex. Coverage stays Unknown until the full
+certificate graph (including SANs) is read; disabled staging remains available.
+
+## Staging and uncertain writes
+
+`site_api` quiet paths require stored route prefixes, so create in this order:
+
+1. Vhost disabled, without quiet paths.
+2. Routes sequentially.
+3. Final vhost save with quiet paths and chosen enabled intent; always perform this
+   step so enable-time validation runs last.
+
+The wizard requires at least one valid create route, though the server accepts
+route-less enabled rows. Edits and Site → Site + API conversion may remain
+route-less; author routes in detail. Existing routes block conversion away from
+Site + API. Unread routes defer quiet-path validation to the server.
+
+Retain acknowledged steps on explicit refusals. Transport loss, malformed receipts
+and 5xx may follow committed writes and stay **unconfirmed**, never “refused” or
+“still disabled”. An unacknowledged create cannot replay: close and inspect Serving.
+An acknowledged partial create offers **Inspect saved hostname**.
+
+**Observe outcome** reads only. Route continuation requires the matching stored
+prefix/upstream; absence stays blocked. Edit/final-save observation compares the
+exact normalized submitted payload, including FK IDs and arrays; unchanged or
+conflicting fields retain the guard and show differences. Only an exact match
+clears it. Continuing requires explicit **Add hostname** or **Save changes**;
+observation never automatically replays a mutation.
+
+Detail edits, route writes, enablement and deletion serialize through one pending
+state. Lock Escape/backdrop/X during preflight and writes. Before each write and
+fresh-auth attempt, check original session/current permission; owner disposal
+closes nested dialogs and prevents later staged writes. Closing cannot cancel an
+already submitted server operation or prove its outcome.
+
+Route safety reads paginate to at most 2,000 rows and reject changed counts,
+duplicate IDs, incomplete pages and excess inventory. Same-count concurrent edits
+cannot all be detected; there is no atomic snapshot guarantee.
+
+Delete confirms the address, stopped serving and route cascade, warns linked sites
+can stop serving, retains domain/certificate and offers Disable as reversible.
+
+## Serving evidence
+
+Read-only `ServingReadiness.tsx`/`serving-data.ts` keep positive projections outside
+Query. `GET /api/account/admin/bootstrap` requires an authenticated matching global
+identity with `view_admin OR manage_users OR manage_settings OR admin` (literal
+superuser bypass); DNS grants alone never request it. Retain only matching user
+ID/superuser, setup capability and edge available/HTTP/issuance fields.
+
+`GET /api/account/admin/setup/readiness?section=hosting_vhosts` additionally requires
+successful same-identity bootstrap with setup capability and literal superuser in
+both Me and bootstrap. Server still refuses key-backed/noninteractive sessions;
+client invents no provenance flag. Schema 1 validates status/time/count/coverage,
+keeps the selected section only, caps checks at 64 and scalar details at 16 keys.
+
+The unboxed summary sits within the page header and keeps timestamp and
+partial-report warning visible. DNS-only sessions that cannot request bootstrap
+see no global checks summary; admitted observation failures remain visible. Check
+details holds technical evidence. HTTP is a file-rendering setting; DNS-01 is an
+issuance method. Checks cover enabled rows' domain/certificate status, **not** live
+serving, expiry/coverage/material installation, fleet convergence/nodes/generation.
+An omitted hostname has no individual verdict. Enabled/saved is configuration intent.
+
+Errors, denied attempted reads, old-backend 404s and malformed responses show Unavailable or
+Unknown. Failed refresh clears old evidence. UID/session revision fence reads;
+same-session loss of admission/bootstrap/superuser/setup authority disposes report
+modals. Reads occur only while mounted/admitted, without polling; configuration
+changes refresh the panel.
+
+## Upstreams and blocklist
+
+An upstream's name/destination are fixed at declaration; only enabled is editable.
+Lists include owned and shared rows. Retiring disables and retains it: reaching
+vhosts/routes stop serving and are not repointed. Confirm that consequence.
+
+Blocklist modes: `log` (default, still served), `enforce` (refused), `allow`
+(exemption), `off` (retained inactive). Start in log, inspect the watch log, then
+enforce. Propagation takes about ten minutes. Save IPs as canonical networks:
+`10.1.2.3/8` becomes `10.0.0.0/8`; show the returned value. Declare and blocklist
+editors guard native dismissal; blocklist save/delete share pending state.
+
+## Boundaries and pitfalls
+
+- No claim-reserved action: django-mojo removed it in `bc2c57b1` (v1.7.1 onward).
+  Platform-owned `mojosec_policy` is read-only; never send it.
+- No owning-WebApp/alias graph, pool catalog, route-disable flag, atomic multi-route
+  write or per-host live readiness. Aliases look like other rows; show refusals.
+- Mock uniqueness wording (enabled hostname, route prefix, blocklist value,
+  upstream name) and missing-relation wording were not measured on the server.
+- Blocklist parsing follows Python `ipaddress`/`re`, not JS RegExp: reject
+  `010.1.2.3` and `\q`; accept `10.0.0.0/255.0.0.0`, `(?i)bot`, `a*+`.
+  Compilation reason text is mock-specific; local validation is only a first pass.
+- Client certificate checks are advisory; only the server validates a save.
 
 ## Themes and showcase
 
-Styles live in `src/styles/components/admin-edge.css` and ship in
-`portal-mojo/styles.css`; the app declares the tokens. They are built from
-tokens only, so both themes render from one sheet. The showcase still carries
-its own identical copy until it adopts the package stylesheet. The showcase
-demo (Develop → Components → Admin → Edge) runs the shipped pages against the
-mock under five identities: platform administrator, DNS manager, DNS viewer,
-security manager and security viewer.
-
-`npm run verify:admin-edge` is the executable contract.
+Canonical token-only `src/styles/components/admin-edge.css` ships through
+`portal-mojo/styles.css`, imported by Admin and Showcase. Demo: Components → Admin
+→ Edge, under platform administrator, DNS manager/viewer and security manager/viewer.
+Verify both themes, desktop/390px, opened dialogs, keyboard/help, busy and error states.
+
+Contracts: `npm run verify:admin-edge` (API plus held dialog writes),
+`node scripts/verify-admin-serving-mounted.mjs` (all shapes, staging, draft/focus,
+conversion, partial inspection, uncertainty, route guards/session races),
+`node scripts/verify-admin-serving-mounted-evidence.mjs` (DTO bounds, exact gates,
+unknown evidence, failed refresh, auth/permission replacement). Mounted tests do
+not establish native layout; actual browser QA remains required.

package/docs/admin-fleet-configuration.md

@@ -7,8 +7,9 @@ page checks `is_superuser === true` before fetching. Backend authority remains
 mandatory, including rejection of diagnostic/key-backed sessions and fresh auth.
 
 Applications register their schema in django-mojo. The page renders the returned
-section, label, description, default, type and restart requirement; no application
-setting names are hardcoded. Each field defaults to Keep current value. Set value
+section, label, description, default, type and restart requirement; application schemas remain server-owned. The three managed shared-validation
+connection fields route to the dedicated topic below, rather than appearing as
+independently editable generic fields. Each field defaults to Keep current value. Set value
 and Remove published override are explicit actions. Clearing falls back to base
 configuration/default; it does not promise erasure of a bootstrap secret.
 
@@ -48,3 +49,98 @@ example. Mock Portal uses representative registered settings and an offline node
 Django receives this page only after a canonical Portal artifact is built and
 vendored; follow `docs/admin-artifact.md` and the Django vendor tool. Ordinary
 Vite build output is not the canonical artifact.
+
+## Shared validation connection
+
+Operations → Fleet Configuration → Shared validation connection is a private, lazy
+route. It requires a current literal superuser; the server additionally requires
+an active interactive session, same-origin writes and fresh authentication.
+Key-backed sessions are rejected by the server even when their user is an owner.
+
+On the validation hub, update every expected node using the existing Deployments
+controls, then use **Enable shared validation** once. The compact hub section is
+independent of consumer connection configuration and uses the same Portal login,
+fresh authentication and native confirmation as the existing page. No separate
+operator service, login or wizard is required. Missing or incompatible deployment
+proof shows the ordinary prerequisite instead of an enabled action. Each issuer
+keeps its own ACME account, certificates and private keys; allocation trust still
+requires explicit approval in the DNS setup screen. Renewal remains automatic.
+
+`GET /api/account/admin/fleet/shared-validation/hub` returns
+`{version:1, enabled, configured, deployment_uuid, can_enable, reason}`.
+The deployment UUID is canonical lowercase with hyphens, unlike consumer project
+UUIDs. `POST` takes only `{deployment_uuid}` after confirmation. The backend
+rechecks the complete deployed roster and framework version atomically before
+enabling. A stale deployment, failed read or fresh-auth refusal requires Refresh
+and another deliberate review; mutations are never replayed. Keep the compatible
+framework on every node after enabling sharing.
+
+The panel consumes the private `/api/account/admin/fleet/shared-validation`
+contract. Choose a named approved hub profile, inspect its exact origin and
+original project UUID, then Keep, Replace or Disable the connection. Replacement
+is a normal write-only password field; blank preserves the existing credential.
+The approved catalog fixes the origin. Arbitrary URLs and raw JSON are not inputs.
+
+Project identity fields also accept existing lowercase16hex Group IDs, preserving
+the exact value through profiles, observations and protected key issuance. Fleet
+revisions/operation IDs remain32hex and deployment IDs remain canonical UUIDs.
+The legacy identity showcase fixture changes wire data only; no Group identity
+is migrated or rewritten.
+
+Preview probes the candidate without saving it. Publication has a separate
+confirmation, frozen against the preview and auth session. Publishing revalidates
+the catalog and expected revision; it does not Apply. Apply has another
+confirmation and targets the exact current revision. Every expected node must
+report installed, restarted and combined request-service/job-engine/scheduler
+health at that revision and the expected topic profile/project identity. Offline,
+draining, stale, partial and missing-node results remain unconfirmed. The UI
+polls at most120 observations and offers deliberate Refresh afterward. Verified
+connection identity with `sharing_ready=false` still needs sharing enabled on the
+approved hub. Refresh the connection after enabling it there.
+
+Create the replacement on the approved hub with the named **ACME validation
+consumer** key form. Preview/Publish, Apply, verify every expected node, then
+explicitly review and deactivate the old key in the hub inventory. Issuance,
+publication and successful dispatch never retire keys. Disable masks the whole
+connection tuple and base credential without deleting base settings or revoking
+remote trust; retained/shared identities can make disabling ineligible.
+
+Secrets remain in an uncontrolled mounted password input and a short-lived
+imperative request draft. They never enter Query/Mutation caches, URL/history,
+storage, receipts or logs. These new writes call `requestFreshAuth` without
+replaying the attempted action; the existing generic Fleet helpers keep their
+prior behavior. Auth/session change or unmount invalidates drafts and closes
+owned confirmations. Double activation is single-flight. A409 revision/catalog
+conflict or `configuration_busy` requires Refresh and a deliberate retry. An
+uncertain publication or issuance may have persisted; read authoritative status
+or exact Group inventory before another attempt.
+
+Unavailable APIs, missing DNSMan/publisher/delegation/schema/enrollment or an empty
+approved catalog render a concrete blocked state. Bootstrap supplies `admin_path`
+and permission facts for existing legacy System Setup, Deployments, topology and
+Fleet Scaling links. Links are same-origin and capability-gated. The backend's
+semantic `capacity` hint maps to the actual registered `#/fleet` route. These
+legacy destinations retain their protected confirmations, policy, release holds
+and IaC restrictions. This React topic reuses those controls without a new
+deployment or root authority service.
+
+The Runtime settings showcase mounts the actual connection panel with central
+mock scenarios and operator/ordinary-manager identities. The named
+`verify:admin-shared-validation-config` gate includes private DTO/API and mounted
+StrictMode contracts, and is included once by `verify:admin-contracts`. Browser
+proof remains necessary for real native dialogs, keyboard/focus and390px in both
+themes. Mock receipts are fixtures, never live configuration evidence.
+
+The private form uses an inline-size container: fact labels stack above UUIDs and
+revision values below420px of available content, including a narrow embedded
+Admin host. The existing Admin sidebar's Collapse control supplies its normal
+compact host at390px; the topic does not change global navigation behavior.
+
+Every successful authoritative refresh invalidates a preview when revision,
+catalog, profile, identity or credential facts change. Late preview/operation
+responses cannot restore spent consent or overwrite a newer observation. After
+the automatic observation limit, explicit Refresh re-observes the tracked exact
+operation and resets the read budget; it never dispatches another Apply. Only
+known healthy report/node statuses with no top-level or node error can turn the
+combined proof green. Apply/read replies remain bound to their exact operation
+ID and requested/tracked revision.