create-qpq-app 0.1.7 → 0.1.8

package/template/docusaurus/docs/config/config-aws/bootstrap-waf.md

@@ -26,6 +26,7 @@ function defineBootstrapWaf(
   options?: {
     managedRuleGroups?: WafManagedRuleGroup[];
     rateLimits?: WafRateLimit[];
+    managedRuleOverrides?: Partial<Record<WafManagedRuleGroup, WafManagedRuleOverride[]>>;
   },
 ): BootstrapWafQPQConfigSetting;
 ```
@@ -38,6 +39,7 @@ function defineBootstrapWaf(
 | --- | --- | --- | --- |
 | `managedRuleGroups` | `WafManagedRuleGroup[]` | `[common, knownBadInputs, sqli]` | AWS-managed rule groups to enable, each added as a managed-rule-group statement with `overrideAction: none`. See [`WafManagedRuleGroup`](#wafmanagedrulegroup). |
 | `rateLimits` | `WafRateLimit[]` | `[]` (none) | Rate-based blocking rules (e.g. brute-force throttling on auth endpoints). Evaluated **before** the managed rule groups. See [`WafRateLimit`](#wafratelimit). |
+| `managedRuleOverrides` | `Partial<Record<WafManagedRuleGroup, WafManagedRuleOverride[]>>` | `undefined` (none) | Per-rule action overrides within a managed group, e.g. force a specific rule to `count` instead of the group's default blocking action. See [`WafManagedRuleOverride`](#wafmanagedruleoverride). |
 
 ### `WafManagedRuleGroup`
 
@@ -73,10 +75,29 @@ export interface WafRateLimit {
 | `limit` | `number` | Maximum requests per 5-minute window per source IP before that IP is blocked (`aggregateKeyType: IP`). |
 | `uriPathStartsWith` | `string` | Optional. Scope the rate limit to URI paths with this prefix (e.g. `/auth`) via a scope-down byte-match statement. Omit to rate limit all paths. |
 
+### `WafManagedRuleOverride`
+
+```typescript
+export interface WafManagedRuleOverride {
+  name: string;
+  action: WafRuleOverrideAction;
+}
+
+export enum WafRuleOverrideAction {
+  count = 'count', // Observe and emit metrics for matching requests, but never block them.
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Rule name inside the managed group, e.g. `'SizeRestrictions_BODY'`. |
+| `action` | `WafRuleOverrideAction` | Action to force for this rule instead of the group's default. Currently only `count` (observe without blocking) is supported. |
+
 ## Notes
 
 - Rate-limit rules are given the lowest priorities (evaluated first as cheap counters), then the managed rule groups follow.
 - To actually apply these ACLs, a service opts in with `defineWafProtection()` in its (shared) service config; the ACL ARNs are resolved by convention from SSM at deploy time, so the bootstrap must be deployed before the service's API/web stacks.
+- `managedRuleOverrides` is keyed by `WafManagedRuleGroup`; overrides for a group only apply if that group is also present in `managedRuleGroups`.
 
 ## Examples
 
@@ -99,6 +120,21 @@ export default [
 ];
 ```
 
+To let large request bodies through instead of being blocked by the `common` group's default 8kb body-size limit:
+
+```typescript
+import { defineBootstrapWaf, WafManagedRuleGroup, WafRuleOverrideAction } from 'quidproquo-config-aws';
+
+export default [
+  defineBootstrapWaf({
+    managedRuleGroups: [WafManagedRuleGroup.common, WafManagedRuleGroup.knownBadInputs, WafManagedRuleGroup.sqli],
+    managedRuleOverrides: {
+      [WafManagedRuleGroup.common]: [{ name: 'SizeRestrictions_BODY', action: WafRuleOverrideAction.count }],
+    },
+  }),
+];
+```
+
 ## Related
 
 - [defineWafProtection](./waf-protection.md) — a per-service setting that opts a service's API Gateway stage and CloudFront distributions into these web ACLs.

package/template/docusaurus/docs/config/core/action-processors.md

@@ -33,17 +33,39 @@ A reference (usually a relative path string of the form `'/path/to/file::exporte
 
 ```typescript
 // getCustomProcessors.ts
-import { ActionProcessorListResolver } from 'quidproquo-core';
+import { ActionProcessorListResolver, actionResult } from 'quidproquo-core';
 
 export const getCustomProcessors: ActionProcessorListResolver = async (qpqConfig, dynamicModuleLoader) => ({
   ['MyDomain.DoThing']: async (payload, session, actionProcessors, logger, updateSession, dynamicModuleLoader, streamRegistry) => {
-    // execute the action and return its result
+    // execute the action, then wrap the outcome with actionResult / actionResultError
+    return actionResult({ ok: true });
   },
 });
 ```
 
 Each key is an **action type**; each value is the processor that runs when a story yields an action of that type. Because the runtime merges all processor sources into a single map (later sources spread over earlier ones), a source that provides a key matching a built-in action type **overrides** the built-in processor, and a source that provides a new key **registers a custom action**. You can declare `defineActionProcessors` more than once — every declared source is loaded and merged. Each source's `uniqueKey` is derived from its runtime reference.
 
+## Returning results from a processor
+
+A processor never returns a bare value or throws to the story. It returns an `ActionProcessorResult`, built with helpers from `quidproquo-core`:
+
+- `actionResult(value)` wraps a successful result. The story receives `value` from its `yield`.
+- `actionResultError(errorType, errorText, errorStack?)` wraps a failure. `errorType` should come from the action's own error enum. By default the failure ends the story with that `QPQError`; a story that yields the action with `returnErrors` set receives it as an `EitherActionResult` instead.
+- `actionResultErrorFromCaughtError(caughtError, errorMap)` converts a caught exception inside a `try`/`catch`. The map is keyed by the error's runtime `code` (Node fs style: `ENOENT`, `EACCES`) first, then its `name` (AWS SDK style: `NoSuchBucket`, `AccessDenied`); the matching entry builds the `actionResultError`. An unmapped error becomes a `GenericError` whose text names only the unmapped key, never the raw error message, so map every error your processor can realistically hit.
+
+```typescript
+import { actionResult, actionResultError, actionResultErrorFromCaughtError, ErrorTypeEnum } from 'quidproquo-core';
+
+try {
+  const item = await readTheThing(payload.id);
+  return actionResult(item);
+} catch (error) {
+  return actionResultErrorFromCaughtError(error, {
+    ENOENT: () => actionResultError(ErrorTypeEnum.NotFound, `Thing not found [${payload.id}]`),
+  });
+}
+```
+
 ## Notes
 
 - The resolver is invoked with the service's `QPQConfig` and a `dynamicModuleLoader`, so it can build processors that depend on config or lazily load further modules.

package/template/docusaurus/docs/config/core/ai.md

@@ -33,7 +33,7 @@ export default [
 ```typescript
 function defineAi(
   aiName: string,
-  options: QPQConfigAdvancedAiSettings,
+  options?: QPQConfigAdvancedAiSettings,
 ): AiQPQConfigSetting;
 ```
 
@@ -43,7 +43,7 @@ function defineAi(
 
 The name of the AI config, and its `uniqueKey` within the config. This is the value you pass as the `aiName` option to the AI prompt actions to bind these tools to a request.
 
-### `options` — `QPQConfigAdvancedAiSettings` (required)
+### `options` — `QPQConfigAdvancedAiSettings` (optional)
 
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -56,7 +56,7 @@ The name of the AI config, and its `uniqueKey` within the config. This is the va
 interface AiToolDefinition {
   name: string;
   description: string;
-  executor: string;
+  executor?: string;
   inputSchema: Record<string, unknown>;
 }
 ```
@@ -65,12 +65,12 @@ interface AiToolDefinition {
 | --- | --- | --- |
 | `name` | `string` | Tool name the model uses to call it. |
 | `description` | `string` | Natural-language description of what the tool does — the model reads this to decide when to call it, so make it precise. |
-| `executor` | `string` | A `QpqFunctionRuntime` reference (`'/path/to/file::exportedFunction'`) to the story that runs when the model calls the tool. It receives the tool input (validated against `inputSchema`) and returns the tool output. |
+| `executor` | `string` (optional) | A `QpqFunctionRuntime` reference (`'/path/to/file::exportedFunction'`) to the story that runs when the model calls the tool. It receives the tool input (validated against `inputSchema`) and returns the tool output. Omit it to declare a **client-side tool**: the model's call isn't run server-side, the turn halts with the call unresolved, and the caller is expected to resolve it out-of-band (e.g. showing a form) and feed the answer back as the next message. |
 | `inputSchema` | `Record<string, unknown>` | A JSON Schema describing the tool's input. The model is constrained to produce arguments matching this schema. |
 
 ## Notes
 
-- When a bound prompt triggers a tool call, the AI action processor runs the tool's `executor` story and returns its result to the model, looping up to 10 tool-calling steps before finishing.
+- When a bound prompt triggers a tool call for a tool with an `executor`, the AI action processor runs that story and returns its result to the model, looping up to 10 tool-calling steps before finishing. A tool call for a tool with no `executor` is left unresolved for the caller to answer.
 - Streaming prompts surface each tool call, result, and approval request as `ToolCall` / `ToolResult` / `ToolApprovalRequest` parts on the stream — see [askAiPromptStream](../../actions/core/ai/ask-ai-prompt-stream.md#aistreamparttype).
 
 ## Related

package/template/docusaurus/docs/config/core/bundle-options.md

@@ -0,0 +1,102 @@
+---
+title: defineBackendBundleOptions / defineFrontendBundleOptions
+description: Tune how the service's backend and frontend bundles are built: externals, ignored modules, suppressed warnings, and shared frontend singletons.
+---
+
+# defineBackendBundleOptions / defineFrontendBundleOptions
+
+Declares **bundler options** for the service. These settings deploy nothing themselves: they are read by the build layer (`quidproquo-deploy-webpack` / `quidproquo-deploy-rspack`) when it bundles the service's backend code and frontend views. You can declare either setting more than once; the build layer merges every declared block (later lists concatenate onto earlier ones).
+
+All regex-shaped fields are plain regex **source strings**, not `RegExp` objects, because a QPQ config must survive JSON serialization. The bundler compiles them with `new RegExp(...)`.
+
+```typescript
+import { defineBackendBundleOptions, defineFrontendBundleOptions } from 'quidproquo-core';
+
+export default [
+  defineBackendBundleOptions({
+    externals: ['sharp'],
+  }),
+
+  defineFrontendBundleOptions({
+    sharedSingletons: ['chakra', 'zod'],
+  }),
+];
+```
+
+## defineBackendBundleOptions
+
+### Signature
+
+```typescript
+function defineBackendBundleOptions(
+  options: BackendBundleOptions,
+): BackendBundleOptionsQPQConfigSetting;
+```
+
+### Options: `BackendBundleOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `externals` | `string[]` | `[]` | Packages to `require()` at runtime instead of bundling. Prefer declaring layer-provided packages on the layer itself (`ApiLayer.modules`); this is the escape hatch for non-layer cases. |
+| `ignoreModules` | [`BundleIgnoreModule[]`](#bundleignoremodule) | `[]` | Optional requires inside dependencies that should resolve to nothing (the bundler drops them). |
+| `ignoreWarnings` | [`BundleIgnoreWarning[]`](#bundleignorewarning) | `[]` | Known-noisy build warnings to suppress. |
+
+### `BundleIgnoreModule`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `resource` | `string` | Regex source for the request to drop from the bundle, e.g. `'^original-fs$'`. |
+| `context` | `string` (optional) | Only drop when required from a module matching this regex source, e.g. `'adm-zip'`. |
+
+### `BundleIgnoreWarning`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `module` | `string` (optional) | Regex source matched against the module emitting the warning. |
+| `message` | `string` (optional) | Regex source matched against the warning message. |
+
+## defineFrontendBundleOptions
+
+### Signature
+
+```typescript
+function defineFrontendBundleOptions(
+  options: FrontendBundleOptions,
+): FrontendBundleOptionsQPQConfigSetting;
+```
+
+### Options: `FrontendBundleOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sharedSingletons` | `string[]` | `[]` | Substring-matched against the hoisted root dependency names; matches are shared as module-federation **singletons** in the views build. `react`, `react-dom`, react-ish deps, and `quidproquo-web*` are always singletons; this adds app-stack packages (e.g. `'chakra'`, `'zod'`) without baking package names into the bundler. |
+
+## Notes
+
+- Multiple declarations merge: `qpqCoreUtils.getBackendBundleOptions` / `getFrontendBundleOptions` concatenate the lists from every declared setting, so a shared config block and a service-specific block can each contribute options.
+- Backend externals combine with the modules declared on the service's Lambda layers; the layer is the preferred home for anything a layer actually provides.
+
+## Examples
+
+```typescript
+import { defineBackendBundleOptions } from 'quidproquo-core';
+
+export default [
+  defineBackendBundleOptions({
+    // Native module provided outside the bundle
+    externals: ['sharp'],
+
+    // adm-zip optionally requires original-fs (an Electron shim) - drop it
+    ignoreModules: [{ resource: '^original-fs$', context: 'adm-zip' }],
+
+    // liquidjs emits a known-noisy parse warning
+    ignoreWarnings: [{ module: 'liquidjs', message: 'module\\.createRequire failed parsing argument' }],
+  }),
+];
+```
+
+## Related
+
+- [defineFederatedModuleStore](./federated-module-store.md): load story code from a store at runtime instead of only the bundled zip.
+- [defineApiBuildPath](./api-build-path.md): where the bundled backend output lives.
+- **Build implementation:** `getWebpackConfigForQpq` / `getRspackConfigForQpq` and `getQpqBundleExternals` in `quidproquo-deploy-webpack` / `quidproquo-deploy-rspack`.

package/template/docusaurus/docs/config/core/global.md

@@ -40,4 +40,4 @@ function defineGlobal<T>(
 - [defineParameter](./parameter.md) — for values that change at runtime.
 - [defineSecret](./secret.md) — for sensitive values.
 - [defineApplicationVersion](./application-version.md) — a specialised global that records the service's version string.
-- [defineWebSocketQueue](../webserver/web-socket-queue.md) — stores its event-bus and user-directory names in globals like these.
+- [defineWebSocketQueue](../features/web-socket-queue.md) — stores its event-bus and user-directory names in globals like these.

package/template/docusaurus/docs/config/core/queue.md

@@ -56,7 +56,7 @@ Each key is matched against a delivered message's `type` field. The key may be a
 | `concurrency` | `number` | `1` | Consumer concurrency hint. |
 | `maxTries` | `number` | `1` | How many times a message is delivered before it is sent to the dead-letter queue (SQS `maxReceiveCount`). |
 | `ttRetryInSeconds` | `number` | `900` | Retry/visibility timeout in seconds — how long a message stays invisible while being processed before it can be redelivered. Also used as the consumer Lambda timeout. Capped at 900 (15 minutes). |
-| `hasDeadLetterQueue` | `boolean` | `true` | Whether a dead-letter queue backs the main queue. |
+| `hasDeadLetterQueue` | `boolean` | `true` | Whether a dead-letter queue backs the main queue. Note: the AWS deploy currently always provisions a DLQ; this flag is recorded in the config but not yet honoured by `QpqCoreQueueConstruct`. |
 | `eventBusSubscriptions` | `string[]` | `[]` | Names of [event buses](./event-bus.md) this queue subscribes to. Each subscribed bus's messages are delivered into this queue. |
 | `maxConcurrentExecutions` | `number` | – | Reserved concurrent executions for the consumer Lambda (caps parallelism). |
 | `isFifo` | `boolean` | `false` | Creates a **FIFO** queue that preserves per-group ordering and supports deduplication. See [FIFO queues](#fifo-queues). |

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

@@ -53,7 +53,6 @@ The root domain the admin service is hosted on. Used to stand up the admin WebSo
 export interface QPQConfigAdvancedLogSettings extends QPQConfigAdvancedSettings {
   logRetentionDays?: number;
   coldStorageAfterDays?: number;
-  claudeAiApiKeySecretName?: string;
   services?: string[];
 }
 ```
@@ -62,7 +61,6 @@ export interface QPQConfigAdvancedLogSettings extends QPQConfigAdvancedSettings
 | --- | --- | --- | --- |
 | `logRetentionDays` | `number` | – (no expiry) | How many days to keep the raw log objects on the logs storage drive before they are deleted. When unset, logs never expire. If `coldStorageAfterDays` is set, the effective retention is padded so that it is at least `coldStorageAfterDays + 180` days — logs always outlive the cold-storage transition window. |
 | `coldStorageAfterDays` | `number` | – (no transition) | When greater than 0, adds a lifecycle rule transitioning log objects to the `DEEP_COLD_STORAGE` tier after this many days, to cut storage cost for old logs. |
-| `claudeAiApiKeySecretName` | `string` | `''` | Name of the secret holding a Claude AI API key, exposed to the admin service as the `claudeAi-api-key` global. Enables the admin dashboard's log-chat feature (asking questions about a log with Claude). |
 | `services` | `string[]` | `[]` | The list of service names the admin dashboard should surface, exposed as the `qpq-serviceNames` global. Returned by the `/admin/services` route. |
 | `deprecated` | `boolean` | `false` | Inherited from `QPQConfigAdvancedSettings`; marks the log storage drives and key-value stores as deprecated. |
 
@@ -73,10 +71,11 @@ export interface QPQConfigAdvancedLogSettings extends QPQConfigAdvancedSettings
 - **Log storage** — a `QPQ_LOGS_STORAGE_DRIVE_NAME` storage drive (with an `onCreate` handler and the retention / cold-storage lifecycle rules), plus a `QPQ_LOG_REPORTS_STORAGE_DRIVE_NAME` drive (30-day retention) for generated reports.
 - **Log indexes** — key-value stores for correlations (indexed by `runtimeType` and `fromCorrelation`, both sorted by `startedAt`, with a `ttl` attribute), log messages, and a log list.
 - **Auth routes** — `POST /login`, `POST /refreshToken`, `POST /challenge`, authenticated against the [admin user directory](./admin-user-directory.md).
-- **Log routes** — `GET /admin/services`, `POST /log/list`, `GET /log/{correlationId}`, its `/toggle`, `/children`, `/hierarchies`, `/downloadurl`, the log-log list, and the `/log/chat` message endpoints — all (except the service list) requiring an admin token.
+- **Log routes** — `GET /admin/services`, `POST /log/list`, `GET /log/{correlationId}`, its `/toggle`, `/children`, `/hierarchies`, `/downloadurl`, and the log-log list — all (except the service list) requiring an admin token.
+- **Log chat** — a `defineEventDocAi` instance scoped to `docId` = log correlation id, with two tools (`getLogActions`, `getLogAction`) instead of the log's JSON pasted into the prompt. Runs on `AiModel.ClaudeSonnet46` over the same admin WebSocket connection, not a separate HTTP route.
 - **WebSocket sync** — an admin event bus (`qpq-admin-wsq`), a `defineWebSocketQueue`, and queues that fan out client messages (config sync, mark-log-checked, refresh-metadata) using `WebsocketAdminClientMessageEventType`.
 - **Alarms** — a `defineNotifyError` publishing to an `admin-notifier` event bus, with a queue handling its Error / Timeout / Throttle events.
-- **Globals** — `qpq-serviceNames`, `qpq-log-retention-days`, and `claudeAi-api-key`.
+- **Globals** — `qpq-serviceNames` and `qpq-log-retention-days`.
 - **Audit sessions** — spreads in [defineAdminSessionEventDoc](./admin-session-event-doc.md) for the admin UI's per-login session document.
 
 ## Examples
@@ -87,12 +86,10 @@ import { defineAdminSettings, defineAdminUserDirectory } from 'quidproquo-featur
 export default [
   ...defineAdminUserDirectory({ owner: { module: 'log' } }),
 
-  // Retain logs 30 days, move to deep cold storage after 7,
-  // enable the Claude log-chat feature.
+  // Retain logs 30 days, move to deep cold storage after 7.
   ...defineAdminSettings('log', 'example.com', {
     logRetentionDays: 30,
     coldStorageAfterDays: 7,
-    claudeAiApiKeySecretName: 'claude-api-key',
     services: ['api', 'workers'],
   }),
 ];

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

@@ -60,6 +60,8 @@ The single `options` argument is an `EventDocRoutesOptions`:
 | `version` | `number` | `1` | Version number for the `/v{version}` path prefix on every route. |
 | `eventValidator` | `string` | – | Name of a registered inline function (see `defineInlineFunction`). When set, every append invokes it with `{ event, events }` to reject lifecycle- or payload-invalid events before they reach the log. The frontend editor runs the same rule for instant feedback. |
 | `eventRenderer` | `string` | – | Name of a registered inline function. When set, a `GET {basePath}/{id}/render` route is mounted; it invokes the renderer with the document's full `{ events }` log, which folds + renders to HTML. |
+| `onPublish` | `string` | – | Name of a registered inline function. When set, every successful append of a Publish event invokes it with `{ docId, event, summary }`, after the event is durably written and the summary re-derived. This is the seam for syncing a folded document into a materialized read model. Errors propagate to the caller: the event has landed but the side effect did not, so the caller learns the read model may be stale. |
+| `scopeResolver` | `string` | – | Name of a registered inline function. When set, every route invokes it with `{ event }` before running; a non-null result becomes the ambient storage scope for the whole request, transparently partitioning the collection's stores and assets (e.g. per-tenant). Null means unscoped. Omit for collections that never partition. |
 
 ### `RouteAuthSettings`
 

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

@@ -47,6 +47,8 @@ function defineEventDoc(options: EventDocRoutesOptions): QPQConfig;
 | `version` | `number` | no | Route version prefix (`/v{version}`), default `1`. |
 | `eventValidator` | `string` | no | Inline-function name run on every append to reject invalid events. |
 | `eventRenderer` | `string` | no | Inline-function name that folds + renders the log to HTML; mounting it adds a `GET {basePath}/{id}/render` route. |
+| `onPublish` | `string` | no | Inline-function name invoked with `{ docId, event, summary }` after every successful Publish append: the seam for syncing the folded document into a materialized read model. |
+| `scopeResolver` | `string` | no | Inline-function name every route invokes with `{ event }` to resolve the request's ambient storage scope (e.g. per-tenant); null means unscoped. |
 
 ## Examples
 

package/template/docusaurus/docs/config/{webserver → features}/state-dispatch-over-websockets.md

@@ -10,7 +10,7 @@ Registers an action processor override that redirects the core **State** domain'
 - **Built from:** `defineActionProcessors(...)` — it overrides the `StateActionType.Dispatch` processor with the WebSocket queue's `getStateDispatch` implementation. That implementation reads the current connection info and sends a typed `StateDispatch` server message to the client over the [WebSocket queue](./web-socket-queue.md). It takes no arguments.
 
 ```typescript
-import { defineStateDispatchOverWebsockets } from 'quidproquo-webserver';
+import { defineStateDispatchOverWebsockets } from 'quidproquo-features';
 
 export default [
   defineStateDispatchOverWebsockets(),
@@ -38,5 +38,5 @@ Because it operates on the connection context the [WebSocket queue](./web-socket
 ## Related
 
 - [defineWebSocketQueue](./web-socket-queue.md) — provides the connection context and outbound messaging this override relies on.
-- [defineWebsocket](./websocket.md) — the raw WebSocket API underneath the queue.
+- [defineWebsocket](../webserver/websocket.md) — the raw WebSocket API underneath the queue.
 - [askStateDispatch](../../actions/core/state/ask-state-dispatch.md) and [askReduceState](../../actions/core/state/ask-reduce-state.md) — the core State-domain effects whose dispatch is redirected to the client.

package/template/docusaurus/docs/config/features/tenant-stores.md

@@ -0,0 +1,80 @@
+---
+title: defineTenantStores
+description: Declare the data stores for the tenant feature, the tenant event-doc collection and the materialized record table.
+---
+
+# defineTenantStores
+
+Declares the **owner-only stores** that back the tenant (org) feature, without any routes or inline functions. It returns a `QPQConfig` (an array of config settings) that expands to:
+
+1. The **tenant event-doc collection**: a [defineEventDocSummary](./event-doc-summary.md) call for the `tenants` store (summary table, append-only event log, and asset drive). This is the audit-trailed source of truth for tenant state.
+2. The **materialized tenant record store**: a [key-value store](../core/key-value-store.md) named `tenantRecords` (partition key `tenantId`). A fast-read table synced from the event doc on publish; it is never written directly by request handlers.
+
+The **user-tenant membership links store** (`userTenantLinks`, partition key `userId`) is declared separately, directly by [defineTenant](./tenant.md) — every service refs it via the same `owner`, so it isn't part of this helper.
+
+- **On AWS:** deploys everything [defineEventDocSummary](./event-doc-summary.md) deploys (two DynamoDB tables plus an S3 bucket), plus one more DynamoDB table (via [defineKeyValueStore](../core/key-value-store.md)) for the record store.
+
+```typescript
+import { defineTenantStores } from 'quidproquo-features';
+
+export default [
+  ...defineTenantStores(),
+];
+```
+
+You rarely call this directly: [defineTenant](./tenant.md) composes it along with the routes and inline functions, gated to the owner's deploy. Call it on its own only when you want the stores without the tenant routes.
+
+## Signature
+
+```typescript
+function defineTenantStores(): QPQConfig;
+```
+
+## Parameters
+
+None. All store names are fixed constants exported from `quidproquo-features`:
+
+| Constant | Value | Store |
+| --- | --- | --- |
+| `TENANT_EVENTDOC_STORE` | `'tenants'` | The tenant event-doc collection. |
+| `TENANT_RECORD_STORE` | `'tenantRecords'` | The materialized tenant record table. |
+
+The membership table's constant, `USER_TENANT_LINKS_STORE` (`'userTenantLinks'`), is also exported, but the store itself is declared by [defineTenant](./tenant.md), not here.
+
+## Store row shapes
+
+The record store holds `TenantRecord` rows, derived from the tenant event doc on publish:
+
+```typescript
+type TenantRecord = {
+  tenantId: string;
+  name: string;
+  brandColors?: Record<string, string>;
+  logoUrl?: string;
+  createdAt: QpqIsoDateTime;
+  updatedAt: QpqIsoDateTime;
+  createdByUserId: string;
+  status: TenantStatus;
+};
+```
+
+The membership store holds `UserTenantLinks` rows:
+
+```typescript
+type UserTenantLinks = {
+  userId: string;
+  tenantIds: string[];
+};
+```
+
+## Notes
+
+- The tenant event-doc collection is the source of truth; the `tenantRecords` table is a read model. The sync between them is the `askTenantOnPublish` inline function, which [defineTenant](./tenant.md) registers and wires into the collection's `onPublish` hook.
+- Creating a tenant appends its id to the caller's `UserTenantLinks` row, so the creator becomes the tenant's first member.
+- Services that do **not** own these stores still call [defineTenant](./tenant.md) (with the same `owner`) to get the scope resolver and a cross-module reference to the membership table — they never call `defineTenantStores` themselves.
+
+## Related
+
+- [defineTenant](./tenant.md): composes these stores with the routes and inline functions; the usual entry point.
+- [defineEventDocSummary](./event-doc-summary.md): the event-doc store helper this composes for the `tenants` collection.
+- [defineKeyValueStore](../core/key-value-store.md): the core setting behind the record table.

package/template/docusaurus/docs/config/features/tenant.md

@@ -0,0 +1,81 @@
+---
+title: defineTenant
+description: Wire up org/tenant support across every service in one call — the registry (stores, publish sync, routes) on the owner, the scope resolver everywhere.
+---
+
+# defineTenant
+
+Wires up **everything for org/tenant support**, declared identically in every service that needs it. You always pass the same `owner`; what actually materializes depends on whether the current module is that owner. It returns a `QPQConfig` (an array of config settings) composed of:
+
+- The scope-resolver and connection-scope-resolver [inline functions](../core/inline-function.md) (`TENANT_SCOPE_RESOLVER_FN`, `TENANT_CONNECTION_SCOPE_RESOLVER_FN`) — registered in **every** service, so each can tenant-scope its own collections and WebSocket connections. The tenant collection itself is an ordinary tenanted collection too: a tenant doc lives in whatever scope the request that created it ran under (the creator's personal partition, or the active tenant when an org creates a sub-tenant), and every tenant route resolves its scope with the same resolver. The cross-scope registry surface is the membership table plus the materialized `TenantRecord` store below, both unscoped.
+- The `userTenantLinks` membership table ([key-value store](../core/key-value-store.md)) — declared with `owner` everywhere, so non-owner services get a cross-module reference to the owner's table instead of their own copy.
+- Everything else, gated to the owner's deploy only via [defineServiceSettings](../core/service-settings.md):
+  - The tenant stores ([defineTenantStores](./tenant-stores.md)): the tenant event-doc collection plus the materialized record table.
+  - The publish-to-record-store sync: an inline function (`askTenantOnPublish`) that runs on every published tenant document, re-folds the full event log, and upserts the resulting `TenantRecord`. It is a plain upsert of the fold result, so publish retries and repair re-runs are safe.
+  - The generic event-doc CRUD under `{basePath}/docs` ([defineEventDocRoutes](./event-doc-routes.md) for the `tenants` store, `tenant` type, with the publish sync wired in as `onPublish`).
+  - The tenant-specific routes at `{basePath}`: list my tenants, create, get record, and get logo.
+
+- **On AWS:** on the owner's deploy, this deploys everything [defineTenantStores](./tenant-stores.md) deploys (two DynamoDB tables and an S3 bucket) plus the API Gateway routes and Lambda handlers from [defineEventDocRoutes](./event-doc-routes.md) and the four tenant routes below. On every other service's deploy, only the `userTenantLinks` reference resolves (no new table); the inline functions deploy no infrastructure of their own anywhere.
+
+```typescript
+import { defineTenant } from 'quidproquo-features';
+
+// Declare identically in every service — the owner service and any other
+// service that needs to tenant-scope its own collections.
+export default [
+  ...defineTenant({
+    owner: { module: 'ca' },
+    basePath: '/tenants',
+    routeAuthSettings: { userDirectoryName: 'users' },
+  }),
+];
+```
+
+## Routes mounted
+
+All paths are prefixed with the version segment `/v{version}` (default `/v1`) and use the `routeAuthSettings` you pass:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `{basePath}` | The authenticated user's tenants, as `EventDocSummary` rows. Runs under the request's scope: memberships homed in the caller's current partition hydrate live (drafts included); the rest hydrate from the published `TenantRecord` registry. |
+| `POST` | `{basePath}` | Create a tenant (body `{ name }`); the caller becomes its first member. Runs under the request's scope, so the new tenant doc lands in the caller's current partition. |
+| `GET` | `{basePath}/{id}` | One tenant's materialized record (the fast path). Members only: non-members get `Forbidden`, a missing record gets `NotFound`. |
+| `GET` | `{basePath}/{id}/logo` | A presigned, short-lived URL for the tenant's logo blob. Members only: non-members get `Forbidden`; a missing record or a tenant with no logo gets `NotFound`. Presigned in the scope the tenant doc was published under (recorded on the `TenantRecord`), not the reader's own scope, since the logo asset lives in the doc's home partition. |
+
+On top of these, the full generic event-doc route set (create, append, list, assets, and so on) is mounted under `{basePath}/docs`; see [defineEventDocRoutes](./event-doc-routes.md#routes-mounted) for the list.
+
+## Signature
+
+```typescript
+function defineTenant(options: TenantOptions): QPQConfig;
+```
+
+## Parameters
+
+The single `options` argument is a `TenantOptions` (a `TenantRoutesOptions` plus `owner`):
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `owner` | `CrossModuleOwner & { module: string }` | – (required) | The service that owns the tenant registry, e.g. `{ module: 'ca' }`. Pass the **same** value in every service's `defineTenant` call; the registry (stores, publish sync, management routes) only materializes when the deploying module matches this. |
+| `basePath` | `` `/${string}` `` | – (required) | URL prefix the tenant routes mount under, e.g. `/tenants`. The generic event-doc CRUD mounts under `{basePath}/docs`. Only used on the owner's deploy, but required on every call for type consistency across services. |
+| `routeAuthSettings` | `RouteAuthSettings` | – (required) | Auth applied to every mounted route (see [route](../webserver/route.md)). Required here, unlike the generic event-doc routes: tenant routes are meaningless unauthenticated, since membership keys off the user. Only used on the owner's deploy. |
+| `version` | `number` | `1` | Version number for the `/v{version}` path prefix on every route. Only used on the owner's deploy. |
+| `tenantHeaderName` | `string` | `'x-qpq-tenant-id'` | The header the client sends its selected tenant id on. Exposed to the tenant routes as the `tenantHeaderName` global, which the scope resolver reads. |
+
+## Notes
+
+- Tenant state is event-sourced: the `tenants` event-doc collection is the audit-trailed source of truth, and the `tenantRecords` table is a read model synced on publish. Request handlers never write the record table directly.
+- The `tenants` collection is scope-resolved like any other tenanted collection (see [defineTenantedEventDoc](./tenanted-event-doc.md)): a doc is only visible/editable from the scope that owns it, including through the generic CRUD under `{basePath}/docs`. There is no cross-scope doc read — listing memberships homed in another scope goes through the published `TenantRecord`, not the doc store.
+- The `TenantRecord` produced by the publish sync carries `tenantId`, `name`, `brandColors`, `logo` (an asset ref, resolved to a URL via the get-logo route above), `scope` (the storage scope the doc was published under, used to presign the logo for cross-scope readers), `createdAt`, `updatedAt`, `createdByUserId`, and a `status` derived from the summary (`deleted` when the summary has a `deletedAt`, otherwise `active`).
+- `defineTenant` registers the scope resolver but does not apply it to anything. To tenant-scope one of your own collections, pass `TENANT_SCOPE_RESOLVER_FN` as that collection's `scopeResolver` option (or use [defineTenantedEventDoc](./tenanted-event-doc.md), which does this for you).
+- The scope resolver always resolves to a typed scope — a membership-checked `TENANT#<id>` for a request that names a tenant, or the caller's own `PERSONAL#<userId>` when it doesn't. A tenant-scoped collection or connection is never left unscoped.
+- Every service — owner and non-owner alike — calls `defineTenant` with the same `owner`. There is no separate call for non-owning services anymore: the gating happens internally via [defineServiceSettings](../core/service-settings.md).
+
+## Related
+
+- [defineTenantStores](./tenant-stores.md): the store half of this helper (owner-only).
+- [defineTenantedEventDoc](./tenanted-event-doc.md): a `defineEventDoc` with `TENANT_SCOPE_RESOLVER_FN` pre-wired as `scopeResolver`.
+- [defineEventDocRoutes](./event-doc-routes.md): the generic CRUD mounted under `{basePath}/docs`, and home of the `scopeResolver` / `onPublish` options.
+- [defineWebSocketQueue](./web-socket-queue.md): where the tenant connection-scope resolver plugs in.
+- [defineTenantedWebSocketQueue](./tenanted-web-socket-queue.md): a `defineWebSocketQueue` with that resolver pre-wired.
+- [defineServiceSettings](../core/service-settings.md): the per-module gating mechanism this uses to materialize the registry only on the owner.

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

@@ -0,0 +1,51 @@
+---
+title: defineTenantedEventDoc
+description: A defineEventDoc with the tenant scope resolver pre-wired, so the collection's stores and assets partition per tenant.
+---
+
+# defineTenantedEventDoc
+
+A [defineEventDoc](./event-doc.md) with the tenant scope resolver pre-wired as its `scopeResolver`, so the collection's stores and assets partition per tenant: request header → membership check → tenant scope, or the caller's own personal scope when no header is sent — the collection is never unscoped. It takes the same arguments as `defineEventDoc` minus `scopeResolver`, which it fills in for you.
+
+The deploying service must still register the resolver implementation by calling [defineTenant](./tenant.md) (with the same `owner` used everywhere else). Use plain [defineEventDoc](./event-doc.md) for collections that never partition by tenant.
+
+```typescript
+import { defineTenantedEventDoc, defineTenant } from 'quidproquo-features';
+
+export default [
+  ...defineTenant({
+    owner: { module: 'ca' },
+    basePath: '/tenants',
+    routeAuthSettings: { userDirectoryName: 'users' },
+  }),
+
+  ...defineTenantedEventDoc({
+    storeName: 'content',
+    type: 'article',
+    basePath: '/articles',
+    routeAuthSettings: { userDirectoryName: 'users' },
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineTenantedEventDoc(options: TenantedEventDocOptions): QPQConfig;
+```
+
+`TenantedEventDocOptions` is `EventDocRoutesOptions` with `scopeResolver` omitted — see [defineEventDoc](./event-doc.md#parameters) for the remaining options.
+
+## Parameters
+
+Same as [defineEventDoc](./event-doc.md#parameters): `storeName`, `type`, `basePath`, `routeAuthSettings`, `version`, `eventValidator`, `eventRenderer`, `onPublish` (without `scopeResolver`, which this always sets to `TENANT_SCOPE_RESOLVER_FN`).
+
+## Returns
+
+Same as [defineEventDoc](./event-doc.md) — a `QPQConfig` array with the collection's `scopeResolver` already pointed at the tenant scope resolver.
+
+## Related
+
+- [defineEventDoc](./event-doc.md) — the underlying define this pre-configures.
+- [defineTenant](./tenant.md) — registers `TENANT_SCOPE_RESOLVER_FN`, the inline function this wires in by name.
+- [defineTenantedWebSocketQueue](./tenanted-web-socket-queue.md) — the same pattern applied to a WebSocket queue's `connectionScopeResolver`.

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

@@ -0,0 +1,52 @@
+---
+title: defineTenantedWebSocketQueue
+description: A defineWebSocketQueue with the tenant scope resolution pre-wired as the connection scope resolver.
+---
+
+# defineTenantedWebSocketQueue
+
+A [defineWebSocketQueue](./web-socket-queue.md) with tenant scope resolution pre-wired as its `connectionScopeResolver`: a tenant id claimed in the WebSocket Authenticate handshake is membership-checked before it is stored, and a handshake with no claim stores the user's own personal scope instead of leaving the connection unscoped. It takes the same arguments as `defineWebSocketQueue` minus `connectionScopeResolver`, which it fills in for you.
+
+The deploying service must still register the resolver implementation by calling [defineTenant](./tenant.md) (with the same `owner` used everywhere else).
+
+```typescript
+import { defineTenantedWebSocketQueue, defineTenant } from 'quidproquo-features';
+
+export default [
+  ...defineTenant({
+    owner: { module: 'ca' },
+    basePath: '/tenants',
+    routeAuthSettings: { userDirectoryName: 'users' },
+  }),
+
+  defineTenantedWebSocketQueue('my-event-bus', 'api', 'example.com', {
+    userDirectoryName: 'users',
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineTenantedWebSocketQueue(
+  eventBusName: string,
+  apiName: string,
+  rootDomain: string,
+  advancedSettings?: QPQConfigAdvancedTenantedWebsocketQueueSettings,
+): QPQConfig;
+```
+
+`QPQConfigAdvancedTenantedWebsocketQueueSettings` is `QPQConfigAdvancedWebsocketQueueSettings` with `connectionScopeResolver` omitted — see [defineWebSocketQueue](./web-socket-queue.md#advancedsettings--qpqconfigadvancedwebsocketqueuesettings-optional) for the remaining options.
+
+## 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`).
+
+## Returns
+
+Same as [defineWebSocketQueue](./web-socket-queue.md#returns) — a `QPQConfig` array with the connection-scope resolver already pointed at the tenant scope resolution.
+
+## Related
+
+- [defineWebSocketQueue](./web-socket-queue.md) — the underlying define this pre-configures.
+- [defineTenant](./tenant.md) — registers `TENANT_CONNECTION_SCOPE_RESOLVER_FN` (the inline function this wires in by name) plus the rest of the tenant setup.