create-qpq-app 0.1.24 → 0.1.26

package/package.json

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

package/template/README.md

@@ -103,3 +103,7 @@ npx qpq go             # interactive aws deploy: pick app, services, stacks (inf
 1. Create its `config`, `models`, `x-models`, `shared-logic`, `x-logic`, `service-utils`, and `service` packages.
 2. Each lib gets a `package.json` with `"build": "tsc -b"` and the dist-pointing `main`, `types`, and `exports`; a `tsconfig.json` (extends the root base, **no paths**, references `./tsconfig.lib.json`); and a `tsconfig.lib.json` (`composite`, `outDir ./dist`, `rootDir .`, with `references` to its workspace deps' `tsconfig.lib.json`). There is no root-level list to touch, since `npm run build --workspaces` discovers the new lib automatically.
 3. `service/` gets a `package.json` (`@qpqjs/<svc>-service`, `private`, `"build": "tsc -p tsconfig.app.json"`) and a `tsconfig.app.json`. No rspack.config.ts and no bundle script, because `qpq go` bundles it by convention. `npm run build` then picks it up automatically.
+
+## Test
+
+Adding a note to test build / deploy - this is a second test.

package/template/apps/qpqjs/account.qpq.ts

@@ -7,6 +7,7 @@ import { QPQConfig } from 'quidproquo';
 import {
   AwsDataStoreRemovalPolicy,
   defineAccountBudget,
+  defineAccountEmailReceiving,
   defineAccountGithubOidcProvider,
   defineAccountSecurityServices,
   defineAwsDataStoreRemovalPolicy,
@@ -21,6 +22,9 @@ export default (): QPQConfig => [
   // GitHub Actions OIDC provider, trusted by every app's deploy role in this account.
   defineAccountGithubOidcProvider(),
 
+  // The one active SES receipt rule set; every app's inbound-email rules live in it.
+  defineAccountEmailReceiving(),
+
   defineAccountSecurityServices({
     // GuardDuty is org-managed for this account
     // (delegated admin 816650600287 auto-enables detectors - a stack-created one

package/template/apps/qpqjs/bootstrap.qpq.ts

@@ -2,7 +2,12 @@
 // domain certificates. The identity plumbing (defineApplication +
 // defineAwsServiceAccountInfo) is provided by quidproquo-deploy-awscdk's
 // workspace CDK app; this fragment must not declare its own.
-import { defineApi, defineDns, QPQConfig } from 'quidproquo';
+import {
+  defineApi,
+  defineDns,
+  defineEmailReceivingDomain,
+  QPQConfig,
+} from 'quidproquo';
 import {
   defineAwsGithubDeployRole,
   defineBootstrapWaf,
@@ -17,8 +22,14 @@ import { QPQJS_DOMAINS, QpqjsServiceEnum } from '@qpqjs/constants';
 export default ({ region }: QpqAppDeployContext): QPQConfig => [
   defineDns(QPQJS_DOMAINS),
 
+  // inbox.<env>.<root>: verified with SES and MX-routed to it, for every defineEmailReceiver.
+  defineEmailReceivingDomain('inbox'),
+
   // The role the deploy workflow assumes (ids from `gh api repos/qpqjs/quidproquo`).
-  defineAwsGithubDeployRole('qpqjs/quidproquo', { ownerId: 314167689, repositoryId: 571382961 }),
+  defineAwsGithubDeployRole('qpqjs/quidproquo', {
+    ownerId: 314167689,
+    repositoryId: 571382961,
+  }),
 
   defineBootstrapWaf({
     rateLimits: [{ name: 'all-traffic', limit: 2000 }],

package/template/apps/qpqjs/packages/service-utils/src/defineQpqjsService.ts

@@ -6,6 +6,7 @@ import {
   defineCache,
   defineDefaultRouteOptions,
   defineDns,
+  defineEmailReceivingDomain,
   defineFrontendBundleOptions,
   QPQConfig,
 } from 'quidproquo';
@@ -59,6 +60,9 @@ export const defineQpqjsService = (
   ),
 
   defineDns(QPQJS_DOMAINS),
+  // Same domain bootstrap.qpq.ts declares: bootstrap owns the records, a service's
+  // defineEmailReceiver resolves its recipients from it.
+  defineEmailReceivingDomain('inbox'),
 
   defineAdminUserDirectory({
     owner: {

package/template/apps/qpqjs/services/test/models/src/SmokeProbeRecord.ts

@@ -5,4 +5,13 @@ export type SmokeProbeRecord = {
   probeId: string;
   category: string;
   value: number;
+
+  // Set by the storage drive event and kvs stream handlers: what the event
+  // said its scope and path/key were, and (for file events) the ambient
+  // storage scope the handler ran under, so a test can prove both agree.
+  scope?: string;
+  ambientScope?: string;
+  path?: string;
+  // Set by the email handler: the provider's spf/dkim verdicts on the message.
+  authentication?: string;
 };

package/template/apps/qpqjs/services/test/models/src/SmokeRunSummary.ts

@@ -4,9 +4,16 @@ import { z } from 'zod/v4';
 // cannot drift from the entries themselves.
 export const SmokeRunSummarySchema = z.object({
   total: z.int().nonnegative().describe('Tests registered for the run'),
-  completed: z.int().nonnegative().describe('Tests that have passed or failed'),
+  completed: z
+    .int()
+    .nonnegative()
+    .describe('Tests that have passed, failed or been skipped'),
   passed: z.int().nonnegative(),
   failed: z.int().nonnegative(),
+  skipped: z
+    .int()
+    .nonnegative()
+    .describe('Deployed-only tests not run on this platform'),
 });
 
 export type SmokeRunSummary = z.infer<typeof SmokeRunSummarySchema>;

package/template/apps/qpqjs/services/test/models/src/SmokeTestStatus.ts

@@ -3,4 +3,6 @@ export enum SmokeTestStatus {
   running = 'running',
   passed = 'passed',
   failed = 'failed',
+  // Deployed-only test on a platform with no equivalent; never queued, never counts either way.
+  skipped = 'skipped',
 }

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

@@ -1,4 +1,7 @@
 import {
+  defineCryptoKey,
+  defineEmailReceiver,
+  defineEmailSender,
   defineEventBus,
   defineKeyValueStore,
   defineParameter,
@@ -31,12 +34,20 @@ import {
   SMOKE_EVENT_DOC_BASE_PATH,
 } from '../constants/smokeEventDoc';
 import {
+  SMOKE_CRYPTO_KEY,
+  SMOKE_EMAIL_RECEIVER,
+  SMOKE_ENCRYPTED_PROBE_DRIVE,
+  SMOKE_ENCRYPTED_PROBE_STORE,
+  SMOKE_FILE_EVENT_DRIVE,
   SMOKE_PROBE_EVENT_BUS,
   SMOKE_PROBE_EVENT_QUEUE,
   SMOKE_PROBE_EVENT_TYPE,
   SMOKE_PROBE_PARAMETER,
   SMOKE_PROBE_PARAMETER_VALUE,
   SMOKE_PROBE_SECRET,
+  SMOKE_SCOPED_PROBE_DRIVE,
+  SMOKE_SCOPED_PROBE_STORE,
+  SMOKE_STREAM_PROBE_STORE,
 } from '../constants/smokeProbe';
 import {
   SMOKE_RUN_QUEUE,
@@ -62,6 +73,12 @@ export const defineSmoke = (): QPQConfig => {
     },
   ];
 
+  const onSmokeFileEvent: QpqFunctionRuntime = {
+    basePath: __dirname,
+    relativePath: '../storageDrive/onSmokeFileEvent',
+    functionName: 'onSmokeFileEvent',
+  };
+
   return [
     // 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.
@@ -93,6 +110,73 @@ export const defineSmoke = (): QPQConfig => {
     // defineCrossServiceProbe) for the cross-service verify test.
     defineSigningKey(SMOKE_PROBE_SIGNING_KEY),
 
+    // Scoped probe resources: the scope gate in both directions (a scoped
+    // resource refuses an unscoped call, an unscoped one refuses a scope) and
+    // partition isolation between two scopes.
+    defineKeyValueStore<SmokeProbeRecord>(
+      SMOKE_SCOPED_PROBE_STORE,
+      'probeId',
+      [],
+      { indexes: ['category'], scoped: true }
+    ),
+    defineStorageDrive(SMOKE_SCOPED_PROBE_DRIVE, {
+      scoped: true,
+      onEvent: { create: onSmokeFileEvent, delete: onSmokeFileEvent },
+    }),
+
+    // File event test path: a write or delete on either drive fires the
+    // handler, which writes a marker into the probe store; the test polls for
+    // it. The scoped drive's events must arrive with the scope split off.
+    defineStorageDrive(SMOKE_FILE_EVENT_DRIVE, {
+      onEvent: { create: onSmokeFileEvent, delete: onSmokeFileEvent },
+    }),
+
+    // Kvs stream test path: a change on this scoped store streams to the
+    // handler, which writes a marker into the probe store; the test polls for
+    // it. The record must carry the scope as its own field with a raw key.
+    defineKeyValueStore<SmokeProbeRecord>(
+      SMOKE_STREAM_PROBE_STORE,
+      'probeId',
+      [],
+      {
+        scoped: true,
+        onStream: {
+          runtime: {
+            basePath: __dirname,
+            relativePath: '../kvsStream/onSmokeStreamRecord',
+            functionName: 'onSmokeStreamRecord',
+          },
+        },
+      }
+    ),
+
+    // Encrypted probe resources: a drive and a store encrypted with an owned
+    // crypto key, so the test proves the role's KMS grant covers data at rest.
+    defineCryptoKey(SMOKE_CRYPTO_KEY),
+    defineKeyValueStore<SmokeProbeRecord>(
+      SMOKE_ENCRYPTED_PROBE_STORE,
+      'probeId',
+      [],
+      { cryptoKeyName: SMOKE_CRYPTO_KEY }
+    ),
+    defineStorageDrive(SMOKE_ENCRYPTED_PROBE_DRIVE, {
+      cryptoKeyName: SMOKE_CRYPTO_KEY,
+    }),
+
+    // Inbound email test path: the test sends to its own receiving domain, the
+    // receiver hands the parsed message to onSmokeEmailReceived, which writes a
+    // marker into the probe store, and the test polls for it. The sender is what
+    // lets the test send; the receiving domain is a verified identity, so the
+    // SES sandbox allows it.
+    defineEmailSender(),
+    defineEmailReceiver(SMOKE_EMAIL_RECEIVER, {
+      onEmail: {
+        basePath: __dirname,
+        relativePath: '../email/onSmokeEmailReceived',
+        functionName: 'onSmokeEmailReceived',
+      },
+    }),
+
     // Event bus test path: publish to the bus, the subscribed queue's entry
     // writes a marker into the probe store, the test polls for it.
     defineEventBus(SMOKE_PROBE_EVENT_BUS),
@@ -123,13 +207,19 @@ export const defineSmoke = (): QPQConfig => {
       },
       { 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',
+    // A writer that loses the slot race past the append retry cap fails its message; a
+    // quick redelivery lets it land instead of vanishing, as a production queue should.
+    defineQueue(
+      SMOKE_EVENT_DOC_APPEND_QUEUE,
+      {
+        [SMOKE_EVENT_DOC_APPEND_MESSAGE_TYPE]: {
+          basePath: __dirname,
+          relativePath: '../queue/onSmokeEventDocAppend',
+          functionName: 'onSmokeEventDocAppend',
+        },
       },
-    }),
+      { maxTries: 3, ttRetryInSeconds: 10 }
+    ),
 
     // The zod models double as the routes' published contract, flattened to
     // JSON Schema here for the OpenAPI document at /v1/docs.

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

@@ -12,3 +12,28 @@ export const SMOKE_PROBE_EVENT_BUS = 'smokeProbe';
 // flows bus -> queue -> store marker for the event bus test.
 export const SMOKE_PROBE_EVENT_QUEUE = 'smokeProbeEvents';
 export const SMOKE_PROBE_EVENT_TYPE = 'smokeProbeEvent';
+
+// Scoped probe resources: every call must carry a scope, an unscoped one is
+// refused. Only the test service uses them, so they stay service-level.
+export const SMOKE_SCOPED_PROBE_STORE = 'smokeScopedProbe';
+export const SMOKE_SCOPED_PROBE_DRIVE = 'smoke-scoped-probe';
+
+// The file event drives: an unscoped and a scoped one, both with create and
+// delete handlers that write a marker row the file event test polls for.
+export const SMOKE_FILE_EVENT_DRIVE = 'smoke-file-event';
+
+// A scoped store with a change stream; the handler writes a marker row the
+// kvs stream test polls for.
+export const SMOKE_STREAM_PROBE_STORE = 'smokeStreamProbe';
+
+// The crypto key the encrypted probe drive and store name: proves the
+// alias-conditioned KMS grant lets the service role write and read data
+// encrypted with a defineCryptoKey. Not 'smokeProbe': the signing key of that
+// name is a KMS alias too, and the two would collide.
+export const SMOKE_CRYPTO_KEY = 'smokeCrypto';
+export const SMOKE_ENCRYPTED_PROBE_STORE = 'smokeEncryptedProbe';
+export const SMOKE_ENCRYPTED_PROBE_DRIVE = 'smoke-encrypted-probe';
+
+// Inbound email: the receiver's onEmail writes a marker the email test polls for.
+// Deployed only.
+export const SMOKE_EMAIL_RECEIVER = 'smoke';

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

@@ -0,0 +1,2 @@
+export * from './onSmokeEmailReceived';
+export * from './smokeEmailMarkerId';

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

@@ -0,0 +1,33 @@
+import {
+  askKeyValueStoreUpsert,
+  AskResponse,
+  EmailReceivedEvent,
+  EmailReceivedEventResponse,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_STORE } from '@qpqjs/constants';
+import { SmokeProbeRecord } from '@qpqjs/test-models';
+
+import { smokeEmailMarkerId } from './smokeEmailMarkerId';
+
+// The smoke receiver's onEmail: one marker per delivered recipient, carrying
+// the subject and the provider's SPF/DKIM verdicts so the test can check the
+// message came through intact and authenticated.
+export function* onSmokeEmailReceived({
+  message,
+}: EmailReceivedEvent): AskResponse<EmailReceivedEventResponse> {
+  for (const recipient of message.recipients) {
+    const marker: SmokeProbeRecord = {
+      probeId: smokeEmailMarkerId(recipient),
+      category: 'email',
+      value: 1,
+      path: message.subject,
+      authentication: [
+        message.authentication.spf,
+        message.authentication.dkim,
+      ].join('/'),
+    };
+
+    yield* askKeyValueStoreUpsert<SmokeProbeRecord>(SMOKE_PROBE_STORE, marker);
+  }
+}

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

@@ -0,0 +1,4 @@
+// The marker row id for one received message: the recipient's local part, which the email
+// test sets to its own run id so the marker it polls for is provably its own.
+export const smokeEmailMarkerId = (recipient: string): string =>
+  `email-${recipient.split('@')[0]}`;

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

@@ -2,9 +2,12 @@ export * from './config';
 export * from './constants';
 export * from './controller';
 export * from './data';
+export * from './email';
 export * from './eventDoc';
+export * from './kvsStream';
 export * from './logic';
 export * from './models';
 export * from './processors';
 export * from './queue';
+export * from './storageDrive';
 export * from './tests';

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

@@ -0,0 +1,2 @@
+export * from './onSmokeStreamRecord';
+export * from './smokeStreamMarkerId';

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

@@ -0,0 +1,31 @@
+import {
+  askKeyValueStoreUpsert,
+  AskResponse,
+  KvsStreamEventResponse,
+  KvsStreamRecord,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_STORE } from '@qpqjs/constants';
+import { SmokeProbeRecord } from '@qpqjs/test-models';
+
+import { smokeStreamMarkerId } from './smokeStreamMarkerId';
+
+// Fan-in for the kvs stream test: the scoped stream store's changes land
+// here. The marker records the scope the record carried and the raw key, so
+// the test can check the stream hands back the scope as its own field with
+// the key stripped of it.
+export function* onSmokeStreamRecord(
+  record: KvsStreamRecord<SmokeProbeRecord>
+): AskResponse<KvsStreamEventResponse> {
+  const key = String(record.keys.probeId);
+
+  const marker: SmokeProbeRecord = {
+    probeId: smokeStreamMarkerId(key, record.eventType),
+    category: 'kvsStream',
+    value: 1,
+    scope: record.scope,
+    path: key,
+  };
+
+  yield* askKeyValueStoreUpsert<SmokeProbeRecord>(SMOKE_PROBE_STORE, marker);
+}

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

@@ -0,0 +1,8 @@
+import { KvsStreamEventType } from 'quidproquo';
+
+// The marker row id for one stream record: the changed item's key plus the
+// event type, so an insert and its remove are two rows the test polls for.
+export const smokeStreamMarkerId = (
+  key: string,
+  eventType: KvsStreamEventType
+): string => `${key}-stream-${eventType.toLowerCase()}`;

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

@@ -40,7 +40,8 @@ function* askRunSmokeTest(
 
 const isTerminal = (result: SmokeTestResult): boolean =>
   result.status === SmokeTestStatus.passed ||
-  result.status === SmokeTestStatus.failed;
+  result.status === SmokeTestStatus.failed ||
+  result.status === SmokeTestStatus.skipped;
 
 // Executes one registered test for an existing run (created by
 // askStartSmokeRun) and records its result. Every test of a run executes
@@ -86,7 +87,7 @@ export function* askExecuteSmokeTest(
 
   const finishedAt = yield* askDateNow();
   const anyFailed = recorded.tests.some(
-    (t) => t.status !== SmokeTestStatus.passed
+    (t) => t.status === SmokeTestStatus.failed
   );
 
   return yield* askSetSmokeRunOutcome(

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

@@ -1,6 +1,7 @@
 import {
   askDateNow,
   askNewGuid,
+  askPlatformGetName,
   askQueueSendMessages,
   AskResponse,
   QueueMessage,
@@ -22,14 +23,15 @@ import { SmokeTestRequestedPayload } from '../../models/SmokeTestRequestedQueueE
 import { SmokeTestDefinition } from '../../tests/SmokeTestDefinition';
 import { smokeTestRegistry } from '../../tests/smokeTestRegistry';
 
-const createPendingResult = (
+const createInitialResult = (
   test: SmokeTestDefinition,
-  index: number
+  index: number,
+  skip: boolean
 ): SmokeTestResult => ({
   id: index + 1,
   name: test.name,
-  status: SmokeTestStatus.pending,
-  message: '',
+  status: skip ? SmokeTestStatus.skipped : SmokeTestStatus.pending,
+  message: skip ? 'deployed only' : '',
   startedAt: null,
   finishedAt: null,
 });
@@ -42,29 +44,41 @@ const createTestRequestedMessage = (
   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.
+// Creates the run record with every registered test pending (or skipped, for
+// a deployed-only test on the dev server), then sends one queue message per
+// pending 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. A run of nothing but skips never gets a worker, so it is finished here.
 export function* askStartSmokeRun(): AskResponse<SmokeRun> {
   const runId = yield* askNewGuid();
   const startedAt = yield* askDateNow();
+  const platformName = yield* askPlatformGetName();
+
+  const shouldSkip = (test: SmokeTestDefinition): boolean =>
+    !!test.deployedOnly && platformName === 'devServer';
+
+  const queued = smokeTestRegistry.filter((test) => !shouldSkip(test));
 
   const smokeRun: SmokeRun = {
     runId,
-    status: SmokeRunStatus.running,
+    status:
+      queued.length === 0 ? SmokeRunStatus.passed : SmokeRunStatus.running,
     startedAt,
-    finishedAt: null,
-    tests: smokeTestRegistry.map(createPendingResult),
+    finishedAt: queued.length === 0 ? startedAt : null,
+    tests: smokeTestRegistry.map((test, index) =>
+      createInitialResult(test, index, shouldSkip(test))
+    ),
   };
 
   yield* askSaveSmokeRun(smokeRun);
 
-  const messages = smokeTestRegistry.map((test) =>
+  const messages = queued.map((test) =>
     createTestRequestedMessage(runId, test)
   );
 
-  yield* askQueueSendMessages(SMOKE_RUN_QUEUE, ...messages);
+  if (messages.length > 0) {
+    yield* askQueueSendMessages(SMOKE_RUN_QUEUE, ...messages);
+  }
 
   return smokeRun;
 }

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

@@ -12,14 +12,18 @@ export const summarizeSmokeRun = (smokeRun: SmokeRun): SmokeRunWithSummary => {
   const failed = smokeRun.tests.filter(
     (t) => t.status === SmokeTestStatus.failed
   ).length;
+  const skipped = smokeRun.tests.filter(
+    (t) => t.status === SmokeTestStatus.skipped
+  ).length;
 
   return {
     ...smokeRun,
     summary: {
       total: smokeRun.tests.length,
-      completed: passed + failed,
+      completed: passed + failed + skipped,
       passed,
       failed,
+      skipped,
     },
   };
 };

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

@@ -0,0 +1,4 @@
+export * from './onSmokeEmailReceived';
+export * from './onSmokeFileEvent';
+export * from './smokeEmailMarkerId';
+export * from './smokeFileEventMarkerId';

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

@@ -0,0 +1,38 @@
+import {
+  askKeyValueStoreUpsert,
+  AskResponse,
+  askStorageScopeRead,
+  StorageDriveEvent,
+  StorageDriveEventResponse,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_STORE } from '@qpqjs/constants';
+import { SmokeProbeRecord } from '@qpqjs/test-models';
+
+import { smokeFileEventMarkerId } from './smokeFileEventMarkerId';
+
+// Fan-in for the file event test: both the scoped and the unscoped event
+// drive point create and delete here. The marker records what the event
+// carried and the scope the handler ran under, so the test can check that a
+// scoped drive's event arrives with its scope split off the path and the
+// handler re-entered that scope.
+export function* onSmokeFileEvent(
+  event: StorageDriveEvent
+): AskResponse<StorageDriveEventResponse> {
+  const ambientScope = yield* askStorageScopeRead();
+
+  for (const filepath of event.filePaths) {
+    const marker: SmokeProbeRecord = {
+      probeId: smokeFileEventMarkerId(filepath, event.eventType),
+      category: 'fileEvent',
+      value: 1,
+      scope: event.scope,
+      ambientScope: ambientScope ?? undefined,
+      path: filepath,
+    };
+
+    // The probe store is unscoped, so the marker is written without a scope
+    // whatever scope this handler runs under.
+    yield* askKeyValueStoreUpsert<SmokeProbeRecord>(SMOKE_PROBE_STORE, marker);
+  }
+}

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

@@ -0,0 +1,14 @@
+import { StorageDriveEventType } from 'quidproquo';
+
+// The marker row id for one file event: the file's own id (its basename
+// without extension) plus the event type, so a create and its delete are two
+// rows the test can poll for separately.
+export const smokeFileEventMarkerId = (
+  filepath: string,
+  eventType: StorageDriveEventType
+): string => {
+  const basename = filepath.split('/').pop() ?? filepath;
+  const fileId = basename.replace(/\.[^.]*$/, '');
+
+  return `${fileId}-${eventType.toLowerCase()}`;
+};

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

@@ -11,4 +11,7 @@ import { AskResponse } from 'quidproquo';
 export type SmokeTestDefinition = {
   name: string;
   askRun: (runId: string) => AskResponse<void>;
+  // The test exercises something only a deployed platform has (inbound email,
+  // say). On the dev server it is recorded as skipped and never queued.
+  deployedOnly?: boolean;
 };

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

@@ -0,0 +1,44 @@
+import {
+  askDelay,
+  askKeyValueStoreDelete,
+  askKeyValueStoreGet,
+  AskResponse,
+  Nullable,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_STORE } from '@qpqjs/constants';
+import { SmokeProbeRecord } from '@qpqjs/test-models';
+
+import { askSmokeAssert } from './askSmokeAssert';
+
+const POLL_ATTEMPTS = 15;
+const POLL_INTERVAL_MS = 2000;
+
+// Fan-in for every async probe: polls the probe store for the marker row an
+// event handler writes, fails the test if it never arrives, and removes it
+// so a rerun starts clean. The default wait covers the dev server's file
+// watcher settle window and S3 / stream delivery latency; a slower path
+// (mail delivery) asks for more attempts.
+export function* askSmokePollForMarker(
+  markerId: string,
+  via: string,
+  attempts: number = POLL_ATTEMPTS
+): AskResponse<SmokeProbeRecord> {
+  let marker: Nullable<SmokeProbeRecord> = null;
+  for (let attempt = 0; attempt < attempts && !marker; attempt += 1) {
+    yield* askDelay(POLL_INTERVAL_MS);
+    marker = yield* askKeyValueStoreGet<SmokeProbeRecord>(
+      SMOKE_PROBE_STORE,
+      markerId
+    );
+  }
+
+  yield* askSmokeAssert(
+    !!marker,
+    `marker [${markerId}] never arrived via ${via}`
+  );
+
+  yield* askKeyValueStoreDelete(SMOKE_PROBE_STORE, markerId);
+
+  return marker!;
+}