create-qpq-app 0.1.11 → 0.1.13

package/lib/esm/types/StepContext.d.ts

@@ -0,0 +1,7 @@
+import { CreateQpqAppAnswers } from './CreateQpqAppAnswers';
+export type StepContext = {
+    targetDirectory: string;
+    templateDirectory: string;
+    ownVersion: string;
+    answers: CreateQpqAppAnswers;
+};

package/lib/esm/types/StepContext.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=StepContext.js.map

package/lib/esm/types/StepContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StepContext.js","sourceRoot":"","sources":["../../../src/types/StepContext.ts"],"names":[],"mappings":"","sourcesContent":["import { CreateQpqAppAnswers } from './CreateQpqAppAnswers';\n\nexport type StepContext = {\n  // Absolute path of the directory being scaffolded (<cwd>/<appName>).\n  targetDirectory: string;\n  // Absolute path of the bundled template snapshot (a pruned quidproquojs.com).\n  templateDirectory: string;\n  // create-qpq-app's own version. The generated app pins its quidproquo-*\n  // dependencies to this (the packages are published in lockstep).\n  ownVersion: string;\n  answers: CreateQpqAppAnswers;\n};\n"]}

package/lib/esm/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './AppLanguage';
+export * from './CreateQpqAppAnswers';
+export * from './CreateQpqAppStep';
+export * from './StepContext';

package/lib/esm/types/index.js

@@ -0,0 +1,5 @@
+export * from './AppLanguage';
+export * from './CreateQpqAppAnswers';
+export * from './CreateQpqAppStep';
+export * from './StepContext';
+//# sourceMappingURL=index.js.map

package/lib/esm/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC","sourcesContent":["export * from './AppLanguage';\nexport * from './CreateQpqAppAnswers';\nexport * from './CreateQpqAppStep';\nexport * from './StepContext';\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.11",
-  "description": "Scaffold a new quidproquo app — npx create-qpq-app my-app",
+  "version": "0.1.13",
+  "description": "Scaffold a new quidproquo app: npx create-qpq-app my-app",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
   "types": "./lib/commonjs/index.d.ts",
@@ -14,7 +14,8 @@
     "template"
   ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "clean": "npx rimraf lib && npx rimraf template && npx rimraf node_modules",
     "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run build:bin-perms",
     "watch": "tsc -p tsconfig.commonjs.json -w",
@@ -51,7 +52,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.13",
-    "quidproquo-tsconfig": "0.1.11"
+    "quidproquo-tsconfig": "0.1.13"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

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

@@ -0,0 +1,7 @@
+{
+  "label": "Crypto",
+  "link": {
+    "type": "generated-index",
+    "description": "Crypto actions encrypt and decrypt values with a key declared by defineCryptoKey. Envelope encryption with an optional context that binds ciphertext to the place it was created."
+  }
+}

package/template/docusaurus/docs/actions/core/crypto/ask-crypto-decrypt.md

@@ -0,0 +1,61 @@
+---
+title: askCryptoDecrypt
+description: Decrypt a ciphertext produced by askCryptoEncrypt, verifying its context.
+---
+
+# askCryptoDecrypt
+
+Decrypts a blob produced by [askCryptoEncrypt](./ask-crypto-encrypt.md) and returns the original string. The `context` supplied here must match the one supplied at encrypt time exactly, or the call fails before any plaintext is produced.
+
+- **Action type:** `CryptoActionType.Decrypt`
+- **On AWS:** unwraps the embedded data key with AWS KMS (`kms:Decrypt`, with the context as KMS encryption context, which also gives a per-context audit trail in CloudTrail) and decrypts locally with AES-256-GCM.
+- **On the dev server:** identical code path against the local master key, including identical context enforcement. A context scoping bug fails the same way locally as in prod.
+
+```typescript
+import { askCryptoDecrypt, askKeyValueStoreGet } from 'quidproquo-core';
+
+export function* askReadCustomerApiKey(customerId: string) {
+  const record = yield* askKeyValueStoreGet('customer-credentials', customerId);
+
+  return yield* askCryptoDecrypt('app-crypto-key', record.apiKey, { customerId });
+}
+```
+
+## Signature
+
+```typescript
+function* askCryptoDecrypt(
+  keyName: string,
+  ciphertext: string,
+  context?: CryptoContext,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyName` | `string` | Name of the crypto key, declared with [defineCryptoKey](../../../config/core/crypto-key.md) (or shared via its `owner` option). |
+| `ciphertext` | `string` | A blob previously returned by [askCryptoEncrypt](./ask-crypto-encrypt.md). |
+| `context` | `CryptoContext` | The same `Record<string, string>` supplied at encrypt time. Omitting it and passing `{}` are equivalent. |
+
+## Returns
+
+`string`: the original plaintext.
+
+## Errors
+
+Each failure mode is distinguishable because they need different handling:
+
+| Error | Meaning |
+| --- | --- |
+| `CryptoDecryptErrorTypeEnum.ContextMismatch` | The supplied context differs from the encrypt-time context. Probable scoping bug in the caller; alert, do not retry. |
+| `CryptoDecryptErrorTypeEnum.MalformedCiphertext` | The blob is corrupt, truncated, or not a qpq crypto blob. Data problem; the stored value needs re-creating. |
+| `CryptoDecryptErrorTypeEnum.KeyNotConfigured` | No `defineCryptoKey` with that name exists in the service config. |
+| `CryptoDecryptErrorTypeEnum.KeyUnavailable` | The key is disabled, deleted, or access was denied. Infrastructure problem; surface to ops. |
+| `CryptoDecryptErrorTypeEnum.Throttling` | The provider rate limit was exceeded; back off and retry. |
+
+## Related
+
+- [askCryptoEncrypt](./ask-crypto-encrypt.md): produces the ciphertext, and documents how `context` works.
+- [defineCryptoKey](../../../config/core/crypto-key.md): declares the key this action uses.

package/template/docusaurus/docs/actions/core/crypto/ask-crypto-encrypt.md

@@ -0,0 +1,66 @@
+---
+title: askCryptoEncrypt
+description: Encrypt a value with a configured crypto key, optionally bound to a context.
+---
+
+# askCryptoEncrypt
+
+Encrypts a string with a [crypto key](../../../config/core/crypto-key.md) and returns an opaque, versioned ciphertext blob. Store the blob anywhere (a key value store, an event doc); only [askCryptoDecrypt](./ask-crypto-decrypt.md) can read it back.
+
+- **Action type:** `CryptoActionType.Encrypt`
+- **On AWS:** envelope encryption backed by AWS KMS. A data key is generated under the CMK (`kms:GenerateDataKey`) and the value is encrypted locally with AES-256-GCM, so there is no practical size limit and most calls never leave the process (data keys are cached briefly). The key itself is provisioned by [defineCryptoKey](../../../config/core/crypto-key.md).
+- **On the dev server:** the same envelope code runs against a local master key seeded at `.qpq-runtime/<app>/cryptoKeys/<service>.json`. No AWS credentials or network needed. Dev ciphertext is not readable in prod (or on another machine), and that is intentional.
+
+```typescript
+import { askCryptoEncrypt, askKeyValueStoreUpdate } from 'quidproquo-core';
+
+export function* askStoreCustomerApiKey(customerId: string, apiKey: string) {
+  const ciphertext = yield* askCryptoEncrypt('app-crypto-key', apiKey, { customerId });
+
+  yield* askKeyValueStoreUpdate('customer-credentials', { customerId, apiKey: ciphertext });
+}
+```
+
+## Context
+
+`context` is an optional `Record<string, string>` mixed into the encryption as additional authenticated data. The crypto layer treats it as opaque: it does not know or care what the keys mean. Supplying it buys two things:
+
+- **Binding.** The ciphertext is only valid under the same context. A blob encrypted with `{ customerId: 'a' }` cannot be decrypted with `{ customerId: 'b' }`, so copying it to another row makes it undecryptable rather than readable.
+- **Non-forgeability.** The association lives inside the authentication tag, not in an editable field beside the ciphertext. Forging it would require the key.
+
+Context values are **not encrypted and not secret**. On AWS they are sent to KMS as encryption context and appear in CloudTrail in the clear, so never put sensitive values in them. Omitting `context` and passing `{}` are equivalent.
+
+## Signature
+
+```typescript
+function* askCryptoEncrypt(
+  keyName: string,
+  plaintext: string,
+  context?: CryptoContext,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyName` | `string` | Name of the crypto key, declared with [defineCryptoKey](../../../config/core/crypto-key.md) (or shared via its `owner` option). |
+| `plaintext` | `string` | The value to encrypt. |
+| `context` | `CryptoContext` | Optional `Record<string, string>` bound into the ciphertext; the same values must be supplied at decrypt. |
+
+## Returns
+
+`string`: an opaque, versioned ciphertext blob (`qpqcrypto:v1:...`). Treat it as a black box; its internal format can change between versions without a migration.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `CryptoEncryptErrorTypeEnum.KeyNotConfigured` | No `defineCryptoKey` with that name exists in the service config. |
+| `CryptoEncryptErrorTypeEnum.KeyUnavailable` | The key exists in config but is disabled, deleted, or access was denied. Infrastructure problem; surface to ops. |
+| `CryptoEncryptErrorTypeEnum.Throttling` | The provider rate limit was exceeded; back off and retry. |
+
+## Related
+
+- [defineCryptoKey](../../../config/core/crypto-key.md): declares the key this action uses.
+- [askCryptoDecrypt](./ask-crypto-decrypt.md): reads the value back.

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/_category_.json

@@ -1 +1 @@
-{ "label": "quidproquo-features", "position": 4, "link": { "type": "generated-index", "description": "Action requesters from quidproquo-features — event-document, AI-chat, admin, and validation stories." } }
+{ "label": "quidproquo-features", "position": 4, "link": { "type": "generated-index", "description": "Action requesters from quidproquo-features — event-document, event-document transfer, AI-chat, admin, and validation stories." } }

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,11 @@ 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. |
 
 ### 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
 
@@ -77,11 +77,11 @@ function* askEventDocEventListAll(modelId: string): AskResponse<EventDocEvent[]>
 
 ### 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-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(