create-qpq-app 0.1.5

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

@@ -0,0 +1,140 @@
+---
+title: askStreamRead
+description: Pull the next chunk from an open stream handle.
+---
+
+# askStreamRead
+
+Reads the next chunk from an open **stream** and returns it. A stream is never opened by this action — it is opened by some other action that hands back a [`StreamHandle`](#streamhandle), such as [askFileStreamOpen](../file/ask-file-stream-open.md) (streaming a large file) or [askAiPromptStream](../ai/ask-ai-prompt-stream.md) (streaming a model response). `askStreamRead` then pulls that stream forward one chunk at a time until it is exhausted.
+
+- **Action type:** `StreamActionType.Read`
+
+Each read returns a [`StreamChunk`](#streamchunk) — an envelope that tells you whether the stream is finished (`done`), whether this poll had nothing ready yet (`skipped`), and, when there is one, the decoded chunk (`data`). The `data` is decoded according to the handle's [encoding](#streamencoding): `'text'` yields a `string`, `'binary'` yields a `Uint8Array`, and `'json'` yields the parsed object.
+
+```typescript
+import { askFileStreamOpen, askStreamRead, askStreamClose } from 'quidproquo-core';
+
+export function* askReadWholeFile(filepath: string) {
+  const handle = yield* askFileStreamOpen('logs', filepath, 'text');
+
+  let contents = '';
+  while (true) {
+    const chunk = yield* askStreamRead(handle);
+    if (chunk.done) {
+      break;
+    }
+    if (chunk.data) {
+      contents += chunk.data;
+    }
+  }
+
+  yield* askStreamClose(handle);
+  return contents;
+}
+```
+
+For most cases you don't need to write this loop yourself — reach for [askStreamProcess](./ask-stream-process.md) or [askStreamMap](./ask-stream-map.md), which wrap read + close.
+
+## Signature
+
+```typescript
+function* askStreamRead<E extends StreamEncoding, T = unknown>(
+  handle: StreamHandle<E, T>,
+  noWait?: boolean,
+): AskResponse<StreamChunk<StreamDataType<E, T>>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `handle` | `StreamHandle<E, T>` | The handle returned by the action that opened the stream. Its `encoding` (`E`) determines how each chunk's `data` is decoded. |
+| `noWait` | `boolean` | When `true`, poll without blocking: if no chunk is ready yet the call returns immediately with `{ done: false, skipped: true }` instead of waiting for the next chunk. Defaults to `false` (wait for the next chunk). |
+
+## Returns
+
+`StreamChunk<StreamDataType<E, T>>` — one envelope describing this read. Inspect the fields in order:
+
+- `done: true` — the stream is exhausted; stop reading. There is no `data`.
+- `skipped: true` — a `noWait` poll found nothing ready this instant; the stream is not finished, so try again. There is no `data`.
+- otherwise — `data` holds the next decoded chunk.
+
+## Stream value types
+
+These types (all importable from quidproquo-core) describe a stream and the chunks it produces. They are the shared vocabulary of the whole Stream domain.
+
+### `StreamHandle`
+
+An opaque reference to an open stream. You never construct one — you receive it from an opening action and pass it to `askStreamRead` / `askStreamClose` / `askStreamProcess` / `askStreamMap`.
+
+```typescript
+interface StreamHandle<E extends StreamEncoding = StreamEncoding, T = unknown> {
+  id: string;
+  encoding: E;
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Identifies the stream in the runtime's stream registry. |
+| `encoding` | `E` | How each chunk is decoded when read — one of the [`StreamEncoding`](#streamencoding) values. |
+
+The `E` and `T` type parameters flow through to reads. A `StreamHandle<'text'>` reads `string` chunks, a `StreamHandle<'binary'>` reads `Uint8Array` chunks, and a `StreamHandle<'json', AiStreamPart>` reads parsed `AiStreamPart` objects.
+
+### `StreamChunk`
+
+The envelope returned by every read.
+
+```typescript
+interface StreamChunk<T = unknown> {
+  done: boolean;
+  skipped?: boolean;
+  data?: T;
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `done` | `boolean` | `true` once the stream is exhausted. When `true` there is no `data`. |
+| `skipped` | `boolean` | Only set on `noWait` polls: `true` means no chunk was ready this instant (the stream is not done — poll again). |
+| `data` | `T` | The decoded chunk, present only when `done` and `skipped` are both falsy. |
+
+### `StreamEncoding`
+
+How each raw chunk is decoded as it is read.
+
+```typescript
+type StreamEncoding = 'text' | 'binary' | 'json';
+```
+
+| Value | Chunk `data` type |
+| --- | --- |
+| `'text'` | `string` |
+| `'binary'` | `Uint8Array` |
+| `'json'` | the JSON-parsed value (`T`) |
+
+### `StreamDataType`
+
+A helper type that maps a `StreamEncoding` (and, for `'json'`, the item type `T`) to the concrete type of a chunk's `data`. You rarely name it directly — it is what makes `askStreamRead` return `string`, `Uint8Array`, or `T` depending on the handle.
+
+```typescript
+type StreamDataType<E extends StreamEncoding, T = unknown> =
+  E extends 'text' ? string :
+  E extends 'binary' ? Uint8Array :
+  E extends 'json' ? T :
+  never;
+```
+
+## Notes
+
+- Reads deliver chunks in order, one per call. `askStreamRead` handles the decoding for you — `'binary'` chunks arrive on the wire as base64 and are turned back into a `Uint8Array`, and `'json'` chunks are `JSON.parse`d — so `data` is always the decoded value matching the handle's encoding.
+- `skipped` only ever appears when you pass `noWait: true`. In the default blocking mode a read either returns the next chunk or reports `done`.
+- Always release the stream with [askStreamClose](./ask-stream-close.md) once you finish, including on early exit. The stream stories do this for you.
+
+## Related
+
+- [askStreamClose](./ask-stream-close.md) — release the handle when you are done.
+- [askStreamProcess](./ask-stream-process.md) — run a callback per chunk, then close (wraps read + close).
+- [askStreamMap](./ask-stream-map.md) — collect / transform chunks into an array, then close.
+- [askFileStreamOpen](../file/ask-file-stream-open.md) — opens a file on a storage drive as a stream.
+- [askAiPromptStream](../ai/ask-ai-prompt-stream.md) — opens a model response as a stream of typed events.

package/template/docusaurus/docs/actions/core/system/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "System",
+  "link": {
+    "type": "generated-index",
+    "description": "System control-flow primitives: catch errors, retry, run stories in parallel, conditionally execute, override action processing."
+  }
+}

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

@@ -0,0 +1,55 @@
+---
+title: askBatch
+description: Process an array of actions together in a single batch.
+---
+
+# askBatch
+
+Yields an array of actions as one **batch** so the runtime processes them together rather than one at a time. The runtime runs the batched actions concurrently and resolves the whole batch before your story resumes, so this is how independent actions avoid paying a round-trip each.
+
+- **Action type:** `SystemActionType.Batch`
+
+```typescript
+import { askBatch } from 'quidproquo-core';
+
+export function* askLoadDashboard(userId: string) {
+  // Both reads are dispatched together instead of sequentially.
+  const [profile, settings] = yield* askBatch([
+    askKvsGet('profiles', userId),
+    askKvsGet('settings', userId),
+  ]);
+
+  return { profile, settings };
+}
+```
+
+## Signature
+
+```typescript
+function* askBatch<TReturn extends Array<any> = any[]>(
+  actions: Action<any>[],
+): AskResponse<TReturn>;
+```
+
+`askBatch` takes raw actions, not stories. Each element is a single yielded action (for example the value produced by an action requester). For running whole sub-stories in parallel, use [askRunParallel](./ask-run-parallel.md), which is built on top of this.
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `actions` | `Action<any>[]` | The actions to process together. Order is preserved: result index `i` corresponds to `actions[i]`. |
+
+## Returns
+
+`TReturn` — an array of results, one per input action, in the same order. Type it via the generic (e.g. `askBatch<[Profile, Settings]>([...])`) to get a typed tuple back.
+
+## Notes
+
+- A batch of exactly one action is short-circuited: the single action is yielded directly instead of being wrapped, so there is no batching overhead for the trivial case.
+- On the JS/Node processor the batched actions run via `Promise.all` — they execute concurrently, so only use `askBatch` for actions that are independent of each other.
+- If a batched action fails and is not individually protected by [askCatch](./ask-catch.md), the failure surfaces as the batch's error and propagates to your story. When wrapped in `askCatch`, failures come back per-action as `EitherActionResult` values instead.
+
+## Related
+
+- [askRunParallel](./ask-run-parallel.md) — run several **stories** (not raw actions) in parallel; it batches their actions for you.
+- [askCatch](./ask-catch.md) — capture errors from batched actions as values.

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

@@ -0,0 +1,85 @@
+---
+title: askCatch
+description: Run a story and capture any error as a value instead of throwing.
+---
+
+# askCatch
+
+Runs a wrapped story and captures the outcome as an `EitherActionResult` object — `{ success: true, result }` when it completes, or `{ success: false, error }` when any action inside it fails. Instead of an error propagating and crashing the story, `askCatch` turns it into a value you branch on.
+
+- **Built from:** a generator that re-yields each of the wrapped story's actions with `returnErrors: true`, so action failures come back as failure objects rather than throwing. It also catches thrown JavaScript errors and reports them as `GenericError`.
+
+```typescript
+import { askCatch } from 'quidproquo-core';
+
+export function* askTryReadConfig() {
+  const outcome = yield* askCatch(askFileReadTextContents('config', 'app.json'));
+
+  if (outcome.success) {
+    return outcome.result; // the file contents
+  }
+
+  // outcome.error is a QPQError: { errorType, errorText, errorStack? }
+  return null;
+}
+```
+
+Always destructure the **object** — `askCatch` never returns a tuple.
+
+## Signature
+
+```typescript
+function* askCatch<T extends AskResponse<any>>(
+  storyIterator: T,
+  finallyIterator?: AskResponse<any>,
+): AskResponse<EitherActionResult<AskResponseReturnType<T>>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `storyIterator` | `AskResponse<...>` | The story to run and protect, e.g. `askFileReadTextContents('config', 'app.json')` or any generator that yields actions. Its return type flows through to `result` on success. |
+| `finallyIterator` | `AskResponse<...>` | Optional cleanup story run in a `finally` — it executes whether the wrapped story succeeds, fails, or throws. Its own return value is discarded; use it for teardown (releasing a lock, closing a stream, etc.). |
+
+## Returns
+
+`EitherActionResult<T>`, where `T` is the wrapped story's return type. It is a discriminated union on `success`:
+
+```typescript
+// success
+{ success: true; result: T }
+
+// failure
+{ success: false; error: QPQError }
+```
+
+`QPQError` is `{ errorType: ErrorTypeEnum | string; errorText: string; errorStack?: string }`. Narrow on `outcome.success` before reading `outcome.result` or `outcome.error` — TypeScript only exposes each field on its matching branch.
+
+```typescript
+const outcome = yield* askCatch(askGetUser(userId));
+
+if (outcome.success) {
+  const user = outcome.result;
+  // ...
+} else {
+  if (outcome.error.errorType === ErrorTypeEnum.NotFound) {
+    // handle the specific failure
+  }
+}
+```
+
+## Notes
+
+- Errors surfaced here are exactly what [askThrowError](../error/ask-throw-error.md) throws — the `error` object is the `QPQError` you threw, with its `errorType` preserved.
+- `askCatch` nests: an inner `askCatch` handles its own errors as values; anything it rethrows (or leaves uncaught) is seen by an outer `askCatch`.
+- A thrown JavaScript `Error` (not an `askThrowError`) is also caught, but reported as `{ errorType: ErrorTypeEnum.GenericError, errorText: e.message }`.
+
+## Related
+
+- [askThrowError](../error/ask-throw-error.md) — throw the errors this captures.
+- [askRetry](./ask-retry.md) — built on `askCatch`; retries a story and returns the same `EitherActionResult`.
+- [askExecuteIf](./ask-execute-if.md) — conditionally run a story.
+- [askWebsocketSendMessage](../../webserver/websocket/ask-websocket-send-message.md) — wrap it in `askCatch` to handle throttled/disconnected clients.
+- [askValidateModelOrThrowError](../../features/validation/ask-validate-model-or-throw-error.md) — wrap it in `askCatch` to handle invalid input inline.
+- [askEventDocGetByIdOrThrow](../../features/event-doc/ask-event-doc-get-by-id.md) — wrap it in `askCatch` to handle a missing event document without a throw.

package/template/docusaurus/docs/actions/core/system/ask-execute-if.md

@@ -0,0 +1,51 @@
+---
+title: askExecuteIf
+description: Run a story only when a condition is true, otherwise return undefined.
+---
+
+# askExecuteIf
+
+Conditionally runs a story. When the condition is `true`, the wrapped story runs and its return value is passed straight back; when it is `false`, the story is skipped entirely and `askExecuteIf` returns `undefined`. It lets you keep a conditional branch inside a single expression instead of an `if` around a `yield*`.
+
+- **Built from:** a thin generator wrapper — it either `yield*`s the wrapped story or returns `undefined`.
+
+```typescript
+import { askExecuteIf } from 'quidproquo-core';
+
+export function* askMaybeNotify(user: User, shouldNotify: boolean) {
+  // askSendWelcomeEmail only runs when shouldNotify is true.
+  const result = yield* askExecuteIf(askSendWelcomeEmail(user), shouldNotify);
+
+  return result; // the email result, or undefined if skipped
+}
+```
+
+## Signature
+
+```typescript
+function* askExecuteIf<T extends AskResponse<any>>(
+  storyIterator: T | boolean,
+  condition?: boolean,
+): AskResponse<AskResponseReturnType<T> | undefined>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `storyIterator` | `AskResponse<...> \| boolean` | – | The story to run when the condition holds, e.g. `askSendWelcomeEmail(user)`. |
+| `condition` | `boolean` | `true` | Whether to run the story. When `false` (or when `storyIterator` isn't a runnable story object), the story is skipped and `undefined` is returned. |
+
+## Returns
+
+The wrapped story's return value when it runs, otherwise `undefined`. The return type is `AskResponseReturnType<T> | undefined`, so callers must account for the skipped case.
+
+## Notes
+
+- `condition` defaults to `true`, so `askExecuteIf(story)` with no second argument always runs the story.
+- The story is only stepped when it actually runs — a skipped story yields none of its actions, so nothing inside it executes.
+
+## Related
+
+- [askCatch](./ask-catch.md) — run a story and capture its errors as a value.
+- [askRunParallel](./ask-run-parallel.md) — run several stories concurrently.

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

@@ -0,0 +1,56 @@
+---
+title: askExecuteStory
+description: Load and run another story by its function runtime reference.
+---
+
+# askExecuteStory
+
+Runs a **separate story**, referenced by its function runtime (the `'/path/to/file::exportedFunctionName'` handle), and returns whatever that story returns. The target is dynamically loaded and executed in-process, receiving the parameters you pass.
+
+- **Action type:** `SystemActionType.ExecuteStory`
+
+```typescript
+import { askExecuteStory } from 'quidproquo-core';
+
+export function* askProcessUpload(fileId: string) {
+  // Run the resize story, whose entry point lives in another module.
+  const thumbnail = yield* askExecuteStory<[string], string>(
+    '/entry/image/resize::resizeImage',
+    [fileId],
+  );
+
+  return thumbnail;
+}
+```
+
+## Signature
+
+```typescript
+function* askExecuteStory<StoryInput extends Array<any>, StoryOutput>(
+  runtime: QpqFunctionRuntime,
+  params: StoryInput,
+  storySession?: StorySession,
+): AskResponse<StoryOutput>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `runtime` | `QpqFunctionRuntime` | Reference to the story entry point to run — either a relative-path string of the form `'/path/to/file::exportedFunctionName'`, or the advanced `{ basePath, relativePath, functionName }` object form. |
+| `params` | `StoryInput` | Positional arguments passed to the target story, as a tuple/array matching its parameters. |
+| `storySession` | `StorySession` | Optional session to run the story under. When omitted, the story runs with a session derived from the current one. |
+
+## Returns
+
+`StoryOutput` — the value the executed story returns. Provide the generics (`askExecuteStory<[Args], Result>`) to type both the parameters and the return.
+
+## Notes
+
+- The target story is resolved through the runtime's dynamic module loader. If it cannot be loaded, the action fails with `ErrorTypeEnum.NotFound`; any error thrown while the story runs surfaces as `ErrorTypeEnum.GenericError`. Wrap the call in [askCatch](./ask-catch.md) if you want to handle those as values.
+- The executed story runs its own actions through the same processors, so it behaves like any other story — it just starts from a runtime reference rather than being imported and called directly.
+
+## Related
+
+- [askGetRuntimeCorrelation](./ask-get-runtime-correlation.md) — the correlation id that links a story and the sub-stories it triggers.
+- [askRunParallel](./ask-run-parallel.md) — run multiple stories concurrently when you already have their generators in hand.

package/template/docusaurus/docs/actions/core/system/ask-get-runtime-correlation.md

@@ -0,0 +1,46 @@
+---
+title: askGetRuntimeCorrelation
+description: Get the correlation id of the currently executing story.
+---
+
+# askGetRuntimeCorrelation
+
+Returns the **correlation id** (a guid) of the story that is currently running. Every action a story processes — and every sub-story it triggers — shares this correlation, so it is the handle that links a whole execution together in the logs and execution history.
+
+- **Action type:** `SystemActionType.GetRuntimeCorrelation`
+
+```typescript
+import { askGetRuntimeCorrelation } from 'quidproquo-core';
+
+export function* askRecordJob() {
+  const correlation = yield* askGetRuntimeCorrelation();
+
+  // Store it so we can later link back to this execution's logs.
+  yield* askKvsUpsert('jobs', { id: correlation, status: 'started' });
+
+  return correlation;
+}
+```
+
+## Signature
+
+```typescript
+function* askGetRuntimeCorrelation(): AskResponse<string>;
+```
+
+## Parameters
+
+None.
+
+## Returns
+
+`string` — the correlation guid of the current story (`session.correlation`). It is stable for the whole execution, so reading it at different points in the same story yields the same value.
+
+## Notes
+
+- Persist this value when you want to correlate an out-of-band record (a KVS row, a queued message, an emitted event) back to the execution that produced it — the admin log viewer keys on the same correlation.
+- Sub-stories run via [askExecuteStory](./ask-execute-story.md) carry a link to their caller's correlation, which is how nested executions stay traceable to their parent.
+
+## Related
+
+- [askExecuteStory](./ask-execute-story.md) — runs another story; correlations chain from caller to callee.

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

@@ -0,0 +1,76 @@
+---
+title: askOverrideActions
+description: Intercept and override how selected actions are processed for a wrapped story.
+---
+
+# askOverrideActions
+
+Runs a wrapped story while **intercepting** the actions it yields. For any action type you supply a handler for, `askOverrideActions` runs your handler instead of letting the runtime process the action; every other action passes through to the runtime unchanged. The wrapped story's return value is passed straight back out.
+
+This is an advanced, low-level primitive. It is the mechanism [askContextProvideValue](../context/ask-context-provide-value.md) is built on — reach for that (or the other context helpers) for everyday needs, and use `askOverrideActions` directly only when you need to intercept arbitrary action types.
+
+- **Built from:** a generator that sits between the story and the runtime, matching each yielded action against an override map and running the matching handler; it also cracks open [askBatch](./ask-batch.md) batches to apply overrides to the actions nested inside.
+
+```typescript
+import { askOverrideActions, MathActionType } from 'quidproquo-core';
+
+export function* askWithFixedRandom(story: AskResponse<number>) {
+  // Force every random-number action inside `story` to resolve to 0.42.
+  return yield* askOverrideActions(story, {
+    [MathActionType.RandomNumber]: function* (action) {
+      return 0.42;
+    },
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askOverrideActions<T extends AskResponse<any>>(
+  storyIterator: T,
+  overrides: ActionOverrideMap,
+): AskResponse<AskResponseReturnType<T>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `storyIterator` | `AskResponse<...>` | The story whose actions you want to intercept. Its return value flows through unchanged. |
+| `overrides` | `ActionOverrideMap` | A map from action type string to a handler. See below. |
+
+### `ActionOverrideMap`
+
+```typescript
+type ActionOverrideHandler<TAction extends Action<any> = Action<any>, TResult = any> =
+  (action: TAction) => AskResponse<TResult>;
+
+type ActionOverrideMap = {
+  [actionType: string]: ActionOverrideHandler<any, any>;
+};
+```
+
+- **Keys** are action type strings — e.g. a `MathActionType.RandomNumber` value — or `'*'` for a wildcard catch-all.
+- **Values** are handler stories (generators). A handler receives the intercepted `action` and returns the value the story should get back in place of that action's normal result. Because a handler is itself a story, it may `yield*` other actions.
+- A specific type match takes priority over `'*'`; the wildcard is checked only when no specific handler matches. The `'*'` wildcard is **not** applied to the internal `Batch` action itself — batches are unwrapped so overrides apply to the actions inside them, not to the batch wrapper.
+
+There are two ways to write a handler:
+
+- **Relay** the action with `return yield action` — the value comes back from the parent already in the shape the story expects (raw, or an `EitherActionResult` when the action is running under [askCatch](./ask-catch.md)). Do not reshape it.
+- **Compute** your own value and return it. If the intercepted action was running under `askCatch` (it carries `returnErrors: true`), a computed value must be shaped into `{ success: true, result }`; the exported helper `getSuccessfulEitherActionResultIfRequired(value, action.returnErrors)` does this for you.
+
+## Returns
+
+`AskResponseReturnType<T>` — the wrapped story's own return value, unchanged. Overriding actions inside a story does not change what the story ultimately returns.
+
+## Notes
+
+- **Batches are handled transparently.** When the story runs actions in parallel (via [askRunParallel](./ask-run-parallel.md) / [askBatch](./ask-batch.md)), the actions arrive bundled in a single batch. `askOverrideActions` opens the batch, applies overrides to each nested action (recursing into batches-within-batches), sends the remaining non-overridden actions to the runtime as a smaller batch, and reassembles the results in their original order.
+- **Error protection is preserved.** Overridden and non-overridden actions still honour `returnErrors`: under `askCatch`, a failure comes back as `{ success: false, error }`; without it, the failure throws up to the story as normal.
+
+## Related
+
+- [askContextProvideValue](../context/ask-context-provide-value.md) — the higher-level context provider built on this primitive; prefer it for propagating values.
+- [askContextRead](../context/ask-context-read.md) — reads context values that a provider injects.
+- [askBatch](./ask-batch.md) / [askRunParallel](./ask-run-parallel.md) — produce the batches this function transparently unwraps.

package/template/docusaurus/docs/actions/core/system/ask-parallel-deprecated.md

@@ -0,0 +1,55 @@
+---
+title: askParallelDEPRECATED
+description: Deprecated — run several stories in parallel. Use askRunParallel instead.
+---
+
+# askParallelDEPRECATED
+
+:::warning Deprecated
+`askParallelDEPRECATED` is the original implementation for running stories in parallel. It has been replaced by [askRunParallel](./ask-run-parallel.md), which is more efficient and fully type-supported. Use `askRunParallel` in new code.
+:::
+
+Runs any number of stories in parallel by driving each generator forward and batching their outstanding actions together on each step. It exists only for backwards compatibility.
+
+- **Built from:** [askBatch](./ask-batch.md) — on every step it collects the not-yet-done stories' current actions and processes them as a single batch, then feeds each result back into the corresponding story.
+
+```typescript
+import { askParallelDEPRECATED } from 'quidproquo-core';
+
+export function* askLoadTwo(aId: string, bId: string) {
+  // Prefer askRunParallel for new code — this is here for reference only.
+  const results = yield* askParallelDEPRECATED([
+    [askLoadA, aId],
+    [askLoadB, bId],
+  ]);
+
+  return results;
+}
+```
+
+## Signature
+
+```typescript
+function* askParallelDEPRECATED(
+  stories: Array<any>,
+): AskResponse<any[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `stories` | `Array<any>` | An array of `[storyFn, ...args]` tuples. Each entry is a story generator function followed by the arguments to call it with; the function is invoked internally and stepped in parallel with the others. |
+
+## Returns
+
+`any[]` — an array of the stories' return values, in the same order as the input. The type is untyped (`any`), which is one of the reasons it was superseded.
+
+## Notes
+
+- The calling convention differs from its replacement: this function takes `[fn, ...args]` tuples and calls the functions for you, whereas [askRunParallel](./ask-run-parallel.md) takes already-invoked generators (`[askLoadA(aId), askLoadB(bId)]`) and returns a precisely typed tuple.
+
+## Related
+
+- [askRunParallel](./ask-run-parallel.md) — the supported replacement.
+- [askBatch](./ask-batch.md) — the batching primitive both are built on.

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

@@ -0,0 +1,72 @@
+---
+title: askRetry
+description: Retry a story on failure with a wait between attempts and optional backoff.
+---
+
+# askRetry
+
+Runs a story and retries it if it fails, waiting between attempts. It returns the same `EitherActionResult` shape as [askCatch](./ask-catch.md): the first successful outcome, or the last failure once retries are exhausted. Optionally restrict retries to specific error types and add linear backoff or jitter.
+
+- **Built from:** [askCatch](./ask-catch.md) (to run each attempt and capture its outcome as a value), plus `askDelay` for the waits and `askNewGuid` for jitter entropy.
+
+```typescript
+import { askRetry, ErrorTypeEnum } from 'quidproquo-core';
+
+export function* askChargeCard(paymentId: string) {
+  const outcome = yield* askRetry(
+    () => askCallPaymentProvider(paymentId),
+    3,      // up to 3 retries after the first attempt
+    1000,   // wait 1000ms between attempts
+    [ErrorTypeEnum.TimeOut, ErrorTypeEnum.OutOfResources], // only retry these
+  );
+
+  if (outcome.success) {
+    return outcome.result;
+  }
+
+  return yield* askThrowError(outcome.error.errorType, outcome.error.errorText);
+}
+```
+
+## Signature
+
+```typescript
+function* askRetry<R>(
+  askRunLogic: () => AskResponse<R>,
+  maxRetries: number,
+  timeToWaitMs: number,
+  errorTypeRetryList?: string[],
+  options?: AskRetryOptions,
+): AskResponse<EitherActionResult<R>>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `askRunLogic` | `() => AskResponse<R>` | – | A **factory** that returns the story to attempt. It is called fresh for each attempt, so each retry starts a new run of the story. |
+| `maxRetries` | `number` | – | The number of retries **after** the first attempt. The story runs at most `maxRetries + 1` times. |
+| `timeToWaitMs` | `number` | – | Milliseconds to wait between attempts (the base wait; see `options.linearBackoff`). |
+| `errorTypeRetryList` | `string[]` | – | If provided, only failures whose `errorType` is in this list are retried; any other error returns immediately. When omitted, every failure is retried. |
+| `options` | `AskRetryOptions` | – | Optional backoff/jitter tuning — see below. |
+
+### `AskRetryOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `linearBackoff` | `boolean` | `false` | When `true`, the wait is multiplied by the (1-based) attempt number — `timeToWaitMs * attempt` — instead of a fixed interval. |
+| `maxJitterMs` | `number` | – | Adds `0..maxJitterMs` of guid-derived jitter to each wait, so many callers losing the same race spread their retries out instead of retrying in lockstep. |
+
+## Returns
+
+`EitherActionResult<R>` — `{ success: true, result }` from the first attempt that succeeds, or `{ success: false, error }` holding the last failure once retries run out (or when a non-retryable error type is hit). This is the same object shape as [askCatch](./ask-catch.md), so branch on `outcome.success`.
+
+## Notes
+
+- Retries stop early when the error's `errorType` is not in `errorTypeRetryList` — the current failure is returned as-is.
+- Jitter uses `askNewGuid` rather than `Math.random`, because stories must stay replay-safe (deterministic) and cannot call `Math.random` directly.
+
+## Related
+
+- [askCatch](./ask-catch.md) — the per-attempt error capture this is built on; same `EitherActionResult` return.
+- [askThrowError](../error/ask-throw-error.md) — throw the failures that `askRetry` retries, and rethrow the final error.