create-qpq-app 0.1.11 → 0.1.13

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

@@ -19,6 +19,8 @@ This is the same pattern as [askContextProvideValue](../../core/context/ask-cont
 | `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`). |
+| `scopeResolver` | `string` (optional) | The collection's ambient storage scope resolver inline-function name, if configured (e.g. per-tenant). |
+| `referenceResolver` | `string` (optional) | The collection's reference-collector inline-function name, if configured (powers `GET .../references` and the transfer feature's manifest walk). |
 
 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.
 
@@ -64,6 +66,10 @@ function* askEventDocProvideStore<T>(
 | `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. |
+| `onPublish` | `string` (optional) | Inline-function name invoked after a Publish append. |
+| `onAppend` | `string` (optional) | Inline-function name invoked after every append. |
+| `scopeResolver` | `string` (optional) | Ambient storage scope resolver inline-function name. |
+| `referenceResolver` | `string` (optional) | Reference-collector inline-function name (powers `GET .../references`). |
 
 ### Returns
 

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

@@ -0,0 +1,47 @@
+---
+title: askEventDocReferences
+description: The other docs one document depends on, one hop out, via its collection's referenceResolver.
+---
+
+# askEventDocReferences
+
+Reads the `EventDocLink`s a document depends on, one hop out. Hands the collection's `referenceResolver` inline function (see [defineEventDocRoutes](../../../config/features/event-doc-routes.md#parameters)) the document's whole event log and lets it fold + walk it. A collection with no resolver configured is a leaf: this returns `[]` without reading the log at all.
+
+- **Built from:** [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore) (to read the collection's `referenceResolver` name) and `askEventDocEventListAll` (the full log the resolver folds). Requires the store context — call it inside `askEventDocProvideStore({ storeName, type }, ...)`, or from a built-in route where the context is already provided.
+
+```typescript
+import { askEventDocReferences } from 'quidproquo-features';
+
+export function* readTemplateDependencies(templateId: string) {
+  const links = yield* askEventDocReferences(templateId);
+
+  return links; // EventDocLink[] — e.g. the template's layout, styles, and content
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocReferences(docId: string): AskResponse<EventDocLink[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `docId` | `string` | The document to read outbound references for. |
+
+## Returns
+
+`EventDocLink[]` — the doc's outbound links, one hop out. Empty when the collection has no `referenceResolver` configured.
+
+## Notes
+
+- This is a **one-hop** read. The recursive walk over these edges (following a template into its content, then that content's own references, and so on) is the transfer feature's job — see [askEventDocManifest](../event-doc-transfer/ask-event-doc-manifest.md).
+- `GET {basePath}/{id}/references`, mounted by [defineEventDocRoutes](../../../config/features/event-doc-routes.md), calls this for one document; the route is always mounted, resolving to `[]` when no `referenceResolver` is configured.
+
+## Related
+
+- [defineEventDocRoutes](../../../config/features/event-doc-routes.md) — declares the `referenceResolver` this reads.
+- [askEventDocManifest](../event-doc-transfer/ask-event-doc-manifest.md) — the recursive walk built on top of this, one collection at a time.
+- [askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md) — read the document's own summary alongside its references.

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/actions/features/event-doc-transfer/_category_.json

@@ -0,0 +1 @@
+{ "label": "Event Doc Transfer", "link": { "type": "generated-index", "description": "Stories behind the export/import bundle feature — walk a doc's references into a manifest, stage a bundle, and plan/apply an import against the target's own collections." } }

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

@@ -0,0 +1,67 @@
+---
+title: askEventDocBundleApply
+description: Import every doc in a staged bundle, in leaves-first order, and report what happened per doc.
+---
+
+# askEventDocBundleApply
+
+Imports every doc in a staged bundle, in bundle order (leaves-first, the order [askEventDocTransferExport](./ask-event-doc-transfer-export.md) wrote it in), and reports what happened per doc in the same row shape [askEventDocBundlePlan](./ask-event-doc-bundle-plan.md) returns.
+
+Docs are imported independently: a blocking row (`diverged`, `codeConflict`) is reported and the rest of the bundle still lands. That is deliberate — the alternative, aborting the whole bundle, would mean one hand-edited doc in the target blocks every unrelated doc's promotion. Every write is conditional (on `(docId, index)`, or on an absent asset guid), so re-running after fixing the blocker is safe.
+
+- **Built from:** `askEventDocTransferProvideCollection` (runs each doc's import against its own collection's store) then `askEventDocBundleApplyDoc` (the per-doc write). Requires an `EventDocTransferRegistry` and a parsed `EventDocBundle` — the built-in `POST /transfer/import` route resolves both from `{ transferId }`, plus the importing user id, before calling this.
+
+```typescript
+import { askEventDocBundleApply, askEventDocTransferReadBundle, askEventDocTransferReadRegistry } from 'quidproquo-features';
+
+export function* applyImport(transferId: string, importerUserId: string, force = false) {
+  const registry = yield* askEventDocTransferReadRegistry();
+  const bundle = yield* askEventDocTransferReadBundle(transferId);
+
+  const rows = yield* askEventDocBundleApply(registry, bundle, { transferId, importerUserId, force });
+
+  return rows; // EventDocTransferPlanRow[] — same shape as a plan, now with eventsWritten/assetsWritten filled in
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocBundleApply(
+  registry: EventDocTransferRegistry,
+  bundle: EventDocBundle,
+  options: EventDocBundleApplyOptions,
+): AskResponse<EventDocTransferPlanRow[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `registry` | `EventDocTransferRegistry` | `{ service, collections }` — which collections the target may import into, as registered by [defineEventDocTransfer](../../../config/features/event-doc-transfer.md). |
+| `bundle` | `EventDocBundle` | The staged bundle to apply, read with `askEventDocTransferReadBundle`. |
+| `options` | `EventDocBundleApplyOptions` | See below. |
+
+### `EventDocBundleApplyOptions`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `transferId` | `string` | Which staged bundle this is, so a discarded (overwritten) tail is parked next to it. |
+| `importerUserId` | `string` | The user id every imported event is attributed to. The source system's user id is deliberately **not** carried over — it resolves to nobody in the target directory — though the author's `userDisplayName` is kept, so history still reads as the person who wrote it. |
+| `force` | `boolean` (optional) | Discard the target's divergent tail and take the bundle's version instead. Off by default and never implicit — it deletes events the target owns and rewrites published version history. Applies only to `diverged` rows; a `codeConflict` is a different problem overwriting cannot fix. |
+
+## Returns
+
+`EventDocTransferPlanRow[]` — one row per doc, in bundle order, same shape as [askEventDocBundlePlan](./ask-event-doc-bundle-plan.md#returns) but with `eventsWritten`/`assetsWritten`/`discardedEvents` now reflecting what was actually written.
+
+## Errors
+
+| Condition | Error |
+| --- | --- |
+| `bundle.formatVersion` doesn't match this deployment's `EVENT_DOC_TRANSFER_BUNDLE_FORMAT_VERSION` | `ErrorTypeEnum.BadRequest` |
+
+## Related
+
+- [askEventDocBundlePlan](./ask-event-doc-bundle-plan.md) — the read-only preview of what this would do.
+- [askEventDocTransferExport](./ask-event-doc-transfer-export.md) — produces the bundle this applies.
+- [defineEventDocTransfer](../../../config/features/event-doc-transfer.md) — mounts `POST /transfer/import`, the HTTP entry point for this story.

package/template/docusaurus/docs/actions/features/event-doc-transfer/ask-event-doc-bundle-plan.md

@@ -0,0 +1,67 @@
+---
+title: askEventDocBundlePlan
+description: What importing an uploaded bundle would do to each of its docs, without writing anything.
+---
+
+# askEventDocBundlePlan
+
+Computes what importing a bundle would do to **each** of its docs, writing nothing. This is the review gate: a UI shows these rows and the operator confirms before anything actually lands. Rows come back in bundle order (leaves-first, the same order [askEventDocBundleApply](./ask-event-doc-bundle-apply.md) applies them in), so the plan and the apply result read the same way.
+
+Each doc is compared against the target's own log for the same id (see `findEventDocLogDivergence`) to decide its `EventDocTransferStatus`: a fresh `new` doc, a `fastForward` (the target's log is a strict prefix of the incoming one), an already-`same` no-op, or a blocking `diverged`/`codeConflict` row that nothing is written for unless the caller forces it.
+
+- **Built from:** `askEventDocTransferProvideCollection` (runs each doc's comparison against its own collection's store) then `askEventDocBundlePlanDoc` (the per-doc comparison). Requires an `EventDocTransferRegistry` and a parsed `EventDocBundle` — the built-in `POST /transfer/plan` route resolves both from `{ transferId }` before calling this.
+
+```typescript
+import { askEventDocBundlePlan, askEventDocTransferReadBundle, askEventDocTransferReadRegistry } from 'quidproquo-features';
+
+export function* reviewImport(transferId: string) {
+  const registry = yield* askEventDocTransferReadRegistry();
+  const bundle = yield* askEventDocTransferReadBundle(transferId);
+
+  const rows = yield* askEventDocBundlePlan(registry, bundle);
+
+  return rows; // EventDocTransferPlanRow[]
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocBundlePlan(
+  registry: EventDocTransferRegistry,
+  bundle: EventDocBundle,
+): AskResponse<EventDocTransferPlanRow[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `registry` | `EventDocTransferRegistry` | `{ service, collections }` — which collections the target may import into, as registered by [defineEventDocTransfer](../../../config/features/event-doc-transfer.md). |
+| `bundle` | `EventDocBundle` | The staged bundle to evaluate (`{ formatVersion, source, docs }`), read with `askEventDocTransferReadBundle`. |
+
+## Returns
+
+`EventDocTransferPlanRow[]` — one row per doc in the bundle, in bundle order:
+
+```typescript
+type EventDocTransferPlanRow = EventDocDocRef & {
+  code: string;
+  name: string;
+  status: EventDocTransferStatus; // 'new' | 'fastForward' | 'same' | 'diverged' | 'codeConflict' | 'overwritten' | 'ignored'
+  incomingEvents: number;
+  existingEvents: number;
+  eventsWritten: number; // always 0 on a plan
+  assetsWritten: number; // always 0 on a plan
+  discardedEvents: number; // always 0 on a plan
+  detail?: string; // why a blocking status blocks
+};
+```
+
+`overwritten` never appears on a plan — it is report-only, produced by a forced [askEventDocBundleApply](./ask-event-doc-bundle-apply.md).
+
+## Related
+
+- [askEventDocBundleApply](./ask-event-doc-bundle-apply.md) — applies the same comparison and actually writes.
+- [askEventDocTransferExport](./ask-event-doc-transfer-export.md) — produces the bundle a plan evaluates.
+- [defineEventDocTransfer](../../../config/features/event-doc-transfer.md) — mounts `POST /transfer/plan`, the HTTP entry point for this story.

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

@@ -0,0 +1,64 @@
+---
+title: askEventDocManifest
+description: Walk one or more docs' references outward to find everything that has to travel with them.
+---
+
+# askEventDocManifest
+
+Finds every doc that has to travel with a list of starting docs, by following each doc's `referenceResolver` links outward — breadth-first, across collections, with a visited set so a stylesheet three templates share is walked once and lands in the result once. Also the source of a cycle's termination: a link cycle (template → content → template) stops on the visited check instead of recursing forever.
+
+Takes a **list** of roots so selecting several documents produces one merged manifest, rather than one per selection. A soft-deleted doc is reported (`deleted: true`) but not walked into — it will never be bundled, so its own dependencies are moot.
+
+- **Built from:** [askEventDocReferences](../event-doc/ask-event-doc-references.md) (per doc, to find its outbound links) and [askEventDocTransferProvideCollection](#askeventdoctransferprovidecollection) (to run each visit against the right collection's store). Requires an `EventDocTransferRegistry` — read one with `askEventDocTransferReadRegistry`, or call from a built-in transfer route where it's already resolved.
+
+```typescript
+import { askEventDocManifest, askEventDocTransferReadRegistry } from 'quidproquo-features';
+
+export function* previewExport(docs: EventDocDocRef[]) {
+  const registry = yield* askEventDocTransferReadRegistry();
+
+  const items = yield* askEventDocManifest(registry, docs);
+
+  return items; // EventDocManifestItem[] — every doc that would travel, roots first
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocManifest(
+  registry: EventDocTransferRegistry,
+  starts: EventDocDocRef[],
+): AskResponse<EventDocManifestItem[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `registry` | `EventDocTransferRegistry` | `{ service, collections }` — which collections a transfer may read, as registered by [defineEventDocTransfer](../../../config/features/event-doc-transfer.md). |
+| `starts` | `EventDocDocRef[]` | The selected root docs (`{ service, type, id }`), depth `0` in the result. |
+
+## Returns
+
+`EventDocManifestItem[]` — every doc discovered, in discovery order (roots first, then whatever they reference, breadth-first):
+
+```typescript
+type EventDocManifestItem = EventDocDocRef & {
+  code: string;
+  name: string;
+  depth: number; // 0 for a start doc, shortest link distance otherwise
+  deleted: boolean; // reported but never bundled
+};
+```
+
+## Notes
+
+- An unregistered or cross-service reference throws `ErrorTypeEnum.BadRequest` rather than being silently skipped — an incomplete manifest can never masquerade as a complete export.
+- Reversing the result is leaves-first, the order [askEventDocTransferExport](./ask-event-doc-transfer-export.md) writes a bundle in and an import applies it in.
+
+## Related
+
+- [askEventDocTransferExport](./ask-event-doc-transfer-export.md) — builds and stages a bundle from the same manifest walk.
+- [defineEventDocTransfer](../../../config/features/event-doc-transfer.md) — mounts `POST /transfer/manifest`, the HTTP entry point for this story.
+- [askEventDocReferences](../event-doc/ask-event-doc-references.md) — the per-doc reference read this walks.

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

@@ -0,0 +1,67 @@
+---
+title: askEventDocTransferExport
+description: Export one or more docs and everything they reference as one staged bundle, and hand back a download link.
+---
+
+# askEventDocTransferExport
+
+Exports one or more docs — and everything they reference — as **one** staged bundle, and returns a short-lived download link plus the manifest it covers (so a UI can show exactly what went in, including any soft-deleted docs that were reported but skipped). Selecting several docs at once produces one bundle: their manifests are merged and deduped, so a stylesheet three templates share travels once, not three times.
+
+The manifest comes back in discovery order (the starting docs first); the bundle itself is written in **reverse**, which is leaves-first, so on import whatever a doc references always lands before the doc that points at it.
+
+- **Built from:** [askEventDocManifest](./ask-event-doc-manifest.md) (the reference walk) then `askEventDocBundleBuild` (reads each doc's full log + assets into the bundle). Requires an `EventDocTransferRegistry` — read one with `askEventDocTransferReadRegistry`, or call from the built-in `POST /transfer/export` route where it's already resolved.
+
+```typescript
+import { askEventDocTransferExport, askEventDocTransferReadRegistry } from 'quidproquo-features';
+
+export function* exportSelection(docs: EventDocDocRef[]) {
+  const registry = yield* askEventDocTransferReadRegistry();
+
+  const result = yield* askEventDocTransferExport(registry, docs);
+
+  return result; // { downloadUrl, filename, items }
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocTransferExport(
+  registry: EventDocTransferRegistry,
+  starts: EventDocDocRef[],
+): AskResponse<EventDocTransferExportResult>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `registry` | `EventDocTransferRegistry` | `{ service, collections }` — which collections a transfer may read, as registered by [defineEventDocTransfer](../../../config/features/event-doc-transfer.md). |
+| `starts` | `EventDocDocRef[]` | The docs the caller selected to export (`{ service, type, id }`). |
+
+## Returns
+
+`EventDocTransferExportResult`:
+
+```typescript
+type EventDocTransferExportResult = {
+  downloadUrl: string; // short-lived, 15 minutes
+  filename: string;
+  items: EventDocManifestItem[]; // the full manifest, roots first
+};
+```
+
+## Errors
+
+| Condition | Error |
+| --- | --- |
+| `starts` is empty | `ErrorTypeEnum.BadRequest` ("Nothing selected to export.") |
+| A root doc (not just one of its dependencies) is soft-deleted | `ErrorTypeEnum.BadRequest` ("Doc `{id}` is deleted and cannot be exported.") |
+
+A dependency that is deleted at source is reported in the manifest and silently skipped from the bundle; a doc the operator explicitly picked being deleted is treated as a mistake worth stopping on instead.
+
+## Related
+
+- [askEventDocManifest](./ask-event-doc-manifest.md) — the reference walk this builds on.
+- [askEventDocBundlePlan](./ask-event-doc-bundle-plan.md) / [askEventDocBundleApply](./ask-event-doc-bundle-apply.md) — the other end: review and apply a bundle produced by this story.
+- [defineEventDocTransfer](../../../config/features/event-doc-transfer.md) — mounts `POST /transfer/export`, the HTTP entry point for this story.

package/template/docusaurus/docs/actions/xstate/ask-state-machine-send-event.md

@@ -8,7 +8,7 @@ description: Send an event to a state-machine instance to drive a transition, ru
 Sends an event to a [state-machine](../../config/xstate/state-machine.md) instance, driving a transition. The runtime rehydrates the instance, evaluates its guards, applies the event, runs any side-effect actions, and persists the new state. This is how a durable workflow moves forward over time.
 
 - **Action type:** `StateMachineActionType.SendEvent`
-- **On the runtime:** the processor loads the instance from the backing key-value store, runs **every** configured guard story with `(entity, event)` to resolve each guard to a boolean, rehydrates the XState actor from the persisted snapshot, sends the event, and captures the new snapshot. If the event did not change state (and the machine is not done), it fails; otherwise it persists the new snapshot and runs the stories mapped to any actions that fired during the transition, passing `(entity, event)`.
+- **On the runtime:** the processor loads the instance from the backing key-value store, runs **every** configured guard story with `(entity, event)` to resolve each guard to a boolean, and rehydrates the XState actor from the persisted snapshot. It then asks XState whether the current state can take the event (with the resolved guard outcomes); if not, it fails with `BadRequest`. Otherwise it sends the event, persists the new snapshot, and runs the stories mapped to any actions that fired during the transition, passing `(entity, event)`.
 
 ```typescript
 import { askStateMachineSendEvent } from 'quidproquo-xstate';
@@ -44,10 +44,10 @@ function* askStateMachineSendEvent<T>(
 ### `StateMachineEvent`
 
 ```typescript
-interface StateMachineEvent {
-  type: string;       // the XState event name (e.g. 'PAY', 'CANCEL')
-  [key: string]: any; // optional payload available to guards and actions
-}
+type StateMachineEvent = {
+  type: string;           // the XState event name (e.g. 'PAY', 'CANCEL')
+  [key: string]: unknown; // optional payload available to guards and actions
+};
 ```
 
 ## Returns
@@ -58,7 +58,7 @@ interface StateMachineEvent {
 
 - **Guards run first, and all of them.** Before the event is applied, every guard story configured on the machine is executed with `(entity, event)` and reduced to a boolean, then fed to XState. Keep guard stories side-effect-light.
 - **Actions run after the transition is persisted.** Each XState action that fires during the transition runs its mapped story with `(entity, event)`; a story error aborts the action with that error.
-- **Invalid events fail.** If the event produces no state change and the machine is not in a final state, the action fails with `ErrorTypeEnum.BadRequest` (`Event '<type>' is not valid for current state '<state>'`).
+- **Invalid events fail.** If the current state cannot take the event (no matching transition, its guard resolved false, or the machine has already reached a final state), the action fails with `ErrorTypeEnum.BadRequest` (`Event '<type>' is not valid for current state '<state>'`). Self and internal transitions that keep the same state value are valid and run their actions as normal.
 - Fails with `ErrorTypeEnum.NotFound` if the machine name is unknown or the instance does not exist. Guard/action story errors and the persistence upsert error propagate with their own error types. Use [askCatch](../core/system/ask-catch.md) to handle these in-story.
 
 ## Related

package/template/docusaurus/docs/config/core/crypto-key.md

@@ -0,0 +1,53 @@
+---
+title: defineCryptoKey
+description: Define a crypto key, an application-level encryption key for askCryptoEncrypt / askCryptoDecrypt (a KMS CMK on AWS).
+---
+
+# defineCryptoKey
+
+Declares a **crypto key**: a named encryption key stories use through [askCryptoEncrypt](../../actions/core/crypto/ask-crypto-encrypt.md) and [askCryptoDecrypt](../../actions/core/crypto/ask-crypto-decrypt.md). The key material never leaves the provider; your code only ever sees opaque ciphertext blobs.
+
+- **On AWS:** provisions a KMS customer managed key with automatic rotation enabled, addressed by a deterministic alias derived from application/module/environment, and grants the service's role use of it (`kms:GenerateDataKey*`, `kms:Decrypt`, `kms:Encrypt`, `kms:DescribeKey`). Rotation needs nothing from the app: old key material stays available for decrypt.
+- **On the dev server:** a local master key is seeded on first use at `.qpq-runtime/<app>/cryptoKeys/<service>.json`, so everything works offline with no AWS credentials.
+
+One application-level key is usually enough. Separation between callers comes from the `context` on each encrypt (see [askCryptoEncrypt](../../actions/core/crypto/ask-crypto-encrypt.md)), not from separate keys.
+
+```typescript
+import { defineCryptoKey } from 'quidproquo-core';
+
+export default [
+  defineCryptoKey('app-crypto-key'),
+];
+```
+
+## Signature
+
+```typescript
+function defineCryptoKey(
+  keyName: string,
+  options?: QPQConfigAdvancedCryptoKeySettings,
+): CryptoKeyQPQConfigSetting;
+```
+
+## Parameters
+
+### `keyName`: `string` (required)
+
+The name of the key, and its `uniqueKey` within the config. This is the name you pass to the crypto actions.
+
+### `options`: `QPQConfigAdvancedCryptoKeySettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `owner` | `CrossModuleOwner<'cryptoKeyName'>` | – | Declares that the key is owned by **another** module/service, so this service is granted use of it rather than creating its own. `{ module, application, feature, environment, cryptoKeyName }`, all optional; unset parts default to the current service. |
+
+## Notes
+
+- Ciphertext blobs are versioned (`qpqcrypto:v1:...`), so the underlying mechanism can evolve without re-encrypting stored data.
+- Dev ciphertext is not readable in prod and vice versa; each environment's key is its own.
+
+## Related
+
+- [askCryptoEncrypt](../../actions/core/crypto/ask-crypto-encrypt.md): encrypts with this key.
+- [askCryptoDecrypt](../../actions/core/crypto/ask-crypto-decrypt.md): decrypts with this key.
+- [defineSecret](./secret.md): for platform-level secret values set out-of-band, rather than values your app encrypts itself.

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`.