create-qpq-app 0.1.24 → 0.1.26

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

@@ -0,0 +1,41 @@
+import { askDnsResolveHosts, askEmailSendEmail, AskResponse } from 'quidproquo';
+
+import { smokeEmailMarkerId } from '../../email/smokeEmailMarkerId';
+import { askSmokeAssert } from '../askSmokeAssert';
+import { askSmokePollForMarker } from '../askSmokePollForMarker';
+
+// The inbound email path end to end: send to this app's own receiving domain
+// with its own sender, SES receives it through the account rule set and the
+// app's rule, the receiver parses it and hands it to onSmokeEmailReceived,
+// which writes the marker. Deployed only: nothing receives mail locally.
+export function* askRunEmailReceiveTest(runId: string): AskResponse<void> {
+  const [receivingHost] = yield* askDnsResolveHosts({ subdomain: 'inbox' });
+  const [siteHost] = yield* askDnsResolveHosts();
+
+  const recipient = `${runId}@${receivingHost}`;
+  const subject = `smoke ${runId}`;
+
+  yield* askEmailSendEmail({
+    from: `smoke@${siteHost}`,
+    to: [recipient],
+    subject,
+    bodyText: `smoke probe ${runId}`,
+  });
+
+  // Mail delivery is the slowest path in the suite: SES receives, scans and
+  // writes to S3 before the drive event fires.
+  const marker = yield* askSmokePollForMarker(
+    smokeEmailMarkerId(recipient),
+    'the inbound email path',
+    45
+  );
+
+  yield* askSmokeAssert(
+    marker.path === subject,
+    `received subject [${marker.path}] did not match [${subject}]`
+  );
+  yield* askSmokeAssert(
+    marker.authentication === 'pass/pass',
+    `received message was not authenticated: spf/dkim [${marker.authentication}]`
+  );
+}

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

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

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

@@ -0,0 +1,63 @@
+import {
+  askFileDelete,
+  askFileReadTextContents,
+  askFileWriteTextContents,
+  askKeyValueStoreDelete,
+  askKeyValueStoreGet,
+  askKeyValueStoreUpsert,
+  askNewGuid,
+  AskResponse,
+} from 'quidproquo';
+
+import { SmokeProbeRecord } from '@qpqjs/test-models';
+
+import {
+  SMOKE_ENCRYPTED_PROBE_DRIVE,
+  SMOKE_ENCRYPTED_PROBE_STORE,
+} from '../../constants/smokeProbe';
+import { askSmokeAssert } from '../askSmokeAssert';
+
+// A drive and a store encrypted with a defineCryptoKey. Deployed, every write
+// needs kms:GenerateDataKey and every read kms:Decrypt on that key through
+// the alias-conditioned grant, so a plain round trip on each is the proof.
+// Locally there is no encryption at rest and this is a plain round trip.
+export function* askRunEncryptedResourcesTest(): AskResponse<void> {
+  const probeId = yield* askNewGuid();
+
+  const record: SmokeProbeRecord = { probeId, category: 'encrypted', value: 1 };
+  yield* askKeyValueStoreUpsert<SmokeProbeRecord>(
+    SMOKE_ENCRYPTED_PROBE_STORE,
+    record
+  );
+
+  const written = yield* askKeyValueStoreGet<SmokeProbeRecord>(
+    SMOKE_ENCRYPTED_PROBE_STORE,
+    probeId
+  );
+  yield* askSmokeAssert(
+    written?.value === 1,
+    'get after upsert on the encrypted store did not return the record'
+  );
+
+  yield* askKeyValueStoreDelete(SMOKE_ENCRYPTED_PROBE_STORE, probeId);
+
+  const filepath = `encrypted/${probeId}.txt`;
+  const contents = `encrypted smoke probe ${probeId}`;
+
+  yield* askFileWriteTextContents(
+    SMOKE_ENCRYPTED_PROBE_DRIVE,
+    filepath,
+    contents
+  );
+
+  const readBack = yield* askFileReadTextContents(
+    SMOKE_ENCRYPTED_PROBE_DRIVE,
+    filepath
+  );
+  yield* askSmokeAssert(
+    readBack === contents,
+    'file on the encrypted drive did not read back as written'
+  );
+
+  yield* askFileDelete(SMOKE_ENCRYPTED_PROBE_DRIVE, [filepath]);
+}

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

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

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

