create-qpq-app 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Scaffold a new quidproquo app: npx create-qpq-app my-app",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
@@ -52,7 +52,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.13",
-    "quidproquo-tsconfig": "0.1.12"
+    "quidproquo-tsconfig": "0.1.14"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

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

@@ -55,6 +55,7 @@ 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. |
+| `consistentRead` | `boolean` | `false` | Strongly consistent (read-your-own-writes) read. Costs roughly double the read capacity on DynamoDB and cannot be served from a global secondary index. Use it when a caller just wrote and is now querying to decide something (e.g. folding a log right after appending to it); leave it off for ordinary reads. |
 | `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. |
 

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

@@ -0,0 +1,98 @@
+---
+title: askKeyValueStoreScanAllScopes
+description: Migration-only scan across every scope in a key-value store, each record tagged with the scope it came from.
+---
+
+# askKeyValueStoreScanAllScopes
+
+Reads a page of records from a [key-value store](../../../config/core/key-value-store.md) across **every** storage scope, plus the unscoped partition, pairing each record with the scope it lives under. This deliberately crosses the scope boundary that [askKeyValueStoreScan](./ask-key-value-store-scan.md) and the rest of the KVS layer hold: an ordinary scan excludes scope-composed records so one tenant's request can never read another's.
+
+Reach for this only from a migration or an equivalent whole-store operation that needs to rewrite every row regardless of scope — never on a request path. Nothing in the framework calls it.
+
+- **Action type:** `KeyValueStoreActionType.ScanAllScopes`
+
+```typescript
+import { askKeyValueStoreScanAllScopes } from 'quidproquo-core';
+
+interface User {
+  userId: string;
+  status: string;
+}
+
+export function* askMigrateAllUsers() {
+  let nextPageKey: string | undefined;
+
+  do {
+    const page = yield* askKeyValueStoreScanAllScopes<User>('users', undefined, nextPageKey);
+
+    for (const { scope, item } of page.items) {
+      // rewrite item back into the same scope it came from
+    }
+
+    nextPageKey = page.nextPageKey;
+  } while (nextPageKey);
+}
+```
+
+## Signature
+
+```typescript
+function* askKeyValueStoreScanAllScopes<KvsItem>(
+  keyValueStoreName: string,
+  filterCondition?: KvsQueryOperation,
+  nextPageKey?: string,
+  options?: KeyValueStoreScanAllScopesOptions,
+): AskResponse<QpqPagedData<KvsScopedItem<KvsItem>>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `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, within every scope. 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` | `KeyValueStoreScanAllScopesOptions` | Optional scan options (see below). |
+
+### `KeyValueStoreScanAllScopesOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `limit` | `number` | – | Accepted but not implemented: no processor currently caps the page size, so setting it has no effect. |
+
+## Returns
+
+`QpqPagedData<KvsScopedItem<KvsItem>>` — one page of results:
+
+```typescript
+interface KvsScopedItem<KvsItem> {
+  scope?: string; // absent for an unscoped record
+  item: KvsItem;
+}
+
+interface QpqPagedData<T> {
+  items: T[];
+  nextPageKey?: string; // present when more pages remain
+}
+```
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `KeyValueStoreScanAllScopesErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
+| `KeyValueStoreScanAllScopesErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+| `KeyValueStoreScanAllScopesErrorTypeEnum.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 }`.
+
+## Notes
+
+- Drain every page: pagination can advance across scope boundaries as well as within a single scope's records, so stopping after the first page silently skips the rest of the store, not just the rest of one scope.
+- The scope is reported rather than dropped because a caller rewriting records across every tenant in one pass has to know which tenant each belongs to, or a write lands in the wrong partition.
+
+## Related
+
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store being scanned.
+- [askKeyValueStoreScan](./ask-key-value-store-scan.md) — the scoped-safe equivalent for request-path code.
+- [askKeyValueStoreScanAll](./ask-key-value-store-scan-all.md) — drains all pages of a single-scope scan into one array.

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

