create-qpq-app 0.1.7 → 0.1.8

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-get-all.md

@@ -37,7 +37,13 @@ function* askKeyValueStoreGetAll<Value>(
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `keyValueStoreName` | `string` | Name of the store to read from — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md) (or one shared via its `owner` option). |
-| `options` | `KeyValueStoreGetAllOptions` | Reserved for future read options; currently empty. |
+| `options` | `KeyValueStoreGetAllOptions` | Optional read options (see below). |
+
+### `KeyValueStoreGetAllOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `scope` | `string` | – | Optional storage scope. The processor enforces it as a begins-with prefix filter on the partition key, so only records written under the same scope are returned (used by tenant/scoped features). Requires the store's partition key to be string-typed. When no scope is given, scope-composed records are excluded, so one tenant's data never appears in an unscoped listing. |
 
 ## Returns
 
@@ -49,6 +55,8 @@ function* askKeyValueStoreGetAll<Value>(
 | --- | --- |
 | `KeyValueStoreGetAllErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreGetAllErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+| `KeyValueStoreGetAllErrorTypeEnum.InvalidScope` | The `scope` option is malformed (empty, `.`, over 128 characters, or containing path separators, `..`, `@`, or null bytes), the store's partition key is not string-typed, or a scoped call's partition-key value contains the reserved `@@QPQSCOPE@@` delimiter. |
+| `KeyValueStoreGetAllErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.
 

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-get.md

@@ -39,7 +39,13 @@ function* askKeyValueStoreGet<Value>(
 | --- | --- | --- |
 | `keyValueStoreName` | `string` | Name of the store to read from — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md) (or one shared via its `owner` option). |
 | `key` | `string` | The partition key value of the record to fetch. |
-| `options` | `KeyValueStoreGetOptions` | Reserved for future read options; currently empty. |
+| `options` | `KeyValueStoreGetOptions` | Optional read options (see below). |
+
+### `KeyValueStoreGetOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `scope` | `string` | – | Optional storage scope. The processor composes it into the partition key value, so scoped and unscoped records live under separate keys in the same store (used by tenant/scoped features). Requires the store's partition key to be string-typed. |
 
 ## Returns
 
@@ -51,6 +57,8 @@ function* askKeyValueStoreGet<Value>(
 | --- | --- |
 | `KeyValueStoreGetErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreGetErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+| `KeyValueStoreGetErrorTypeEnum.InvalidScope` | The `scope` option is malformed (empty, `.`, over 128 characters, or containing path separators, `..`, `@`, or null bytes), the store's partition key is not string-typed, or the partition-key value contains the reserved `@@QPQSCOPE@@` delimiter (reserved on string-pk stores, so unscoped calls reject it too). |
+| `KeyValueStoreGetErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an object — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-query-single.md

@@ -32,6 +32,7 @@ function* askKeyValueStoreQuerySingle<T>(
   filter?: KvsQueryOperation,
   sortAscending?: boolean,
   limit?: number,
+  scope?: string,
 ): AskResponse<T | null>;
 ```
 
@@ -44,6 +45,7 @@ function* askKeyValueStoreQuerySingle<T>(
 | `filter` | `KvsQueryOperation` | – | Optional filter on non-key attributes, applied after the key match. |
 | `sortAscending` | `boolean` | – | Order by the sort key; `false` returns the highest/newest first. |
 | `limit` | `number` | `1` | How many records to fetch per underlying page while searching. The story still returns only the first matching record. |
+| `scope` | `string` | – | Optional storage scope, passed through as the underlying query's `scope` option. See [`KeyValueStoreQueryOptions`](./ask-key-value-store-query.md#keyvaluestorequeryoptions). An invalid scope surfaces as `KeyValueStoreQueryErrorTypeEnum.InvalidScope`. |
 
 ## Returns
 
@@ -52,6 +54,7 @@ function* askKeyValueStoreQuerySingle<T>(
 ## Notes
 
 - Because `filter` is applied after the key match, when a filter is supplied the helper pages through results until it has gathered up to `limit` records before returning the first — so a matching record isn't missed just because it fell outside the first page.
+- The record returned is the first one **collected across all fetched pages**, so a match found on an early page still wins even when a later page comes back empty.
 - Errors surface the same as the underlying query (`KeyValueStoreQueryErrorTypeEnum`); catch them with `askCatch`.
 
 ## Related

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-query.md

@@ -55,7 +55,8 @@ function* askKeyValueStoreQuery<KvsItem>(
 | `sortAscending` | `boolean` | `true` | Order results by the sort key. `false` returns the newest/highest first. |
 | `limit` | `number` | – | Maximum number of records to return in this page. |
 | `nextPageKey` | `string` | – | Opaque cursor from a previous page's `nextPageKey`; pass it to fetch the following page. |
-| `ttlInSeconds` | `number` | – | Time-to-live in seconds for a cached result of this query. |
+| `ttlInSeconds` | `number` | – | Accepted but not implemented: no processor currently applies a TTL to query results, so setting it has no effect. |
+| `scope` | `string` | – | Optional storage scope. The processor composes it into the partition-key conditions, so the query only matches records written under the same scope (used by tenant/scoped features). Requires a string-typed partition key, and the key condition must constrain the partition key. |
 
 ## Query conditions (`KvsQueryOperation`)
 
@@ -116,6 +117,8 @@ When `nextPageKey` is set, pass it back as `options.nextPageKey` to fetch the ne
 | --- | --- |
 | `KeyValueStoreQueryErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreQueryErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+| `KeyValueStoreQueryErrorTypeEnum.InvalidScope` | The `scope` option is malformed (empty, `.`, over 128 characters, or containing path separators, `..`, `@`, or null bytes), the store's partition key is not string-typed, a scoped query's key condition does not constrain the partition key (or constrains it with an operator that cannot be scoped), or a partition-key condition value contains the reserved `@@QPQSCOPE@@` delimiter (reserved on string-pk stores, so unscoped queries reject it too). |
+| `KeyValueStoreQueryErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.
 

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-scan-all.md

@@ -29,6 +29,7 @@ export function* askAllSuspendedUsers() {
 function* askKeyValueStoreScanAll<T>(
   storeName: string,
   filterCondition?: KvsQueryOperation,
+  options?: KeyValueStoreScanOptions,
 ): AskResponse<T[]>;
 ```
 
@@ -38,6 +39,7 @@ function* askKeyValueStoreScanAll<T>(
 | --- | --- | --- |
 | `storeName` | `string` | Name of the store to scan — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md). |
 | `filterCondition` | `KvsQueryOperation` | Optional filter applied to every scanned record — see [Query conditions](./ask-key-value-store-query.md#query-conditions-kvsqueryoperation). Omit it to return every record. |
+| `options` | `KeyValueStoreScanOptions` | Optional scan options, forwarded to the underlying scan on **every** page (see [`KeyValueStoreScanOptions`](./ask-key-value-store-scan.md#keyvaluestorescanoptions)). In particular `scope` restricts every page to records written under that storage scope. |
 
 ## Returns
 

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-scan.md

@@ -30,6 +30,7 @@ function* askKeyValueStoreScan<KvsItem>(
   keyValueStoreName: string,
   filterCondition?: KvsQueryOperation,
   nextPageKey?: string,
+  options?: KeyValueStoreScanOptions,
 ): AskResponse<QpqPagedData<KvsItem>>;
 ```
 
@@ -40,6 +41,15 @@ function* askKeyValueStoreScan<KvsItem>(
 | `keyValueStoreName` | `string` | Name of the store to scan — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md) (or one shared via its `owner` option). |
 | `filterCondition` | `KvsQueryOperation` | Optional filter applied to every scanned record. Built with the `kvs*` condition helpers — see [Query conditions](./ask-key-value-store-query.md#query-conditions-kvsqueryoperation). Omit it to return everything. |
 | `nextPageKey` | `string` | Opaque cursor from a previous page's `nextPageKey`; pass it to fetch the following page. |
+| `options` | `KeyValueStoreScanOptions` | Optional scan options (see below). |
+
+### `KeyValueStoreScanOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `limit` | `number` | – | Accepted but not implemented: no processor currently caps the page size of a scan, so setting it has no effect. |
+| `ttlInSeconds` | `number` | – | Accepted but not implemented: no processor currently applies a TTL to scans, so setting it has no effect. |
+| `scope` | `string` | – | Optional storage scope. The processor enforces it as a begins-with prefix filter on the partition key, so only records written under the same scope are returned (used by tenant/scoped features). It is still a full-table scan on the storage side; only the results are isolated. Requires the store's partition key to be string-typed. When no scope is given, scope-composed records are excluded, so one tenant's data never appears in an unscoped listing. |
 
 ## Returns
 
@@ -60,6 +70,8 @@ When `nextPageKey` is set, pass it back as the third argument to fetch the next
 | --- | --- |
 | `KeyValueStoreScanErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreScanErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+| `KeyValueStoreScanErrorTypeEnum.InvalidScope` | The `scope` option is malformed (empty, `.`, over 128 characters, or containing path separators, `..`, `@`, or null bytes), the store's partition key is not string-typed, or a scoped call's partition-key value contains the reserved `@@QPQSCOPE@@` delimiter. |
+| `KeyValueStoreScanErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.
 

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-update-partial-properties.md

@@ -38,6 +38,8 @@ function* askKeyValueStoreUpdatePartialProperties<TModel, PartitionKey extends k
   keyValueStoreName: string,
   partitionKeyName: PartitionKey,
   partialProperties: Partial<TModel> & { [k in PartitionKey]: TModel[PartitionKey] },
+  sortKeyName?: undefined,
+  options?: KeyValueStoreUpdateOptions,
 ): AskResponse<TModel>;
 
 // Partition + sort key
@@ -46,6 +48,7 @@ function* askKeyValueStoreUpdatePartialProperties<TModel, PartitionKey extends k
   partitionKeyName: PartitionKey,
   partialProperties: Partial<TModel> & { [k in PartitionKey]: TModel[PartitionKey] } & { [k in SortKey]: TModel[SortKey] },
   sortKeyName: SortKey,
+  options?: KeyValueStoreUpdateOptions,
 ): AskResponse<TModel>;
 ```
 
@@ -57,6 +60,7 @@ function* askKeyValueStoreUpdatePartialProperties<TModel, PartitionKey extends k
 | `partitionKeyName` | `keyof TModel` | The property name that holds the partition key. That property must be present in `partialProperties`; it is used to address the record, not written. |
 | `partialProperties` | `Partial<TModel>` (with the key properties required) | The record patch. Each non-key property becomes a `Set`; a property explicitly set to `undefined` becomes a `Remove`. |
 | `sortKeyName` | `keyof TModel` | (Overload) The property name holding the sort key, when the store has one. Must be present in `partialProperties`. |
+| `options` | `KeyValueStoreUpdateOptions` | Optional update options, passed straight through to the underlying update (see [`KeyValueStoreUpdateOptions`](./ask-key-value-store-update.md#keyvaluestoreupdateoptions)). In particular `scope` addresses the record written under that storage scope. |
 
 ## Returns
 
@@ -65,7 +69,7 @@ function* askKeyValueStoreUpdatePartialProperties<TModel, PartitionKey extends k
 ## Notes
 
 - The partition-key (and sort-key) properties are skipped when building the operations — they identify the record rather than mutate it.
-- A property whose value is `undefined` is turned into a `Remove`; a property with a valid value is turned into a `Set`. Values that aren't a supported store data type are silently skipped (validated internally via `isValidKvsAdvancedDataType`).
+- A property whose value is `undefined` is turned into a `Remove`; a property with a valid value is turned into a `Set`. A value that isn't a supported store data type (validated via `isValidKvsAdvancedDataType`, e.g. a nested object) throws an `InvalidKvsPartialPropertyError` (code `unsupportedValueType`) before anything is written, rather than being silently skipped.
 - Errors surface the same as the underlying update (`KeyValueStoreUpdateErrorTypeEnum`); catch them with `askCatch`.
 
 ## Related

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-update.md

@@ -52,7 +52,13 @@ function* askKeyValueStoreUpdate<Value>(
 | `updates` | `KvsUpdate` | The list of update operations to apply. See [Update operations](#update-operations-kvsupdate). |
 | `key` | `KvsCoreDataType` | Partition key value of the record to update (`string \| number`). |
 | `sortKey` | `KvsCoreDataType` | Sort key value, required only if the store declares a sort key (`string \| number`). |
-| `options` | `KeyValueStoreUpdateOptions` | Reserved for future update options; currently empty. |
+| `options` | `KeyValueStoreUpdateOptions` | Optional update options (see below). |
+
+### `KeyValueStoreUpdateOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `scope` | `string` | – | Optional storage scope. The processor composes it into the partition key value, so the update only addresses the record written under that scope (used by tenant/scoped features). Requires the store's partition key to be string-typed. |
 
 ## Update operations (`KvsUpdate`)
 
@@ -95,6 +101,8 @@ Each `path` is a `KvsAttributePath` — either a top-level attribute name (`'bal
 | --- | --- |
 | `KeyValueStoreUpdateErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreUpdateErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+| `KeyValueStoreUpdateErrorTypeEnum.InvalidScope` | The `scope` option is malformed (empty, `.`, over 128 characters, or containing path separators, `..`, `@`, or null bytes), the store's partition key is not string-typed, or the partition-key value contains the reserved `@@QPQSCOPE@@` delimiter (reserved on string-pk stores, so unscoped calls reject it too). |
+| `KeyValueStoreUpdateErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.
 

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-upsert-with-retry.md

@@ -42,7 +42,7 @@ function* askKeyValueStoreUpsertWithRetry<KvsItem>(
 
 ### `KeyValueStoreUpsertWithRetryOptions`
 
-Extends `KeyValueStoreUpsertOptions` (`ttlInSeconds`, `ifNotExists`) with:
+Extends `KeyValueStoreUpsertOptions` (`ttlInSeconds`, `ifNotExists`, `scope`) with:
 
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-upsert.md

@@ -47,6 +47,7 @@ function* askKeyValueStoreUpsert<KvsItem>(
 | --- | --- | --- | --- |
 | `ttlInSeconds` | `number` | – | Time-to-live in seconds; sets the record's expiry (used with the store's `ttlAttribute`). |
 | `ifNotExists` | `boolean` | `false` | Conditional insert: only write when no item with the same key exists. A losing concurrent writer receives `KeyValueStoreUpsertErrorTypeEnum.Conflict` instead of silently overwriting — the primitive for optimistic-concurrency schemes (e.g. append-only event logs where the sort key is a claimed index). |
+| `scope` | `string` | – | Optional storage scope. The processor composes it into the item's partition key value, so the record is written under that scope and only scoped reads see it (used by tenant/scoped features). Requires the store's partition key to be string-typed. |
 
 ## Returns
 
@@ -59,6 +60,8 @@ function* askKeyValueStoreUpsert<KvsItem>(
 | `KeyValueStoreUpsertErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreUpsertErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
 | `KeyValueStoreUpsertErrorTypeEnum.Conflict` | A conditional (`ifNotExists`) write lost to an existing item. Namespaced — not the generic `ErrorTypeEnum.Conflict` — so retry logic can target the write race specifically without also catching domain-level conflicts. |
+| `KeyValueStoreUpsertErrorTypeEnum.InvalidScope` | The `scope` option is malformed (empty, `.`, over 128 characters, or containing path separators, `..`, `@`, or null bytes), the store's partition key is not string-typed, or the partition-key value contains the reserved `@@QPQSCOPE@@` delimiter (reserved on string-pk stores, so unscoped calls reject it too). |
+| `KeyValueStoreUpsertErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.
 

package/template/docusaurus/docs/actions/core/network/ask-network-request.md

@@ -88,7 +88,7 @@ if (outcome.success) {
 
 ## Notes
 
-- Requests abort after 25 seconds, surfacing as `NetworkRequestErrorTypeEnum.Timeout`.
+- Requests abort after 30 seconds, surfacing as `NetworkRequestErrorTypeEnum.Timeout`. (30s deliberately outlasts API Gateway's 29s integration timeout, so a slow upstream shows up as a real gateway error rather than a client-side abort.)
 
 ## Related
 

package/template/docusaurus/docs/actions/core/state/ask-reduce-state.md

@@ -157,4 +157,4 @@ Effects the reducer doesn't handle leave the state unchanged and are skipped. Us
 
 - [askStateDispatch](./ask-state-dispatch.md) — dispatch the effects this story reduces.
 - [askStateRead](./ask-state-read.md) — read the accumulated state mid-story.
-- [defineStateDispatchOverWebsockets](../../../config/webserver/state-dispatch-over-websockets.md) — stream reduced dispatches to a WebSocket client.
+- [defineStateDispatchOverWebsockets](../../../config/features/state-dispatch-over-websockets.md) — stream reduced dispatches to a WebSocket client.

package/template/docusaurus/docs/actions/core/state/ask-state-dispatch.md

@@ -84,4 +84,4 @@ function* askStateDispatchEffect<E extends Effect<any, any>>(
 
 - [askStateRead](./ask-state-read.md) — read the state that dispatches accumulate into.
 - [askReduceState](./ask-reduce-state.md) — run a story purely for its dispatched effects and return the reduced state.
-- [defineStateDispatchOverWebsockets](../../../config/webserver/state-dispatch-over-websockets.md) — redirect these dispatches to a connected WebSocket client.
+- [defineStateDispatchOverWebsockets](../../../config/features/state-dispatch-over-websockets.md) — redirect these dispatches to a connected WebSocket client.

package/template/docusaurus/docs/actions/core/stream/ask-stream-map.md

@@ -61,7 +61,7 @@ function* askStreamMap<E extends StreamEncoding, T, R = StreamDataType<E, T>>(
 ## Notes
 
 - The `index` counts only chunks handed to your callback — chunks that are `skipped` or carry no `data` are dropped and do not advance it.
-- The handle is closed for you when the loop ends.
+- The handle is closed for you when the loop ends. This includes failures: when a read or your callback fails, the stream is closed first and the original error is then rethrown, so a surrounding [askCatch](../system/ask-catch.md) can handle it without leaking the stream.
 - Because it buffers the entire stream in memory, prefer [askStreamProcess](./ask-stream-process.md) when you only need to react to each chunk and don't need the full list.
 
 ## Related

package/template/docusaurus/docs/actions/core/stream/ask-stream-process.md

@@ -46,7 +46,8 @@ function* askStreamProcess<E extends StreamEncoding, T>(
 ## Notes
 
 - The `index` counts only chunks handed to your callback — chunks that are `skipped` or carry no `data` are dropped and do not advance it.
-- The handle is closed for you when the loop ends. If you need finer control — reading only part of a stream, or polling with `noWait` — drive [askStreamRead](./ask-stream-read.md) / [askStreamClose](./ask-stream-close.md) directly instead.
+- The handle is closed for you when the loop ends. This includes failures: when a read or your callback fails, the stream is closed first and the original error is then rethrown, so a surrounding [askCatch](../system/ask-catch.md) can handle it without leaking the stream.
+- If you need finer control — reading only part of a stream, or polling with `noWait` — drive [askStreamRead](./ask-stream-read.md) / [askStreamClose](./ask-stream-close.md) directly instead.
 - To build up a result rather than react to each chunk, use [askStreamMap](./ask-stream-map.md).
 
 ## Related

package/template/docusaurus/docs/actions/core/system/ask-trace-story.md

@@ -0,0 +1,66 @@
+---
+title: askTraceStory
+description: Replay a recorded story against its real code and capture a line-by-line execution trace.
+---
+
+# askTraceStory
+
+Replays a previously recorded story execution (a `StoryResult` from the logs) against the story's real code and records a **line-by-line execution trace**: every statement the story executed, with the values of its local variables at that moment.
+
+- **Action type:** `SystemActionType.TraceStory`
+- **Runtime support:** only node runtimes (AWS Lambda and the dev server) implement a processor. The tracer drives the V8 inspector, so browser runtimes cannot process this action.
+
+The recorded `StoryResult` already contains every action result the original run saw, so the replay is deterministic: the story re-executes with the exact same inputs and answers, and the tracer captures what happened between the actions. The story's code is loaded through the runtime's dynamic module loader (which federates on Lambda), so the trace runs the same code that ran originally.
+
+```typescript
+import { askTraceStory } from 'quidproquo-core';
+
+export function* askDebugExecution(storyResult: StoryResult<any>) {
+  const trace = yield* askTraceStory(storyResult);
+
+  // trace.steps: one entry per executed statement, with locals captured at that point.
+  return trace;
+}
+```
+
+## Signature
+
+```typescript
+function* askTraceStory(
+  storyResult: StoryResult<any>,
+  scriptPatterns?: string[],
+  onlyOwnCode?: boolean,
+): AskResponse<QpqExecutionTrace>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `storyResult` | `StoryResult<any>` | The recorded execution to replay. Must carry `qpqFunctionRuntimeInfo` so the processor can locate the story's code. |
+| `scriptPatterns` | `string[]` | Optional regex sources matched against script urls, tracing extra scripts in addition to the story function's own script (for bundles split across chunks). |
+| `onlyOwnCode` | `boolean` | Optional. When true, breakpoints are only set on statements whose source-mapped origin is the service's own code; positions mapping into node_modules (framework and dependencies) are skipped, so the step budget is spent entirely on user statements. |
+
+## Returns
+
+`QpqExecutionTrace`: the trace of the replay.
+
+- `sources`: the original source files the trace maps into (with content when source maps shipped `sourcesContent`).
+- `steps`: one entry per executed statement (source position, function name, captured locals, and the return value at function-return points).
+- `truncated`: true when the step budget was hit; the replay still ran to completion but later steps were not recorded.
+- `stats`: pause/breakpoint counts and timing, including the urls of every instrumented script.
+
+## Errors
+
+| Error type | When |
+| --- | --- |
+| `ErrorTypeEnum.BadRequest` | The `storyResult` has no `qpqFunctionRuntimeInfo`, so the processor cannot locate its code. |
+| `ErrorTypeEnum.NotFound` | The story's module could not be dynamically loaded. |
+| `ErrorTypeEnum.GenericError` | The tracer itself failed while replaying the story. |
+
+Wrap the call in [askCatch](./ask-catch.md) to handle these as values.
+
+## Related
+
+- [askGetRuntimeCorrelation](./ask-get-runtime-correlation.md): the correlation id that identifies the recorded execution to trace.
+- [askExecuteStory](./ask-execute-story.md): run a story fresh from its runtime reference (rather than replaying a recorded run).

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-authenticate-user.md

@@ -65,7 +65,7 @@ function* askUserDirectoryAuthenticateUser(
 | `userDirectoryName` | `string` | Name of the directory to authenticate against — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md) (or one shared via its `owner` option). |
 | `isCustom` | `boolean` | `false` for a standard email + password sign-in; `true` to start Cognito's custom auth flow (requires a [customAuthRuntime](../../../config/core/user-directory.md#custom-auth-runtime)). When `true`, `password` is not used. |
 | `email` | `string` | The user's email / username. |
-| `password` | `string` | The user's password. Required for a standard (`isCustom: false`) sign-in; omitted for custom auth. |
+| `password` | `string` | The user's password. Required for a standard (`isCustom: false`) sign-in: a missing or empty password throws `InvalidPassword`. Omitted for custom auth. |
 
 ## Returns
 
@@ -98,8 +98,8 @@ interface AuthenticationInfo {
 
 | Error | Meaning |
 | --- | --- |
-| `UserDirectoryAuthenticateUserErrorTypeEnum.UserNotFound` | No user matches the supplied email. |
-| `UserDirectoryAuthenticateUserErrorTypeEnum.InvalidPassword` | The supplied password is incorrect. |
+| `UserDirectoryAuthenticateUserErrorTypeEnum.UserNotFound` | The email or password is incorrect. Unknown users and wrong passwords are deliberately reported the same way so callers cannot probe which accounts exist. |
+| `UserDirectoryAuthenticateUserErrorTypeEnum.InvalidPassword` | A standard (`isCustom: false`) sign-in was attempted without a password. Thrown before the request reaches the identity provider. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-set-access-token.md

@@ -43,6 +43,7 @@ function* askUserDirectorySetAccessToken(
 ## Notes
 
 - The token is stored on the session only; sessions are not transferred across service boundaries (queues, event buses, service functions), so the identity does not leak beyond the current in-process runtime.
+- A token that cannot be verified (missing, malformed, wrong pool, bad signature, or expired) fails the action with a generic `Unauthorized` error and leaves the session untouched. Catch it with `askCatch` from quidproquo-core when a failed load should not abort the story.
 
 ## Related
 

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

@@ -0,0 +1,47 @@
+---
+title: askApplyEventDocEvent
+description: Declaratively apply an event-doc event, leaving HOW it is applied (optimistic UI append, direct server append, ...) to a registered processor.
+---
+
+# askApplyEventDocEvent
+
+A **purely declarative** way to apply an event-doc event: the story yields an `eventType` and its `data`, and a registered processor decides how that turns into an actual write — for example an optimistic local append followed by a POST in a browser editor, or a direct [askEventDocEventAppend](./ask-event-doc-event-append.md) on the backend. Because it has no side effect of its own, verbs written in terms of it (like a domain's `askXSetY` action creators) run unchanged wherever a processor for it is registered — backend, tests, or transforms.
+
+- **Action type:** `EventDocActionType.ApplyEvent`
+- **quidproquo-features ships no default processor** for this action. Each consumer registers the implementation that fits its runtime via `defineActionProcessors`. Calling it with no processor registered fails the same way any unhandled action type does.
+- The version stamped on the resulting event is not passed by the caller — the registered processor (the "editor") stamps its own configured schema version and provenance when it applies the event.
+
+```typescript
+import { askApplyEventDocEvent } from 'quidproquo-features';
+
+export function* askTenantSetBrand(data: TenantSetBrandData) {
+  yield* askApplyEventDocEvent(TenantEffect.setBrand, data);
+}
+```
+
+## Signature
+
+```typescript
+function* askApplyEventDocEvent(eventType: string, data: unknown): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `eventType` | `string` | The effect/event type discriminant, matched by the reducer that folds the document and by the registered processor. |
+| `data` | `unknown` | The typed domain data for the event, opaque to this action itself. |
+
+## Returns
+
+`AskResponse<void>` — applying an event never returns a value; a processor that fails to apply it surfaces the failure as its own runtime's error state (e.g. UI error state in a browser processor) rather than throwing back through this call.
+
+## Notes
+
+- This is the contract only — it carries no default behavior. A service that yields it must also register a processor for `EventDocActionType.ApplyEvent` (via `defineActionProcessors`) appropriate to where the story runs.
+- Prefer this over calling [askEventDocEventAppend](./ask-event-doc-event-append.md) directly when you want the same verb (e.g. a domain's action creator) to work identically in a browser editor with optimistic updates and on the backend with a direct append.
+
+## Related
+
+- [askEventDocEventAppend](./ask-event-doc-event-append.md) — the store-backed backend append a processor for this action typically delegates to.
+- [askEventDocAppendServerEvent](./ask-event-doc-append-server-event.md) — builds a server-authored event envelope; a natural implementation for a backend `ApplyEvent` processor.

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

@@ -91,6 +91,7 @@ What the client POSTs to append an event. `modelId` and the server-stamped prove
 ## Related
 
 - [askEventDocAppendServerEvent](./ask-event-doc-append-server-event.md) — the server-authored wrapper that builds the input envelope for you.
+- [askApplyEventDocEvent](./ask-apply-event-doc-event.md) — a declarative, processor-dispatched alternative when the same verb must also run in a browser editor.
 - [askEventDocEventWrite](./ask-event-doc-event-write.md) — the low-level conditional write this composes.
 - [askEventDocEventList / EventListAll / EventLast](./ask-event-doc-event-list.md) — reading the log this appends to.
 - [askEventDocProvideStore](./ask-event-doc-provide-store.md) — provides the store context this requires.

package/template/docusaurus/docs/actions/features/event-doc-ai/ask-event-doc-ai-process-send.md

@@ -5,7 +5,7 @@ description: The backend chat turn — persist the user message, stream the mode
 
 # askEventDocAiProcessSend
 
-Runs one conversational turn on the backend. It appends the user's message to the chat history, streams the assistant's reply through [askAiPromptStream](../../core/ai/ask-ai-prompt-stream.md) — dispatching each stream part to the browser live — then folds the completed reply into durable segments, saves it, and bumps the chat to the top of the list. This is the handler behind the `ChatSend` websocket method (`onChatSend`).
+Runs one conversational turn on the backend. It appends the user's message to the chat history, then streams the assistant's reply through [askAiPromptStream](../../core/ai/ask-ai-prompt-stream.md) — dispatching each stream part to the browser live — folding each completed reply into durable segments and saving it. If a round stops with `finishReason: toolCalls` (the underlying step limit cut it off while the model still wanted to act), it automatically resends the updated history so the model continues the same turn, up to a bounded number of rounds. Once a round finishes naturally, it bumps the chat to the top of the list and returns. This is the handler behind the `ChatSend` websocket method (`onChatSend`).
 
 - Built from [askConfigGetGlobal](../../core/config/ask-config-get-global.md), [askAiPromptStream](../../core/ai/ask-ai-prompt-stream.md), [askStreamMap](../../core/stream/ask-stream-map.md), the history/list helpers, and the `askUIEventDocAi*` stream dispatches.
 
@@ -47,13 +47,16 @@ function* askEventDocAiProcessSend(
 1. Reads the AI name, model, and reasoning budget from the feature's globals, and resolves the system prompt — freshest source first: the configured `systemPromptGenerator` inline function (run per-turn with `{ docId }` so it can carry live document state), else the static `systemPrompt`, else a built-in default. The prompt is never persisted.
 2. [Validates the attachments](./ask-event-doc-ai-attachments-validate.md) against the document's storage drive and trusted `docId`.
 3. Loads the chat history, appends the new user message (attachments first, then text), and **saves** immediately — so a refresh mid-reply still shows the question.
-4. Streams the reply with [askAiPromptStream](../../core/ai/ask-ai-prompt-stream.md). File segments in the history become drive-referenced file parts (no URLs), which the action processor resolves to contents at prompt time. Tools do **not** receive `docId` from the model — executors inherit the session context and read the trusted id there.
-5. Maps over the stream with [askStreamMap](../../core/stream/ask-stream-map.md), dispatching each part to the UI as it arrives (the live typing view) and collecting the parts.
-6. Folds the collected parts into durable segments (`text`/`reasoning` deltas merged, tool calls paired with results). A stream that produced no content (e.g. it errored before any text) saves no assistant message.
-7. If there are segments, **saves** the finalized assistant message, dispatches it to the UI as the finalized message, then clears the UI's now-superseded live-stream buffer.
-8. Touches the chat (bumps `updatedAt`) and returns `{ complete: true }`.
-
-Steps 5–7 use the `askUIEventDocAiAppendStreamChunk`, `askUIEventDocAiAppendChatMessage`, and `askUIEventDocAiClearStream` UI actions — the client renders the reply from those dispatches while this request is still in flight, then reconciles to the finalized message.
+4. Runs one or more rounds (bounded, currently up to 20):
+   1. Streams the reply with [askAiPromptStream](../../core/ai/ask-ai-prompt-stream.md). File segments in the history become drive-referenced file parts (no URLs), which the action processor resolves to contents at prompt time. Tools do **not** receive `docId` from the model — executors inherit the session context and read the trusted id there. From the second round on, a transport-only nudge message (never saved to history) is appended so the conversation doesn't end on an assistant turn.
+   2. Maps over the stream with [askStreamMap](../../core/stream/ask-stream-map.md), dispatching each part to the UI as it arrives (the live typing view) and collecting the parts.
+   3. Folds the collected parts into durable segments (`text`/`reasoning` deltas merged, tool calls paired with results). A stream that produced no content (e.g. it errored before any text) saves no assistant message.
+   4. If there are segments, **saves** the finalized assistant message and dispatches it to the UI as the finalized message.
+   5. Clears the UI's now-superseded live-stream buffer.
+   6. If the round's [`finishReason`](../../core/ai/ask-ai-prompt-stream.md#aistreamfinishreasonenum) was `toolCalls` (halted early) and it produced segments, loops back to stream another round from the updated history; otherwise stops.
+5. Touches the chat (bumps `updatedAt`) and returns `{ complete: true }`.
+
+Steps 4.ii–4.v use the `askUIEventDocAiAppendStreamChunk`, `askUIEventDocAiAppendChatMessage`, and `askUIEventDocAiClearStream` UI actions — the client renders the reply from those dispatches while this request is still in flight, then reconciles to the finalized message. Because rounds can repeat, the UI may see more than one finalized assistant message appended for what is presented as a single turn.
 
 ## The chat model
 

package/template/docusaurus/docs/actions/features/web-socket-queue/_category_.json

@@ -0,0 +1 @@
+{ "label": "WebSocket queue", "link": { "type": "generated-index", "description": "Send RPC-style requests to another qpq service over the WebSocket queue." } }

package/template/docusaurus/docs/actions/{webserver/service → features/web-socket-queue}/ask-service-request.md

@@ -11,7 +11,7 @@ Sends an **RPC-style request to another qpq service**, identified by a service n
 - The request is dispatched as a `qpq/serviceRequest/<serviceName>/<method>` message and its correlated response is awaited. In a browser (quidproquo-web-react) client this travels over the app's WebSocket queue connection; the response is returned when the correlated reply arrives.
 
 ```typescript
-import { askServiceRequest } from 'quidproquo-webserver';
+import { askServiceRequest } from 'quidproquo-features';
 
 interface GetQuoteRequest { symbol: string; }
 interface GetQuoteResponse { symbol: string; price: number; }
@@ -30,7 +30,7 @@ export function* askGetQuote(symbol: string) {
 Prefer `createServiceRequester` for a typed, reusable wrapper:
 
 ```typescript
-import { createServiceRequester } from 'quidproquo-webserver';
+import { createServiceRequester } from 'quidproquo-features';
 
 // Bind the service + method once, with request/response types
 const askGetQuote = createServiceRequester<GetQuoteRequest, GetQuoteResponse>('market', 'getQuote');
@@ -65,5 +65,6 @@ function* askServiceRequest<TPayload, TResponse>(
 
 ## Related
 
-- [askServiceFunctionExecute](../service-function/ask-service-function-execute.md) — direct Lambda-invoke of a named service function.
+- [askServiceFunctionExecute](../../webserver/service-function/ask-service-function-execute.md) — direct Lambda-invoke of a named service function.
+- [defineWebSocketQueue](../../../config/features/web-socket-queue.md) — the WebSocket queue this request travels over in a browser client.
 - [askCatch](../../core/system/ask-catch.md) — catch errors returned by the service handler.

package/template/docusaurus/docs/actions/webserver/generic-data-resource/ask-put-generic-data-resource.md

@@ -9,6 +9,10 @@ Writes a single item into a **generic data resource** — a named table addresse
 
 - **Action type:** `GenericDataResourceActionTypeEnum.Put`
 
+:::warning Not implemented by any runtime
+No action processor currently implements this action on any platform (AWS, dev server, or browser). Yielding it from a story will fail at runtime with an unknown-action error. The action type exists so tooling (like the admin log viewer) can label historical log entries. Use a [key-value store](../../../config/core/key-value-store.md) for application data.
+:::
+
 ```typescript
 import { askPutGenericDataResource } from 'quidproquo-webserver';
 

package/template/docusaurus/docs/actions/webserver/generic-data-resource/ask-scan-generic-data-resource.md

@@ -9,6 +9,10 @@ Reads items out of a **generic data resource** — a named table addressed direc
 
 - **Action type:** `GenericDataResourceActionTypeEnum.Scan`
 
+:::warning Not implemented by any runtime
+No action processor currently implements this action on any platform (AWS, dev server, or browser). Yielding it from a story will fail at runtime with an unknown-action error. The action type exists so tooling (like the admin log viewer) can label historical log entries. Use a [key-value store](../../../config/core/key-value-store.md) for application data.
+:::
+
 ```typescript
 import { askScanGenericDataResource } from 'quidproquo-webserver';
 

package/template/docusaurus/docs/actions/webserver/websocket/ask-websocket-send-message.md

@@ -35,7 +35,7 @@ function* askWebsocketSendMessage<T>(
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `websocketApiName` | `string` | The `apiName` of the target [WebSocket API](../../../config/webserver/websocket.md) (the `apiName` option of [defineWebsocket](../../../config/webserver/websocket.md), or the `apiName` argument to [defineWebSocketQueue](../../../config/webserver/web-socket-queue.md)). Identifies which deployed API the connection belongs to. |
+| `websocketApiName` | `string` | The `apiName` of the target [WebSocket API](../../../config/webserver/websocket.md) (the `apiName` option of [defineWebsocket](../../../config/webserver/websocket.md), or the `apiName` argument to [defineWebSocketQueue](../../../config/features/web-socket-queue.md)). Identifies which deployed API the connection belongs to. |
 | `connectionId` | `string` | Identifier of the client connection to send to. You receive this on the `WebsocketEvent` in your connect/message handlers; persist it (e.g. keyed by user) if you need to send outside the request that created it. |
 | `payload` | `T` | The message to send. Serialized to JSON before transmission, so any JSON-serializable value works. |
 
@@ -67,5 +67,5 @@ export function* askTrySend(connectionId: string, payload: unknown) {
 ## Related
 
 - [defineWebsocket](../../../config/webserver/websocket.md) — declares the WebSocket API and its connect/disconnect/message handlers.
-- [defineWebSocketQueue](../../../config/webserver/web-socket-queue.md) — managed messaging layer that tracks connections for you.
+- [defineWebSocketQueue](../../../config/features/web-socket-queue.md) — managed messaging layer that tracks connections for you.
 - [askCatch](../../../actions/core/system/ask-catch.md) — catch the throttled/disconnected errors above.

package/template/docusaurus/docs/architecture-overview.md

@@ -332,6 +332,8 @@ interface StorySession {
   accessToken?: string;        // Auth token (not transferred)
   decodedAccessToken?: DecodedAccessToken; // User info
   context: QpqContext<any>;    // Contextual data
+  localContext?: QpqContext<any>; // Service-local context (never crosses a service boundary)
+  functionGlobals?: Record<string, unknown>; // Globals from the executing function's runtime definition
 }
 ```