create-qpq-app 0.1.19 → 0.1.21

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-event-append.md

@@ -1,15 +1,18 @@
 ---
 title: askEventDocEventAppend
-description: Append a client-authored event to a document's log — a single unconditional write with no read, no retry, and no validation.
+description: Append a client-authored event to a document's log at the next contiguous position, validating it against the document's state and retrying under write contention.
 ---
 
 # askEventDocEventAppend
 
-Appends a single client-authored event to a document's ordered event stream — the write half of the event-sourcing core. The event's id is a sortable id (UUIDv7, minted by [askNewSortableGuid](../../core/guid/ask-new-sortable-guid.md)), so the write needs no allocator and no coordination: it does not read the tail, does not validate, and has no retry loop. Concurrent appends to the same document neither contend nor fail on each other. After the event is written it also re-derives the queryable summary record so the document's status, version, name, and timestamps stay in sync with the log.
+Appends a single client-authored event to a document's ordered event stream — the write half of the event-sourcing core. The event's id is its **contiguous position** in the log (`INIT_STATE` is `0`, every append is head + 1), so log order IS commit order: a cursor "after N" is exact, and a snapshot "at N" holds exactly events `0..N`.
 
-**Validation happens later, at fold time, not here.** Dedup (a repeated `clientMessageId`), version monotonicity, and lifecycle/domain rules are all decided when the log is folded, against the accepted events before the one in question. An event that fails one of those checks is not rejected at append — it is written, then silently skipped by every fold, so the document reads as though it was never sent. That silence is deliberate: clients are expected to validate before they send (the same rules run client-side against the pending buffer), so a skipped event means a client skipped its own pre-flight, not that the append needs to report an error.
+The append is **expected-version optimistic concurrency**: it resolves the log's current head with a consistent read (and, when `options.validate` is true and the collection has registered validation functions, the document state at that head), validates the event against that state, then writes it at `head + 1` with a **conditional** write. Two writers that resolved the same head race for that slot; exactly one wins, and the other gets back the namespaced Upsert `Conflict`. A losing lap does not start over — it folds only the handful of events that beat it onto the state it already holds, re-validates, and claims the new head + 1 — and retries up to a bounded number of times before giving up (see [Notes](#notes)).
 
-- **Built from:** `askDateNow`, `askNewSortableGuid`, `askEventDocEventWrite`, and `askEventDocSummaryRederive` (plus, when the collection configures `onPublish`/`onAppend`, `askEventDocGetByIdOrThrow`, `askEventDocEventListAll`, and `askInlineFunctionExecute`). Not a single action.
+**Validation against the resolved state happens here, at append time, when enabled.** Dedup (a repeated `clientMessageId`) and version monotonicity are still decided when the log is folded, against the accepted events before the one in question, and the fold's own acceptance rules remain in place as defence in depth. But the collection's registered `validateEvent` runs against the exact state the event will land on, before the write — the gate that stops a bad event from ever entering the log, not just from being read back. A collection with no registered validation functions (or a caller that passes `{ validate: false }`, e.g. trusted server-authored appends) skips the state resolve and the check, and behaves as write-and-go instead.
+
+- **Built from:** `askDateNow`, `askEventDocAppendBaseResolve` / `askEventDocAppendBaseAdvance` (head + state resolution), `askEventDocValidateAppend`, `askEventDocEventWrite`, and `askRetry` (plus, when the collection configures `onPublish`/`onAppend`, `askEventDocGetByIdOrThrow`, `askEventDocHookStates`, and `askInlineFunctionExecute`). Not a single action.
+- **Does not maintain the summary record itself.** The queryable summary is rebuilt from the log by the events store's stream projector ([`onStream`](../../../config/features/event-doc-summary.md)), so it is eventually (not immediately) consistent with a just-written event.
 - **Requires the store context** — wrap the call in [askEventDocProvideStore](./ask-event-doc-provide-store.md) (custom routes) or [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals) (built-in routes).
 
 ```typescript
@@ -41,6 +44,7 @@ function* askEventDocEventAppend(
   modelId: string,
   input: EventDocEventInput,
   actor: EventDocEventActor,
+  options?: EventDocEventAppendOptions, // default { validate: true }
 ): AskResponse<EventDocEvent>;
 ```
 