@@ -50,11 +50,11 @@ function* askEventDocAppendServerEvent<T>(
 
 ## Returns
 
-`AskResponse<EventDocEvent>` — the appended event with its server-stamped metadata (`index`, `createdAt`, `createdBy`, and the generated `clientMessageId`).
+`AskResponse<EventDocEvent>` — the appended event with its server-stamped metadata (`eventId`, `createdAt`, `createdBy`, and the generated `clientMessageId`).
 
 ## Notes
 
-- All of [askEventDocEventAppend](./ask-event-doc-event-append.md)'s invariants apply — version monotonicity, lifecycle/payload validation, and optimistic-concurrency retry — since this is a thin envelope-building wrapper over it. It can therefore throw the same `ErrorTypeEnum.NotFound` / `ErrorTypeEnum.Conflict`.
+- This is a thin envelope-building wrapper over [askEventDocEventAppend](./ask-event-doc-event-append.md), so the same caveat applies: the event is written unconditionally, and version/lifecycle validation is decided later at fold time, not here. A server event that a validator would reject is written but silently skipped by every fold.
 - A fresh `clientMessageId` is generated on every call, so this path does not participate in client retry dedup — each call is a distinct intended event.
 
 ## Related

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

@@ -64,7 +64,7 @@ A point-in-time snapshot of who produced an event, captured server-side at appen
 
 ## askEventDocSeedInitState
 
-Seeds a new document's log with its `INIT_STATE` event at index `0`, carrying the identity (`id`/`code`/`name`). This is the create-only primitive `askEventDocCreate` composes; clients never send `INIT_STATE` themselves. It writes the event and returns it.
+Seeds a new document's log with its `INIT_STATE` event, carrying the identity (`id`/`code`/`name`). This is the create-only primitive `askEventDocCreate` composes; clients never send `INIT_STATE` themselves. It writes the event and returns it.
 
 ```typescript
 function* askEventDocSeedInitState(
@@ -82,7 +82,7 @@ function* askEventDocSeedInitState(
 | `name` | `string` | The document's name. |
 | `actor` | `EventDocEventActor` | Who is creating the document. |
 
-**Returns** `EventDocEvent` — the written `INIT_STATE` event, with `payload.metadata.index === 0` and `version === 1`.
+**Returns** `EventDocEvent` — the written `INIT_STATE` event, with a freshly minted sortable `payload.metadata.eventId` and `version === 1`.
 
 Use `askEventDocCreate` unless you are building a custom create flow that needs the raw event; `askEventDocSeedInitState` alone writes the log but does **not** derive or persist the summary record.
 

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

@@ -1,13 +1,15 @@
 ---
 title: askEventDocEventAppend
-description: Append a client-authored event to a document's log with dedup, version and lifecycle validation, and optimistic-concurrency retry.
+description: Append a client-authored event to a document's log — a single unconditional write with no read, no retry, and no validation.
 ---
 
 # askEventDocEventAppend
 
-Appends a single client-authored event to a document's ordered event stream — the write half of the event-sourcing core. This is where the append-time safety invariants live: idempotent dedup, version monotonicity, lifecycle/payload validation, and optimistic-concurrency retry. After the event is written it also re-derives the queryable summary record so the document's status, version, name, and timestamps stay in sync with the log.
+Appends a single client-authored event to a document's ordered event stream — the write half of the event-sourcing core. The event's id is a sortable id (UUIDv7, minted by [askNewSortableGuid](../../core/guid/ask-new-sortable-guid.md)), so the write needs no allocator and no coordination: it does not read the tail, does not validate, and has no retry loop. Concurrent appends to the same document neither contend nor fail on each other. After the event is written it also re-derives the queryable summary record so the document's status, version, name, and timestamps stay in sync with the log.
 
-- **Built from:** a story composing `askRetry`, `askEventDocEventLast`, `askEventDocEventListAll`, `askEventDocEventWrite`, `askEventDocGetByIdOrThrow`, and (when the collection configures one) an `askInlineFunctionExecute` validator. Not a single action.
+**Validation happens later, at fold time, not here.** Dedup (a repeated `clientMessageId`), version monotonicity, and lifecycle/domain rules are all decided when the log is folded, against the accepted events before the one in question. An event that fails one of those checks is not rejected at append — it is written, then silently skipped by every fold, so the document reads as though it was never sent. That silence is deliberate: clients are expected to validate before they send (the same rules run client-side against the pending buffer), so a skipped event means a client skipped its own pre-flight, not that the append needs to report an error.
+
+- **Built from:** `askDateNow`, `askNewSortableGuid`, `askEventDocEventWrite`, and `askEventDocSummaryRederive` (plus, when the collection configures `onPublish`/`onAppend`, `askEventDocGetByIdOrThrow`, `askEventDocEventListAll`, and `askInlineFunctionExecute`). Not a single action.
 - **Requires the store context** — wrap the call in [askEventDocProvideStore](./ask-event-doc-provide-store.md) (custom routes) or [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals) (built-in routes).
 
 ```typescript
@@ -28,7 +30,7 @@ export function* appendTitleChange(docId: string) {
     actor,
   );
 
-  return event.payload.metadata.index;
+  return event.payload.metadata.eventId;
 }
 ```
 
@@ -46,20 +48,20 @@ function* askEventDocEventAppend(
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `modelId` | `string` | The document id whose log the event is appended to. The document must already have an `INIT_STATE` event (created via `askEventDocCreate`), or the append throws `NotFound`. |
+| `modelId` | `string` | The document id whose log the event is appended to. Not checked against an existing `INIT_STATE` at append time — an event appended before `INIT_STATE` exists is simply written and then skipped by every fold, since the reducer has no document to fold it onto. |
 | `input` | `EventDocEventInput` | The client-authored event envelope — see below. |
 | `actor` | `EventDocEventActor` | Who authored the event; stamped onto the event as `createdBy`. Usually obtained from [askEventDocResolveActor](./ask-event-doc-resolve-actor.md). |
 
 ### `EventDocEventInput`
 
-What the client POSTs to append an event. `modelId` and the server-stamped provenance (`index`, `createdAt`, `createdBy`) are NOT part of it.
+What the client POSTs to append an event. `modelId` and the server-stamped provenance (`eventId`, `createdAt`, `createdBy`) are NOT part of it.
 
 | Property | Type | Description |
 | --- | --- | --- |
 | `type` | `string` | The effect/event type discriminant (e.g. `SET_NAME`). The reducer folds it by this. |
 | `payload.data` | `T` | The typed domain data for the event. |
-| `payload.metadata.version` | `number` | The schema version the client authored against. Must be `>=` the last event's version — an older version throws `Conflict`. |
-| `payload.metadata.clientMessageId` | `string` | A client-generated id used for dedup: if the latest event already carries it, the append is a no-op and returns that event unchanged. |
+| `payload.metadata.version` | `number` | The schema version the client authored against. Expected `>=` the log's highest accepted version so far — the fold, not the append, silently skips an older one when it later folds the log. |
+| `payload.metadata.clientMessageId` | `string` | A client-generated id used for dedup: the fold ignores a later event carrying a `clientMessageId` it has already accepted. The append itself does not check this — a retry is written as a new row in the log either way. |
 
 ### `EventDocEventActor`
 
@@ -70,7 +72,7 @@ What the client POSTs to append an event. `modelId` and the server-stamped prove
 
 ## Returns
 
-`AskResponse<EventDocEvent>` — the event that now lives in the log, with server-stamped metadata (`index`, `createdAt`, `createdBy`) filled in. On a deduped retry, the pre-existing event is returned unchanged.
+`AskResponse<EventDocEvent>` — the event now written to the log, with server-stamped metadata (`eventId`, `createdAt`, `createdBy`) filled in. Unlike before, this is not conditional on the event surviving validation — a fold may still skip it.
 
 ### `EventDocEvent`
 
@@ -78,15 +80,15 @@ What the client POSTs to append an event. `modelId` and the server-stamped prove
 | --- | --- | --- |
 | `type` | `string` | The event type discriminant. |
 | `payload.data` | `T` | The typed domain data. |
-| `payload.metadata` | `EventDocEventMetadata` | Full provenance: `version`, `clientMessageId`, `createdBy`, `createdAt`, and `index` (mirrors the storage sort key). |
+| `payload.metadata` | `EventDocEventMetadata` | Full provenance: `version`, `clientMessageId`, `createdBy`, `createdAt`, and `eventId` (a sortable id — mirrors the storage sort key, sorts lexicographically in creation order). |
 
 ## Notes
 
-- **Dedup** is best-effort against the latest event only (until a GSI exists): a retry that re-sends the same `clientMessageId` returns the existing tail event without writing.
-- **Validation** always runs against the log folded from prior events. If the collection configured an `eventValidator` inline function it runs that (a complete validator that already composes the reserved lifecycle guard); otherwise it runs `defaultEventDocEventValidator` — the same guard with no domain rules. Exactly one validator runs. A rejected event throws `Conflict` with the validator's reason.
-- **Concurrency:** the underlying write ([askEventDocEventWrite](./ask-event-doc-event-write.md)) claims the `(modelId, index)` slot conditionally. A losing concurrent writer gets a key-value-store upsert conflict — the only error the internal `askRetry` re-laps on — re-reads the tail, and re-runs dedup/validation against fresh state, so concurrent appends serialize onto consecutive indexes. After `MAX_APPEND_ATTEMPTS` (8) lost races it throws `ErrorTypeEnum.Conflict`.
-- **Thrown `ErrorTypeEnum` values:** `NotFound` (no `INIT_STATE`), `Conflict` (stale version, failed validation, or exhausted concurrency retries). These are thrown via `askThrowError`, not a per-action error enum.
-- After writing, it re-derives and upserts the document's summary record (via `applyEventDocSummaryEvent`) so the queryable view stays consistent with the log.
+- **No dedup, no version check, and no lifecycle/domain validation at append time.** All three are decided when the log is folded (`foldEventDocLog`), against the accepted events before the one in question: a repeated `clientMessageId` is ignored, an event whose version is older than the log's highest accepted version is ignored, and the collection's `eventValidator` (or `defaultEventDocEventValidator` when none is configured) is run there too. A rejected event is skipped silently — the document reads as though it was never written — rather than causing the append to throw.
+- **No read, no retry, no coordination.** The append does not read the tail or the log; it mints a sortable id and writes. Two appends landing in the same millisecond get an arbitrary but stable relative order, which is fine because ordering only has to be stable, not wall-clock-precise.
+- **Write uniqueness** is still enforced by [askEventDocEventWrite](./ask-event-doc-event-write.md)'s conditional (`ifNotExists`) write, but since ids are unique by construction this should never fire in practice — a collision surfaces as `KeyValueStoreUpsertErrorTypeEnum.Conflict` and indicates a bug (two writers minting the same id), not ordinary contention, so there is no retry around it.
+- After writing, it calls `askEventDocSummaryRederive`, which re-folds the whole log and re-derives the document's summary record so the queryable view (identity, version history, timestamps) stays in sync — this is the one piece of read-model maintenance still on the write path, until a stream projector replaces it.
+- Hooks (`onPublish`/`onAppend`, when the collection configures them) run after the event is durably written; a hook failure propagates so the caller knows the side effect — not the append — failed.
 
 ## Related
 

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

@@ -5,21 +5,21 @@ description: Read a document's event log — a page of events, the whole log fla
 
 # Reading the event log
 
-Three read helpers over a document's event stream. All three resolve the collection's events store from the store context and query it by `pk = modelId`, ascending by log index (except `askEventDocEventLast`, which reads the tail). They are the read side of the event-sourcing core, feeding the fold that reconstructs a document from its events.
+Three read helpers over a document's event stream. All three resolve the collection's events store from the store context and query it by `pk = modelId`, ascending by event id (except `askEventDocEventLast`, which reads the tail). Event ids are sortable ids (UUIDv7) whose string form sorts lexicographically in creation order, so ascending-by-id and ascending-by-creation-time agree. They are the read side of the event-sourcing core, feeding the fold that reconstructs a document from its events.
 
 - **Requires the store context** — provide it via [askEventDocProvideStore](./ask-event-doc-provide-store.md) / [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals).
 - **Built from:** [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md) against the events store, plus [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore). Not single actions.
 
 ## askEventDocEventList
 
-Returns one page of events for a document, oldest first. Supports paging and, via `afterIndex`, fetching only the tail since a known index — an incremental refresh.
+Returns one page of events for a document, oldest first. Supports paging and, via `afterEventId`, fetching only the tail since a known event — an incremental refresh.
 
 ```typescript
 import { askEventDocEventList } from 'quidproquo-features';
 
