create-qpq-app 0.1.19 → 0.1.21

package/template/docusaurus/docs/config/core/user-directory.md

@@ -95,11 +95,10 @@ Each handler is a `QpqFunctionRuntime` — a reference to a story entry point, u
 ```typescript
 export type AuthDirectoryDnsRecord = {
   subdomain: string;
-  rootDomain: string;
 };
 ```
 
-Attaches a Cognito custom domain (`subdomain.rootDomain`) to the pool and creates the matching Route 53 alias record. Because Cognito custom domains run on CloudFront, the ACM certificate is looked up in `us-east-1`.
+Attaches a Cognito custom domain to the pool and creates the matching Route 53 alias record. A pool has one custom domain, so it lives on the **primary** root from [defineDns](../webserver/dns.md) (the `{ subdomain }` target under the app's domain resolver). Because Cognito custom domains run on CloudFront, the ACM certificate is looked up in `us-east-1`.
 
 ## Custom auth runtime
 
@@ -167,7 +166,7 @@ export default [
   // Required MFA served from a custom domain
   defineUserDirectory('staff', {
     mfa: { mode: UserDirectoryMfaMode.required },
-    dnsRecord: { subdomain: 'auth', rootDomain: 'example.com' },
+    dnsRecord: { subdomain: 'auth' },
   }),
 
   // Authenticate against a directory owned by another service

package/template/docusaurus/docs/config/features/admin-settings.md

@@ -20,7 +20,7 @@ export default [
   ...defineAdminUserDirectory({ owner: { module: 'log' } }),
 
   // The admin dashboard backend, owned by the 'log' service
-  ...defineAdminSettings('log', 'example.com', {
+  ...defineAdminSettings('log', {
     logRetentionDays: 90,
     services: ['api', 'workers', 'web'],
   }),
@@ -32,7 +32,6 @@ export default [
 ```typescript
 function defineAdminSettings(
   logServiceName: string,
-  rootDomain: string,
   advancedSettings?: QPQConfigAdvancedLogSettings,
 ): QPQConfig;
 ```
@@ -43,9 +42,6 @@ function defineAdminSettings(
 
 The name of the service that **owns** the admin resources. Owner-stamped settings (the log storage drives, the admin WebSocket event bus/queues, the key-value stores, the auth and log routes, the alarm pipeline, and the [session event doc](./admin-session-event-doc.md)) only flatten into deployable resources when the deploying service matches this name; elsewhere they resolve as foreign references. Owner resolution runs at IAM-scoping time.
 
-### `rootDomain` — `string` (required)
-
-The root domain the admin service is hosted on. Used to stand up the admin WebSocket endpoint (`defineWebSocketQueue`) under the `qpqadmin` subdomain of this domain.
 
 ### `advancedSettings` — `QPQConfigAdvancedLogSettings` (optional)
 
@@ -90,7 +86,7 @@ export default [
   ...defineAdminUserDirectory({ owner: { module: 'log' } }),
 
   // Retain logs 30 days, move to deep cold storage after 7.
-  ...defineAdminSettings('log', 'example.com', {
+  ...defineAdminSettings('log', {
     logRetentionDays: 30,
     coldStorageAfterDays: 7,
     services: ['api', 'workers'],

package/template/docusaurus/docs/config/features/event-doc-summary.md

@@ -8,8 +8,8 @@ description: Declare the stores for an event-sourced document collection — its
 Declares the **stores** that back an event-document collection, without any routes. It returns a `QPQConfig` (an array of config settings) that expands to five underlying core stores:
 
 1. A **summary key-value store** (partition key `type`, sort key `id`) — the queryable record for each document, derived by folding the identity/lifecycle events of its log. Rows are the [`EventDocSummary`](../../actions/features/event-doc/ask-event-doc-get-by-id.md) shape and carry the version history. A secondary index on `(type, updatedAt)` supports the recently-updated ordering [askEventDocList](../../actions/features/event-doc/ask-event-doc-list.md) returns. It is a pure projection: nothing on the append path writes it directly. The events store below declares an [`onStream`](../core/key-value-store.md#change-data-capture-onstream) handler that rebuilds a document's summary row from its log whenever an event is appended, so the summary is eventually (not immediately) consistent with the log.
-2. An **append-only events store** (`<storeName>EventLog`, partition key `pk`, string sort key `sk`) — the live ordered log every document is folded from, keyed on a sortable event id (UUIDv7). It has **no** secondary index on purpose: the local dev-server query processor can't target one, so all event reads go through the main table.
-3. A **snapshots store** (`<storeName>SS`, partition key `pk`, sort key `sk`) — per-view folded states at points along the log (`pk = docId#view`, `sk` the same sortable event id the log is ordered by). Populated only for the document types you enable via `options.snapshotFunctions`; a type with no entry there simply is not snapshotted. For a type with a registered functions object, the `onStream` handler runs ONE incremental fold per delivery — resuming from the newest usable snapshot and folding only the gap since it — and persists both the snapshot set and the summary row from that same fold (the fold's `summary` view IS the queryable record). The whole-log summary re-derivation remains only as the fallback: types with no registered functions, Remove stream records (a transfer rewrote the log, so snapshots can't seed), and folds that decline.
+2. An **append-only events store** (`<storeName>EventLog`, partition key `pk`, numeric sort key `sk`) — the live ordered log every document is folded from, keyed on the event's contiguous position (`INIT_STATE` is `0`, every append is head + 1, claimed by a conditional write with retry under contention). Log order IS commit order. It has **no** secondary index on purpose: the local dev-server query processor can't target one, so all event reads go through the main table.
+3. A **snapshots store** (`<storeName>SS`, partition key `pk`, sort key `sk`) — per-view folded states at points along the log (`pk = docId#view`, `sk` the same contiguous event id the log is ordered by). Populated only for the document types you enable via `options.snapshotFunctions`; a type with no entry there simply is not snapshotted. For a type with a registered functions object, the `onStream` handler runs ONE incremental fold per delivery — resuming from the newest usable snapshot and folding only the gap since it — and persists both the snapshot set and the summary row from that same fold (the fold's `summary` view IS the queryable record). The whole-log summary re-derivation remains only as the fallback: types with no registered functions, Remove stream records (a transfer rewrote the log, so snapshots can't seed), and folds that decline.
 4. A **legacy events store** (`<storeName>Events`, partition key `pk`, numeric sort key `sk`) — the pre-sortable-id log, kept declared but unread/unwritten at runtime so its data stays reachable until it is migrated into the events store above.
 5. A **storage drive** (`<storeName>edocs`, lower-cased) — the collection's blob bucket, holding each document's immutable uploaded assets (and later its derived runtime artifacts) under per-document prefixes.
 

package/template/docusaurus/docs/config/features/open-api-routes.md

@@ -0,0 +1,82 @@
+---
+title: defineOpenApiRoutes
+description: Serve a generated OpenAPI document and an interactive reference page for the service's routes.
+---
+
+# defineOpenApiRoutes
+
+Mounts two routes: an interactive API reference page and the OpenAPI 3.1 document it reads. Nothing is written by hand. The document is generated from the service's route config, so every `defineRoute` shows up in it, and routes that declare a schema show their request and response shapes too.
+
+- **On AWS:** two ordinary routes on the API Lambda. The document is built on request from the config already bundled with the service, so there is no extra infrastructure and nothing to keep in sync.
+
+```typescript
+import { defineOpenApiRoutes } from 'quidproquo-features';
+
+export default [
+  // GET /v1/docs (reference page) and GET /v1/docs/openapi.json (document)
+  defineOpenApiRoutes({ info: { title: 'Widgets API', version: '1.2.0' } }),
+];
+```
+
+The reference page loads [Scalar](https://scalar.com) from a CDN and points it at the document next to it. Browsers need to reach `cdn.jsdelivr.net` for the page to render; the document itself has no such dependency.
+
+## Signature
+
+```typescript
+function defineOpenApiRoutes(options?: OpenApiRoutesOptions): QPQConfig;
+```
+
+## Parameters
+
+### `options` — `OpenApiRoutesOptions` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `basePath` | `string` | `'/docs'` | Where the reference page is served. The document is always at `${basePath}/openapi.json`. |
+| `version` | `number` | `1` | Version prefix, as with [defineVersionedRoute](./versioned-route.md). |
+| `info` | `OpenApiDocumentOptions` | – | `title`, `version` and `description` for the document's info block. The title defaults to the application and module name. |
+| `routeAuthSettings` | `RouteAuthSettings` | – | Gate the docs behind a user directory or api key. Public when omitted. |
+
+## Describing a route
+
+Any route can carry a `schema` in its options: `bodyJsonSchema`, `queryJsonSchema` and `responseJsonSchema` as plain JSON Schema (from zod, `z.toJSONSchema(MySchema)`), plus `summary`, `description` and `tags`. Set `hidden: true` to keep a route out of the document.
+
+Routes written with `dynamicRoute` (or a `createRouteDefinition` family) take zod schemas instead and get validation for free. The body and query are parsed before the handler runs, a mismatch becomes a 422, and the parsed values arrive typed as the handler's third argument.
+
+```typescript
+import { z } from 'zod/v4';
+import { dynamicRoute } from 'quidproquo-features';
+
+export const create = dynamicRoute(
+  ['POST', '/widgets'],
+  function* (event, params, { body }) {
+    // body is { name: string }
+    return qpqWebServerUtils.toJsonEventResponse({ id: 'w1', name: body.name });
+  },
+  {
+    schema: {
+      summary: 'Create a widget',
+      tags: ['widgets'],
+      body: z.object({ name: z.string().min(1) }),
+      response: z.object({ id: z.string(), name: z.string() }),
+    },
+    knownErrors: { [WidgetErrorTypeEnum.Duplicate]: 409 },
+  },
+);
+```
+
+## What the document contains
+
+- One operation per route, keyed by path and method, with a stable `operationId` derived from both.
+- Path parameters read from the `{param}` segments of the path.
+- One query parameter per property of the query schema.
+- A JSON request body when a body schema is declared, and a typed 200 response when a response schema is.
+- A 422 response on routes that validate input, and a 401 on routes with auth settings.
+- Security requirements from the route's merged auth settings: bearer JWT for a user directory, `x-api-key` for api keys. Only the schemes in use are published.
+- A server entry per non-deprecated [defineApi](../webserver/api.md) when the service has a domain.
+
+## Related
+
+- [askOpenApiGetDocument](../../actions/webserver/open-api/ask-open-api-get-document.md) — the action the document route yields; use it to serve the document somewhere else.
+- [defineRoute](../webserver/route.md) — the `schema` option on plain routes.
+- [defineVersionedRoute](./versioned-route.md) — the version prefix these routes sit under.

package/template/docusaurus/docs/config/features/tenanted-web-socket-queue.md

@@ -19,7 +19,7 @@ export default [
     routeAuthSettings: { userDirectoryName: 'users' },
   }),
 
-  defineTenantedWebSocketQueue('my-event-bus', 'api', 'example.com', {
+  defineTenantedWebSocketQueue('my-event-bus', 'api', {
     userDirectoryName: 'users',
   }),
 ];
@@ -31,7 +31,6 @@ export default [
 function defineTenantedWebSocketQueue(
   eventBusName: string,
   apiName: string,
-  rootDomain: string,
   advancedSettings?: QPQConfigAdvancedTenantedWebsocketQueueSettings,
 ): QPQConfig;
 ```
@@ -40,7 +39,7 @@ function defineTenantedWebSocketQueue(
 
 ## Parameters
 
-Same as [defineWebSocketQueue](./web-socket-queue.md#parameters): `eventBusName`, `apiName`, `rootDomain`, and `advancedSettings` (without `connectionScopeResolver`, which this always sets to `TENANT_CONNECTION_SCOPE_RESOLVER_FN`).
+Same as [defineWebSocketQueue](./web-socket-queue.md#parameters): `eventBusName`, `apiName`, and `advancedSettings` (without `connectionScopeResolver`, which this always sets to `TENANT_CONNECTION_SCOPE_RESOLVER_FN`).
 
 ## Returns
 

package/template/docusaurus/docs/config/features/web-socket-queue.md

@@ -16,7 +16,7 @@ Defines a **WebSocket queue**: a batteries-included messaging layer on top of a
 import { defineWebSocketQueue } from 'quidproquo-features';
 
 export default [
-  defineWebSocketQueue('my-event-bus', 'api', 'example.com', {
+  defineWebSocketQueue('my-event-bus', 'api', {
     userDirectoryName: 'users',
   }),
 ];
@@ -40,7 +40,6 @@ Because the underlying WebSocket API is created with `apiName` equal to the `api
 function defineWebSocketQueue(
   eventBusName: string,
   apiName: string,
-  rootDomain: string,
   advancedSettings?: QPQConfigAdvancedWebsocketQueueSettings,
 ): QPQConfig;
 ```
@@ -57,9 +56,6 @@ Name of the [event bus](../core/event-bus.md) the queue is associated with (stor
 
 Logical name of the WebSocket API. Drives the resource names of the deployed API, the connection key-value store (`qpq-wsq-<apiName>`), and the globals — and is the value you pass as `websocketApiName` to send actions. Also used as the API subdomain.
 
-### `rootDomain` — `string` (required)
-
-The registered domain the WebSocket API is served under (passed straight through to the underlying [defineWebsocket](../webserver/websocket.md)).
 
 ### `advancedSettings` — `QPQConfigAdvancedWebsocketQueueSettings` (optional)
 

package/template/docusaurus/docs/config/webserver/api.md

@@ -7,13 +7,13 @@ description: Define an HTTP API — the public web endpoint (a custom subdomain
 
 Defines an **API**: the public HTTP endpoint for a service. An API declares the subdomain and root domain the service is reachable on; every [route](./route.md) you declare in the same service is served under it. A service typically declares exactly one API.
 
-- **On AWS:** deploys a **regional API Gateway REST API** (`LambdaRestApi`, proxy mode, binary media types `*/*`) backed by a single Lambda that handles every route (`ApiQpqWebserverApiConstruct` in `quidproquo-deploy-awscdk`). The API is attached to a custom domain (`apiSubdomain.rootDomain`) via a base-path mapping keyed on the module name, so multiple modules can share one domain. Access logs (JSON, one-year retention) and CloudWatch metrics are enabled; a 5XX alarm is wired by default, plus 401/403 rate alarms when error notifications are configured. When WAF protection is enabled for the deploy, the shared regional Web ACL is associated with the stage.
+- **On AWS:** deploys a **regional API Gateway REST API** (`LambdaRestApi`, proxy mode, binary media types `*/*`) backed by a single Lambda that handles every route (`ApiQpqWebserverApiConstruct` in `quidproquo-deploy-awscdk`). The API is attached to a custom domain on every root declared with [defineDns](./dns.md) (the `{ subdomain: apiName }` target under the app's [domain resolver](../../domains.md)) via a base-path mapping keyed on the module name, so multiple modules can share one domain. Access logs (JSON, one-year retention) and CloudWatch metrics are enabled; a 5XX alarm is wired by default, plus 401/403 rate alarms when error notifications are configured. When WAF protection is enabled for the deploy, the shared regional Web ACL is associated with the stage.
 
 ```typescript
 import { defineApi } from 'quidproquo-webserver';
 
 export default [
-  defineApi('api', 'example.com'),
+  defineApi('api'),
 ];
 ```
 
@@ -24,7 +24,6 @@ This serves the service's routes at `https://api.<module-base>.example.com/<modu
 ```typescript
 function defineApi(
   apiName: string,
-  rootDomain: string,
   options?: QPQConfigAdvancedApiSettings,
 ): ApiQPQWebServerConfigSetting;
 ```
@@ -33,11 +32,8 @@ function defineApi(
 
 ### `apiName` — `string` (required)
 
-The API's name and its `uniqueKey` within the config. Unless overridden by `options.subDomain`, it is also the **subdomain** the API is served on (so `defineApi('api', 'example.com')` serves on `api.<...>.example.com`).
+The API's name and its `uniqueKey` within the config. Unless overridden by `options.subDomain`, it is also the **subdomain** the API is served on: the host is the `{ subdomain: apiName }` target resolved on each root (`api.development.example.com` with the default shape).
 
-### `rootDomain` — `string` (required)
-
-The root domain the API is hosted under, e.g. `'example.com'`. The deploy derives the full hostname from this plus the environment/feature and the API subdomain, so the same config deploys to multiple environments without collisions.
 
 ### `options` — `QPQConfigAdvancedApiSettings` (optional)
 
@@ -56,7 +52,7 @@ import { defineApi, defineRoute } from 'quidproquo-webserver';
 
 export default [
   // Serve on a custom subdomain, capped at 50 concurrent requests
-  defineApi('public', 'example.com', {
+  defineApi('public', {
     subDomain: 'api',
     maxConcurrentExecutions: 50,
   }),
@@ -71,5 +67,6 @@ export default [
 - [defineRoute](./route.md) — declares the individual method+path endpoints served under the API.
 - [defineDefaultRouteOptions](./default-route-options.md) — service-wide defaults (CORS, auth) merged into every route.
 - [defineServiceFunction](./service-function.md) — RPC-style callable functions, deployed as their own Lambdas rather than under the API.
-- [defineDomainCertificate](../config-aws/domain-certificate.md) — the ACM certificate for the API's domain (resolved with the same `rootDomain` prefixing).
+- [defineDns](./dns.md) — the roots the API's domain is created on.
+- [defineDomainCertificate](../config-aws/domain-certificate.md) — the ACM certificate covering the API's host on every root.
 - [defineWafProtection](../config-aws/waf-protection.md) — opt the API Gateway stage into the app's WAF web ACL.

package/template/docusaurus/docs/config/webserver/cache.md

@@ -81,7 +81,7 @@ export default [
     buildPath: './web/dist',
     cacheSettingsName: 'default',
     ignoreCache: ['index.html'],
-    domain: { onRootDomain: true, rootDomain: 'example.com' },
+    domain: { onRootDomain: true },
   }),
 ];
 ```

package/template/docusaurus/docs/config/webserver/dns.md

@@ -1,19 +1,21 @@
 ---
 title: defineDns
-description: Declare the base DNS domain a service lives under, so every domain, certificate, and DNS record it deploys hangs off one root.
+description: Declare the root domains a service is served on; every hostname the service deploys is derived from them.
 ---
 
 # defineDns
 
-Declares the **base DNS domain** for a service. Everything else in quidproquo-webserver that needs a hostname — API custom domains, web entries, [domain proxies](./domain-proxy.md), and [subdomain redirects](./subdomain-redirect.md) — derives its fully-qualified name from this single `dnsBase`. A service has one DNS base.
+Declares the **root domains** for a service, primary first. Everything else that needs a hostname (API custom domains, web entries, websockets, [domain proxies](./domain-proxy.md), [subdomain redirects](./subdomain-redirect.md), email identities, CORS and CSP origins) is derived from this list through the app's [domain resolver](../../domains.md). A service has one `defineDns`; a second one is a synth error.
 
-- **On AWS:** `defineDns` does **not** create a Route53 hosted zone by itself. The hosted zone for `dnsBase` (after environment/feature prefixing) must already exist in Route53 — deploy constructs look it up with `HostedZone.fromLookup`, then add the `A` records they need into that existing zone. Think of `defineDns` as declaring "this is my root domain"; the zone that owns it is expected to be there already.
+- **On AWS:** `defineDns` does **not** create a Route53 hosted zone. Deploy constructs look zones up with `HostedZone.fromLookup` and add records into them. A host's zone is its root's site root when it sits under it (`api.development.example.com` in `development.example.com`), otherwise the root itself (`development-api.example.com` in `example.com`); see [Domains](../../domains.md).
 
 ```typescript
 import { defineDns } from 'quidproquo-webserver';
 
 export default [
-  defineDns('example.com'),
+  defineDns(['example.com', 'example.org'], {
+    resolver: { basePath: __dirname, relativePath: 'domainResolver', functionName: 'domainResolver' },
+  }),
 ];
 ```
 
@@ -21,22 +23,22 @@ export default [
 
 ```typescript
 function defineDns(
-  dnsBase: string,
+  rootDomains: string | string[],
+  options?: { resolver?: QpqPureFunction },
 ): DnsQPQWebServerConfigSetting;
 ```
 
 ## Parameters
 
-### `dnsBase` — `string` (required)
+### `rootDomains` — `string | string[]` (required)
+
+The root domains the service is served on. The first is the **primary**: anything that must bake exactly one absolute URL (email links, module-federation remotes, the Cognito custom domain) uses it. Every other resource is created on every root, so the app is fully live on all of them at once.
 
-The root domain the service is served from, e.g. `'example.com'`. This value becomes the config's `uniqueKey` and is the base that all of the service's hostnames are built on. quidproquo prefixes it per environment and feature before use, so a single config deploys cleanly to multiple environments:
+Hostnames are not built here. They come from the app's [domain resolver](../../domains.md), which by default produces `[subdomain.][service.][feature.][environment.]root` with no environment label in production.
 
-- In `production` the base stays `example.com`.
-- In another environment it becomes `<environment>.example.com` (e.g. `development.example.com`).
-- With a feature branch it becomes `<feature>.<environment>.example.com`.
-- A service's own resources then live under `<service>.<base>` (e.g. an API at `api.<service>.development.example.com`).
+### `options.resolver` — `QpqPureFunction` (optional)
 
-The list of declared bases is what [askDnsList](../../actions/webserver/dns/ask-dns-list.md) returns at runtime.
+A pointer (`{ basePath, relativePath, functionName }`) to the app's `DomainResolver` export. The deploy tooling `require`s it at synth and build time, and the runtime loads it through the dynamic module loader (the pointer is a bundled src entry like a route), so every site resolves hosts the same way: `resolveHosts(qpqConfig, target, resolver)`. Omit it for the default shape.
 
 ## Examples
 
@@ -44,14 +46,20 @@ The list of declared bases is what [askDnsList](../../actions/webserver/dns/ask-
 import { defineDns } from 'quidproquo-webserver';
 
 export default [
-  // Serve this service under example.com (and its env/feature-prefixed variants)
+  // One root
   defineDns('example.com'),
+
+  // Two roots, example.com primary: every api, web entry and websocket is served on both,
+  // shaped by the app's own resolver
+  defineDns(['example.com', 'example.org'], {
+    resolver: { basePath: __dirname, relativePath: 'domainResolver', functionName: 'domainResolver' },
+  }),
 ];
 ```
 
 ## Related
 
-- [askDnsList](../../actions/webserver/dns/ask-dns-list.md) — returns the `dnsBase` values declared with `defineDns`.
-- [defineCertificate](./certificate.md) — TLS certificate for a domain rooted at this base.
-- [defineDomainProxy](./domain-proxy.md) — front a domain under this base with CloudFront.
-- [defineSubdomainRedirect](./subdomain-redirect.md) — redirect a subdomain under this base to another URL.
+- [Domains](../../domains.md) — how roots, the resolver, zones and certificates fit together.
+- [askDnsList](../../actions/webserver/dns/ask-dns-list.md) — returns the root list at runtime.
+- [askDnsResolveHosts](../../actions/webserver/dns/ask-dns-resolve-hosts.md) — a target's host on every root at runtime.
+- [defineDomainCertificate](../config-aws/domain-certificate.md) — the per-region certificate covering every root.

package/template/docusaurus/docs/config/webserver/domain-proxy.md

@@ -16,7 +16,6 @@ export default [
   defineDomainProxy('marketing-proxy', {
     httpProxyDomain: 'origin.internal.example.com',
     domain: {
-      rootDomain: 'example.com',
       onRootDomain: true,
     },
     domainProxyViewerProtocolPolicy: DomainProxyViewerProtocolPolicy.REDIRECT_TO_HTTPS,
@@ -53,7 +52,6 @@ Unique name for this proxy (the config's `uniqueKey`). Used to derive the distri
 
 ```typescript
 export interface DomainProxyDomainOptions {
-  rootDomain: string;
   subDomainNames?: string[];
   onRootDomain: boolean;
 }
@@ -61,7 +59,6 @@ export interface DomainProxyDomainOptions {
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `rootDomain` | `string` | The root domain (matches the service's [`dnsBase`](./dns.md)); the apex is resolved from it with the usual environment/feature prefixing, and the hosted zone is looked up in Route53. |
 | `subDomainNames` | `string[]` | Subdomains to serve, each expanded to `<subDomain>.<apex>`. An `A` alias record is created for each. |
 | `onRootDomain` | `boolean` | When `true` and no subdomains are given, the distribution also answers on the apex domain itself. |
 
@@ -91,7 +88,6 @@ export default [
   defineDomainProxy('api-proxy', {
     httpProxyDomain: 'backend.example.net',
     domain: {
-      rootDomain: 'example.com',
       subDomainNames: ['api', 'api-v2'],
       onRootDomain: false,
     },
@@ -104,6 +100,6 @@ export default [
 
 ## Related
 
-- [defineDns](./dns.md) — declares the `rootDomain` this proxy attaches to.
+- [defineDns](./dns.md) — declares the roots this proxy is served on.
 - [defineCertificate](./certificate.md) — related certificate configuration (the proxy uses the central certificate).
 - [defineSubdomainRedirect](./subdomain-redirect.md) — redirect a subdomain instead of proxying it.

package/template/docusaurus/docs/config/webserver/email-sender.md

@@ -1,43 +1,37 @@
 ---
 title: defineEmailSender
-description: Declare a domain a service is allowed to send email from.
+description: Declare that a service sends email from the app's root domains.
 ---
 
 # defineEmailSender
 
-Declares a domain the service can send email from with [askEmailSendEmail](../../actions/webserver/email/ask-email-send-email.md). The domain must live under a base declared with [defineDns](./dns.md) — deploy resolves it the same way (environment/feature prefixed) before creating the sending identity.
+Declares that the service sends email with [askEmailSendEmail](../../actions/webserver/email/ask-email-send-email.md) from the app's root domains. The sending identity on each root is that root's site root under the app's [domain resolver](../../domains.md) (`development.example.com` with the default shape).
 
-- **On AWS:** creates an SES `EmailIdentity` for the resolved domain in its Route53 hosted zone (DKIM records land there automatically), and scopes the service role's `ses:SendEmail` / `ses:SendRawEmail` grant to that identity's exact ARN. `ses:SendRawEmail` is needed for emails with attachments, which are sent as raw MIME. No grant or identity is created for services that declare no `defineEmailSender`.
+- **On AWS:** creates an SES `EmailIdentity` per root in its Route53 hosted zone (DKIM records land there automatically), and scopes the service role's `ses:SendEmail` / `ses:SendRawEmail` grant to those identities' exact ARNs. `ses:SendRawEmail` is needed for emails with attachments, which are sent as raw MIME. No grant or identity is created for services that declare no `defineEmailSender`.
 
 ```typescript
 import { defineDns, defineEmailSender } from 'quidproquo-webserver';
 
 export default [
   defineDns('example.com'),
-  defineEmailSender('example.com'),
+  defineEmailSender(),
 ];
 ```
 
 ## Signature
 
 ```typescript
-function defineEmailSender(
-  rootDomain: string,
-): EmailSenderQPQWebServerConfigSetting;
+function defineEmailSender(): EmailSenderQPQWebServerConfigSetting;
 ```
 
-## Parameters
-
-### `rootDomain` — `string` (required)
-
-The domain to send from, resolved the same way as [defineDns](./dns.md)'s `dnsBase` (environment/feature prefixed). This value is also the config's `uniqueKey`, so a service declares one sender per root domain.
+Takes no arguments; a service declares it once.
 
 ## Returns
 
-An `EmailSenderQPQWebServerConfigSetting` config entry. Deploy reads every declared entry with `qpqWebServerUtils.getEmailSenderSettings` to create the SES identities and IAM grants.
+An `EmailSenderQPQWebServerConfigSetting` config entry. Deploy reads it with `qpqWebServerUtils.getEmailSenderSettings` to create the SES identities and IAM grants.
 
 ## Related
 
-- [askEmailSendEmail](../../actions/webserver/email/ask-email-send-email.md) — send email from a domain declared here.
-- [defineDns](./dns.md) — the base domain this sender's `rootDomain` resolves against.
+- [askEmailSendEmail](../../actions/webserver/email/ask-email-send-email.md) — send email from the identities declared here.
+- [defineDns](./dns.md) — the roots the identities are created on.
 - [defineEmailSenderAllowList](../config-aws/email-sender-allow-list.md) — recipient addresses allowed while the SES account is in sandbox mode.

package/template/docusaurus/docs/config/webserver/route.md

@@ -48,6 +48,7 @@ A reference to the story that handles the request. Usually written as a relative
 | --- | --- | --- | --- |
 | `allowedOrigins` | `(string \| ServiceAllowedOrigin)[]` | – | Browser origins allowed to call this route (CORS). Either literal origin strings or `ServiceAllowedOrigin` descriptors resolved to another qpq service's domain. Merged with any [default route options](./default-route-options.md). |
 | `routeAuthSettings` | `RouteAuthSettings` | – | How the route is authenticated/authorized. See below. |
+| `schema` | `RouteSchema` | – | `bodyJsonSchema`, `queryJsonSchema` and `responseJsonSchema` as JSON Schema, plus `summary`, `description`, `tags` and `hidden`. Feeds the generated OpenAPI document; see [defineOpenApiRoutes](../features/open-api-routes.md). Routes written with `dynamicRoute` fill this in from zod schemas for you. |
 
 #### `RouteAuthSettings`
 

package/template/docusaurus/docs/config/webserver/seo.md

@@ -53,7 +53,7 @@ import { defineSeo, defineWebEntry } from 'quidproquo-webserver';
 export default [
   defineWebEntry('website', {
     buildPath: './web/dist',
-    domain: { onRootDomain: true, rootDomain: 'example.com' },
+    domain: { onRootDomain: true },
   }),
 
   // Render product pages server-side for crawlers & link previews

package/template/docusaurus/docs/config/webserver/web-entry.md

@@ -17,7 +17,6 @@ export default [
     buildPath: './web/dist',
     domain: {
       onRootDomain: true,
-      rootDomain: 'example.com',
     },
   }),
 ];
@@ -60,13 +59,11 @@ The web entry's name and `uniqueKey`. This is the name you pass to [askWebEntryI
 export interface WebDomainOptions {
   subDomainName?: string;
   onRootDomain: boolean;
-  rootDomain: string;
 }
 ```
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `rootDomain` | `string` | The apex/root domain to host under, e.g. `'example.com'`. The ACM certificate and Route 53 hosted zone are resolved from this. |
 | `onRootDomain` | `boolean` | Serve on the apex domain itself (`example.com`). |
 | `subDomainName` | `string` (optional) | Serve on a subdomain instead of / in addition to the apex, e.g. `'app'` → `app.example.com`. |
 
@@ -112,7 +109,6 @@ export default [
     ignoreCache: ['index.html', 'remoteEntry.js', 'mf-manifest.json'],
     domain: {
       onRootDomain: true,
-      rootDomain: 'example.com',
     },
   }),
 ];
@@ -126,7 +122,6 @@ const options: QPQConfigAdvancedWebEntrySettings = {
   domain: {
     subDomainName: 'views',
     onRootDomain: false,
-    rootDomain: 'example.com',
   },
   storageDrive: {
     sourceStorageDrive: 'views',

package/template/docusaurus/docs/config/webserver/websocket.md

@@ -7,13 +7,13 @@ description: Define a WebSocket API with connect, disconnect, and message route
 
 Defines a **WebSocket API**: a persistent, bidirectional connection endpoint served on its own subdomain. You supply story entry points that run when a client connects, disconnects, or sends a message, and the runtime wires them to the platform's WebSocket transport. Stories push messages back to connected clients with [askWebsocketSendMessage](../../actions/webserver/websocket/ask-websocket-send-message.md).
 
-- **On AWS:** deploys an **API Gateway v2 WebSocket API** (`QpqApiWebserverWebsocketConstruct` in `quidproquo-deploy-awscdk`) fronted by a single Lambda proxy integration. Three routes — `$connect`, `$disconnect`, and `$default` — all target that Lambda, which dispatches to the matching handler in `eventProcessors`. The API is mapped to a custom subdomain (`apiSubdomain.rootDomain`) and served from the `prod` stage. Routes use `authorizationType: NONE`; do your own auth inside the `onConnect`/`onMessage` handlers. When `deprecated` is set, nothing is deployed.
+- **On AWS:** deploys an **API Gateway v2 WebSocket API** (`QpqApiWebserverWebsocketConstruct` in `quidproquo-deploy-awscdk`) fronted by a single Lambda proxy integration. Three routes — `$connect`, `$disconnect`, and `$default` — all target that Lambda, which dispatches to the matching handler in `eventProcessors`. The API is mapped to a custom domain on every root from [defineDns](./dns.md) (the `{ subdomain: apiSubdomain, service }` target, or `{ subdomain: apiSubdomain }` when `onRootDomain` is set) and served from the `prod` stage. Routes use `authorizationType: NONE`; do your own auth inside the `onConnect`/`onMessage` handlers. When `deprecated` is set, nothing is deployed.
 
 ```typescript
 import { defineWebsocket } from 'quidproquo-webserver';
 
 export default [
-  defineWebsocket('ws', 'example.com', {
+  defineWebsocket('ws', {
     onConnect: '/entry/ws/onConnect::onConnect',
     onDisconnect: '/entry/ws/onDisconnect::onDisconnect',
     onMessage: '/entry/ws/onMessage::onMessage',
@@ -54,7 +54,6 @@ export type WebsocketEvent<T extends string | Blob | ArrayBuffer = string> = {
 ```typescript
 function defineWebsocket(
   apiSubdomain: string,
-  rootDomain: string,
   eventProcessors: QpqWebSocketEventProcessors,
   options?: QPQConfigAdvancedWebSocketSettings,
 ): WebSocketQPQWebServerConfigSetting;
@@ -64,11 +63,8 @@ function defineWebsocket(
 
 ### `apiSubdomain` — `string` (required)
 
-The subdomain the WebSocket API is served on. Combined with `rootDomain` it forms the connection host (`apiSubdomain.rootDomain`). It alone is the setting's `uniqueKey`.
+The subdomain the WebSocket API is served on; with the default shape the host is `apiSubdomain.<service>.<base>` (or `apiSubdomain.<base>` when `onRootDomain` is set). It alone is the setting's `uniqueKey`.
 
-### `rootDomain` — `string` (required)
-
-The registered domain the API lives under. On AWS a custom-domain mapping is created for `apiSubdomain.rootDomain` (or, when `onRootDomain` is set, directly under the base/service domain).
 
 ### `eventProcessors` — `QpqWebSocketEventProcessors` (required)
 

package/template/docusaurus/docs/domains.md

@@ -0,0 +1,76 @@
+---
+title: Domains
+description: How root domains, the app's hostname shape, hosted zones and certificates fit together.
+---
+
+# Domains
+
+An app is served on one or more **root domains** and every hostname it needs is derived from them. Three things decide the final names:
+
+1. **The root list**: [defineDns](./config/webserver/dns.md), primary first, declared by the bootstrap fragment and by every service (normally from one shared constant).
+2. **The domain resolver**: the app's hostname shape, a pure `DomainResolver` export that `defineDns` points at with a `QpqPureFunction` (`{ basePath, relativePath, functionName }`). Omit the pointer for the default shape.
+3. **Hosted zones** (AWS only): derived from the resolver's output, nothing to declare. A host's records go in its root's site root when it sits under it (`api.development.example.com` in the delegated `development.example.com` zone), otherwise in the root itself (`development-api.example.com` in `example.com`). Whichever applies must already exist in Route53.
+
+## Targets
+
+Every place that needs a host asks for a **target**, `{ subdomain?, service? }`, and gets one host per root:
+
+| Setting | Target |
+| --- | --- |
+| `defineApi('api')` | `{ subdomain: 'api' }` |
+| `defineWebEntry('site', { domain: { onRootDomain: true } })` | `{}` (the site root) |
+| `defineWebEntry('views', { domain: { subDomainName: 'views', onRootDomain: true } })` | `{ subdomain: 'views' }` |
+| `defineWebsocket('ws', ...)` on service `chat` | `{ subdomain: 'ws', service: 'chat' }` |
+| CORS or CSP entry `{ api: 'admin', service: 'admin' }` | `{ subdomain: 'admin', service: 'admin' }` |
+
+## The resolver
+
+```typescript
+// packages/domain/src/domainResolver.ts
+import { DomainResolver } from 'quidproquo';
+
+// dev-api.example.com, dev-ws-chat.example.com, example.com in production
+export const domainResolver: DomainResolver = {
+  resolveHost: ({ rootDomain, environment, feature, service, subdomain }) => {
+    const env = environment === 'production' ? undefined : environment;
+    const label = [feature, env, subdomain, service].filter(Boolean).join('-');
+    return label ? `${label}.${rootDomain}` : rootDomain;
+  },
+};
+
+// packages/domain/src/index.ts: the pointer every config passes to defineDns
+export const DOMAIN_RESOLVER = { basePath: __dirname, relativePath: 'domainResolver', functionName: 'domainResolver' };
+```
+
+```typescript
+defineDns(APP_DOMAINS, { resolver: DOMAIN_RESOLVER });
+```
+
+The resolver receives the root, environment, feature and target and returns a host that must be the root or end with `.<root>`. It can branch per root. It must be pure: no actions, no I/O, deterministic. The CDK app and the rspack builds `require` the pointer under ts-node; the lambda runtime bundles it as a src entry and loads it through the dynamic module loader once per processor (CORS, OpenAPI servers, the CloudFront origin-request domain, [askDnsResolveHosts](./actions/webserver/dns/ask-dns-resolve-hosts.md)). Nothing is precomputed and config is never rewritten: every site calls `resolveHosts(qpqConfig, target, resolver)`.
+
+The default shape, with no pointer, is `[subdomain.][service.][feature.][environment.]root` with no environment label in production.
+
+## The browser
+
+Nothing here reaches the browser. How a page finds its api is the app's own concern, as before.
+
+## Certificates
+
+[defineDomainCertificate](./config/config-aws/domain-certificate.md) issues one certificate per region covering its targets on every root. CloudFront serves all roots from one distribution with the `us-east-1` cert; API Gateway custom domains use the deploy-region cert.
+
+## Orphaned certificates
+
+A certificate's names are immutable, so any change to the name set (a root added or removed, a target added, a resolver change) issues a new certificate and retains the old one until every distribution and api domain has redeployed. Retained certificates never expire away on their own. They are tagged `application` / `environment` (and `feature`), so list them per app and delete the ones nothing uses:
+
+```bash
+aws acm list-certificates --region us-east-1 \
+  --query 'CertificateSummaryList[?InUseBy==`[]`].[CertificateArn,DomainName,Status]' --output table
+```
+
+## Adding a root
+
+1. Create the Route53 zone for the new root in the deploy account.
+2. Append it to the app's domain constant, which every `defineDns` reads.
+3. Deploy the domain phase (new certificates, api domains), then each service.
+
+The first root keeps the existing CloudFormation logical ids; extra roots get suffixed ones, so adding is purely additive and removing is purely deletes. Reordering the list rebuilds domain resources (aliases, records, api domain names), so do it in a quiet window.