create-qpq-app 0.1.19 → 0.1.21

package/template/apps/qpqjs/services/test/service/src/smoke/config/defineSmoke.ts

@@ -9,11 +9,22 @@ import {
   QPQConfig,
   QpqFunctionRuntime,
 } from 'quidproquo';
+import { defineEventDoc } from 'quidproquo-features';
 
+import { z } from 'zod/v4';
 import { SMOKE_PROBE_DRIVE, SMOKE_PROBE_STORE } from '@qpqjs/constants';
-import { SmokeProbeRecord } from '@qpqjs/test-models';
+import {
+  SmokeProbeRecord,
+  SmokeRunStartedSchema,
+  SmokeRunWithSummarySchema,
+} from '@qpqjs/test-models';
 
 import { SMOKE_RUNS_STORE } from '../constants/SMOKE_RUNS_STORE';
+import {
+  SMOKE_EVENT_DOC_APPEND_MESSAGE_TYPE,
+  SMOKE_EVENT_DOC_APPEND_QUEUE,
+  SMOKE_EVENT_DOC_BASE_PATH,
+} from '../constants/smokeEventDoc';
 import {
   SMOKE_PROBE_EVENT_BUS,
   SMOKE_PROBE_EVENT_QUEUE,
@@ -24,8 +35,9 @@ import {
 } from '../constants/smokeProbe';
 import {
   SMOKE_RUN_QUEUE,
-  SMOKE_RUN_REQUESTED_MESSAGE_TYPE,
+  SMOKE_TEST_REQUESTED_MESSAGE_TYPE,
 } from '../constants/smokeRunQueue';
+import { smokeProbeDocDefinition } from '../eventDoc/smokeProbeDocDefinition';
 
 // Everything the smoke feature needs: the run store, the queue runs execute
 // on, and the two routes. Runtimes are located relative to this file, so the
@@ -46,15 +58,17 @@ export const defineSmoke = (): QPQConfig => {
   ];
 
   return [
-    // One record per run, keyed by runId; the queue entry updates it as tests
-    // complete and the GET route polls it.
+    // One record per run, keyed by runId; the queue workers each write their
+    // own test's entry as it completes and the GET route polls it.
     defineKeyValueStore(SMOKE_RUNS_STORE, 'runId'),
 
+    // One message per test per run. Not FIFO and no concurrency cap, so the
+    // tests of a run fan out and execute in parallel.
     defineQueue(SMOKE_RUN_QUEUE, {
-      [SMOKE_RUN_REQUESTED_MESSAGE_TYPE]: {
+      [SMOKE_TEST_REQUESTED_MESSAGE_TYPE]: {
         basePath: __dirname,
-        relativePath: '../queue/onSmokeRunRequested',
-        functionName: 'onSmokeRunRequested',
+        relativePath: '../queue/onSmokeTestRequested',
+        functionName: 'onSmokeTestRequested',
       },
     }),
 
@@ -85,18 +99,69 @@ export const defineSmoke = (): QPQConfig => {
       { eventBusSubscriptions: [SMOKE_PROBE_EVENT_BUS] }
     ),
 
-    defineRoute('POST', '/smoke/run', {
-      basePath: __dirname,
-      relativePath: '../controller/askRunSmokeTests',
-      functionName: 'askRunSmokeTests',
-      actionProcessors: githubOidcAuth,
+    // The event-doc probe collection: a full registered collection (stores, stream
+    // projector, dynamic functions, routes) so the smoke tests exercise event docs the
+    // way a real service does. NOTE the routes mount with no auth - the test service
+    // has no user directory - so the collection is world-writable; it holds nothing
+    // but throwaway probe docs. The queue fans a test's writers out one invocation
+    // each, so their appends race across lambdas.
+    defineEventDoc(
+      smokeProbeDocDefinition,
+      {
+        basePath: __dirname,
+        relativePath: '../eventDoc/smokeProbeDocDefinition',
+        functionName: 'smokeProbeDocDefinition',
+      },
+      { basePath: SMOKE_EVENT_DOC_BASE_PATH }
+    ),
+    defineQueue(SMOKE_EVENT_DOC_APPEND_QUEUE, {
+      [SMOKE_EVENT_DOC_APPEND_MESSAGE_TYPE]: {
+        basePath: __dirname,
+        relativePath: '../queue/onSmokeEventDocAppend',
+        functionName: 'onSmokeEventDocAppend',
+      },
     }),
 
-    defineRoute('GET', '/smoke/run/{runId}', {
-      basePath: __dirname,
-      relativePath: '../controller/askGetSmokeRun',
-      functionName: 'askGetSmokeRun',
-      actionProcessors: githubOidcAuth,
-    }),
+    // The zod models double as the routes' published contract, flattened to
+    // JSON Schema here for the OpenAPI document at /v1/docs.
+    defineRoute(
+      'POST',
+      '/smoke/run',
+      {
+        basePath: __dirname,
+        relativePath: '../controller/askRunSmokeTests',
+        functionName: 'askRunSmokeTests',
+        actionProcessors: githubOidcAuth,
+      },
+      {
+        schema: {
+          summary: 'Start a smoke run',
+          description:
+            'Queues every registered smoke test and returns the run id to poll. Requires a GitHub Actions OIDC token for this repo.',
+          tags: ['smoke'],
+          responseJsonSchema: z.toJSONSchema(SmokeRunStartedSchema),
+        },
+      }
+    ),
+
+    defineRoute(
+      'GET',
+      '/smoke/run/{runId}',
+      {
+        basePath: __dirname,
+        relativePath: '../controller/askGetSmokeRun',
+        functionName: 'askGetSmokeRun',
+        actionProcessors: githubOidcAuth,
+      },
+      {
+        schema: {
+          summary: 'Get a smoke run',
+          description:
+            'The stored run plus pass/fail counts. Poll until status leaves running.',
+          tags: ['smoke'],
+          responseJsonSchema: z.toJSONSchema(SmokeRunWithSummarySchema),
+        },
+      }
+    ),
   ];
 };

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

@@ -1,4 +1,5 @@
 export * from './githubOidc';
 export * from './SMOKE_RUNS_STORE';
+export * from './smokeEventDoc';
 export * from './smokeProbe';
 export * from './smokeRunQueue';

package/template/apps/qpqjs/services/test/service/src/smoke/constants/smokeEventDoc.ts

@@ -0,0 +1,27 @@
+import { EventDocEventActor, EventDocStoreOptions } from 'quidproquo-features';
+
+// The throwaway event-doc collection the smoke tests write to, registered in full via
+// defineEventDoc (see ../eventDoc/smokeProbeDocDefinition): stores, stream projector,
+// dynamic functions and routes, exactly as a real service's collection.
+export const SMOKE_EVENT_DOC_STORE = 'smokeEventDocs';
+export const SMOKE_EVENT_DOC_TYPE = 'smokeProbeDoc';
+export const SMOKE_EVENT_DOC_BASE_PATH = '/smoke/probe-docs' as const;
+
+export const SMOKE_EVENT_DOC_STORE_OPTIONS: EventDocStoreOptions = {
+  storeName: SMOKE_EVENT_DOC_STORE,
+  type: SMOKE_EVENT_DOC_TYPE,
+};
+
+// The queue the tests fan their writers out on: one message per writer, each landing in
+// its own invocation, so the appends race across lambdas rather than inside one.
+export const SMOKE_EVENT_DOC_APPEND_QUEUE = 'smokeEventDocAppends';
+export const SMOKE_EVENT_DOC_APPEND_MESSAGE_TYPE = 'smokeEventDocAppend';
+
+// The one event type the probe docs ever carry; its data is a SmokeEventDocMark.
+export const SMOKE_EVENT_DOC_MARK_EVENT = 'SMOKE_MARK';
+export const SMOKE_EVENT_DOC_SCHEMA_VERSION = 1;
+
+export const SMOKE_EVENT_DOC_ACTOR: EventDocEventActor = {
+  userId: 'smoke',
+  userDisplayName: 'Smoke run',
+};

package/template/apps/qpqjs/services/test/service/src/smoke/constants/smokeRunQueue.ts

@@ -1,6 +1,6 @@
 // The queue a smoke run is executed from, and the one message type on it.
-// POST /smoke/run creates the run record and sends this message; the queue
-// entry picks it up and runs the registered tests, so the request returns at
-// once and polling shows real progress.
+// POST /smoke/run creates the run record and sends one message per registered
+// test; the queue entry runs that single test, so the tests execute in
+// parallel, the request returns at once, and polling shows real progress.
 export const SMOKE_RUN_QUEUE = 'smokeRuns';
-export const SMOKE_RUN_REQUESTED_MESSAGE_TYPE = 'smokeRunRequested';
+export const SMOKE_TEST_REQUESTED_MESSAGE_TYPE = 'smokeTestRequested';

package/template/apps/qpqjs/services/test/service/src/smoke/controller/askRunSmokeTests.ts

@@ -5,6 +5,8 @@ import {
   qpqWebServerUtils,
 } from 'quidproquo';
 
+import { SmokeRunStarted } from '@qpqjs/test-models';
+
 import { askStartSmokeRun } from '../logic/smokeRun/askStartSmokeRun';
 
 // POST /smoke/run. Auth happened in the route preamble via the GitHub OIDC
@@ -15,5 +17,7 @@ export function* askRunSmokeTests(
 ): AskResponse<HTTPEventResponse> {
   const smokeRun = yield* askStartSmokeRun();
 
-  return qpqWebServerUtils.toJsonEventResponse({ runId: smokeRun.runId });
+  const started: SmokeRunStarted = { runId: smokeRun.runId };
+
+  return qpqWebServerUtils.toJsonEventResponse(started);
 }

package/template/apps/qpqjs/services/test/service/src/smoke/data/askRecordSmokeTestResult.ts

@@ -0,0 +1,32 @@
+import {
+  askKeyValueStoreUpdate,
+  AskResponse,
+  KvsAdvancedDataType,
+  kvsSet,
+  kvsUpdate,
+} from 'quidproquo';
+
+import { SmokeRun, SmokeTestResult } from '@qpqjs/test-models';
+
+import { SMOKE_RUNS_STORE } from '../constants/SMOKE_RUNS_STORE';
+
+// Writes one test's entry into the run record, touching nothing else, so the
+// tests running in parallel cannot clobber each other the way a whole-record
+// upsert would. Returns the record as it stands after this write: updates to
+// one item are serialized by the store, so the returned `tests` include every
+// result recorded before this one.
+export function* askRecordSmokeTestResult(
+  runId: string,
+  testIndex: number,
+  result: SmokeTestResult
+): AskResponse<SmokeRun> {
+  // A completed entry carries no nulls, but the KVS value type cannot express
+  // that the model's Nullable timestamps are filled in by now.
+  const value = result as unknown as KvsAdvancedDataType;
+
+  return yield* askKeyValueStoreUpdate<SmokeRun>(
+    SMOKE_RUNS_STORE,
+    kvsUpdate([kvsSet(['tests', testIndex], value)]),
+    runId
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/data/askSetSmokeRunOutcome.ts

@@ -0,0 +1,24 @@
+import {
+  askKeyValueStoreUpdate,
+  AskResponse,
+  kvsSet,
+  kvsUpdate,
+} from 'quidproquo';
+
+import { SmokeRun, SmokeRunStatus } from '@qpqjs/test-models';
+
+import { SMOKE_RUNS_STORE } from '../constants/SMOKE_RUNS_STORE';
+
+// Stamps the run's terminal status. Only the status and finish time are
+// written, so it cannot undo a test result that landed in the meantime.
+export function* askSetSmokeRunOutcome(
+  runId: string,
+  status: SmokeRunStatus,
+  finishedAt: string
+): AskResponse<SmokeRun> {
+  return yield* askKeyValueStoreUpdate<SmokeRun>(
+    SMOKE_RUNS_STORE,
+    kvsUpdate([kvsSet('status', status), kvsSet('finishedAt', finishedAt)]),
+    runId
+  );
+}

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

@@ -1,2 +1,4 @@
 export * from './askGetSmokeRunById';
+export * from './askRecordSmokeTestResult';
 export * from './askSaveSmokeRun';
+export * from './askSetSmokeRunOutcome';

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

@@ -0,0 +1 @@
+export * from './smokeProbeDocDefinition';

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

@@ -0,0 +1,74 @@
+import { AskResponse, Effect, QpqReducer } from 'quidproquo';
+import {
+  askApplyEventDocEvent,
+  buildEventDocFoldReducer,
+  createEventDocDefinition,
+  createEventDocInitialDocumentState,
+  EventDocDocument,
+  EventDocEvent,
+  EventDocEventPayload,
+} from 'quidproquo-features';
+
+import {
+  SMOKE_EVENT_DOC_MARK_EVENT,
+  SMOKE_EVENT_DOC_STORE,
+  SMOKE_EVENT_DOC_TYPE,
+} from '../constants/smokeEventDoc';
+import { SmokeEventDocMark } from '../models/SmokeEventDocMark';
+
+// How many numbers the document keeps: a rolling window, so the fold is a real
+// reducer (it drops as well as adds) rather than an append.
+export const SMOKE_PROBE_DOC_WINDOW = 100;
+
+// The probe doc type the event-doc smoke tests write to: one event (a mark carrying a
+// number) folded into the last SMOKE_PROBE_DOC_WINDOW numbers, in log order. Small on
+// purpose - it exists so the deployed runtime exercises a REGISTERED collection end to
+// end: the append gate, the stream projector's snapshot fold, and the state reads that
+// resolve through the dynamic-functions registration all run this definition.
+export type SmokeProbeDocState = EventDocDocument & {
+  numbers: number[];
+};
+
+const createInitialSmokeProbeDocState = (): SmokeProbeDocState => ({
+  ...createEventDocInitialDocumentState(1),
+  numbers: [],
+});
+
+type SmokeProbeDocEffects = Effect<
+  typeof SMOKE_EVENT_DOC_MARK_EVENT,
+  EventDocEventPayload<SmokeEventDocMark>
+>;
+
+const smokeProbeDocFoldReducer = buildEventDocFoldReducer<
+  SmokeProbeDocState,
+  SmokeProbeDocEffects
+>(createInitialSmokeProbeDocState, {
+  [SMOKE_EVENT_DOC_MARK_EVENT]: (state, payload) => ({
+    ...state,
+    numbers: [...state.numbers, payload.data.value].slice(
+      -SMOKE_PROBE_DOC_WINDOW
+    ),
+  }),
+}) as QpqReducer<SmokeProbeDocState, EventDocEvent>;
+
+function* askSmokeProbeDocMark(mark: SmokeEventDocMark): AskResponse<void> {
+  yield* askApplyEventDocEvent(SMOKE_EVENT_DOC_MARK_EVENT, mark);
+}
+
+export const smokeProbeDocDefinition = createEventDocDefinition({
+  storeName: SMOKE_EVENT_DOC_STORE,
+  type: SMOKE_EVENT_DOC_TYPE,
+  schemaVersion: 1,
+  versions: [
+    {
+      version: 1,
+      views: {
+        document: {
+          foldReducer: smokeProbeDocFoldReducer,
+          createInitialViewState: createInitialSmokeProbeDocState,
+        },
+      },
+    },
+  ],
+  api: { askSmokeProbeDocMark },
+});

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

@@ -2,6 +2,7 @@ export * from './config';
 export * from './constants';
 export * from './controller';
 export * from './data';
+export * from './eventDoc';
 export * from './logic';
 export * from './models';
 export * from './processors';

package/template/apps/qpqjs/services/test/service/src/smoke/logic/smokeRun/askExecuteSmokeTest.ts

@@ -0,0 +1,97 @@
+import {
+  askCatch,
+  askDateNow,
+  AskResponse,
+  askThrowError,
+  ErrorTypeEnum,
+} from 'quidproquo';
+
+import {
+  SmokeRun,
+  SmokeRunStatus,
+  SmokeTestResult,
+  SmokeTestStatus,
+} from '@qpqjs/test-models';
+
+import { askGetSmokeRunById } from '../../data/askGetSmokeRunById';
+import { askRecordSmokeTestResult } from '../../data/askRecordSmokeTestResult';
+import { askSetSmokeRunOutcome } from '../../data/askSetSmokeRunOutcome';
+import { SmokeTestDefinition } from '../../tests/SmokeTestDefinition';
+import { smokeTestRegistry } from '../../tests/smokeTestRegistry';
+
+// Runs one registered test, returning its completed result entry.
+function* askRunSmokeTest(
+  test: SmokeTestDefinition,
+  pending: SmokeTestResult,
+  runId: string
+): AskResponse<SmokeTestResult> {
+  const startedAt = yield* askDateNow();
+  const outcome = yield* askCatch(test.askRun(runId));
+  const finishedAt = yield* askDateNow();
+
+  return {
+    ...pending,
+    status: outcome.success ? SmokeTestStatus.passed : SmokeTestStatus.failed,
+    message: outcome.success ? 'passed' : outcome.error.errorText,
+    startedAt,
+    finishedAt,
+  };
+}
+
+const isTerminal = (result: SmokeTestResult): boolean =>
+  result.status === SmokeTestStatus.passed ||
+  result.status === SmokeTestStatus.failed;
+
+// Executes one registered test for an existing run (created by
+// askStartSmokeRun) and records its result. Every test of a run executes
+// concurrently through its own queue message, so nobody owns the run's
+// finish: the write of each result returns the record as it stands, and
+// because writes to one record serialize, exactly one worker (whichever
+// lands last) sees every test terminal. That worker stamps the run's outcome.
+export function* askExecuteSmokeTest(
+  runId: string,
+  testName: string
+): AskResponse<SmokeRun> {
+  const test = smokeTestRegistry.find((t) => t.name === testName);
+  if (!test) {
+    return yield* askThrowError(
+      ErrorTypeEnum.NotFound,
+      `no smoke test [${testName}] registered`
+    );
+  }
+
+  const smokeRun = yield* askGetSmokeRunById(runId);
+  if (!smokeRun) {
+    return yield* askThrowError(
+      ErrorTypeEnum.NotFound,
+      `no smoke run [${runId}] to execute`
+    );
+  }
+
+  const testIndex = smokeRun.tests.findIndex((t) => t.name === testName);
+  if (testIndex < 0) {
+    return yield* askThrowError(
+      ErrorTypeEnum.NotFound,
+      `smoke run [${runId}] has no entry for test [${testName}]`
+    );
+  }
+
+  const result = yield* askRunSmokeTest(test, smokeRun.tests[testIndex], runId);
+
+  const recorded = yield* askRecordSmokeTestResult(runId, testIndex, result);
+
+  if (!recorded.tests.every(isTerminal)) {
+    return recorded;
+  }
+
+  const finishedAt = yield* askDateNow();
+  const anyFailed = recorded.tests.some(
+    (t) => t.status !== SmokeTestStatus.passed
+  );
+
+  return yield* askSetSmokeRunOutcome(
+    runId,
+    anyFailed ? SmokeRunStatus.failed : SmokeRunStatus.passed,
+    finishedAt
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/logic/smokeRun/askStartSmokeRun.ts

@@ -15,10 +15,10 @@ import {
 
 import {
   SMOKE_RUN_QUEUE,
-  SMOKE_RUN_REQUESTED_MESSAGE_TYPE,
+  SMOKE_TEST_REQUESTED_MESSAGE_TYPE,
 } from '../../constants/smokeRunQueue';
 import { askSaveSmokeRun } from '../../data/askSaveSmokeRun';
-import { SmokeRunRequestedPayload } from '../../models/SmokeRunRequestedQueueEvent';
+import { SmokeTestRequestedPayload } from '../../models/SmokeTestRequestedQueueEvent';
 import { SmokeTestDefinition } from '../../tests/SmokeTestDefinition';
 import { smokeTestRegistry } from '../../tests/smokeTestRegistry';
 
@@ -34,9 +34,18 @@ const createPendingResult = (
   finishedAt: null,
 });
 
-// Creates the run record with every registered test pending, then hands the
-// run to the queue. The record exists before the message is sent so a poll
-// that races the queue still finds it.
+const createTestRequestedMessage = (
+  runId: string,
+  test: SmokeTestDefinition
+): QueueMessage<SmokeTestRequestedPayload> => ({
+  type: SMOKE_TEST_REQUESTED_MESSAGE_TYPE,
+  payload: { runId, testName: test.name },
+});
+
+// Creates the run record with every registered test pending, then sends one
+// queue message per test so they execute in parallel. The record exists
+// before the messages are sent so a poll (or a worker) that races the queue
+// still finds it.
 export function* askStartSmokeRun(): AskResponse<SmokeRun> {
   const runId = yield* askNewGuid();
   const startedAt = yield* askDateNow();
@@ -51,12 +60,11 @@ export function* askStartSmokeRun(): AskResponse<SmokeRun> {
 
   yield* askSaveSmokeRun(smokeRun);
 
-  const message: QueueMessage<SmokeRunRequestedPayload> = {
-    type: SMOKE_RUN_REQUESTED_MESSAGE_TYPE,
-    payload: { runId },
-  };
+  const messages = smokeTestRegistry.map((test) =>
+    createTestRequestedMessage(runId, test)
+  );
 
-  yield* askQueueSendMessages(SMOKE_RUN_QUEUE, message);
+  yield* askQueueSendMessages(SMOKE_RUN_QUEUE, ...messages);
 
   return smokeRun;
 }

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

@@ -1,4 +1,4 @@
-export * from './askExecuteSmokeRun';
+export * from './askExecuteSmokeTest';
 export * from './askFindSmokeRun';
 export * from './askStartSmokeRun';
 export * from './summarizeSmokeRun';

package/template/apps/qpqjs/services/test/service/src/smoke/models/SmokeEventDocAppendQueueEvent.ts

@@ -0,0 +1,15 @@
+import { QueueEvent, QueueMessage } from 'quidproquo';
+
+// One writer's instruction: append one mark per value to `docId` for `runId`. A single
+// value goes through the single server append, several through the batch append, so
+// the tests exercise both paths against the same log.
+export type SmokeEventDocAppendPayload = {
+  docId: string;
+  runId: string;
+  writerId: number;
+  values: number[];
+};
+
+export type SmokeEventDocAppendQueueEvent = QueueEvent<
+  QueueMessage<SmokeEventDocAppendPayload>
+>;

package/template/apps/qpqjs/services/test/service/src/smoke/models/SmokeEventDocMark.ts

@@ -0,0 +1,8 @@
+// The data on every event a smoke writer appends: the number it contributes to the
+// document, and which run and writer produced it. The document folds the numbers;
+// the tests read them back to prove every writer's every event landed exactly once.
+export type SmokeEventDocMark = {
+  value: number;
+  runId: string;
+  writerId: number;
+};

package/template/apps/qpqjs/services/test/service/src/smoke/models/SmokeTestRequestedQueueEvent.ts

@@ -0,0 +1,12 @@
+import { QueueEvent, QueueMessage } from 'quidproquo';
+
+// One registered test of one run. `testName` is the registry's stable key,
+// never the positional id.
+export type SmokeTestRequestedPayload = {
+  runId: string;
+  testName: string;
+};
+
+export type SmokeTestRequestedQueueEvent = QueueEvent<
+  QueueMessage<SmokeTestRequestedPayload>
+>;

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

@@ -1,3 +1,5 @@
 export * from './GithubOidcClaims';
+export * from './SmokeEventDocAppendQueueEvent';
+export * from './SmokeEventDocMark';
 export * from './SmokeProbeEventQueueEvent';
-export * from './SmokeRunRequestedQueueEvent';
+export * from './SmokeTestRequestedQueueEvent';

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

@@ -1,2 +1,3 @@
+export * from './onSmokeEventDocAppend';
 export * from './onSmokeProbeEvent';
-export * from './onSmokeRunRequested';
+export * from './onSmokeTestRequested';

package/template/apps/qpqjs/services/test/service/src/smoke/queue/onSmokeEventDocAppend.ts

@@ -0,0 +1,64 @@
+import { AskResponse, QueueEventResponse } from 'quidproquo';
+import {
+  askEventDocAppendServerEvent,
+  askEventDocAppendServerEvents,
+  askEventDocProvideStore,
+  EventDocServerEventInput,
+} from 'quidproquo-features';
+
+import {
+  SMOKE_EVENT_DOC_ACTOR,
+  SMOKE_EVENT_DOC_MARK_EVENT,
+  SMOKE_EVENT_DOC_SCHEMA_VERSION,
+  SMOKE_EVENT_DOC_STORE_OPTIONS,
+} from '../constants/smokeEventDoc';
+import { SmokeEventDocAppendQueueEvent } from '../models/SmokeEventDocAppendQueueEvent';
+import { SmokeEventDocMark } from '../models/SmokeEventDocMark';
+
+// One writer in the event-doc concurrency tests. Every message is its own invocation,
+// so the writers of a test race each other for the log's next slots for real - the
+// conditional-write loop in the append stories is what has to keep them contiguous.
+function* askAppendMarks(
+  docId: string,
+  runId: string,
+  writerId: number,
+  values: number[]
+): AskResponse<void> {
+  const mark = (value: number): SmokeEventDocMark => ({
+    value,
+    runId,
+    writerId,
+  });
+
+  if (values.length === 1) {
+    yield* askEventDocAppendServerEvent(
+      docId,
+      SMOKE_EVENT_DOC_MARK_EVENT,
+      mark(values[0]),
+      SMOKE_EVENT_DOC_SCHEMA_VERSION,
+      SMOKE_EVENT_DOC_ACTOR
+    );
+    return;
+  }
+
+  const inputs: EventDocServerEventInput[] = values.map((value) => ({
+    type: SMOKE_EVENT_DOC_MARK_EVENT,
+    data: mark(value),
+    version: SMOKE_EVENT_DOC_SCHEMA_VERSION,
+  }));
+
+  yield* askEventDocAppendServerEvents(docId, inputs, SMOKE_EVENT_DOC_ACTOR);
+}
+
+export function* onSmokeEventDocAppend(
+  event: SmokeEventDocAppendQueueEvent
+): AskResponse<QueueEventResponse> {
+  const { docId, runId, writerId, values } = event.message.payload;
+
+  yield* askEventDocProvideStore(
+    SMOKE_EVENT_DOC_STORE_OPTIONS,
+    askAppendMarks(docId, runId, writerId, values)
+  );
+
+  return true;
+}

package/template/apps/qpqjs/services/test/service/src/smoke/queue/onSmokeTestRequested.ts

@@ -0,0 +1,17 @@
+import { AskResponse, QueueEventResponse } from 'quidproquo';
+
+import { askExecuteSmokeTest } from '../logic/smokeRun/askExecuteSmokeTest';
+import { SmokeTestRequestedQueueEvent } from '../models/SmokeTestRequestedQueueEvent';
+
+// Queue entry for one test of a smoke run: executes it against the run record
+// askStartSmokeRun created and records its result. A throw here (e.g. the
+// record is missing) fails the message so the platform can redeliver it.
+export function* onSmokeTestRequested(
+  event: SmokeTestRequestedQueueEvent
+): AskResponse<QueueEventResponse> {
+  const { runId, testName } = event.message.payload;
+
+  yield* askExecuteSmokeTest(runId, testName);
+
+  return true;
+}

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

@@ -0,0 +1,18 @@
+import { AskResponse } from 'quidproquo';
+import { EventDocEvent } from 'quidproquo-features';
+
+import { askSmokeAssert } from '../askSmokeAssert';
+
+// The whole point of numeric event ids: an ascending list read of the log is exactly
+// 0, 1, 2, ... with no hole and no repeat, whatever order the writers raced in.
+export function* askAssertContiguousEventIds(
+  events: EventDocEvent[]
+): AskResponse<void> {
+  const ids = events.map((event) => event.payload.metadata.eventId);
+  const expected = ids.map((_, index) => index);
+
+  yield* askSmokeAssert(
+    ids.every((id, index) => id === expected[index]),
+    `event ids are not contiguous from 0: [${ids.join(', ')}]`
+  );
+}