-export function* refreshSince(docId: string, lastSeenIndex: number) {
-  const page = yield* askEventDocEventList(docId, { afterIndex: lastSeenIndex });
-  return page.items; // events with index > lastSeenIndex
+export function* refreshSince(docId: string, lastSeenEventId: string) {
+  const page = yield* askEventDocEventList(docId, { afterEventId: lastSeenEventId });
+  return page.items; // events after lastSeenEventId
 }
 ```
 
@@ -45,11 +45,12 @@ function* askEventDocEventList(
 | --- | --- | --- | --- |
 | `limit` | `number` | (store default) | Max number of events to return in the page. |
 | `nextPageKey` | `string` | — | Continuation token from a previous page's `nextPageKey`. |
-| `afterIndex` | `number` | — | Return only events whose log index is greater than this (exclusive). A sort-key range condition on the events store's primary key — no GSI involved. |
+| `afterEventId` | `string` | — | Return only events whose event id sorts after this one (exclusive). A sort-key range condition on the events store's primary key — no GSI involved. |
+| `consistentRead` | `boolean` | `false` | Strongly consistent read. Needed by a caller that just appended and is now folding to decide something — the default eventually-consistent read can otherwise miss that caller's own most recent event. Costs roughly double the read capacity, so leave it off for ordinary reads. |
 
 ### Returns
 
-`AskResponse<QpqPagedData<EventDocEvent>>` — `{ items: EventDocEvent[]; nextPageKey?: string }`. Events are ordered ascending by index; `nextPageKey` is present when more events remain.
+`AskResponse<QpqPagedData<EventDocEvent>>` — `{ items: EventDocEvent[]; nextPageKey?: string }`. Events are ordered ascending by event id (equivalently, creation order); `nextPageKey` is present when more events remain.
 
 ## askEventDocEventListAll
 
@@ -66,7 +67,10 @@ export function* fullHistory(docId: string) {
 ### Signature
 
 ```typescript
-function* askEventDocEventListAll(modelId: string): AskResponse<EventDocEvent[]>;
+function* askEventDocEventListAll(
+  modelId: string,
+  options?: { consistentRead?: boolean },
+): AskResponse<EventDocEvent[]>;
 ```
 
 ### Parameters
@@ -74,14 +78,15 @@ function* askEventDocEventListAll(modelId: string): AskResponse<EventDocEvent[]>
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `modelId` | `string` | The document id to read the full log for. |
+| `options.consistentRead` | `boolean` | Optional, default `false`. Strongly consistent read — for a caller that just appended and is now folding to decide something, so it does not miss its own most recent event. Leave off for ordinary reads; it doubles the read cost. |
 
 ### Returns
 
-`AskResponse<EventDocEvent[]>` — every event for the document, ordered ascending by index. Internally loops [askEventDocEventList](#askeventdoceventlist) until there is no `nextPageKey`.
+`AskResponse<EventDocEvent[]>` — every event for the document, ordered ascending by event id. Internally loops [askEventDocEventList](#askeventdoceventlist) until there is no `nextPageKey`.
 
 ## askEventDocEventLast
 
-Returns the newest event in the log, or `null` if the document has no events. Used to assign the next index, dedup, and validate during an append. Relies on numeric sort-key ordering (the dev server sorts numeric sort keys numerically, matching DynamoDB), so it returns the true latest.
+Returns the newest event in the log, or `null` if the document has no events. Relies on string sort-key ordering (a sortable event id's string form sorts lexicographically in creation order, and the dev server sorts string sort keys the same way DynamoDB does), so it returns the true latest.
 
 ```typescript
 import { askEventDocEventLast } from 'quidproquo-features';

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

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

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-generate-asset-upload-url.md

@@ -1,13 +1,13 @@
 ---
 title: askEventDocGenerateAssetUploadUrl
-description: Manage a document's immutable assets — mint presigned upload/download URLs, or write server-generated bytes directly.
+description: Manage a document's immutable assets and size-aware values — mint presigned upload/download URLs, write server-generated bytes directly, or record a value inline vs as an asset depending on its size.
 ---
 
 # Document assets
 
 A document can point at binary **assets** — images, fonts, rendered artifacts — without embedding the bytes. Each asset is stored immutably on the collection's storage drive under `<docId>/assets/<guid>`, and the document records only a reference (the guid) inside a domain event. Because every upload gets a fresh guid, a re-upload is a new blob and prior references stay addressable for history and rollback.
 
-These three helpers cover the two flows: presigned URLs for a browser to upload/download bytes directly, and a server-side write for when the backend already holds the bytes.
+These helpers cover three flows: presigned URLs for a browser to upload/download bytes directly, a server-side write for when the backend already holds the bytes, and a size-aware write that decides between inline and asset storage for values of unpredictable size.
 
 - **Requires the store context** — provide it via [askEventDocProvideStore](./ask-event-doc-provide-store.md) / [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals). The drive name is resolved from that context.
 - **Built from:** the core file secure-URL / binary-write actions on the collection's storage drive, plus [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore). Not single actions.
@@ -115,10 +115,49 @@ function* askEventDocWriteAsset(
 
 `AskResponse<EventDocAssetRef>` — `{ guid, filename, mimetype }`, a first-class reference to record in a domain event so the document points at the bytes without embedding them.
 
+## askEventDocWriteValue
+
+Records a **value** (data of unpredictable size — a node output, a variable, a trigger input) for an event: inline when it is small enough, or as an asset when it is not. This is the size-aware counterpart to `askEventDocWriteAsset` above, which stays the right choice for genuine files where a reference is always correct.
+
+```typescript
+import { askEventDocWriteValue } from 'quidproquo-features';
+
+export function* recordNodeOutput(docId: string, nodeId: string, output: unknown) {
+  const ref = yield* askEventDocWriteValue(docId, output, `${nodeId}.json`);
+  // ref is either { kind: 'inline', value } or { kind: 'asset', guid, filename, mimetype }
+  return ref;
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocWriteValue(
+  docId: string,
+  value: unknown,
+  filename: string,
+  maxInlineBytes?: number,
+): AskResponse<EventDocValueRef>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `docId` | `string` | The document the value belongs to — used for the asset blob key when the value doesn't fit inline. |
+| `value` | `unknown` | The value to record. Serialised with `JSON.stringify`; `undefined` is normalised to `null`. |
+| `filename` | `string` | Filename to use if the value is written as an asset. |
+| `maxInlineBytes` | `number` | Optional, default 4KB. The per-value inline ceiling. A caller recording several values against one event's combined size budget can pass the *remaining* budget so a value that no longer fits falls back to an asset; passing `0` always forces an asset. |
+
+### Returns
+
+`AskResponse<EventDocValueRef>` — either `{ kind: 'inline', value }` (the value travelled in the event, nothing to fetch) or `{ kind: 'asset', guid, filename, mimetype }` (fetch it like any other asset reference).
+
 ## Notes
 
-- All three resolve the drive from the store context, so a missing context throws (see [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore)).
+- All four resolve the drive from the store context, so a missing context throws (see [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore)).
 - Assets are immutable: guid-named so a re-upload is always a fresh blob; the old one stays addressable for history/rollback. Assets live under `<docId>/assets/<guid>`; derived, disposable artifacts use a sibling `<docId>/runtime/<...>` prefix written elsewhere.
+- On the read side, `isInlineEventDocValueRef`, `readInlineEventDocValueRefs`, and `resolveEventDocValueRef` (all in `quidproquo-features`) are the shared helpers for branching on a ref's `kind` and resolving it against fetched asset snapshots — use them rather than checking `ref.kind` by hand, so every reader agrees on what "available" means.
 
 ## Related
 

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

@@ -25,8 +25,8 @@ export function* loadArticle(id: string) {
 
 An event document is never stored as a mutable blob. Its authoritative state is an **append-only log of events**; the document you read is *derived by folding that log*.
 
-- **Summary record** ([`EventDocSummary`](#the-summary-record)) — the queryable projection folded from the log's identity/lifecycle events (`INIT_STATE`, `SET_CODE`, `SET_NAME`, `PUBLISH`, …). 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).
+- **Summary record** ([`EventDocSummary`](#the-summary-record)) — the queryable projection folded from the log's identity/lifecycle events (`INIT_STATE`, `SET_CODE`, `SET_NAME`, `PUBLISH`, `DELETE`, `RESTORE`, …). It holds identity (`id`, `code`, `name`), audit fields, and a `versions` array. Every field on it is derived from the log — including `deletedAt`, set and cleared by `DELETE`/`RESTORE` events rather than written directly — so the whole record can be dropped and rebuilt from the log at any time. The document's editable **content** is folded separately (on the client) from the same log; the backend never reduces content.
+- **Draft vs published** — the tail (highest) version with no `publishedAt` is the **draft**; a `PUBLISH` event freezes it and starts the next draft. Each version pointer records the `eventId` (a sortable id) of its last event (its head), so folding events whose `eventId` sorts at or before that head reconstructs the version's content as it was. `publishedAt` is when a version was published; `effectiveFrom` is when that publish takes effect (used for as-of time-travel).
 - **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.
@@ -41,7 +41,7 @@ type EventDocSummary = {
   name: string;
   createdAt: string;   // ISO datetime
   updatedAt: string;   // ISO datetime
-  deletedAt?: string;  // set by soft delete
+  deletedAt?: string;  // derived from a DELETE event; cleared by RESTORE
   createdBy: string;
   updatedBy: string;
   versions: EventDocVersion[];
@@ -49,7 +49,7 @@ type EventDocSummary = {
 
 type EventDocVersion = {
   version: number;
-  eventIndex: number;    // log index of this version's head event
+  eventId: string;       // sortable id of this version's head event
   publishedAt?: string;  // unset while it is the tail draft
   effectiveFrom?: string; // when the publish takes effect (as-of selection)
 };
@@ -116,6 +116,6 @@ if (outcome.success) {
 - [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.
+- [askEventDocCreate](./ask-event-doc-create.md) — create a document. [askEventDocSoftDelete / askEventDocRestore](./ask-event-doc-soft-delete.md) — retire a document, or bring it back.
 - [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

@@ -9,7 +9,7 @@ Resolves the current **draft** version pointer for a document by `id`, or `null`
 
 - **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.
+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 `eventId` 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';
@@ -41,13 +41,13 @@ function* askEventDocGetDraft(id: string): AskResponse<Nullable<EventDocVersion>
 ```typescript
 type EventDocVersion = {
   version: number;
-  eventIndex: number;    // log index of this version's head event
+  eventId: string;       // sortable id of this version's head event
   publishedAt?: string;  // unset while it is the tail draft
   effectiveFrom?: string; // when the publish takes effect (as-of selection)
 };
 ```
 
-To fold or render a version's content, fold the log's events with index ≤ its `eventIndex`.
+To fold or render a version's content, fold the log's events whose `eventId` sorts at or before the version's `eventId`.
 
 ---
 
@@ -85,7 +85,7 @@ function* askEventDocGetPublishedAsOf(
 
 ## 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`.)
+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 whose `eventId` sorts at or before `version.eventId`. 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(

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

@@ -1,13 +1,17 @@
 ---
 title: askEventDocList
-description: List every event document in the current collection, newest-updated first, hiding soft-deleted rows by default.
+description: List event documents in the current collection, newest-updated first, hiding soft-deleted rows by default — as a full array or one page at a time.
 ---
 
-# askEventDocList
+# Listing a collection
 
-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.
+Two ways to list the summary records of a 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. Both require the store context — call inside `askEventDocProvideStore({ storeName, type }, ...)`, or from a built-in route where the context is already provided.
 
-- **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.
+## askEventDocList
+
+Reads the **whole** collection into memory, filters and sorts it, and returns it as a flat array. Fine for a handful of documents; costs read capacity proportional to the whole collection, so it does not scale to a large collection — use [askEventDocListPage](#askeventdoclistpage) for that.
+
+- **Built from:** a key-value store query over the collection's `type`, filtered and sorted in memory.
 
 ```typescript
 import { askEventDocList } from 'quidproquo-features';
@@ -18,7 +22,7 @@ export function* listArticles() {
 }
 ```
 
-## Signature
+### Signature
 
 ```typescript
 function* askEventDocList<T extends EventDocSummary = EventDocSummary>(
@@ -26,9 +30,9 @@ function* askEventDocList<T extends EventDocSummary = EventDocSummary>(
 ): AskResponse<T[]>;
 ```
 
-## Parameters
+### Parameters
 
-### `options` — `EventDocListOptions` (optional)
+#### `options` — `EventDocListOptions` (optional)
 
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -36,18 +40,60 @@ function* askEventDocList<T extends EventDocSummary = EventDocSummary>(
 
 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
+### Returns
 
 `EventDocSummary[]` — the collection's records, sorted by `updatedAt` descending. Empty array when the collection has no (visible) documents.
 
-## Notes
+### 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.
 
+## askEventDocListPage
+
+Reads **one page** of the collection straight off the store, newest first, without reading or holding the rest of the collection in memory. This is what the built-in `GET {basePath}` list route uses.
+
+- **Built from:** [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md) against the summary store, ordered by its `(type, updatedAt)` index (descending), with soft-deleted rows excluded by a query filter.
+
+```typescript
+import { askEventDocListPage } from 'quidproquo-features';
+
+export function* listArticlesPage(nextPageKey?: string) {
+  return yield* askEventDocListPage({ nextPageKey }); // QpqPagedData<EventDocSummary>
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocListPage<T extends EventDocSummary = EventDocSummary>(
+  options?: EventDocListPageOptions,
+): AskResponse<QpqPagedData<T>>;
+```
+
+### Parameters
+
+#### `options` — `EventDocListPageOptions` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `includeDeleted` | `boolean` | `false` | When `true`, soft-deleted documents are included. When `false` (default), they are excluded by a query filter. |
+| `limit` | `number` | `10` | 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. |
+
+### Returns
+
+`AskResponse<QpqPagedData<T>>` — `{ items: T[]; nextPageKey?: string }`, one page ordered by `updatedAt` descending.
+
+### Notes
+
+- Because the exclusion of soft-deleted rows is a query filter (applied **after** rows are read), a page can come back shorter than `limit` while more pages remain. Page on the presence of `nextPageKey`, never on item count, or documents past a short page are silently hidden.
+- There is no jump-to-page-N or total count without reading the whole collection — the store hands back an opaque "continue from here" cursor, not an offset, so pages are walked rather than addressed.
+
 ## 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.
+- [askEventDocSoftDelete](./ask-event-doc-soft-delete.md) — sets the `deletedAt` these actions filter on.
+- [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md) — the underlying paged query action.
+- [defineEventDocSummary](../../../config/features/event-doc-summary.md) — declares the store (and its ordering index) these read from.

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

@@ -1,19 +1,19 @@
 ---
 title: askEventDocSoftDelete
-description: Soft-delete an event document by stamping deletedAt, keeping its versions and assets intact.
+description: Soft-delete an event document by appending a DELETE event, keeping its versions and assets intact — and restore it with askEventDocRestore.
 ---
 
 # askEventDocSoftDelete
 
-Soft-deletes an event document by stamping `deletedAt` (and refreshing `updatedAt`/`updatedBy`) on its summary record. The document's versions and blob claims stay intact — nothing is destroyed — and [askEventDocList](./ask-event-doc-list.md) hides it by default. This is the **public** deletion path. Returns the updated [`EventDocSummary`](./ask-event-doc-get-by-id.md#the-summary-record).
+Soft-deletes an event document by appending a reserved `DELETE` event to its log. `deletedAt` on the summary record is derived from that event by the fold (not written directly), and [askEventDocList](./ask-event-doc-list.md) hides the document by default once it's set. The document's versions and blob claims stay intact — nothing is destroyed. This is the **public** deletion path. Returns the updated [`EventDocSummary`](./ask-event-doc-get-by-id.md#the-summary-record).
 
-- **Built from:** [askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md#askeventdocgetbyidorthrow) (loads the record, throwing `NotFound` if missing), then a validated [askEventDocUpsert](./ask-event-doc-create.md#askeventdocupsert). Requires the store context — call it inside `askEventDocProvideStore({ storeName, type }, ...)`.
+- **Built from:** [askEventDocAppendServerEvent](./ask-event-doc-append-server-event.md) (appends the `DELETE` event) then [askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md#askeventdocgetbyidorthrow) (re-reads the re-derived record). Requires the store context — call it inside `askEventDocProvideStore({ storeName, type }, ...)`.
 
 ```typescript
 import { askEventDocSoftDelete } from 'quidproquo-features';
 
-export function* archiveArticle(id: string, userId: string) {
-  const summary = yield* askEventDocSoftDelete(id, userId);
+export function* archiveArticle(id: string, userId: string, schemaVersion: number) {
+  const summary = yield* askEventDocSoftDelete(id, userId, schemaVersion);
   return summary; // deletedAt is now set
 }
 ```
@@ -24,6 +24,7 @@ export function* archiveArticle(id: string, userId: string) {
 function* askEventDocSoftDelete(
   id: string,
   updatedBy: string,
+  schemaVersion: number,
 ): AskResponse<EventDocSummary>;
 ```
 
@@ -32,19 +33,55 @@ function* askEventDocSoftDelete(
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `id` | `string` | Id of the document to soft-delete. |
-| `updatedBy` | `string` | User id to record as having performed the deletion (written to `updatedBy`). |
+| `updatedBy` | `string` | User id to record as having authored the `DELETE` event (used as both `userId` and `userDisplayName` on the event's actor). |
+| `schemaVersion` | `number` | The schema version to stamp the `DELETE` event with, same as any other event — the fold rejects an event authored against an older schema than the log has already reached. |
 
 ## Returns
 
-`EventDocSummary` — the updated record with `deletedAt` set to the deletion time.
+`EventDocSummary` — the re-derived record, with `deletedAt` set to the `DELETE` event's time.
 
 ## Notes
 
-- Throws `ErrorTypeEnum.NotFound` (from quidproquo-core) when no document exists for `id`.
+- The reserved `DELETE` validator (`requireNotDeleted`) rejects a `DELETE` on an already-deleted document — but rejection happens at fold time, not at append (see [askEventDocEventAppend](./ask-event-doc-event-append.md)), so calling this on an already-deleted document does not throw: the event is written, the fold silently skips it, and the re-derived summary comes back unchanged.
 - Soft-deleted rows are still returned by [askEventDocGetById](./ask-event-doc-get-by-id.md) (filtering is the caller's concern) and by [askEventDocList](./ask-event-doc-list.md) only when `includeDeleted: true`.
 
 ---
 
+## askEventDocRestore
+
+Undoes a soft delete by appending a reserved `RESTORE` event. The `DELETE` event stays in the log — history is append-only, so the deletion remains auditable — but the fold stops treating the document as deleted from this point on: `deletedAt` is cleared on the re-derived summary record, and the document goes back into default (non-`includeDeleted`) listings. Everything else (versions, blob claims) is untouched, so the document comes back exactly as it was. Returns the updated `EventDocSummary`.
+
+```typescript
+import { askEventDocRestore } from 'quidproquo-features';
+
+export function* unarchiveArticle(id: string, userId: string, schemaVersion: number) {
+  const summary = yield* askEventDocRestore(id, userId, schemaVersion);
+  return summary; // deletedAt is cleared
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocRestore(
+  id: string,
+  updatedBy: string,
+  schemaVersion: number,
+): AskResponse<EventDocSummary>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Id of the document to restore. |
+| `updatedBy` | `string` | User id to record as having authored the `RESTORE` event. |
+| `schemaVersion` | `number` | The schema version to stamp the `RESTORE` event with, for the same reason as `askEventDocSoftDelete`. |
+
+**Returns** `EventDocSummary` — the re-derived record, with `deletedAt` cleared.
+
+The reserved `RESTORE` validator (`requireDeleted`) rejects a `RESTORE` on a document that isn't currently deleted — again at fold time, not append, so calling this on a non-deleted document does not throw; it's a silent no-op. Requires the store context, built the same way as `askEventDocSoftDelete` above.
+
+---
+
 ## askEventDocDelete
 
 **Hard delete** — permanently removes the document's summary row from the store. This is for internal cleanup/admin only; the public lifecycle uses soft delete (above). It does not touch the event log or the asset bucket, so a hard delete of the summary alone leaves orphaned events/assets — use deliberately.
@@ -63,7 +100,8 @@ Requires the store context. Prefer `askEventDocSoftDelete` for anything user-fac
 
 ## Related
 
-- [askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md#askeventdocgetbyidorthrow) — the load-or-throw this composes.
+- [askEventDocAppendServerEvent](./ask-event-doc-append-server-event.md) — appends the `DELETE`/`RESTORE` event both actions compose.
+- [askEventDocEventAppend](./ask-event-doc-event-append.md) — the underlying append; explains why rejection is silent rather than thrown.
+- [askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md#askeventdocgetbyidorthrow) — reads the re-derived record back.
 - [askEventDocList](./ask-event-doc-list.md) — hides soft-deleted documents by default.
 - [askEventDocCreate](./ask-event-doc-create.md) — the create counterpart.
-- [askDateNow](../../core/date/ask-date-now.md) — supplies the `deletedAt` timestamp.

package/template/docusaurus/docs/config/core/key-value-store.md

@@ -56,6 +56,7 @@ Zero or more sort keys. The list is significant:
 | `ttlAttribute` | `string` | – | Name of a record attribute holding a Unix-epoch (seconds) timestamp. DynamoDB automatically deletes records once that time passes. |
 | `disablePointInTimeRecovery` | `boolean` | `false` | Point-in-time recovery (35-day continuous backups / restore) is on by default; set this to opt out. |
 | `encryption` | `boolean` | `false` | Enables customer-managed KMS encryption for the table (the KMS key comes from the service's AWS config). When a customer-managed key isn't configured, AWS-managed encryption is used instead; when `false`, DynamoDB's default provider-managed encryption still applies. |
+| `onStream` | `KvsStreamSettings` | – | Turns on change data capture and runs a story for every insert/modify/remove on the store. See [Change data capture (`onStream`)](#change-data-capture-onstream). |
 
 ## Keys (`CompositeKvsKey`)
 
@@ -98,6 +99,56 @@ defineKeyValueStore('orders', 'orderId', [], {
 
 On AWS each index becomes a Global Secondary Index whose name is the index's partition-key attribute (`customerId`, `status` above).
 
+## Change data capture (`onStream`)
+
+```typescript
+export type KvsStreamSettings = {
+  runtime: QpqFunctionRuntime;
+  coalesceByPartitionKey?: boolean;
+  batchSize?: number;
+  maximumBatchingWindowInSeconds?: number;
+};
+```
+
+Declaring `onStream` puts the table into DynamoDB's `NEW_AND_OLD_IMAGES` stream mode and deploys a handler lambda subscribed to it. Records for a given partition key are always delivered to the handler in order; different partition keys may be processed concurrently. A table nothing subscribes to gets no stream at all, since a stream on it would be pure cost.
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `runtime` | `QpqFunctionRuntime` | – (required) | The handler story, usually a relative path string in the form `'/path/to/file::exportedFunctionName'`. Invoked once per record with a `KvsStreamRecord<T>` (exported from `quidproquo-core`). |
+| `coalesceByPartitionKey` | `boolean` | `false` | Collapse each delivered batch down to one record per partition key (the latest), instead of invoking the handler once per record. Off by default, since a generic consumer (audit trail, change notifications) needs to see every change. Turn it on for a projection, where the handler re-derives state from source and only needs to know a key changed. |
+| `batchSize` | `number` | `100` | Records per invocation. DynamoDB streams allow up to 1000. |
+| `maximumBatchingWindowInSeconds` | `number` | – | How long to wait accumulating records before invoking, 0–300 seconds. Trades latency for fewer invocations, and gives `coalesceByPartitionKey` more to collapse. |
+
+The handler receives a `KvsStreamRecord<T>`:
+
+```typescript
+export enum KvsStreamEventType {
+  Insert = 'Insert',
+  Modify = 'Modify',
+  Remove = 'Remove',
+}
+
+export type KvsStreamRecord<TItem extends object = any> = {
+  keyValueStoreName: string;
+  eventType: KvsStreamEventType;
+  scope?: string;                  // present when the item was written under a storage scope
+  keys: Record<string, unknown>;   // always present, including on Remove
+  newImage?: TItem;                // absent on Remove
+  oldImage?: TItem;                // absent on Insert
+};
+```
+
+Images are plain objects, already unmarshalled from DynamoDB's wire format and with any storage scope stripped back out of the key values — a handler is ordinary story code and never sees a raw AttributeValue or a composed partition key.
+
+```typescript
+defineKeyValueStore('documents', 'id', [], {
+  onStream: {
+    runtime: '/entry/kvsStream/onDocumentChanged::onDocumentChanged',
+    coalesceByPartitionKey: true,
+  },
+});
+```
+
 ## Examples
 
 ```typescript
@@ -132,4 +183,5 @@ export default [
 - **Query & scan:** [askKeyValueStoreQuery](../../actions/core/key-value-store/ask-key-value-store-query.md) · [askKeyValueStoreScan](../../actions/core/key-value-store/ask-key-value-store-scan.md)
 - **Write:** [askKeyValueStoreUpsert](../../actions/core/key-value-store/ask-key-value-store-upsert.md) · [askKeyValueStoreUpdate](../../actions/core/key-value-store/ask-key-value-store-update.md) · [askKeyValueStoreDelete](../../actions/core/key-value-store/ask-key-value-store-delete.md)
 - **AWS tuning:** [defineAwsKmsKey](../config-aws/aws-kms-key.md) (customer-managed encryption key for the `encryption` flag), [defineAwsDyanmoOverrideForKvs](../config-aws/aws-dyanmo-override-for-kvs.md) (back the store with a pre-existing DynamoDB table), and [defineAwsDataStoreRemovalPolicy](../config-aws/aws-data-store-removal-policy.md) (retain vs destroy the table on teardown).
-- **AWS implementation:** `QpqCoreKeyValueStoreConstruct` (DynamoDB table, LSIs, GSIs, TTL, PITR, KMS, IAM grants) in `quidproquo-deploy-awscdk`; KVS action processors in `quidproquo-actionprocessor-awslambda`.
+- [defineEventDocSummary](../features/event-doc-summary.md) — a real `onStream` consumer: rebuilds a document's summary record from its event log on every change.
+- **AWS implementation:** `QpqCoreKeyValueStoreConstruct` (DynamoDB table, LSIs, GSIs, TTL, PITR, KMS, IAM grants) and `QpqApiCoreKeyValueStoreStreamConstruct` (the `onStream` handler lambda + event source) in `quidproquo-deploy-awscdk`; KVS action processors in `quidproquo-actionprocessor-awslambda`.

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

@@ -52,7 +52,7 @@ Each key is matched against a delivered message's `type` field. The key may be a
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
 | `batchSize` | `number` | `0` | Max number of messages delivered to the consumer Lambda per invocation. `0` leaves the SQS default. When set (> 0), the event source uses this batch size. |
-| `batchWindowInSeconds` | `number` | `5` | Max time SQS waits to fill a batch before invoking the consumer. Only applied when `batchSize > 0`, and **not** applied to FIFO queues (which don't support a batching window). |
+| `batchWindowInSeconds` | `number` | `0` | Max time SQS waits to fill a batch before invoking the consumer — invoke as soon as a message arrives. Only applied when `batchSize > 0`, and **not** applied to FIFO queues (which don't support a batching window). A queue that wants to accumulate a batch before invoking should set this explicitly. |
 | `concurrency` | `number` | `1` | Consumer concurrency hint. |
 | `maxTries` | `number` | `1` | How many times a message is delivered before it is sent to the dead-letter queue (SQS `maxReceiveCount`). |
 | `ttRetryInSeconds` | `number` | `900` | Retry/visibility timeout in seconds — how long a message stays invisible while being processed before it can be redelivered. Also used as the consumer Lambda timeout. Capped at 900 (15 minutes). |

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

@@ -31,7 +31,7 @@ All paths are prefixed with the version segment `/v{version}` (default `/v1`):
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `{basePath}` | List the collection's documents. |
+| `GET` | `{basePath}` | List one page of the collection's documents (newest first). Accepts `?limit=` and `?nextPageKey=` and returns `QpqPagedData`. |
 | `GET` | `{basePath}/{id}` | Get one document's summary record. |
 | `GET` | `{basePath}/{id}/events` | List a document's event log. |
 | `GET` | `{basePath}/{id}/render` | Render the document to HTML. **Only mounted when `eventRenderer` is set.** |

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

@@ -5,15 +5,16 @@ description: Declare the stores for an event-sourced document collection — its
 
 # defineEventDocSummary
 
-Declares the **stores** that back an event-document collection, without any routes. It returns a `QPQConfig` (an array of config settings) that expands to three underlying core stores:
+Declares the **stores** that back an event-document collection, without any routes. It returns a `QPQConfig` (an array of config settings) that expands to four underlying core stores:
 
-1. A **summary key-value store** (partition key `type`, sort key `id`) — the queryable record for each document, derived by folding the identity/lifecycle events of its log. Rows are the [`EventDocSummary`](../../actions/features/event-doc/ask-event-doc-get-by-id.md) shape and carry the version history. A secondary index on `(type, updatedAt)` supports the recently-updated ordering [askEventDocList](../../actions/features/event-doc/ask-event-doc-list.md) returns.
-2. An **append-only events store** (`<storeName>Events`, partition key `pk`, numeric sort key `sk`) — the ordered log every document is folded from. It has **no** secondary index on purpose: the local dev-server query processor can't target one, so all event reads go through the main table.
-3. A **storage drive** (`<storeName>edocs`, lower-cased) — the collection's blob bucket, holding each document's immutable uploaded assets (and later its derived runtime artifacts) under per-document prefixes.
+1. A **summary key-value store** (partition key `type`, sort key `id`) — the queryable record for each document, derived by folding the identity/lifecycle events of its log. Rows are the [`EventDocSummary`](../../actions/features/event-doc/ask-event-doc-get-by-id.md) shape and carry the version history. A secondary index on `(type, updatedAt)` supports the recently-updated ordering [askEventDocList](../../actions/features/event-doc/ask-event-doc-list.md) returns. It is a pure projection: nothing on the append path writes it directly. The events store below declares an [`onStream`](../core/key-value-store.md#change-data-capture-onstream) handler that rebuilds a document's summary row from its log whenever an event is appended, so the summary is eventually (not immediately) consistent with the log.
+2. An **append-only events store** (`<storeName>EventLog`, partition key `pk`, string sort key `sk`) — the live ordered log every document is folded from, keyed on a sortable event id (UUIDv7). It has **no** secondary index on purpose: the local dev-server query processor can't target one, so all event reads go through the main table.
+3. A **legacy events store** (`<storeName>Events`, partition key `pk`, numeric sort key `sk`) — the pre-sortable-id log, kept declared but unread/unwritten at runtime so its data stays reachable until it is migrated into the events store above.
+4. A **storage drive** (`<storeName>edocs`, lower-cased) — the collection's blob bucket, holding each document's immutable uploaded assets (and later its derived runtime artifacts) under per-document prefixes.
 
-Point-in-time recovery is enabled on both tables.
+Point-in-time recovery is enabled on all three tables.
 
-- **On AWS:** deploys two DynamoDB tables (via [defineKeyValueStore](../core/key-value-store.md)) and one S3 bucket (via [defineStorageDrive](../core/storage-drive.md)). All physical names are derived from `keyValueStoreName`, so a collection needs only that one name.
+- **On AWS:** deploys three DynamoDB tables (via [defineKeyValueStore](../core/key-value-store.md)) and one S3 bucket (via [defineStorageDrive](../core/storage-drive.md)). All physical names are derived from `keyValueStoreName`, so a collection needs only that one name.
 
 ```typescript
 import { defineEventDocSummary } from 'quidproquo-features';

package/template/docusaurus/docs/config/webserver/migration.md

@@ -32,6 +32,10 @@ The generated deploy event fires on each qualifying stack status change:
 - **On the first (Create) deploy** every migration is recorded as *already run* without executing it — a freshly created service is expected to start from clean [seed](./seed.md) data, so there is nothing to migrate.
 - **On later (Update) deploys** each migration whose `deployType` matches the stack that changed and that has **not** already been recorded is enqueued on the `qpqMigrations` queue (which runs its story) and then recorded as run. Migrations already recorded are skipped, so re-deploying is safe.
 
+## Testing locally
+
+Nothing local ever deploys, so a migration never runs on its own while you develop against `go:dev`. Run `qpq migrate` to execute every pending migration against the local dev store, once, through the same queue the deployed path uses. It records what it ran in the same tracking store, so a second call is a no-op until you add a new migration.
+
 ## Signature
 
 ```typescript