@@ -1,26 +1,16 @@
 import {
-  askDelay,
   askEventBusSendMessages,
-  askKeyValueStoreDelete,
-  askKeyValueStoreGet,
   askNewGuid,
   AskResponse,
   EventBusMessage,
-  Nullable,
 } from 'quidproquo';
 
-import { SMOKE_PROBE_STORE } from '@qpqjs/constants';
-import { SmokeProbeRecord } from '@qpqjs/test-models';
-
 import {
   SMOKE_PROBE_EVENT_BUS,
   SMOKE_PROBE_EVENT_TYPE,
 } from '../../constants/smokeProbe';
 import { SmokeProbeEventPayload } from '../../models/SmokeProbeEventQueueEvent';
-import { askSmokeAssert } from '../askSmokeAssert';
-
-const POLL_ATTEMPTS = 15;
-const POLL_INTERVAL_MS = 2000;
+import { askSmokePollForMarker } from '../askSmokePollForMarker';
 
 // The full async fan-out / fan-in path: publish to the owned event bus, the
 // subscribed queue's entry (onSmokeProbeEvent) writes a marker row, and this
@@ -39,19 +29,5 @@ export function* askRunEventBusTest(): AskResponse<void> {
     eventBusMessages: [message],
   });
 
-  let marker: Nullable<SmokeProbeRecord> = null;
-  for (let attempt = 0; attempt < POLL_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 the event bus and queue`
-  );
-
-  yield* askKeyValueStoreDelete(SMOKE_PROBE_STORE, markerId);
+  yield* askSmokePollForMarker(markerId, 'the event bus and queue');
 }

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

@@ -3,7 +3,8 @@ import { askEventDocEventListAll, EventDocEvent } from 'quidproquo-features';
 
 import { askSmokeAssert } from '../askSmokeAssert';
 
-const POLL_ATTEMPTS = 20;
+// Long enough to cover a writer's retry laps plus one queue redelivery.
+const POLL_ATTEMPTS = 45;
 const POLL_INTERVAL_MS = 2000;
 
 // Poll a probe doc's log until it holds `expectedLength` events (INIT_STATE included),

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

@@ -1,8 +1,12 @@
 export * from './askSmokeAssert';
+export * from './askSmokePollForMarker';
 export * from './crossService';
+export * from './emailReceive';
+export * from './encryptedResources';
 export * from './eventBus';
 export * from './eventDoc';
 export * from './keyValueStore';
+export * from './keyValueStoreStream';
 export * from './noop';
 export * from './openApi';
 export * from './parameter';
@@ -11,3 +15,4 @@ export * from './signingKey';
 export * from './SmokeTestDefinition';
 export * from './smokeTestRegistry';
 export * from './storageDrive';
+export * from './storageDriveEvent';

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

@@ -0,0 +1,60 @@
+import {
+  askKeyValueStoreDelete,
+  askKeyValueStoreUpsert,
+  askNewGuid,
+  AskResponse,
+  KvsStreamEventType,
+} from 'quidproquo';
+
+import { SmokeProbeRecord } from '@qpqjs/test-models';
+
+import { SMOKE_STREAM_PROBE_STORE } from '../../constants/smokeProbe';
+import { smokeStreamMarkerId } from '../../kvsStream/smokeStreamMarkerId';
+import { askSmokeAssert } from '../askSmokeAssert';
+import { askSmokePollForMarker } from '../askSmokePollForMarker';
+
+// The kvs stream path end to end on a scoped store: an upsert streams an
+// Insert and a delete streams a Remove to the handler. On dynamo the scope is
+// composed into the stored partition key, so the record must hand it back as
+// its own field with the key stripped, the same as the dev server does.
+export function* askRunKeyValueStoreStreamTest(): AskResponse<void> {
+  const probeId = yield* askNewGuid();
+  const scope = `smoke-st-${probeId}`;
+
+  const record: SmokeProbeRecord = {
+    probeId,
+    category: 'stream',
+    value: 1,
+  };
+  yield* askKeyValueStoreUpsert<SmokeProbeRecord>(
+    SMOKE_STREAM_PROBE_STORE,
+    record,
+    { scope }
+  );
+
+  const inserted = yield* askSmokePollForMarker(
+    smokeStreamMarkerId(probeId, KvsStreamEventType.Insert),
+    'the kvs stream insert'
+  );
+  yield* askSmokeAssert(
+    inserted.scope === scope,
+    `stream insert carried scope [${inserted.scope}], expected [${scope}]`
+  );
+  yield* askSmokeAssert(
+    inserted.path === probeId,
+    `stream insert key [${inserted.path}] was not the raw key`
+  );
+
+  yield* askKeyValueStoreDelete(SMOKE_STREAM_PROBE_STORE, probeId, undefined, {
+    scope,
+  });
+
+  const removed = yield* askSmokePollForMarker(
+    smokeStreamMarkerId(probeId, KvsStreamEventType.Remove),
+    'the kvs stream remove'
+  );
+  yield* askSmokeAssert(
+    removed.scope === scope && removed.path === probeId,
+    'stream remove did not carry the scope and raw key'
+  );
+}

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

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

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

@@ -0,0 +1,102 @@
+import {
+  askCatch,
+  askKeyValueStoreDelete,
+  askKeyValueStoreGet,
+  askKeyValueStoreGetBase,
+  askKeyValueStoreQuery,
+  askKeyValueStoreUpsert,
+  askKeyValueStoreUpsertBase,
+  askNewGuid,
+  AskResponse,
+  kvsEqual,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_STORE } from '@qpqjs/constants';
+import { SmokeProbeRecord } from '@qpqjs/test-models';
+
+import { SMOKE_SCOPED_PROBE_STORE } from '../../constants/smokeProbe';
+import { askSmokeAssert } from '../askSmokeAssert';
+
+// The scope gate on a store, on whichever backend is running: a scoped store
+// serves scoped calls (including a query) and keeps two scopes apart,
+// refuses an unscoped call, and an unscoped store refuses a scoped one. On
+// dynamo the scope is composed into the partition key, so the read-back also
+// proves the composed form never leaks to the caller.
+export function* askRunScopedKeyValueStoreTest(): AskResponse<void> {
+  const probeId = yield* askNewGuid();
+  const scopeA = `smoke-a-${probeId}`;
+  const scopeB = `smoke-b-${probeId}`;
+  const category = `scoped-kvs-${probeId}`;
+
+  const record: SmokeProbeRecord = { probeId, category, value: 1 };
+  yield* askKeyValueStoreUpsert<SmokeProbeRecord>(
+    SMOKE_SCOPED_PROBE_STORE,
+    record,
+    { scope: scopeA }
+  );
+
+  const written = yield* askKeyValueStoreGet<SmokeProbeRecord>(
+    SMOKE_SCOPED_PROBE_STORE,
+    probeId,
+    { scope: scopeA }
+  );
+  yield* askSmokeAssert(
+    written?.probeId === probeId && written.value === 1,
+    'scoped get did not return the record with its raw key'
+  );
+
+  // A scoped query must constrain the partition key (the scope is composed
+  // into it on dynamo), so the query is on probeId, not the category index.
+  const byKey = yield* askKeyValueStoreQuery<SmokeProbeRecord>(
+    SMOKE_SCOPED_PROBE_STORE,
+    kvsEqual('probeId', probeId),
+    { scope: scopeA }
+  );
+  yield* askSmokeAssert(
+    byKey.items.some((item) => item.category === category),
+    'scoped query by partition key did not return the record'
+  );
+
+  const fromB = yield* askKeyValueStoreGet<SmokeProbeRecord>(
+    SMOKE_SCOPED_PROBE_STORE,
+    probeId,
+    { scope: scopeB }
+  );
+  yield* askSmokeAssert(
+    !fromB,
+    'record written under scope A is visible from scope B'
+  );
+
+  const unscopedGet = yield* askCatch(
+    askKeyValueStoreGet<SmokeProbeRecord>(SMOKE_SCOPED_PROBE_STORE, probeId)
+  );
+  yield* askSmokeAssert(
+    !unscopedGet.success &&
+      unscopedGet.error.errorType ===
+        askKeyValueStoreGetBase.errorType.InvalidScope,
+    'unscoped get on the scoped store was not refused with InvalidScope'
+  );
+
+  const scopedUpsertOnUnscopedStore = yield* askCatch(
+    askKeyValueStoreUpsert<SmokeProbeRecord>(SMOKE_PROBE_STORE, record, {
+      scope: scopeA,
+    })
+  );
+  yield* askSmokeAssert(
+    !scopedUpsertOnUnscopedStore.success &&
+      scopedUpsertOnUnscopedStore.error.errorType ===
+        askKeyValueStoreUpsertBase.errorType.InvalidScope,
+    'scoped upsert on the unscoped store was not refused with InvalidScope'
+  );
+
+  yield* askKeyValueStoreDelete(SMOKE_SCOPED_PROBE_STORE, probeId, undefined, {
+    scope: scopeA,
+  });
+
+  const deleted = yield* askKeyValueStoreGet<SmokeProbeRecord>(
+    SMOKE_SCOPED_PROBE_STORE,
+    probeId,
+    { scope: scopeA }
+  );
+  yield* askSmokeAssert(!deleted, 'scoped record still present after delete');
+}

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

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

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

@@ -0,0 +1,116 @@
+import {
+  askCatch,
+  askFileDelete,
+  askFileExists,
+  askFileListDirectory,
+  askFileReadTextContents,
+  askFileWriteTextContents,
+  askNewGuid,
+  AskResponse,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_DRIVE } from '@qpqjs/constants';
+
+import { SMOKE_SCOPED_PROBE_DRIVE } from '../../constants/smokeProbe';
+import { askSmokeAssert } from '../askSmokeAssert';
+
+// The scope gate on a drive, on whichever backend is running: a scoped drive
+// serves scoped calls and keeps two scopes apart, refuses an unscoped call,
+// and an unscoped drive refuses a scoped one. Each refusal must be the typed
+// InvalidScope error, not a generic failure.
+export function* askRunScopedStorageDriveTest(): AskResponse<void> {
+  const fileId = yield* askNewGuid();
+  const scopeA = `smoke-a-${fileId}`;
+  const scopeB = `smoke-b-${fileId}`;
+  const folder = 'scoped';
+  const filepath = `${folder}/${fileId}.txt`;
+  const contents = `scoped smoke probe ${fileId}`;
+
+  yield* askFileWriteTextContents(
+    SMOKE_SCOPED_PROBE_DRIVE,
+    filepath,
+    contents,
+    undefined,
+    scopeA
+  );
+
+  const readBack = yield* askFileReadTextContents(
+    SMOKE_SCOPED_PROBE_DRIVE,
+    filepath,
+    scopeA
+  );
+  yield* askSmokeAssert(
+    readBack === contents,
+    'scoped file contents did not read back as written'
+  );
+
+  const listingA = yield* askFileListDirectory(
+    SMOKE_SCOPED_PROBE_DRIVE,
+    folder,
+    undefined,
+    undefined,
+    scopeA
+  );
+  yield* askSmokeAssert(
+    listingA.fileInfos.some((info) => info.filepath === filepath),
+    'scoped listing does not show the file under its own scope'
+  );
+
+  const existsInB = yield* askFileExists(
+    SMOKE_SCOPED_PROBE_DRIVE,
+    filepath,
+    scopeB
+  );
+  yield* askSmokeAssert(
+    !existsInB,
+    'file written under scope A is visible from scope B'
+  );
+
+  const unscopedRead = yield* askCatch(
+    askFileReadTextContents(SMOKE_SCOPED_PROBE_DRIVE, filepath)
+  );
+  yield* askSmokeAssert(
+    !unscopedRead.success &&
+      unscopedRead.error.errorType ===
+        askFileReadTextContents.errorType.InvalidScope,
+    'unscoped read on the scoped drive was not refused with InvalidScope'
+  );
+
+  const unscopedList = yield* askCatch(
+    askFileListDirectory(SMOKE_SCOPED_PROBE_DRIVE, folder)
+  );
+  yield* askSmokeAssert(
+    !unscopedList.success &&
+      unscopedList.error.errorType ===
+        askFileListDirectory.errorType.InvalidScope,
+    'unscoped listing on the scoped drive was not refused with InvalidScope'
+  );
+
+  const scopedWriteOnUnscopedDrive = yield* askCatch(
+    askFileWriteTextContents(
+      SMOKE_PROBE_DRIVE,
+      filepath,
+      contents,
+      undefined,
+      scopeA
+    )
+  );
+  yield* askSmokeAssert(
+    !scopedWriteOnUnscopedDrive.success &&
+      scopedWriteOnUnscopedDrive.error.errorType ===
+        askFileWriteTextContents.errorType.InvalidScope,
+    'scoped write on the unscoped drive was not refused with InvalidScope'
+  );
+
+  yield* askFileDelete(SMOKE_SCOPED_PROBE_DRIVE, [filepath], scopeA);
+
+  const existsAfterDelete = yield* askFileExists(
+    SMOKE_SCOPED_PROBE_DRIVE,
+    filepath,
+    scopeA
+  );
+  yield* askSmokeAssert(
+    !existsAfterDelete,
+    'scoped file still exists after delete'
+  );
+}

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

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

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

@@ -1,18 +1,24 @@
 import { askRunCrossServiceKeyValueStoreTest } from './crossService/askRunCrossServiceKeyValueStoreTest';
 import { askRunCrossServiceSigningKeyTest } from './crossService/askRunCrossServiceSigningKeyTest';
 import { askRunCrossServiceStorageDriveTest } from './crossService/askRunCrossServiceStorageDriveTest';
+import { askRunEmailReceiveTest } from './emailReceive/askRunEmailReceiveTest';
+import { askRunEncryptedResourcesTest } from './encryptedResources/askRunEncryptedResourcesTest';
 import { askRunEventBusTest } from './eventBus/askRunEventBusTest';
 import { askRunEventDocConcurrentAppendTest } from './eventDoc/askRunEventDocConcurrentAppendTest';
 import { askRunEventDocInterleavedBatchAppendTest } from './eventDoc/askRunEventDocInterleavedBatchAppendTest';
 import { askRunKeyValueStoreTest } from './keyValueStore/askRunKeyValueStoreTest';
+import { askRunKeyValueStoreStreamTest } from './keyValueStoreStream/askRunKeyValueStoreStreamTest';
 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 { askRunScopedKeyValueStoreTest } from './scopedKeyValueStore/askRunScopedKeyValueStoreTest';
+import { askRunScopedStorageDriveTest } from './scopedStorageDrive/askRunScopedStorageDriveTest';
 import { askRunSecretTest } from './secret/askRunSecretTest';
 import { askRunSigningKeyTest } from './signingKey/askRunSigningKeyTest';
 import { askRunStorageDriveTest } from './storageDrive/askRunStorageDriveTest';
+import { askRunStorageDriveEventTest } from './storageDriveEvent/askRunStorageDriveEventTest';
 import { SmokeTestDefinition } from './SmokeTestDefinition';
 
 // Every smoke test a run executes. They run in parallel, one queue message
@@ -51,4 +57,10 @@ export const smokeTestRegistry: SmokeTestDefinition[] = [
     name: 'crossServiceSigningKey',
     askRun: askRunCrossServiceSigningKeyTest,
   },
+  { name: 'scopedStorageDrive', askRun: askRunScopedStorageDriveTest },
+  { name: 'scopedKeyValueStore', askRun: askRunScopedKeyValueStoreTest },
+  { name: 'storageDriveEvent', askRun: askRunStorageDriveEventTest },
+  { name: 'keyValueStoreStream', askRun: askRunKeyValueStoreStreamTest },
+  { name: 'encryptedResources', askRun: askRunEncryptedResourcesTest },
+  { name: 'emailReceive', askRun: askRunEmailReceiveTest, deployedOnly: true },
 ];

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

@@ -0,0 +1,80 @@
+import {
+  askFileDelete,
+  askFileWriteTextContents,
+  askNewGuid,
+  AskResponse,
+  StorageDriveEventType,
+} from 'quidproquo';
+
+import {
+  SMOKE_FILE_EVENT_DRIVE,
+  SMOKE_SCOPED_PROBE_DRIVE,
+} from '../../constants/smokeProbe';
+import { smokeFileEventMarkerId } from '../../storageDrive/smokeFileEventMarkerId';
+import { askSmokeAssert } from '../askSmokeAssert';
+import { askSmokePollForMarker } from '../askSmokePollForMarker';
+
+// The storage drive event path end to end: a write fires the create handler
+// and a delete fires the delete handler, locally through the file watcher and
+// deployed through the S3 notification. On the scoped drive the event must
+// arrive with the scope as its own field, the path made scope-relative, and
+// the handler running under that scope.
+export function* askRunStorageDriveEventTest(): AskResponse<void> {
+  const fileId = yield* askNewGuid();
+  const filepath = `events/${fileId}.txt`;
+  const scope = `smoke-ev-${fileId}`;
+
+  yield* askFileWriteTextContents(SMOKE_FILE_EVENT_DRIVE, filepath, fileId);
+
+  const created = yield* askSmokePollForMarker(
+    smokeFileEventMarkerId(filepath, StorageDriveEventType.Create),
+    'the unscoped drive create event'
+  );
+  yield* askSmokeAssert(
+    created.path === filepath && created.scope === undefined,
+    'unscoped create event did not carry the bare path with no scope'
+  );
+
+  yield* askFileDelete(SMOKE_FILE_EVENT_DRIVE, [filepath]);
+
+  yield* askSmokePollForMarker(
+    smokeFileEventMarkerId(filepath, StorageDriveEventType.Delete),
+    'the unscoped drive delete event'
+  );
+
+  yield* askFileWriteTextContents(
+    SMOKE_SCOPED_PROBE_DRIVE,
+    filepath,
+    fileId,
+    undefined,
+    scope
+  );
+
+  const scopedCreated = yield* askSmokePollForMarker(
+    smokeFileEventMarkerId(filepath, StorageDriveEventType.Create),
+    'the scoped drive create event'
+  );
+  yield* askSmokeAssert(
+    scopedCreated.scope === scope,
+    `scoped create event carried scope [${scopedCreated.scope}], expected [${scope}]`
+  );
+  yield* askSmokeAssert(
+    scopedCreated.path === filepath,
+    `scoped create event path [${scopedCreated.path}] was not scope-relative`
+  );
+  yield* askSmokeAssert(
+    scopedCreated.ambientScope === scope,
+    'scoped create handler did not run under the event scope'
+  );
+
+  yield* askFileDelete(SMOKE_SCOPED_PROBE_DRIVE, [filepath], scope);
+
+  const scopedDeleted = yield* askSmokePollForMarker(
+    smokeFileEventMarkerId(filepath, StorageDriveEventType.Delete),
+    'the scoped drive delete event'
+  );
+  yield* askSmokeAssert(
+    scopedDeleted.scope === scope && scopedDeleted.path === filepath,
+    'scoped delete event did not carry the scope and scope-relative path'
+  );
+}

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

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

package/template/docusaurus/docs/actions/core/ai/ask-ai-prompt-stream.md

@@ -42,7 +42,7 @@ The parameters are identical to [askAiPrompt](./ask-ai-prompt.md) — see there
 | --- | --- | --- |
 | `model` | `AiModel` | Which model to prompt. |
 | `prompt` | `string` | The user prompt. Ignored when `options.messages` is set. |
-| `options` | `AskAiPromptStreamOptions` | `{ system?, aiName?, messages?, reasoning?, caching? }` — same shape and meaning as [`AskAiPromptOptions`](./ask-ai-prompt.md#askaipromptoptions). |
+| `options` | `AskAiPromptStreamOptions` | `{ system?, aiName?, messages?, reasoning?, caching?, maxDurationMs?, maxSteps?, maxOutputTokens? }` — same shape and meaning as [`AskAiPromptOptions`](./ask-ai-prompt.md#askaipromptoptions). |
 
 ## Returns
 
@@ -92,7 +92,7 @@ Within a step, text / reasoning / tool-input events arrive as matched `*Start
 | `stop` | `stop` | The model completed its answer naturally. |
 | `length` | `length` | The response hit the output token limit. |
 | `contentFilter` | `content-filter` | The provider's content filter stopped the response. |
-| `toolCalls` | `tool-calls` | Generation stopped while the model still had tool calls in flight. On the final `Finish` part this means the turn was halted early by a stop condition (e.g. a step limit) rather than finishing naturally, and can be resumed by re-sending the recorded history. |
+| `toolCalls` | `tool-calls` | Generation stopped while the model still had tool calls in flight. On the final `Finish` part this means the turn was halted early by a stop condition (`maxSteps` or `maxDurationMs`) rather than finishing naturally, and can be resumed by re-sending the recorded history. |
 | `error` | `error` | The stream errored. |
 | `other` | `other` | The provider reported a reason outside this catalog. |
 | `unknown` | `unknown` | The provider reported no reason, or one this version does not recognise. |

package/template/docusaurus/docs/actions/core/ai/ask-ai-prompt.md

@@ -50,6 +50,9 @@ function* askAiPrompt(
 | `messages` | [`AiMessage[]`](#aimessage) | – | A full conversation history. When present, this is sent instead of `prompt`, letting you carry a multi-turn dialogue (including prior assistant turns and tool results). |
 | `reasoning` | [`AiReasoningConfig`](#aireasoningconfig) | – | Enables extended thinking. Its presence turns reasoning on; `budgetTokens` caps how many tokens the model may spend thinking before it answers (defaults to `4096` on AWS). |
 | `caching` | `boolean` | – | Marks the system prompt and the last message (or the last `messages` entry) with a Bedrock cache point, so a following call in the same conversation can read everything up to there from cache instead of reprocessing it. |
+| `maxSteps` | `number` | – | Cap on model/tool steps in one call. Unset means no cap: the loop runs until the model stops on its own or `maxDurationMs` trips. A client-side tool call (a tool with no executor) still halts it immediately. |
+| `maxOutputTokens` | `number` | provider default | Output token cap per model call. Bedrock defaults to 8192, which a reasoning block plus a large tool input can exceed; the step then finishes with `length` and the tool call arrives truncated. Raise it for agentic workloads (Claude Sonnet allows 64k). |
+| `maxDurationMs` | `number` | – | Wall-clock budget for the tool loop. Checked between steps, so the loop can overrun by one step; leave headroom. When it trips with tool calls still outstanding the result finishes with `toolCalls`, and re-sending the recorded history resumes the turn. Pair it with [askGetRuntimeRemainingTime](../system/ask-get-runtime-remaining-time.md) to stop before the platform deadline. |
 
 ### `AiModel`
 

package/template/docusaurus/docs/actions/core/file/ask-file-write-text-contents.md

@@ -60,7 +60,7 @@ function* askFileWriteTextContents(
 ## Notes
 
 - If the drive declares an `onEvent.create` handler in [defineStorageDrive](../../../config/core/storage-drive.md#file-events-onevent), that story is triggered by this write.
-- Writes to a drive with `encryption: true` are encrypted at rest automatically — nothing extra is needed at the call site.
+- Every drive is encrypted at rest; `cryptoKeyName` swaps in one of your own `defineCryptoKey`s. Nothing changes at the call site either way.
 
 ## Related