@@ -48,9 +52,10 @@ function* askEventDocEventAppend(
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `modelId` | `string` | The document id whose log the event is appended to. Not checked against an existing `INIT_STATE` at append time — an event appended before `INIT_STATE` exists is simply written and then skipped by every fold, since the reducer has no document to fold it onto. |
+| `modelId` | `string` | The document id whose log the event is appended to. The base resolve throws `NotFound` when the log has no head to append after — every real log opens with `INIT_STATE`, so a missing document (not an empty log) is what this catches. |
 | `input` | `EventDocEventInput` | The client-authored event envelope — see below. |
 | `actor` | `EventDocEventActor` | Who authored the event; stamped onto the event as `createdBy`. Usually obtained from [askEventDocResolveActor](./ask-event-doc-resolve-actor.md). |
+| `options.validate` | `boolean` | Default `true`. Whether to resolve the document state at the append's head and run the collection's registered `validateEvent` before the write. The append route (the client trust boundary) leaves this on; [askEventDocAppendServerEvent](./ask-event-doc-append-server-event.md) passes `false` for trusted server-authored writes, since the fold remains their gate. |
 
 ### `EventDocEventInput`
 
@@ -72,7 +77,7 @@ What the client POSTs to append an event. `modelId` and the server-stamped prove
 
 ## Returns
 
-`AskResponse<EventDocEvent>` — the event now written to the log, with server-stamped metadata (`eventId`, `createdAt`, `createdBy`) filled in. Unlike before, this is not conditional on the event surviving validation — a fold may still skip it.
+`AskResponse<EventDocEvent>` — the event now durably written to the log at its claimed `eventId`, with server-stamped metadata (`eventId`, `createdAt`, `createdBy`) filled in. Passing pre-write validation does not exempt it from the fold's own rules — a fold may still skip it on a duplicate `clientMessageId` or a stale version.
 
 ### `EventDocEvent`
 
@@ -80,15 +85,16 @@ What the client POSTs to append an event. `modelId` and the server-stamped prove
 | --- | --- | --- |
 | `type` | `string` | The event type discriminant. |
 | `payload.data` | `T` | The typed domain data. |
-| `payload.metadata` | `EventDocEventMetadata` | Full provenance: `version`, `clientMessageId`, `createdBy`, `createdAt`, and `eventId` (a sortable id — mirrors the storage sort key, sorts lexicographically in creation order). |
+| `payload.metadata` | `EventDocEventMetadata` | Full provenance: `version`, `clientMessageId`, `createdBy`, `createdAt`, and `eventId` (the event's contiguous position in the log — mirrors the storage sort key). |
 
 ## Notes
 
-- **No dedup, no version check, and no lifecycle/domain validation at append time.** All three are decided when the log is folded (`foldEventDocLog`), against the accepted events before the one in question: a repeated `clientMessageId` is ignored, an event whose version is older than the log's highest accepted version is ignored, and the collection's `validators` registry (or `defaultEventDocEventValidator` when none is configured) is run there too. A rejected event is skipped silently — the document reads as though it was never written — rather than causing the append to throw.
-- **No read, no retry, no coordination.** The append does not read the tail or the log; it mints a sortable id and writes. Two appends landing in the same millisecond get an arbitrary but stable relative order, which is fine because ordering only has to be stable, not wall-clock-precise.
-- **Write uniqueness** is still enforced by [askEventDocEventWrite](./ask-event-doc-event-write.md)'s conditional (`ifNotExists`) write, but since ids are unique by construction this should never fire in practice — a collision surfaces as `KeyValueStoreUpsertErrorTypeEnum.Conflict` and indicates a bug (two writers minting the same id), not ordinary contention, so there is no retry around it.
-- After writing, it calls `askEventDocSummaryRederive`, which re-folds the whole log and re-derives the document's summary record so the queryable view (identity, version history, timestamps) stays in sync — this is the one piece of read-model maintenance still on the write path, until a stream projector replaces it.
-- Hooks (`onPublish`/`onAppend`, when the collection configures them) run after the event is durably written; a hook failure propagates so the caller knows the side effect — not the append — failed.
+- **Dedup and version monotonicity are still decided at fold time**, against the accepted events before the one in question: a repeated `clientMessageId` is ignored, and an event whose version is older than the log's highest accepted version is ignored. The append does not check either.
+- **Domain/lifecycle validation now runs at append time too, when enabled.** When `options.validate` is `true` and the collection has registered `validateEvent` functions, the event is checked against the document state at the head it will land on, before the write; a rejection throws `ErrorTypeEnum.Invalid` and nothing is written. A collection with no registered functions has nothing to validate with and falls back to write-and-go, same as `{ validate: false }`.
+- **Write contention is expected and retried, not treated as a bug.** [askEventDocEventWrite](./ask-event-doc-event-write.md)'s conditional (`ifNotExists`) write is the slot two writers that resolved the same head race for; the loser gets `KeyValueStoreUpsertErrorTypeEnum.Conflict`, folds just the events that beat it onto the state it already holds, re-validates, and re-laps at the new head. Retries are bounded (`EVENT_DOC_APPEND_MAX_RETRIES`, with linear backoff and jitter); exhausting them throws `ErrorTypeEnum.Conflict` — sustained contention on one document means something is hammering it, not ordinary concurrent editing. Different documents are different partition keys and never contend with each other.
+- **Log order is commit order.** Because the id is the log's next contiguous position rather than a value minted independently by each writer, `afterEventId` cursors and snapshot positions (`upToEventId`) are exact — no two events can claim the same position, and there is no "arbitrary but stable" ordering case to reason about.
+- **Does not maintain the summary record.** The summary is rebuilt from the log by the events store's stream projector, so it lags a just-written event until the stream delivers.
+- Hooks (`onPublish`/`onAppend`, when the collection configures them) run after the event is durably written and outside the retry loop; a hook failure propagates so the caller knows the side effect — not the append — failed.
 
 ## Related
 

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-event-list.md

@@ -5,7 +5,7 @@ description: Read a document's event log — a page of events, the whole log fla
 
 # Reading the event log
 
-Three read helpers over a document's event stream. All three resolve the collection's events store from the store context and query it by `pk = modelId`, ascending by event id (except `askEventDocEventLast`, which reads the tail). Event ids are sortable ids (UUIDv7) whose string form sorts lexicographically in creation order, so ascending-by-id and ascending-by-creation-time agree. They are the read side of the event-sourcing core, feeding the fold that reconstructs a document from its events.
+Three read helpers over a document's event stream. All three resolve the collection's events store from the store context and query it by `pk = modelId`, ascending by event id (except `askEventDocEventLast`, which reads the tail). Event ids are the event's contiguous position in the log (`INIT_STATE` is `0`, every append is head + 1, claimed by a conditional write), so log order IS commit order and ascending-by-id and ascending-by-creation-time always agree. They are the read side of the event-sourcing core, feeding the fold that reconstructs a document from its events.
 
 - **Requires the store context** — provide it via [askEventDocProvideStore](./ask-event-doc-provide-store.md) / [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals).
 - **Built from:** [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md) against the events store, plus [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore). Not single actions.
@@ -17,7 +17,7 @@ Returns one page of events for a document, oldest first. Supports paging and, vi
 ```typescript
 import { askEventDocEventList } from 'quidproquo-features';
 
-export function* refreshSince(docId: string, lastSeenEventId: string) {
+export function* refreshSince(docId: string, lastSeenEventId: number) {
   const page = yield* askEventDocEventList(docId, { afterEventId: lastSeenEventId });
   return page.items; // events after lastSeenEventId
 }
@@ -45,8 +45,8 @@ function* askEventDocEventList(
 | --- | --- | --- | --- |
 | `limit` | `number` | (store default) | Max number of events to return in the page. |
 | `nextPageKey` | `string` | — | Continuation token from a previous page's `nextPageKey`. |
-| `afterEventId` | `string` | — | Return only events whose event id sorts after this one (exclusive). A sort-key range condition on the events store's primary key — no GSI involved. |
-| `upToEventId` | `string` | — | Return only events whose event id sorts at or before this one (inclusive) — the log prefix up to a known event, for folding a document as of that event (a snapshot). Not combinable with `afterEventId`: a key condition holds one sort-key range. |
+| `afterEventId` | `number` | — | Return only events whose event id is greater than this one (exclusive). A sort-key range condition on the events store's primary key — no GSI involved. |
+| `upToEventId` | `number` | — | Return only events whose event id is less than or equal to this one (inclusive) — the log prefix up to a known event, for folding a document as of that event (a snapshot). Combinable with `afterEventId` for a bounded gap range. |
 | `sortDescending` | `boolean` | `false` | Newest first, for a display read that walks backwards in time (e.g. a history panel's latest-page-then-load-older). Folding reads never set this — a fold consumes the log in order. |
 | `consistentRead` | `boolean` | `false` | Strongly consistent read. Needed by a caller that just appended and is now folding to decide something — the default eventually-consistent read can otherwise miss that caller's own most recent event. Costs roughly double the read capacity, so leave it off for ordinary reads. |
 

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-event-write.md

@@ -1,13 +1,13 @@
 ---
 title: askEventDocEventWrite
-description: Low-level conditional write of a single event to a document's events store, keyed by its sortable event id.
+description: Low-level conditional write of a single event to a document's events store, keyed by its contiguous event id.
 ---
 
 # askEventDocEventWrite
 
-The low-level write primitive behind the event log. It persists one already-built [EventDocEvent](./ask-event-doc-event-append.md#eventdocevent) into the collection's events store, keyed by `pk = modelId` / `sk = eventId` (a sortable id — UUIDv7 — whose string form sorts lexicographically in creation order). The write is **conditional** (`ifNotExists`), but since ids are minted uniquely (via `askNewSortableGuid`) rather than allocated, this is a cheap uniqueness assertion rather than a contested slot: a `Conflict` here means two writers minted the same id, which should never happen and indicates a bug, not ordinary concurrent-write contention.
+The low-level write primitive behind the event log. It persists one already-built [EventDocEvent](./ask-event-doc-event-append.md#eventdocevent) into the collection's events store, keyed by `pk = modelId` / `sk = eventId` (a contiguous integer — `INIT_STATE` is `0`, every later event is the previous head plus one). The write is **conditional** (`ifNotExists`), and that condition is the slot two concurrent writers race for: whichever append resolved the losing writer's `headEventId` first claims `headEventId + 1`, and the loser gets `Conflict` back.
 
-Id assignment, dedup, and validation all live one layer up in [askEventDocEventAppend](./ask-event-doc-event-append.md) (dedup and validation are actually decided later still, at fold time) — you almost always want that instead. Call this directly only when you are implementing your own append semantics.
+Id assignment (advancing past a lost race), dedup, and domain validation all live one layer up in [askEventDocEventAppend](./ask-event-doc-event-append.md) (dedup and domain validation are decided later still, at fold time) — you almost always want that instead. Call this directly only when you are implementing your own append semantics.
 
 - **Built from:** [askKeyValueStoreUpsertWithRetry](../../core/key-value-store/ask-key-value-store-upsert-with-retry.md) with `{ ifNotExists: true }`, plus [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore) to find the events store name. Not a single action.
 - **Requires the store context** — provide it via [askEventDocProvideStore](./ask-event-doc-provide-store.md) / [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals).
@@ -31,7 +31,7 @@ function* askEventDocEventWrite(modelId: string, event: EventDocEvent): AskRespo
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `modelId` | `string` | The document id — becomes the partition key (`pk`) of the stored event. |
-| `event` | `EventDocEvent` | A fully-formed event, including `payload.metadata.eventId` — the sortable id becomes the sort key (`sk`) and the slot that is claimed conditionally. |
+| `event` | `EventDocEvent` | A fully-formed event, including `payload.metadata.eventId` — the contiguous id becomes the sort key (`sk`) and the slot that is claimed conditionally. |
 
 ## Returns
 
@@ -40,11 +40,11 @@ function* askEventDocEventWrite(modelId: string, event: EventDocEvent): AskRespo
 ## Notes
 
 - The stored shape is `{ pk: modelId, sk: eventId, data: event }`; the `EventDocStoredEvent` mapping is the only place that knows the key layout, keeping the domain event free of storage concerns.
-- Because the write is conditional, an id collision surfaces `KeyValueStoreUpsertErrorTypeEnum.Conflict`. [askEventDocEventAppend](./ask-event-doc-event-append.md) does not catch or retry on it — with sortable ids minted uniquely per append, this is not an expected contention path.
+- Because the write is conditional, a slot already taken surfaces `KeyValueStoreUpsertErrorTypeEnum.Conflict`. [askEventDocEventAppend](./ask-event-doc-event-append.md) treats that as the expected outcome of losing a race for `headEventId + 1` — it catches the conflict and retries at the new head, up to a bounded number of laps, rather than treating it as a bug.
 
 ## Related
 
-- [askEventDocEventAppend](./ask-event-doc-event-append.md) — the high-level append that mints the sortable id and writes through this.
+- [askEventDocEventAppend](./ask-event-doc-event-append.md) — the high-level append that resolves the next contiguous id and writes through this.
 - [askEventDocEventList / EventListAll / EventLast](./ask-event-doc-event-list.md) — reading events back.
 - [askKeyValueStoreUpsertWithRetry](../../core/key-value-store/ask-key-value-store-upsert-with-retry.md) — the underlying conditional upsert.
 - [askEventDocProvideStore](./ask-event-doc-provide-store.md) — provides the required store context.

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-get-by-id.md

@@ -26,7 +26,7 @@ export function* loadArticle(id: string) {
 An event document is never stored as a mutable blob. Its authoritative state is an **append-only log of events**; the document you read is *derived by folding that log*.
 
 - **Summary record** ([`EventDocSummary`](#the-summary-record)) — the queryable projection folded from the log's identity/lifecycle events (`INIT_STATE`, `SET_CODE`, `SET_NAME`, `PUBLISH`, `DELETE`, `RESTORE`, …). It holds identity (`id`, `code`, `name`), audit fields, and a `versions` array. Every field on it is derived from the log — including `deletedAt`, set and cleared by `DELETE`/`RESTORE` events rather than written directly — so the whole record can be dropped and rebuilt from the log at any time. The document's editable **content** is folded separately (on the client) from the same log; the backend never reduces content.
-- **Draft vs published** — the tail (highest) version with no `publishedAt` is the **draft**; a `PUBLISH` event freezes it and starts the next draft. Each version pointer records the `eventId` (a sortable id) of its last event (its head), so folding events whose `eventId` sorts at or before that head reconstructs the version's content as it was. `publishedAt` is when a version was published; `effectiveFrom` is when that publish takes effect (used for as-of time-travel).
+- **Draft vs published** — the tail (highest) version with no `publishedAt` is the **draft**; a `PUBLISH` event freezes it and starts the next draft. Each version pointer records the `eventId` (its contiguous position in the log) of its last event (its head), so folding events whose `eventId` is at or before that head reconstructs the version's content as it was. `publishedAt` is when a version was published; `effectiveFrom` is when that publish takes effect (used for as-of time-travel).
 - **Code** — the caller-chosen, stable business key set at create (via `INIT_STATE`) and editable with `SET_CODE`. It stays constant across versions and is expected unique within the collection (and any owner scope), so you can address a document by `code` instead of its generated `id`.
 
 The version-pointer reads ([askEventDocGetDraft, askEventDocGetLatestPublished, askEventDocGetPublishedAsOf, askEventDocPublishedVersionAsOf](./ask-event-doc-get-draft.md)) resolve entries in this model.
@@ -49,7 +49,7 @@ type EventDocSummary = {
 
 type EventDocVersion = {
   version: number;
-  eventId: string;       // sortable id of this version's head event
+  eventId: number;       // log id of this version's head event
   publishedAt?: string;  // unset while it is the tail draft
   effectiveFrom?: string; // when the publish takes effect (as-of selection)
 };

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-get-draft.md

@@ -41,13 +41,13 @@ function* askEventDocGetDraft(id: string): AskResponse<Nullable<EventDocVersion>
 ```typescript
 type EventDocVersion = {
   version: number;
-  eventId: string;       // sortable id of this version's head event
+  eventId: number;       // log id of this version's head event
   publishedAt?: string;  // unset while it is the tail draft
   effectiveFrom?: string; // when the publish takes effect (as-of selection)
 };
 ```
 
-To fold or render a version's content, fold the log's events whose `eventId` sorts at or before the version's `eventId`.
+To fold or render a version's content, fold the log's events whose `eventId` is at or before the version's `eventId`.
 
 ---
 

package/template/docusaurus/docs/actions/webserver/dns/ask-dns-list.md

@@ -1,20 +1,20 @@
 ---
 title: askDnsList
-description: List the base DNS domains a service has declared.
+description: List the root domains a service has declared.
 ---
 
 # askDnsList
 
-Returns the list of base DNS domains the service has declared with [defineDns](../../../config/webserver/dns.md). Use it when a story needs to know which root domain(s) the service is served under.
+Returns the root domains the service declared with [defineDns](../../../config/webserver/dns.md), primary first. Use it when a story needs to know which roots the service is served on; for a hostname, use [askDnsResolveHosts](./ask-dns-resolve-hosts.md).
 
 - **Action type:** `DnsActionType.List`
 
 ```typescript
 import { askDnsList } from 'quidproquo-webserver';
 
-export function* askPrimaryDomain() {
-  const domains = yield* askDnsList();
-  return domains[0];
+export function* askPrimaryRootDomain() {
+  const roots = yield* askDnsList();
+  return roots[0];
 }
 ```
 
@@ -28,10 +28,11 @@ Takes no arguments.
 
 ## Returns
 
-`string[]` — the `dnsBase` values from every [defineDns](../../../config/webserver/dns.md) config in the service. Typically a single entry.
+`string[]` — the `rootDomains` of the service's [defineDns](../../../config/webserver/dns.md) config, empty when it declares none.
 
-- **On AWS:** this does **not** query Route53. The processor reads the service's own config and maps each DNS config to its `dnsBase`, so the result is exactly what was declared with `defineDns` — no live DNS lookup is performed.
+- **On AWS:** this does **not** query Route53. The processor reads the service's own config, so the result is exactly what was declared.
 
 ## Related
 
-- [defineDns](../../../config/webserver/dns.md) — declares the domains this action returns.
+- [defineDns](../../../config/webserver/dns.md) — declares the roots this action returns.
+- [askDnsResolveHosts](./ask-dns-resolve-hosts.md) — a target's host on every root.

package/template/docusaurus/docs/actions/webserver/dns/ask-dns-resolve-hosts.md

@@ -0,0 +1,42 @@
+---
+title: askDnsResolveHosts
+description: Resolve a host target to its hostname on every root domain the service declares.
+---
+
+# askDnsResolveHosts
+
+Returns the hostname for a `{ subdomain?, service? }` target on every root the service declared with [defineDns](../../../config/webserver/dns.md), primary first. The processor runs the app's [domain resolver](../../../domains.md) (loaded once through the dynamic module loader), so any target resolves, not only ones the config declares.
+
+- **Action type:** `DnsActionType.ResolveHosts`
+
+```typescript
+import { askDnsResolveHosts } from 'quidproquo-webserver';
+
+export function* askPrimarySiteUrl() {
+  const [siteHost] = yield* askDnsResolveHosts();
+  return `https://${siteHost}`;
+}
+
+export function* askApiHosts() {
+  return yield* askDnsResolveHosts({ subdomain: 'api' });
+}
+```
+
+## Signature
+
+```typescript
+function* askDnsResolveHosts(target?: DomainTarget): AskResponse<string[]>;
+```
+
+### `target` — `DomainTarget` (optional)
+
+`{ subdomain?: string; service?: string }`. Omitted means the site root.
+
+## Returns
+
+`string[]` — one host per root, primary first; empty when the service declares no domain.
+
+## Related
+
+- [defineDns](../../../config/webserver/dns.md) — the roots resolved against.
+- [askDnsList](./ask-dns-list.md) — the root list itself.

package/template/docusaurus/docs/actions/webserver/open-api/_category_.json

@@ -0,0 +1 @@
+{ "label": "OpenAPI", "link": { "type": "generated-index", "description": "Generate the service's OpenAPI document from its route config." } }

package/template/docusaurus/docs/actions/webserver/open-api/ask-open-api-get-document.md

@@ -0,0 +1,41 @@
+---
+title: askOpenApiGetDocument
+description: Build the service's OpenAPI 3.1 document from its route config.
+---
+
+# askOpenApiGetDocument
+
+Returns the **OpenAPI document** describing every route in the service. Stories never see the service config, so the walk happens in the processor, which has it. The result is plain data, ready to serialise.
+
+- **Action type:** `OpenApiActionType.GetDocument`
+
+```typescript
+import { askOpenApiGetDocument, qpqWebServerUtils } from 'quidproquo-webserver';
+
+export function* getSpec() {
+  const document = yield* askOpenApiGetDocument({ title: 'Widgets API', version: '1.2.0' });
+
+  return qpqWebServerUtils.toJsonEventResponse(document);
+}
+```
+
+## Signature
+
+```typescript
+function* askOpenApiGetDocument(options?: OpenApiDocumentOptions): AskResponse<OpenApiDocument>;
+```
+
+## Parameters
+
+### `options` — `OpenApiDocumentOptions` (optional)
+
+`title`, `version` and `description` for the document's info block. The title defaults to the application and module name, the version to `1.0.0`.
+
+## Returns
+
+`OpenApiDocument` — an OpenAPI 3.1 document with `info`, `servers`, `paths` and `components.securitySchemes`. The same structure `buildOpenApiDocument` in `qpqWebServerUtils` produces when given a config directly, which is the way to generate it at build time.
+
+## Related
+
+- [defineOpenApiRoutes](../../../config/features/open-api-routes.md) — serves this document and a reference page for it.
+- [defineRoute](../../../config/webserver/route.md) — the `schema` option that fills in request and response shapes.

package/template/docusaurus/docs/config/config-aws/account-github-oidc-provider.md

@@ -0,0 +1,31 @@
+---
+title: defineAccountGithubOidcProvider
+description: The account-level GitHub Actions OpenID Connect provider that every app's deploy role trusts.
+---
+
+# defineAccountGithubOidcProvider
+
+Declares the account's **GitHub Actions OpenID Connect provider**, `token.actions.githubusercontent.com`. It is an account setting: declared once in `account.qpq.ts`, deployed by the `qpq-account` stack, and shared by every app's [`defineAwsGithubDeployRole`](./github-deploy-role.md) in that account.
+
+- **On AWS:** creates an `aws_iam.OpenIdConnectProvider` for `https://token.actions.githubusercontent.com` with the `sts.amazonaws.com` audience. The provider's ARN is fixed by its URL, which is what the deploy roles trust. An account can hold only one provider for that URL, so a provider created by hand must be deleted before the account stack can own it.
+
+```typescript
+import { defineAccountGithubOidcProvider } from 'quidproquo-config-aws';
+
+export default [
+  defineAccountGithubOidcProvider(),
+];
+```
+
+## Signature
+
+```typescript
+function defineAccountGithubOidcProvider(): AccountGithubOidcProviderQPQConfigSetting;
+```
+
+Takes no arguments.
+
+## Related
+
+- [defineAwsGithubDeployRole](./github-deploy-role.md) — the per-app, per-environment role that trusts this provider.
+- [defineAccountBudget](./account-budget.md) — another account-stack setting.

package/template/docusaurus/docs/config/config-aws/domain-certificate.md

@@ -1,20 +1,23 @@
 ---
 title: defineDomainCertificate
-description: Issue a real ACM certificate with DNS validation for a root domain and its subdomains.
+description: Issue one DNS-validated ACM certificate per region covering the app's hosts on every root domain.
 ---
 
 # defineDomainCertificate
 
-Issues a real **ACM (AWS Certificate Manager) certificate**, DNS-validated against a Route 53 hosted zone, for a root domain and a set of subdomains. This is the concrete certificate that API Gateway and CloudFront distributions use for HTTPS. The webserver [`defineCertificate`](../webserver/certificate.md) is a portable shim that ultimately defers to a domain certificate like this one on AWS.
+Issues a real **ACM (AWS Certificate Manager) certificate** for a region, covering a set of host targets on **every** root declared with [defineDns](../webserver/dns.md). This is the certificate API Gateway and CloudFront use for HTTPS.
 
-- **On AWS:** each unique `(region, rootDomain)` becomes a `DomainCertificateStack` (via `createDomainCertificateStacks` in `quidproquo-deploy-awscdk`). The stack resolves the root domain through the same environment/feature prefixing as [`defineApi`](../webserver/api.md) (`resolveDomainRoot`), so `rootDomain: "example.com"` in a dev deploy issues against `development.example.com`. It looks up the hosted zone, creates an `aws_certificatemanager.Certificate` with `CertificateValidation.fromDns(...)` covering the resolved subdomains (and the apex when `includeApex`), and publishes the cert ARN to SSM (keyed by region + root domain) — writing cross-region via a custom resource when the cert region differs from the deploy region. Entries sharing a `(region, rootDomain)` are merged into one cert covering the union of their names.
+- **On AWS:** each region becomes one `DomainCertificateStack` (via `createDomainCertificateStacks` in `quidproquo-deploy-awscdk`). Every target is resolved on every root through the app's [domain resolver](../../domains.md), each name is DNS-validated in its own hosted zone (`CertificateValidation.fromDnsMultiZone`), and the ARN is published to SSM under an app-keyed parameter (`/qpq/domain/certificate-arn/<region>/<app>-<environment>[-<feature>]`), cross-region via a custom resource when the cert region differs from the deploy region. The certificate is **retained** on replacement: changing the name set issues a new cert while distributions still referencing the old ARN keep working until they redeploy. Entries for the same region are merged. ACM allows 10 names per certificate by default; synth fails with the name list when a config exceeds it.
 
 ```typescript
 import { defineDomainCertificate } from 'quidproquo-config-aws';
 
-export default [
-  // A cert for api.example.com and admin.example.com in the deploy region
-  defineDomainCertificate('example.com', 'us-east-1', ['api', 'admin']),
+export default ({ region }) => [
+  // CloudFront: the site root plus www on every root
+  defineDomainCertificate('us-east-1', [{ subdomain: 'www' }], { includeApex: true }),
+
+  // Regional API Gateway: the api and a service-scoped websocket
+  defineDomainCertificate(region, [{ subdomain: 'api' }, { subdomain: 'ws', service: 'chat' }]),
 ];
 ```
 
@@ -22,48 +25,29 @@ export default [
 
 ```typescript
 function defineDomainCertificate(
-  rootDomain: string,
   region: string,
-  subdomains: string[],
+  targets: DomainTarget[],
   options?: { includeApex?: boolean },
 ): DomainCertificateQPQConfigSetting;
 ```
 
 ## Parameters
 
-### `rootDomain` — `string` (required)
-
-The base, un-prefixed apex domain — the same value you pass to `defineApi` / web-entry `rootDomain` fields. At synth time it is resolved against the config's environment and feature (a dev deploy of `"example.com"` becomes `development.example.com`, or `myfeature.development.example.com`). Together with `region` it forms the setting's `uniqueKey`.
-
 ### `region` — `string` (required)
 
-The AWS region to issue the certificate in. CloudFront requires certificates in `us-east-1`, while regional API Gateway certs live in the deploy region — declaring both for the same apex is a valid, merged case.
+The AWS region to issue the certificate in. CloudFront requires `us-east-1`; regional API Gateway custom domains need the deploy region. It is the setting's `uniqueKey`, so entries for one region merge.
 
-### `subdomains` — `string[]` (required)
+### `targets` — `DomainTarget[]` (required)
 
-The subdomain labels to cover, each combined with the resolved apex (e.g. `'api'` → `api.<resolved-apex>`). At least one subdomain must be declared unless `includeApex` is `true`, or synth throws.
+The hosts to cover, as `{ subdomain?, service? }` targets. Each is resolved on every root with the app's domain resolver, exactly as the api, web entry or websocket that uses it will be. `{ subdomain: 'api' }` covers the api host; `{ subdomain: 'ws', service: 'chat' }` covers a websocket that is not `onRootDomain`.
 
 ### `options` — `{ includeApex?: boolean }` (optional)
 
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
-| `includeApex` | `boolean` | `false` | Also cover the resolved apex domain itself (in addition to the subdomains). Merged entries OR this flag together. |
-
-## Examples
-
-```typescript
-import { defineDomainCertificate } from 'quidproquo-config-aws';
-
-export default [
-  // Regional API cert in the deploy region
-  defineDomainCertificate('example.com', 'us-east-1', ['api']),
-
-  // CloudFront cert (must be us-east-1) covering the apex and www
-  defineDomainCertificate('example.com', 'us-east-1', ['www'], { includeApex: true }),
-];
-```
+| `includeApex` | `boolean` | `false` | Also cover each root's site root (the `{}` target), which a web entry with `onRootDomain: true` and no subdomain serves on. |
 
 ## Related
 
-- [defineCertificate](../webserver/certificate.md) — the portable webserver shim that defers to this real ACM certificate on AWS.
-- [defineApi](../webserver/api.md) — its `rootDomain` uses the same resolution as this certificate's `rootDomain`.
+- [Domains](../../domains.md) — the resolver every target goes through.
+- [defineDns](../webserver/dns.md) — the roots the certificate covers.

package/template/docusaurus/docs/config/config-aws/email-sender-allow-list.md

@@ -1,22 +1,21 @@
 ---
 title: defineEmailSenderAllowList
-description: Recipient addresses a service is allowed to email while its SES account is in sandbox mode.
+description: Recipient addresses a service may email while its SES account is still in sandbox mode.
 ---
 
 # defineEmailSenderAllowList
 
-Declares recipient addresses a service is allowed to send to while its SES account is still in **sandbox mode**. In sandbox, SES authorizes a send against the recipient's identity as well as the sender's, so [defineEmailSender](../webserver/email-sender.md)'s exact-ARN send grant needs each recipient identity listed too. The addresses must also be verified identities in the SES console (sandbox requires that anyway).
+Declares recipient addresses the service is allowed to email while the SES account is in **sandbox** mode. In sandbox, SES authorises a send against the recipient's identity as well as the sender's, so the exact-ARN send grant needs each recipient identity listed too. The addresses must also be verified identities in the SES console.
 
-This is an AWS-specific concession, not a portable email concept, which is why it lives in `quidproquo-config-aws` keyed by the same `rootDomain` as `defineEmailSender` rather than on that webserver setting directly. Once the account has SES production access this setting does nothing useful and can be deleted.
+This is an AWS-specific concession, not a portable email concept, which is why it lives in `quidproquo-config-aws` beside [defineEmailSender](../webserver/email-sender.md) rather than on that webserver setting. Once the account has SES production access this setting does nothing useful and can be deleted.
 
 ```typescript
 import { defineEmailSender } from 'quidproquo-webserver';
 import { defineEmailSenderAllowList } from 'quidproquo-config-aws';
 
 export default [
-  defineEmailSender('example.com'),
-
-  defineEmailSenderAllowList('example.com', ['joe@external.com', 'test@external.com']),
+  defineEmailSender(),
+  defineEmailSenderAllowList(['joe@external.com', 'test@external.com']),
 ];
 ```
 
@@ -24,22 +23,16 @@ export default [
 
 ```typescript
 function defineEmailSenderAllowList(
-  rootDomain: string,
   allowedEmailAddresses: string[],
 ): EmailSenderAllowListQPQConfigSetting;
 ```
 
 ## Parameters
 
-### `rootDomain` — `string` (required)
-
-The `rootDomain` of the matching [defineEmailSender](../webserver/email-sender.md) this allow-list applies to.
-
 ### `allowedEmailAddresses` — `string[]` (required)
 
-Recipient addresses to grant sandbox send access to. Multiple calls for the same `rootDomain` are additive.
+Recipient addresses to grant sandbox send access to. Multiple calls are additive.
 
 ## Related
 
-- [defineEmailSender](../webserver/email-sender.md) — the sending domain this allow-list is keyed by.
-- [askEmailSendEmail](../../actions/webserver/email/ask-email-send-email.md) — the action these addresses need to be reachable from.
+- [defineEmailSender](../webserver/email-sender.md) — the sending identities this allow-list extends.

package/template/docusaurus/docs/config/config-aws/github-deploy-role.md

@@ -0,0 +1,68 @@
+---
+title: defineAwsGithubDeployRole
+description: The IAM role GitHub Actions assumes through OIDC to deploy an app environment.
+---
+
+# defineAwsGithubDeployRole
+
+Declares the **IAM role a GitHub Actions workflow assumes** (via OpenID Connect, no stored keys) to deploy this app's environment. It is a bootstrap setting: declared once in `bootstrap.qpq.ts`, deployed by the bootstrap stack.
+
+- **On AWS:** creates `github-actions-deploy-<app>-<environment>` with a two-hour session and only what a deploy needs: `sts:AssumeRole` on the CDK bootstrap roles (deploy, file-publishing, image-publishing, lookup) in every region the app deploys to, read and write on this app's S3 buckets (`*-<app>-*-<environment>`, where the built views and federated remotes are synced), and read on the `/cdk-bootstrap/*` and `/qpq/*` SSM parameters. CloudFormation applies the stacks as the bootstrap exec role, so the deploy identity never holds the permissions of what it deploys. Its trust policy allows `sts:AssumeRoleWithWebIdentity` from the account's `token.actions.githubusercontent.com` provider when the token's audience is `sts.amazonaws.com` and its subject is the repository's immutable-id form `repo:<owner>@<ownerId>/<name>@<repositoryId>:environment:<githubEnvironment>`. The name form `repo:<owner>/<name>:...` is trusted only when no ids are given or `trustNameForm` is set, since a name can be re-earned by whoever next owns it and an id cannot. GitHub only issues the id form for repositories switched to immutable subjects (new repositories, or `gh api -X PUT repos/<owner>/<name>/actions/oidc/customization/sub -F use_default=false -F use_immutable_subject=true` for older ones); switch the repository before deploying an id-only role. The role ARN is a stack output. The provider itself is one per account and comes from [`defineAccountGithubOidcProvider`](./account-github-oidc-provider.md) in the account config.
+
+```typescript
+import { defineAwsGithubDeployRole } from 'quidproquo-config-aws';
+
+export default [
+  defineAwsGithubDeployRole('qpqjs/quidproquo', { ownerId: 314167689, repositoryId: 571382961 }),
+];
+```
+
+## Signature
+
+```typescript
+function defineAwsGithubDeployRole(
+  repository: string,
+  options?: { ownerId?: number; repositoryId?: number; githubEnvironment?: string },
+): AwsGithubDeployRoleQPQConfigSetting;
+```
+
+## Parameters
+
+### `repository` — `string` (required)
+
+`owner/name` of the GitHub repository whose workflows may assume the role.
+
+### `options` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ownerId` | `number` | – | The owner's numeric GitHub id. `gh api repos/<owner>/<name> --jq .owner.id`. With `repositoryId`, also trusts the immutable-id subject form. |
+| `repositoryId` | `number` | – | The repository's numeric GitHub id. `gh api repos/<owner>/<name> --jq .id`. |
+| `githubEnvironment` | `string` | the deploy environment | The GitHub Environment the deploy job declares (`environment:` on the job). A job without it is refused by STS. |
+| `trustNameForm` | `boolean` | `true` without ids, else `false` | Also trust the name-form subject. Only for a repository not yet switched to immutable subjects. |
+
+## Locking it down further
+
+Protect the GitHub Environment itself (Settings, Environments): required reviewers and a deployment-branch rule limited to `main` mean a token with the right subject only exists for approved runs of trusted branches.
+
+## Wiring the workflow
+
+After the bootstrap stack deploys, `qpq setup --check` prints the role ARN. Put it in the GitHub Environment's variables as `DEPLOY_ROLE_ARN` with `AWS_REGION`, and have the job declare that environment and `permissions: id-token: write`:
+
+```yaml
+jobs:
+  deploy:
+    environment: development
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION }}
+```
+
+## Related
+
+- [defineBootstrapWaf](./bootstrap-waf.md) — another bootstrap-stack setting.