create-qpq-app 0.1.5

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

@@ -0,0 +1,97 @@
+---
+title: askEventDocGetByCode
+description: Look up an event document by its stable business code — plus id-only and create-on-miss variants.
+---
+
+# askEventDocGetByCode
+
+Finds the single non-deleted document in the current collection whose `code` matches — optionally scoped to an owner (matched on `createdBy`). The **code** is a document's stable business key (see [the event-document model](./ask-event-doc-get-by-id.md#the-event-document-model)); it is expected unique within the collection (and any owner scope), so this returns one record or `null`.
+
+- **Built from:** [askEventDocList](./ask-event-doc-list.md) filtered in memory by `code` (there is no secondary index on `code`, and the dev key-value store can't query one anyway). Requires the store context — call it inside `askEventDocProvideStore({ storeName, type }, ...)`.
+
+```typescript
+import { askEventDocGetByCode } from 'quidproquo-features';
+
+export function* findByCode(code: string) {
+  const summary = yield* askEventDocGetByCode(code);
+  return summary; // EventDocSummary | null
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocGetByCode<T extends EventDocSummary = EventDocSummary>(
+  code: string,
+  ownerUserId?: string,
+): AskResponse<Nullable<T>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `code` | `string` | The business code to match. |
+| `ownerUserId` | `string` (optional) | When given, only documents whose `createdBy` equals this id are considered — scopes the code's uniqueness to one owner. Omit to search the whole collection. |
+
+The generic `T` narrows to a collection-specific extension of [`EventDocSummary`](./ask-event-doc-get-by-id.md#the-summary-record); defaults to `EventDocSummary`.
+
+## Returns
+
+`EventDocSummary | null` — the single matching non-deleted record, or `null` when none match.
+
+## Notes
+
+- Because `code` is expected unique in scope, **more than one match is treated as a data-integrity error** and throws `ErrorTypeEnum.Conflict` (from quidproquo-core) — it does not pick one arbitrarily.
+- Soft-deleted documents are excluded (this filters via [askEventDocList](./ask-event-doc-list.md)'s default).
+
+---
+
+## askEventDocGetByCodeOrCreate
+
+Returns the document with `code` (optionally owner-scoped), **creating it on first use** if none exists. Finds via `askEventDocGetByCode` (so >1 existing match is still a `Conflict`); on a miss it creates the document with the given `name`/`code`/`actor` via [askEventDocCreate](./ask-event-doc-create.md).
+
+```typescript
+function* askEventDocGetByCodeOrCreate(
+  code: string,
+  name: string,
+  actor: EventDocEventActor,
+  ownerUserId?: string,
+): AskResponse<EventDocSummary>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `code` | `string` | The business code to find or create. |
+| `name` | `string` | Name to give the document if it must be created. |
+| `actor` | [`EventDocEventActor`](./ask-event-doc-create.md#eventdoceventactor) | Who to attribute the creation to (used only on a miss). |
+| `ownerUserId` | `string` (optional) | Owner scope for both the lookup and the `createdBy` match. |
+
+**Returns** `EventDocSummary` — the existing or newly created record. Requires the store context.
+
+**Not concurrency-safe** — two simultaneous misses both create. Serialise (e.g. queue concurrency 1) or add a conditional create if callers can race.
+
+## askEventDocGetIdByCode
+
+A thin convenience over `askEventDocGetByCode` for callers that only need the document's `id` and no per-record policy.
+
+```typescript
+function* askEventDocGetIdByCode(
+  code: string,
+  ownerUserId?: string,
+): AskResponse<Nullable<string>>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `code` | `string` | The business code to look up. |
+| `ownerUserId` | `string` (optional) | Owner scope, as above. |
+
+**Returns** `string | null` — the matching document's `id`, or `null` when none match. Inherits the same `Conflict`-on-duplicate behaviour as `askEventDocGetByCode`.
+
+## Related
+
+- [askEventDocGetById / askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md) — read by generated id instead of business code.
+- [askEventDocCreate](./ask-event-doc-create.md) — the create used on a miss by `askEventDocGetByCodeOrCreate`.
+- [askEventDocList](./ask-event-doc-list.md) — the collection scan these filter over.
+- [defineEventDocSummary](../../../config/features/event-doc-summary.md) — declares the store these read from.

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

@@ -0,0 +1,121 @@
+---
+title: askEventDocGetById
+description: Read an event document's summary record by id — nullable, or a load-or-throw variant.
+---
+
+# askEventDocGetById
+
+Reads one event document's **summary record** by `id` and returns it, or `null` if no document with that id exists in the current collection. Soft-deleted rows are returned as-is — filtering deleted documents is the caller's concern.
+
+- **Built from:** a single-item key-value store query scoped to the collection's `type` + `id`. Requires the store context — call it inside `askEventDocProvideStore({ storeName, type }, ...)`, or from a built-in route where the context is already provided.
+
+```typescript
+import { askEventDocGetById } from 'quidproquo-features';
+
+export function* loadArticle(id: string) {
+  const summary = yield* askEventDocGetById(id);
+  if (!summary) {
+    return null; // not found
+  }
+  return summary;
+}
+```
+
+## The event-document model
+
+An event document is never stored as a mutable blob. Its authoritative state is an **append-only log of events**; the document you read is *derived by folding that log*.
+
+- **Summary record** ([`EventDocSummary`](#the-summary-record)) — the queryable projection folded from the log's identity/lifecycle events (`INIT_STATE`, `SET_CODE`, `SET_NAME`, `PUBLISH`, …). It holds identity (`id`, `code`, `name`), audit fields, and a `versions` array. The document's editable **content** is folded separately (on the client) from the same log; the backend never reduces content.
+- **Draft vs published** — the tail (highest) version with no `publishedAt` is the **draft**; a `PUBLISH` event freezes it and starts the next draft. Each version pointer records the `eventIndex` of its last event (its head), so folding events with index ≤ that head reconstructs the version's content as it was. `publishedAt` is when a version was published; `effectiveFrom` is when that publish takes effect (used for as-of time-travel).
+- **Code** — the caller-chosen, stable business key set at create (via `INIT_STATE`) and editable with `SET_CODE`. It stays constant across versions and is expected unique within the collection (and any owner scope), so you can address a document by `code` instead of its generated `id`.
+
+The version-pointer reads ([askEventDocGetDraft, askEventDocGetLatestPublished, askEventDocGetPublishedAsOf, askEventDocPublishedEventsAsOf](./ask-event-doc-get-draft.md)) resolve entries in this model.
+
+### The summary record
+
+```typescript
+type EventDocSummary = {
+  type: string;
+  id: string;
+  code: string;
+  name: string;
+  createdAt: string;   // ISO datetime
+  updatedAt: string;   // ISO datetime
+  deletedAt?: string;  // set by soft delete
+  createdBy: string;
+  updatedBy: string;
+  versions: EventDocVersion[];
+};
+
+type EventDocVersion = {
+  version: number;
+  eventIndex: number;    // log index of this version's head event
+  publishedAt?: string;  // unset while it is the tail draft
+  effectiveFrom?: string; // when the publish takes effect (as-of selection)
+};
+```
+
+## Signature
+
+```typescript
+function* askEventDocGetById<T extends EventDocSummary = EventDocSummary>(
+  id: string,
+): AskResponse<Nullable<T>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Id of the document to read. |
+
+The generic `T` lets callers narrow to a collection-specific extension of `EventDocSummary`; it defaults to `EventDocSummary`.
+
+## Returns
+
+`EventDocSummary | null` — the record, or `null` when no document with that id exists in the collection. Soft-deleted records are returned (not filtered).
+
+---
+
+## askEventDocGetByIdOrThrow
+
+Loads the summary record for `id`, throwing `ErrorTypeEnum.NotFound` (from quidproquo-core) instead of returning `null` when it does not exist. Use this in write flows where a missing document is an error.
+
+```typescript
+function* askEventDocGetByIdOrThrow(id: string): AskResponse<EventDocSummary>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Id of the document to load. |
+
+**Returns** `EventDocSummary` — always a record; throws `NotFound` otherwise. Requires the store context.
+
+```typescript
+import { askEventDocGetByIdOrThrow } from 'quidproquo-features';
+
+export function* renameArticle(id: string) {
+  const summary = yield* askEventDocGetByIdOrThrow(id); // throws NotFound if absent
+  return summary;
+}
+```
+
+Catch the throw with [askCatch](../../core/system/ask-catch.md) if you want to handle "not found" without an exception:
+
+```typescript
+const outcome = yield* askCatch(askEventDocGetByIdOrThrow(id));
+if (outcome.success) {
+  // outcome.result — the EventDocSummary
+} else {
+  // outcome.error.errorType === ErrorTypeEnum.NotFound
+}
+```
+
+## Related
+
+- [askEventDocList](./ask-event-doc-list.md) — read every document in the collection.
+- [askEventDocGetByCode](./ask-event-doc-get-by-code.md) — look a document up by its business `code` instead of `id`.
+- [askEventDocGetDraft / …LatestPublished / …PublishedAsOf / …PublishedEventsAsOf](./ask-event-doc-get-draft.md) — resolve a document's versions.
+- [askEventDocCreate](./ask-event-doc-create.md) — create a document. [askEventDocSoftDelete](./ask-event-doc-soft-delete.md) — retire one.
+- [defineEventDocSummary](../../../config/features/event-doc-summary.md) — declares the store these read from.
+- [askCatch](../../core/system/ask-catch.md) — handle thrown errors as a result object.

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

@@ -0,0 +1,109 @@
+---
+title: askEventDocGetDraft
+description: Resolve an event document's version pointers — draft, latest published, and as-of time-travel reads.
+---
+
+# askEventDocGetDraft
+
+Resolves the current **draft** version pointer for a document by `id`, or `null` if there is no draft (or the document is missing). Together with the three actions below, this is the set of **version reads** over an event document's `versions` history.
+
+- **Built from:** [askEventDocGetById](./ask-event-doc-get-by-id.md) plus an in-memory version selector. Requires the store context — call it inside `askEventDocProvideStore({ storeName, type }, ...)`, or from a built-in route where the context is already provided.
+
+First, a quick recap of the model (full detail on the [read-by-id page](./ask-event-doc-get-by-id.md#the-event-document-model)): an event document is derived by folding its event log. Each **version** pointer in the summary's `versions` array records the `eventIndex` of its last event (its head) and, once published, its `publishedAt` and `effectiveFrom` times. The tail version with no `publishedAt` is the **draft**; a `PUBLISH` event freezes a version and opens the next draft.
+
+```typescript
+import { askEventDocGetDraft } from 'quidproquo-features';
+
+export function* currentDraft(id: string) {
+  const draft = yield* askEventDocGetDraft(id);
+  return draft; // EventDocVersion | null
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocGetDraft(id: string): AskResponse<Nullable<EventDocVersion>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Id of the document. |
+
+## Returns
+
+`EventDocVersion | null` — the draft version pointer (the tail version with no `publishedAt`), or `null` when the document has no draft or does not exist.
+
+### `EventDocVersion`
+
+```typescript
+type EventDocVersion = {
+  version: number;
+  eventIndex: number;    // log index of this version's head event
+  publishedAt?: string;  // unset while it is the tail draft
+  effectiveFrom?: string; // when the publish takes effect (as-of selection)
+};
+```
+
+To fold or render a version's content, fold the log's events with index ≤ its `eventIndex`.
+
+---
+
+## askEventDocGetLatestPublished
+
+Resolves the **latest published** version pointer for a document (the highest version that has a `publishedAt`), or `null` if nothing is published yet or the document is missing.
+
+```typescript
+function* askEventDocGetLatestPublished(id: string): AskResponse<Nullable<EventDocVersion>>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Id of the document. |
+
+**Returns** `EventDocVersion | null` — the highest version with a `publishedAt`, or `null`.
+
+## askEventDocGetPublishedAsOf
+
+Resolves the version **published at or before** a given clock time — as-of-clock time-travel keyed on `publishedAt`. Pass a version's own `publishedAt` to render it as-was, or `now` for the latest. Returns `null` when nothing was published by that time (or the document is missing).
+
+```typescript
+function* askEventDocGetPublishedAsOf(
+  id: string,
+  clock: QpqIsoDateTime,
+): AskResponse<Nullable<EventDocVersion>>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Id of the document. |
+| `clock` | `QpqIsoDateTime` | ISO-8601 timestamp to resolve as-of. |
+
+**Returns** `EventDocVersion | null` — the highest version with `publishedAt <= clock`, or `null`.
+
+## askEventDocPublishedEventsAsOf
+
+Returns the **events** that make up the version published and *effective* at `clock` — the log truncated at that version's head. It resolves the version from the summary via `effectiveFrom` (when the publish takes effect, so a publish scheduled for the future stays invisible until then), then returns every event with `index <= version.eventIndex`. Fold the returned events to get the published, as-of-`clock` content — the generic backbone of a "render published" flow. (This mirrors `askEventDocGetPublishedAsOf`, which returns the version pointer rather than its events, and keys on `publishedAt` rather than `effectiveFrom`.)
+
+```typescript
+function* askEventDocPublishedEventsAsOf(
+  id: string,
+  clock: QpqIsoDateTime,
+): AskResponse<Nullable<EventDocEvent[]>>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Id of the document. |
+| `clock` | `QpqIsoDateTime` | ISO-8601 timestamp to resolve the effective version as-of. |
+
+**Returns** `EventDocEvent[] | null` — the truncated event log for the effective version, or `null` when the document is missing/deleted or nothing is effective yet. Reads the full log via `askEventDocEventListAll` (quidproquo-features).
+
+## Related
+
+- [askEventDocGetById / askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md) — read the full summary record (and the model reference).
+- [askEventDocList](./ask-event-doc-list.md) — enumerate a collection's documents.
+- **Publishing / appending events:** `askEventDocEventAppend` (quidproquo-features) advances the log that these reads project.
+- [defineEventDocSummary](../../../config/features/event-doc-summary.md) — declares the store these read from.

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

@@ -0,0 +1,53 @@
+---
+title: askEventDocList
+description: List every event document in the current collection, newest-updated first, hiding soft-deleted rows by default.
+---
+
+# askEventDocList
+
+Lists the summary records of every document in the current collection (all rows sharing the collection's `type`), sorted by `updatedAt` **descending** (most recently updated first). Soft-deleted documents are hidden unless you opt in.
+
+- **Built from:** a key-value store query over the collection's `type`, filtered and sorted in memory. Requires the store context — call it inside `askEventDocProvideStore({ storeName, type }, ...)`, or from a built-in route where the context is already provided.
+
+```typescript
+import { askEventDocList } from 'quidproquo-features';
+
+export function* listArticles() {
+  const items = yield* askEventDocList(); // newest-updated first, deleted hidden
+  return items;
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocList<T extends EventDocSummary = EventDocSummary>(
+  options?: EventDocListOptions,
+): AskResponse<T[]>;
+```
+
+## Parameters
+
+### `options` — `EventDocListOptions` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `includeDeleted` | `boolean` | `false` | When `true`, soft-deleted documents (those with a `deletedAt`) are included in the result. When `false` (default), they are filtered out. |
+
+The generic `T` lets callers narrow to a collection-specific extension of [`EventDocSummary`](./ask-event-doc-get-by-id.md#the-summary-record); it defaults to `EventDocSummary`.
+
+## Returns
+
+`EventDocSummary[]` — the collection's records, sorted by `updatedAt` descending. Empty array when the collection has no (visible) documents.
+
+## Notes
+
+- Ordering is applied in memory, but the summary store carries a `(type, updatedAt)` index so this stays efficient.
+- Because there is no secondary index on `code`, the code-based reads ([askEventDocGetByCode](./ask-event-doc-get-by-code.md) and friends) list the collection via this action and filter in memory.
+
+## Related
+
+- [askEventDocGetById / askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md) — read a single document.
+- [askEventDocGetByCode](./ask-event-doc-get-by-code.md) — find one document by its business `code`.
+- [askEventDocSoftDelete](./ask-event-doc-soft-delete.md) — sets the `deletedAt` this action filters on.
+- [defineEventDocSummary](../../../config/features/event-doc-summary.md) — declares the store (and its ordering index) this reads from.

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

@@ -0,0 +1,160 @@
+---
+title: askEventDocProvideStore
+description: Provide and read the EventDoc store context that binds the generic event-doc data stories to one collection.
+---
+
+# The EventDoc store context
+
+Every generic event-doc data story — [askEventDocEventAppend](./ask-event-doc-event-append.md), the [event readers](./ask-event-doc-event-list.md), the [asset helpers](./ask-event-doc-generate-asset-upload-url.md), `askEventDocGetByIdOrThrow`, and the rest — needs to know **which collection** it is operating on: the events-store name, the record store name, the blob drive, and the document `type`. Rather than thread that through every call, event-doc uses the core context system: you **provide** the store binding once around a sub-story, and the data stories **read** it back internally.
+
+This is the same pattern as [askContextProvideValue](../../core/context/ask-context-provide-value.md) / [askContextRead](../../core/context/ask-context-read.md), specialised to an `EventDocStore`. The context is a **local** context (never serialized across a service boundary), and its default is empty — so reads outside a provider return blank fields, which is why [askEventDocResolveStore](#askeventdocresolvestore) exists to fail loudly.
+
+### `EventDocStore` — the binding
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `storeName` | `string` | The record (summary) store name for the collection. |
+| `eventsStoreName` | `string` | The events-log store name — by convention `` `${storeName}Events` ``. |
+| `type` | `string` | Pins the document type within a store that can hold several. |
+| `storageDriveName` | `string` | The collection's blob bucket (assets + runtime artifacts), keyed per-doc. |
+| `eventValidator` | `string` (optional) | The collection's append-time validator inline-function name, if configured. |
+| `eventRenderer` | `string` (optional) | The collection's render inline-function name, if configured (powers `GET .../render`). |
+
+There are two ways to establish the context — one for custom routes, one for the built-in routes — plus the raw provide/read primitives and a resolver that throws when the binding is missing.
+
+## askEventDocProvideStore
+
+Provides the store context for a collection identified by `storeName` + `type`, deriving the events-store and blob-drive names from `storeName`. Use it in a **custom** route (one outside `defineEventDocRoutes`, which has no per-route globals) so its sub-story can call the generic `askEventDocEvent*` / `askEventDocGetByIdOrThrow` data functions. It is the hand-written counterpart to [askEventDocProvideStoreFromGlobals](#askeventdocprovidestorefromglobals).
+
+```typescript
+import { askEventDocProvideStore } from 'quidproquo-features';
+
+export function* customAppendRoute(docId: string, input: EventDocEventInput) {
+  return yield* askEventDocProvideStore(
+    { storeName: 'reports', type: 'report' },
+    (function* () {
+      const actor = yield* askEventDocResolveActor();
+      return yield* askEventDocEventAppend(docId, input, actor);
+    })(),
+  );
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocProvideStore<T>(
+  options: EventDocStoreOptions,
+  story: AskResponse<T>,
+): AskResponse<T>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `EventDocStoreOptions` | The collection identity, minus the derivable bits — see below. |
+| `story` | `AskResponse<T>` | The sub-story to run with the store context bound. Its return value is passed through. |
+
+#### `EventDocStoreOptions`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `storeName` | `string` | The collection's record store name; the events-table and blob-drive names are derived from it. |
+| `type` | `string` | The document type pinned within the store. |
+| `eventValidator` | `string` (optional) | Append-time validator inline-function name. |
+| `eventRenderer` | `string` (optional) | Render inline-function name. |
+
+### Returns
+
+`AskResponse<T>` — whatever `story` returns.
+
+## askEventDocProvideStoreFromGlobals
+
+The built-in-routes counterpart: bridges the per-route **globals** that `defineEventDocRoutes` sets (store name, events-store name, type, storage drive, and the optional validator/renderer) into the store context, then runs the controller sub-story. Reads each global with [askConfigGetGlobal](../../core/config/ask-config-get-global.md), which throws if a route forgot to set them.
+
+```typescript
+import { askEventDocProvideStoreFromGlobals } from 'quidproquo-features';
+
+export function* getEventsController(event: HTTPEvent) {
+  return yield* askEventDocProvideStoreFromGlobals(
+    (function* () {
+      const docId = event.params.id;
+      return yield* askEventDocEventList(docId);
+    })(),
+  );
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocProvideStoreFromGlobals<T>(story: AskResponse<T>): AskResponse<T>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `story` | `AskResponse<T>` | The controller sub-story to run with the store context bound from route globals. |
+
+### Returns
+
+`AskResponse<T>` — whatever `story` returns.
+
+## askEventDocStoreProvide
+
+The raw context **provider**: binds a fully-formed [`EventDocStore`](#eventdocstore--the-binding) (no derivation) around a sub-story. Built with `createContextProvider`. Both [askEventDocProvideStore](#askeventdocprovidestore) and [askEventDocProvideStoreFromGlobals](#askeventdocprovidestorefromglobals) delegate to it once they have assembled the full store object; call it directly only when you already hold an `EventDocStore`.
+
+### Signature
+
+```typescript
+function* askEventDocStoreProvide<T>(
+  store: EventDocStore,
+  story: AskResponse<T>,
+): AskResponse<T>;
+```
+
+## askEventDocStoreRead
+
+The raw context **reader**: returns the currently bound [`EventDocStore`](#eventdocstore--the-binding). Built with `createContextReader`. Outside a provider it returns the **empty default** (blank `storeName` / `type`) rather than throwing — so most callers should prefer [askEventDocResolveStore](#askeventdocresolvestore). Internal data stories that only need one field (e.g. `eventValidator`) read it directly.
+
+### Signature
+
+```typescript
+function* askEventDocStoreRead(): AskResponse<EventDocStore>;
+```
+
+## askEventDocResolveStore
+
+Reads the store context and **throws if it was not provided** — a plain read otherwise silently returns the empty default and the data stories would target a blank store. This is the safe accessor the event/asset data stories use to get the store; it validates that `storeName` and `type` are set.
+
+```typescript
+import { askEventDocResolveStore } from 'quidproquo-features';
+
+export function* eventsStoreName() {
+  const { eventsStoreName } = yield* askEventDocResolveStore();
+  return eventsStoreName;
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocResolveStore(): AskResponse<EventDocStore>;
+```
+
+### Returns
+
+`AskResponse<EventDocStore>` — the bound store binding.
+
+### Notes
+
+- Throws `ErrorTypeEnum.GenericError` when `storeName` or `type` is missing, with the message: *"EventDoc store context was not provided. Wrap the call in askEventDocStoreProvide(...)"*.
+
+## Related
+
+- [askContextProvideValue](../../core/context/ask-context-provide-value.md) / [askContextRead](../../core/context/ask-context-read.md) — the core context system this specialises.
+- [askConfigGetGlobal](../../core/config/ask-config-get-global.md) — reads the per-route globals `askEventDocProvideStoreFromGlobals` bridges.
+- [askEventDocEventAppend](./ask-event-doc-event-append.md) · [event readers](./ask-event-doc-event-list.md) · [asset helpers](./ask-event-doc-generate-asset-upload-url.md) — the data stories that require this context.
+- [askEventDocResolveActor / ResolveUserId / ParseBody](./ask-event-doc-resolve-actor.md) — the other request-time helpers used in controllers.

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

@@ -0,0 +1,107 @@
+---
+title: askEventDocResolveActor
+description: Request-time helpers for event-doc route controllers — resolve the acting user from the access token and parse the request body.
+---
+
+# Request helpers
+
+Small helpers used inside event-doc route controllers to turn an authenticated HTTP request into the pieces an append needs: who is acting, and the parsed body. `askEventDocResolveActor` and `askEventDocResolveUserId` both read the already-validated access token (route auth gated the request), so they stamp provenance without a separate user lookup; `askEventDocParseBody` parses JSON safely.
+
+## askEventDocResolveActor
+
+Resolves the acting user as an `EventDocEventActor` — `{ userId, userDisplayName }` — straight off the validated access token (which carries the username). The natural source for the `actor` argument of [askEventDocEventAppend](./ask-event-doc-event-append.md) and [askEventDocAppendServerEvent](./ask-event-doc-append-server-event.md).
+
+- **Built from:** [askConfigGetGlobal](../../core/config/ask-config-get-global.md) (the user-directory global) + [askUserDirectoryReadAccessToken](../../core/user-directory/ask-user-directory-read-access-token.md). Not a single action.
+
+```typescript
+import { askEventDocResolveActor } from 'quidproquo-features';
+
+export function* appendController(docId: string, input: EventDocEventInput) {
+  const actor = yield* askEventDocResolveActor();
+  return yield* askEventDocEventAppend(docId, input, actor);
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocResolveActor(): AskResponse<EventDocEventActor>;
+```
+
+### Returns
+
+`AskResponse<EventDocEventActor>` — `{ userId, userDisplayName }`. `userId` is the stable authoritative key; `userDisplayName` is the token's username, captured for display at append time.
+
+### Notes
+
+- Throws `ErrorTypeEnum.Unauthorized` ("User not authenticated") when the token has no `userId`.
+- Reads the user directory named by the `eventDocUserDirectory` route global.
+
+## askEventDocResolveUserId
+
+Resolves just the acting user's id — a `string` — from the same validated access token. Use it where only the id is needed (e.g. stamping `createdBy` / `updatedBy` on a record) rather than the full actor.
+
+- **Built from:** [askConfigGetGlobal](../../core/config/ask-config-get-global.md) + [askUserDirectoryReadAccessToken](../../core/user-directory/ask-user-directory-read-access-token.md). Not a single action.
+
+```typescript
+import { askEventDocResolveUserId } from 'quidproquo-features';
+
+export function* whoAmI() {
+  return yield* askEventDocResolveUserId(); // string userId
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocResolveUserId(): AskResponse<string>;
+```
+
+### Returns
+
+`AskResponse<string>` — the acting user's id.
+
+### Notes
+
+- Throws `ErrorTypeEnum.Unauthorized` ("User not authenticated") when the token has no `userId`.
+
+## askEventDocParseBody
+
+Parses an HTTP request body as JSON, transparently base64-decoding it first when the event is base64-encoded, and throwing on malformed input. A typed convenience for controllers reading a JSON POST body (e.g. an `EventDocEventInput`).
+
+```typescript
+import { askEventDocParseBody } from 'quidproquo-features';
+import { HTTPEvent } from 'quidproquo-webserver';
+
+export function* appendRoute(event: HTTPEvent) {
+  const input = yield* askEventDocParseBody<EventDocEventInput>(event);
+  // ... use input
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocParseBody<T extends object>(event: HTTPEvent): AskResponse<T>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `event` | `HTTPEvent` | The incoming HTTP event (from `quidproquo-webserver`); its `body` / `isBase64Encoded` fields are read. |
+
+### Returns
+
+`AskResponse<T>` — the parsed body, cast to `T`. An absent body parses as `{}`.
+
+### Notes
+
+- Throws `ErrorTypeEnum.BadRequest` ("Invalid JSON request body") when the body is not valid JSON or does not parse to an object.
+
+## Related
+
+- [askEventDocEventAppend](./ask-event-doc-event-append.md) — consumes the resolved actor and parsed body.
+- [askEventDocAppendServerEvent](./ask-event-doc-append-server-event.md) — also takes a resolved actor.
+- [askEventDocProvideStore](./ask-event-doc-provide-store.md) — the store context controllers establish alongside these helpers.
+- [askUserDirectoryReadAccessToken](../../core/user-directory/ask-user-directory-read-access-token.md) — the core action the actor/user resolvers read.