create-qpq-app 0.1.19 → 0.1.21

package/template/apps/qpqjs/services/test/service/src/smoke/tests/eventDoc/askAssertSmokeProbeDocState.ts

@@ -0,0 +1,32 @@
+import { AskResponse } from 'quidproquo';
+import { askEventDocDocumentStateLatest } from 'quidproquo-features';
+
+import { SmokeProbeDocState } from '../../eventDoc/smokeProbeDocDefinition';
+import { askSmokeAssert } from '../askSmokeAssert';
+
+// The folded document, read the way the render/references routes read it: snapshot
+// seeded (whatever the stream projector has stored so far) plus the gap, through the
+// collection's REGISTERED fold. Proves the dynamic-functions registration resolves in
+// the deployed runtime and that the fold saw every event: the numbers it holds are
+// exactly `expectedNumbers`, no extras, none missing, none twice.
+export function* askAssertSmokeProbeDocState(
+  docId: string,
+  expectedNumbers: number[]
+): AskResponse<void> {
+  const latest = yield* askEventDocDocumentStateLatest(docId, {
+    consistentRead: true,
+  });
+  const numbers =
+    (latest?.state as SmokeProbeDocState | undefined)?.numbers ?? [];
+
+  const sorted = [...numbers].sort((a, b) => a - b);
+  const expected = [...expectedNumbers].sort((a, b) => a - b);
+  const same =
+    sorted.length === expected.length &&
+    sorted.every((value, index) => value === expected[index]);
+
+  yield* askSmokeAssert(
+    same,
+    `folded state holds ${numbers.length} numbers, expected ${expected.length} (1..${expected.length}); got [${sorted.join(', ')}]`
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/eventDoc/askAwaitSmokeEventDocLog.ts

@@ -0,0 +1,35 @@
+import { askDelay, AskResponse } from 'quidproquo';
+import { askEventDocEventListAll, EventDocEvent } from 'quidproquo-features';
+
+import { askSmokeAssert } from '../askSmokeAssert';
+
+const POLL_ATTEMPTS = 20;
+const POLL_INTERVAL_MS = 2000;
+
+// Poll a probe doc's log until it holds `expectedLength` events (INIT_STATE included),
+// consistently read so a just-landed append is never missed. Fails the test if the
+// writers have not all landed in time - a stuck writer (one that lost the slot race
+// past its retry cap) shows up here as a short log. Assumes the store context.
+export function* askAwaitSmokeEventDocLog(
+  docId: string,
+  expectedLength: number
+): AskResponse<EventDocEvent[]> {
+  let events: EventDocEvent[] = [];
+
+  for (let attempt = 0; attempt < POLL_ATTEMPTS; attempt += 1) {
+    events = yield* askEventDocEventListAll(docId, { consistentRead: true });
+
+    if (events.length >= expectedLength) {
+      break;
+    }
+
+    yield* askDelay(POLL_INTERVAL_MS);
+  }
+
+  yield* askSmokeAssert(
+    events.length === expectedLength,
+    `expected ${expectedLength} events on doc [${docId}], found ${events.length}`
+  );
+
+  return events;
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/eventDoc/askRunEventDocConcurrentAppendTest.ts

@@ -0,0 +1,82 @@
+import { askQueueSendMessages, AskResponse } from 'quidproquo';
+import {
+  askEventDocCreate,
+  askEventDocProvideStore,
+  askEventDocSoftDelete,
+} from 'quidproquo-features';
+
+import {
+  SMOKE_EVENT_DOC_ACTOR,
+  SMOKE_EVENT_DOC_APPEND_MESSAGE_TYPE,
+  SMOKE_EVENT_DOC_APPEND_QUEUE,
+  SMOKE_EVENT_DOC_MARK_EVENT,
+  SMOKE_EVENT_DOC_SCHEMA_VERSION,
+  SMOKE_EVENT_DOC_STORE_OPTIONS,
+} from '../../constants/smokeEventDoc';
+import { SMOKE_PROBE_DOC_WINDOW } from '../../eventDoc/smokeProbeDocDefinition';
+import { SmokeEventDocAppendPayload } from '../../models/SmokeEventDocAppendQueueEvent';
+import { SmokeEventDocMark } from '../../models/SmokeEventDocMark';
+import { askSmokeAssert } from '../askSmokeAssert';
+import { askAssertContiguousEventIds } from './askAssertContiguousEventIds';
+import { askAssertSmokeProbeDocState } from './askAssertSmokeProbeDocState';
+import { askAwaitSmokeEventDocLog } from './askAwaitSmokeEventDocLog';
+
+// One writer per number the document can hold, so the folded window is exactly full.
+const WRITERS = SMOKE_PROBE_DOC_WINDOW;
+
+// N writers, each its own queue invocation, each appending ONE number (1..N) to the
+// same fresh document at the same moment. The conditional-write append loop has to
+// serialise them onto consecutive slots: afterwards the log is INIT_STATE plus one mark
+// per writer, ids 0..N with no hole and no duplicate, and the document folded through
+// the registered definition holds exactly the numbers 1..N.
+function* askRunInStore(runId: string): AskResponse<void> {
+  const doc = yield* askEventDocCreate(
+    `smoke-${runId}`,
+    `smoke-${runId}`,
+    SMOKE_EVENT_DOC_ACTOR
+  );
+
+  const numbers = Array.from({ length: WRITERS }, (_, index) => index + 1);
+
+  const messages = numbers.map((value) => ({
+    type: SMOKE_EVENT_DOC_APPEND_MESSAGE_TYPE,
+    payload: {
+      docId: doc.id,
+      runId,
+      writerId: value,
+      values: [value],
+    } satisfies SmokeEventDocAppendPayload,
+  }));
+
+  yield* askQueueSendMessages(SMOKE_EVENT_DOC_APPEND_QUEUE, ...messages);
+
+  const events = yield* askAwaitSmokeEventDocLog(doc.id, WRITERS + 1);
+
+  yield* askAssertContiguousEventIds(events);
+
+  const marks = events
+    .filter((event) => event.type === SMOKE_EVENT_DOC_MARK_EVENT)
+    .map((event) => event.payload.data as SmokeEventDocMark);
+
+  yield* askSmokeAssert(
+    marks.every((mark) => mark.runId === runId),
+    "a mark from another run is on this run's document"
+  );
+
+  yield* askAssertSmokeProbeDocState(doc.id, numbers);
+
+  yield* askEventDocSoftDelete(
+    doc.id,
+    SMOKE_EVENT_DOC_ACTOR.userId,
+    SMOKE_EVENT_DOC_SCHEMA_VERSION
+  );
+}
+
+export function* askRunEventDocConcurrentAppendTest(
+  runId: string
+): AskResponse<void> {
+  yield* askEventDocProvideStore(
+    SMOKE_EVENT_DOC_STORE_OPTIONS,
+    askRunInStore(runId)
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/eventDoc/askRunEventDocInterleavedBatchAppendTest.ts

@@ -0,0 +1,110 @@
+import { askQueueSendMessages, AskResponse } from 'quidproquo';
+import {
+  askEventDocCreate,
+  askEventDocProvideStore,
+  askEventDocSoftDelete,
+} from 'quidproquo-features';
+
+import {
+  SMOKE_EVENT_DOC_ACTOR,
+  SMOKE_EVENT_DOC_APPEND_MESSAGE_TYPE,
+  SMOKE_EVENT_DOC_APPEND_QUEUE,
+  SMOKE_EVENT_DOC_MARK_EVENT,
+  SMOKE_EVENT_DOC_SCHEMA_VERSION,
+  SMOKE_EVENT_DOC_STORE_OPTIONS,
+} from '../../constants/smokeEventDoc';
+import { SmokeEventDocAppendPayload } from '../../models/SmokeEventDocAppendQueueEvent';
+import { SmokeEventDocMark } from '../../models/SmokeEventDocMark';
+import { askSmokeAssert } from '../askSmokeAssert';
+import { askAssertContiguousEventIds } from './askAssertContiguousEventIds';
+import { askAssertSmokeProbeDocState } from './askAssertSmokeProbeDocState';
+import { askAwaitSmokeEventDocLog } from './askAwaitSmokeEventDocLog';
+
+const BATCH_WRITERS = 4;
+const BATCH_SIZE = 5;
+const SINGLE_WRITERS = 6;
+
+// Batch writers (one transactional write of BATCH_SIZE consecutive slots each) racing
+// single writers on the same fresh document. Every writer lands, the log is contiguous,
+// each batch's events sit in one unbroken run in input order (a batch that lost its
+// slots was re-laid whole above whoever beat it, never split around them), and the
+// document folded through the registered definition holds exactly the numbers sent.
+function* askRunInStore(runId: string): AskResponse<void> {
+  const doc = yield* askEventDocCreate(
+    `smoke-batch-${runId}`,
+    `smoke-batch-${runId}`,
+    SMOKE_EVENT_DOC_ACTOR
+  );
+
+  // Numbers are dealt out in send order: a batch writer takes the next BATCH_SIZE, a
+  // single writer the next one. The two kinds alternate so neither gets a head start.
+  let nextNumber = 1;
+  const takeNumbers = (count: number): number[] =>
+    Array.from({ length: count }, () => nextNumber++);
+
+  const messages = Array.from(
+    { length: BATCH_WRITERS + SINGLE_WRITERS },
+    (_, index) => {
+      const isBatch = index < BATCH_WRITERS * 2 && index % 2 === 0;
+      return {
+        type: SMOKE_EVENT_DOC_APPEND_MESSAGE_TYPE,
+        payload: {
+          docId: doc.id,
+          runId,
+          writerId: index + 1,
+          values: takeNumbers(isBatch ? BATCH_SIZE : 1),
+        } satisfies SmokeEventDocAppendPayload,
+      };
+    }
+  );
+
+  const expectedNumbers = messages.flatMap((message) => message.payload.values);
+
+  yield* askQueueSendMessages(SMOKE_EVENT_DOC_APPEND_QUEUE, ...messages);
+
+  const events = yield* askAwaitSmokeEventDocLog(
+    doc.id,
+    expectedNumbers.length + 1
+  );
+
+  yield* askAssertContiguousEventIds(events);
+
+  const marked = events
+    .filter((event) => event.type === SMOKE_EVENT_DOC_MARK_EVENT)
+    .map((event) => ({
+      eventId: event.payload.metadata.eventId,
+      mark: event.payload.data as SmokeEventDocMark,
+    }));
+
+  for (const message of messages.filter((m) => m.payload.values.length > 1)) {
+    const { writerId, values } = message.payload;
+    const run = marked.filter((entry) => entry.mark.writerId === writerId);
+    const consecutive = run.every(
+      (entry, index) =>
+        entry.mark.value === values[index] &&
+        (index === 0 || entry.eventId === run[index - 1].eventId + 1)
+    );
+
+    yield* askSmokeAssert(
+      run.length === values.length && consecutive,
+      `batch writer ${writerId} did not land as one consecutive run in order: ids [${run.map((entry) => entry.eventId).join(', ')}]`
+    );
+  }
+
+  yield* askAssertSmokeProbeDocState(doc.id, expectedNumbers);
+
+  yield* askEventDocSoftDelete(
+    doc.id,
+    SMOKE_EVENT_DOC_ACTOR.userId,
+    SMOKE_EVENT_DOC_SCHEMA_VERSION
+  );
+}
+
+export function* askRunEventDocInterleavedBatchAppendTest(
+  runId: string
+): AskResponse<void> {
+  yield* askEventDocProvideStore(
+    SMOKE_EVENT_DOC_STORE_OPTIONS,
+    askRunInStore(runId)
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/eventDoc/index.ts

@@ -0,0 +1,5 @@
+export * from './askAssertContiguousEventIds';
+export * from './askAssertSmokeProbeDocState';
+export * from './askAwaitSmokeEventDocLog';
+export * from './askRunEventDocConcurrentAppendTest';
+export * from './askRunEventDocInterleavedBatchAppendTest';

package/template/apps/qpqjs/services/test/service/src/smoke/tests/index.ts

@@ -1,8 +1,10 @@
 export * from './askSmokeAssert';
 export * from './crossService';
 export * from './eventBus';
+export * from './eventDoc';
 export * from './keyValueStore';
 export * from './noop';
+export * from './openApi';
 export * from './parameter';
 export * from './secret';
 export * from './SmokeTestDefinition';

package/template/apps/qpqjs/services/test/service/src/smoke/tests/openApi/askRunEchoRoundTripTest.ts

@@ -0,0 +1,45 @@
+import {
+  askNetworkRequest,
+  askOpenApiGetDocument,
+  AskResponse,
+} from 'quidproquo';
+
+import { EchoRequest, EchoResponse } from '@qpqjs/test-models';
+
+import { askSmokeAssert } from '../askSmokeAssert';
+
+// The public echo route over real HTTP, from the document's own servers entry,
+// so the same test also proves that entry is a reachable base for this
+// environment (the deployed api domain, or the dev server's mount path).
+// The runId is the echoed value, so the response is provably this run's.
+export function* askRunEchoRoundTripTest(runId: string): AskResponse<void> {
+  const document = yield* askOpenApiGetDocument();
+  const baseUrl = document.servers[0]?.url;
+  yield* askSmokeAssert(!!baseUrl, 'document lists no servers to call');
+
+  const valid: EchoRequest = { bodyValue: runId };
+  const ok = yield* askNetworkRequest<EchoRequest, EchoResponse>(
+    'POST',
+    `${baseUrl}/v1/echo/${runId}`,
+    { body: valid }
+  );
+  yield* askSmokeAssert(
+    ok.status === 200,
+    `echo returned [${ok.status}] for a valid body`
+  );
+  yield* askSmokeAssert(
+    ok.data.pathValue === runId && ok.data.bodyValue === runId,
+    `echo returned [${JSON.stringify(ok.data)}], expected both values to be [${runId}]`
+  );
+
+  // An empty bodyValue fails the min(1) on the schema; the route must 422, not 200
+  const invalid = yield* askNetworkRequest<EchoRequest, unknown>(
+    'POST',
+    `${baseUrl}/v1/echo/${runId}`,
+    { body: { bodyValue: '' } }
+  );
+  yield* askSmokeAssert(
+    invalid.status === 422,
+    `echo returned [${invalid.status}] for an invalid body, expected 422`
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/openApi/askRunOpenApiDocumentTest.ts

@@ -0,0 +1,42 @@
+import { askOpenApiGetDocument, AskResponse } from 'quidproquo';
+
+import { askSmokeAssert } from '../askSmokeAssert';
+
+// The generated document, built in-process from the deployed config. Proves the
+// openApi processor is registered on this runtime and that the route schemas
+// survived the trip from config into the bundle. No network involved.
+export function* askRunOpenApiDocumentTest(): AskResponse<void> {
+  const document = yield* askOpenApiGetDocument();
+
+  const echo = document.paths['/v1/echo/{pathValue}']?.post;
+  yield* askSmokeAssert(!!echo, 'echo route is missing from the document');
+  yield* askSmokeAssert(
+    !!echo?.requestBody?.content['application/json'].schema.properties,
+    'echo route has no request body schema'
+  );
+  yield* askSmokeAssert(
+    echo?.parameters?.some((p) => p.in === 'path' && p.name === 'pathValue') ===
+      true,
+    'echo route has no pathValue path parameter'
+  );
+  yield* askSmokeAssert(
+    !!echo?.responses['422'],
+    'echo route does not document its 422'
+  );
+
+  const smokeRun = document.paths['/smoke/run/{runId}']?.get;
+  yield* askSmokeAssert(
+    !!smokeRun?.responses['200'].content?.['application/json'].schema,
+    'smoke run route has no response schema'
+  );
+
+  yield* askSmokeAssert(
+    !document.paths['/v1/docs'] && !document.paths['/v1/docs/openapi.json'],
+    'docs routes should be hidden from the document'
+  );
+
+  yield* askSmokeAssert(
+    document.servers.length > 0,
+    'document lists no servers'
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/openApi/index.ts

@@ -0,0 +1,2 @@
+export * from './askRunEchoRoundTripTest';
+export * from './askRunOpenApiDocumentTest';

package/template/apps/qpqjs/services/test/service/src/smoke/tests/smokeTestRegistry.ts

@@ -1,16 +1,22 @@
 import { askRunCrossServiceKeyValueStoreTest } from './crossService/askRunCrossServiceKeyValueStoreTest';
 import { askRunCrossServiceStorageDriveTest } from './crossService/askRunCrossServiceStorageDriveTest';
 import { askRunEventBusTest } from './eventBus/askRunEventBusTest';
+import { askRunEventDocConcurrentAppendTest } from './eventDoc/askRunEventDocConcurrentAppendTest';
+import { askRunEventDocInterleavedBatchAppendTest } from './eventDoc/askRunEventDocInterleavedBatchAppendTest';
 import { askRunKeyValueStoreTest } from './keyValueStore/askRunKeyValueStoreTest';
 import { askRunNoopTest } from './noop/askRunNoopTest';
+import { askRunEchoRoundTripTest } from './openApi/askRunEchoRoundTripTest';
+import { askRunOpenApiDocumentTest } from './openApi/askRunOpenApiDocumentTest';
 import { askRunParameterTest } from './parameter/askRunParameterTest';
 import { askRunScheduleTest } from './schedule/askRunScheduleTest';
 import { askRunSecretTest } from './secret/askRunSecretTest';
 import { askRunStorageDriveTest } from './storageDrive/askRunStorageDriveTest';
 import { SmokeTestDefinition } from './SmokeTestDefinition';
 
-// Every smoke test a run executes, in order. A test's id in the run record is
-// its 1-based position here, so append rather than reorder where possible.
+// Every smoke test a run executes. They run in parallel, one queue message
+// each, so nothing here may depend on another test having finished. A test's
+// id in the run record is its 1-based position here, so append rather than
+// reorder where possible; `name` is the key the queue message carries.
 // Adding a test: one folder with its askRun<Name>Test story, one line here.
 export const smokeTestRegistry: SmokeTestDefinition[] = [
   { name: 'noop', askRun: askRunNoopTest },
@@ -28,4 +34,14 @@ export const smokeTestRegistry: SmokeTestDefinition[] = [
     askRun: askRunCrossServiceStorageDriveTest,
   },
   { name: 'schedule', askRun: askRunScheduleTest },
+  { name: 'openApiDocument', askRun: askRunOpenApiDocumentTest },
+  { name: 'echoRoundTrip', askRun: askRunEchoRoundTripTest },
+  {
+    name: 'eventDocConcurrentAppend',
+    askRun: askRunEventDocConcurrentAppendTest,
+  },
+  {
+    name: 'eventDocInterleavedBatchAppend',
+    askRun: askRunEventDocInterleavedBatchAppendTest,
+  },
 ];

package/template/apps/todo/deploy.config.json

@@ -1,6 +1,5 @@
 {
   "prefix": "todo",
-  "domain": "todo.quidproquojs.com",
   "environments": {
     "development": {
       "platform": "docker"

package/template/apps/todo/packages/constants/src/domain.ts

@@ -1 +1,2 @@
-export const TODO_DOMAIN = 'todo.quidproquojs.com';
+// Root domains the app is served on, primary first.
+export const TODO_DOMAINS = ['todo.quidproquojs.com'];

package/template/apps/todo/packages/service-utils/src/defineTodoService.ts

@@ -22,7 +22,7 @@ import {
 
 import { execSync } from 'child_process';
 import {
-  TODO_DOMAIN,
+  TODO_DOMAINS,
   TODO_USER_DIRECTORY,
   TodoServiceEnum,
   todoServiceNames,
@@ -52,8 +52,7 @@ export const defineTodoService = (
   configRoot: string,
   apiBuildPath: string,
   apiLayers: ApiLayer[] = [],
-  lambdaMemoryInMiB = 1024,
-  domainName = TODO_DOMAIN
+  lambdaMemoryInMiB = 1024
 ): QPQConfig => [
   defineApplicationModule(
     modulePrefix,
@@ -66,7 +65,7 @@ export const defineTodoService = (
 
   defineApplicationVersion(`${getVersionTag()}-${new Date().toISOString()}`),
 
-  defineDns(domainName),
+  defineDns(TODO_DOMAINS),
 
   defineAdminUserDirectory({
     owner: {
@@ -99,7 +98,7 @@ export const defineTodoService = (
     sharedSingletons: ['chakra', 'zod'],
   }),
 
-  defineApi('api', domainName),
+  defineApi('api'),
   defineDefaultRouteOptions('api', {
     allowedOrigins: [
       'http://localhost:3080',
@@ -128,7 +127,7 @@ export const defineTodoService = (
     }
   ),
 
-  defineAdminSettings(TodoServiceEnum.Admin, TODO_DOMAIN, {
+  defineAdminSettings(TodoServiceEnum.Admin, {
     services: todoServiceNames,
     coldStorageAfterDays: 90,
   }),

package/template/apps/todo/services/shell/service/src/infrastructure.ts

@@ -6,7 +6,7 @@ import {
 import { defineDevServerOptions } from 'quidproquo-dev-server/config';
 import { defineDynamicRoutes } from 'quidproquo-features';
 
-import { TODO_DOMAIN, TodoServiceEnum } from '@todo/constants';
+import { TodoServiceEnum } from '@todo/constants';
 import { defineTodoService } from '@todo/service-utils';
 
 import * as dynamicRoutes from './entry/controller';
@@ -23,7 +23,6 @@ const webEntryOptions: QPQConfigAdvancedWebEntrySettings = {
   cacheSettingsName: 'default',
   domain: {
     onRootDomain: true,
-    rootDomain: TODO_DOMAIN,
   },
   storageDrive: {
     sourceStorageDrive: websiteWebEntryStorageDriveName,
@@ -40,7 +39,6 @@ const mfeHostWebEntryOptions: QPQConfigAdvancedWebEntrySettings = {
   domain: {
     subDomainName: 'views',
     onRootDomain: true,
-    rootDomain: TODO_DOMAIN,
   },
   storageDrive: {
     sourceStorageDrive: mfeHostWebEntryStorageDriveName,

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-upsert-with-retry.md

@@ -7,7 +7,7 @@ description: Upsert a record into a key-value store, retrying automatically on t
 
 Writes a record with [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md), automatically retrying when the store is temporarily unavailable. Use it for writes that must succeed through transient DynamoDB throttling rather than failing the story on the first hiccup.
 
-- **Built from:** wraps [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md) in `askRetry`, retrying only on `KeyValueStoreUpsertErrorTypeEnum.ServiceUnavailable`. It is a helper story, not a distinct action.
+- **Built from:** wraps [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md) in `askRetry`, retrying on `KeyValueStoreUpsertErrorTypeEnum.ServiceUnavailable` and `KeyValueStoreUpsertErrorTypeEnum.WriteContention`. It is a helper story, not a distinct action.
 
 ```typescript
 import { askKeyValueStoreUpsertWithRetry } from 'quidproquo-core';
@@ -54,7 +54,7 @@ Extends `KeyValueStoreUpsertOptions` (`ttlInSeconds`, `ifNotExists`, `scope`) wi
 
 ## Notes
 
-- Only `ServiceUnavailable` (throttling / transient DynamoDB errors) is retried. A `Conflict` from an `ifNotExists` write is **not** retried — that's a genuine key collision, not a transient fault. If every attempt fails, the last error is re-thrown.
+- `ServiceUnavailable` (throttling / transient DynamoDB errors) and `WriteContention` (another write momentarily holding the item) are retried. A `Conflict` from an `ifNotExists` write is **not** retried — that's a genuine key collision, not a transient fault. If every attempt fails, the last error is re-thrown.
 - Errors that escape the retries surface the same `KeyValueStoreUpsertErrorTypeEnum` members as the plain upsert; catch them with `askCatch`.
 
 ## Related

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

@@ -59,7 +59,8 @@ function* askKeyValueStoreUpsert<KvsItem>(
 | --- | --- |
 | `KeyValueStoreUpsertErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreUpsertErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
-| `KeyValueStoreUpsertErrorTypeEnum.Conflict` | A conditional (`ifNotExists`) write lost to an existing item. Namespaced — not the generic `ErrorTypeEnum.Conflict` — so retry logic can target the write race specifically without also catching domain-level conflicts. |
+| `KeyValueStoreUpsertErrorTypeEnum.Conflict` | A conditional (`ifNotExists`) write lost to an existing item — final, the slot is taken. Namespaced — not the generic `ErrorTypeEnum.Conflict` — so retry logic can target the write race specifically without also catching domain-level conflicts. |
+| `KeyValueStoreUpsertErrorTypeEnum.WriteContention` | A conditional (`ifNotExists`) write lost to another write (a transaction) holding the item right now — transient, the item may still be absent once it settles. |
 | `KeyValueStoreUpsertErrorTypeEnum.InvalidScope` | The `scope` option is malformed (empty, `.`, over 128 characters, or containing path separators, `..`, `@`, or null bytes), the store's partition key is not string-typed, or the partition-key value contains the reserved `@@QPQSCOPE@@` delimiter (reserved on string-pk stores, so unscoped calls reject it too). |
 | `KeyValueStoreUpsertErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 

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

@@ -54,7 +54,7 @@ function* askEventDocAppendServerEvent<T>(
 
 ## Notes
 
-- 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.
+- This is a thin envelope-building wrapper over [askEventDocEventAppend](./ask-event-doc-event-append.md), called with `{ validate: false }`: it still claims the next contiguous `eventId` with a conditional write and retries under slot contention, but it skips the pre-write state resolve and `validateEvent` check, trusting server code to author valid events. Version/lifecycle validation is decided later at fold time instead — 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

@@ -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 a freshly minted sortable `payload.metadata.eventId` and `version === 1`.
+**Returns** `EventDocEvent` — the written `INIT_STATE` event, with `payload.metadata.eventId === 0` (the log's opening position) 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.