create-qpq-app 0.1.26 → 0.1.27

package/template/apps/qpqjs/services/test/service/src/smoke/suites/signingKey/signingKeySmokeSuite.ts

@@ -0,0 +1,16 @@
+import { SmokeSuite } from '../../harness/types/SmokeSuite';
+import { defineSigningKeySmoke } from './config/defineSigningKeySmoke';
+import { askRunCrossServiceSigningKeyTest } from './logic/askRunCrossServiceSigningKeyTest';
+import { askRunSigningKeyTest } from './logic/askRunSigningKeyTest';
+
+/** An owned signing key, and testa verifying (but never signing) with it. */
+export const signingKeySmokeSuite: SmokeSuite = {
+  defineConfig: defineSigningKeySmoke,
+  tests: [
+    { name: 'signingKey', askRun: askRunSigningKeyTest },
+    {
+      name: 'crossServiceSigningKey',
+      askRun: askRunCrossServiceSigningKeyTest,
+    },
+  ],
+};

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

@@ -0,0 +1,46 @@
+import { SmokeSuite } from '../harness/types/SmokeSuite';
+import { emailReceiveSmokeSuite } from './emailReceive/emailReceiveSmokeSuite';
+import { encryptedResourcesSmokeSuite } from './encryptedResources/encryptedResourcesSmokeSuite';
+import { eventBusSmokeSuite } from './eventBus/eventBusSmokeSuite';
+import { eventDocSmokeSuite } from './eventDoc/eventDocSmokeSuite';
+import { keyValueStoreSmokeSuite } from './keyValueStore/keyValueStoreSmokeSuite';
+import { keyValueStoreStreamSmokeSuite } from './keyValueStoreStream/keyValueStoreStreamSmokeSuite';
+import { noopSmokeSuite } from './noop/noopSmokeSuite';
+import { openApiSmokeSuite } from './openApi/openApiSmokeSuite';
+import { parameterSmokeSuite } from './parameter/parameterSmokeSuite';
+import { scheduleSmokeSuite } from './schedule/scheduleSmokeSuite';
+import { scopedKeyValueStoreSmokeSuite } from './scopedKeyValueStore/scopedKeyValueStoreSmokeSuite';
+import { scopedStorageDriveSmokeSuite } from './scopedStorageDrive/scopedStorageDriveSmokeSuite';
+import { secretSmokeSuite } from './secret/secretSmokeSuite';
+import { signingKeySmokeSuite } from './signingKey/signingKeySmokeSuite';
+import { storageDriveSmokeSuite } from './storageDrive/storageDriveSmokeSuite';
+import { storageDriveEventSmokeSuite } from './storageDriveEvent/storageDriveEventSmokeSuite';
+
+/**
+ * Every suite a smoke run executes. Adding one: a folder under suites/
+ * exporting a SmokeSuite, and a line here. A suite with a cross-service half
+ * also has a folder of the same name under testa's smoke/suites.
+ *
+ * Every test runs in parallel on its own queue message, so none may depend on
+ * another having finished. A test's name is the key its queue message carries
+ * and must be unique across suites; its id in the run record is its position
+ * across this list, so append rather than reorder where possible.
+ */
+export const smokeSuites: SmokeSuite[] = [
+  noopSmokeSuite,
+  keyValueStoreSmokeSuite,
+  parameterSmokeSuite,
+  secretSmokeSuite,
+  storageDriveSmokeSuite,
+  eventBusSmokeSuite,
+  scheduleSmokeSuite,
+  openApiSmokeSuite,
+  eventDocSmokeSuite,
+  signingKeySmokeSuite,
+  scopedStorageDriveSmokeSuite,
+  storageDriveEventSmokeSuite,
+  scopedKeyValueStoreSmokeSuite,
+  keyValueStoreStreamSmokeSuite,
+  encryptedResourcesSmokeSuite,
+  emailReceiveSmokeSuite,
+];

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

@@ -0,0 +1,2 @@
+export * from './logic';
+export * from './storageDriveSmokeSuite';

package/template/apps/qpqjs/services/test/service/src/smoke/{tests/crossService → suites/storageDrive/logic}/askRunCrossServiceStorageDriveTest.ts

@@ -16,7 +16,7 @@ import {
   CrossServiceStorageDriveProbeResult,
 } from '@qpqjs/testa-models';
 
-import { askSmokeAssert } from '../askSmokeAssert';
+import { askSmokeAssert } from '../../../harness/assert/askSmokeAssert';
 
 // testa writes a file into the drive THIS service owns, through its foreign
 // (exact-ARN) S3 grant. An error from inside testa is that grant; the

package/template/apps/qpqjs/services/test/service/src/smoke/{tests/storageDrive → suites/storageDrive/logic}/askRunStorageDriveTest.ts

@@ -10,7 +10,7 @@ import {
 
 import { SMOKE_PROBE_DRIVE } from '@qpqjs/constants';
 
-import { askSmokeAssert } from '../askSmokeAssert';
+import { askSmokeAssert } from '../../../harness/assert/askSmokeAssert';
 
 // Every S3 action the owned-drive grant covers (PutObject, GetObject,
 // ListBucket, DeleteObject). Unlike the other kinds this grant is a bucket

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

@@ -0,0 +1,2 @@
+export * from './askRunCrossServiceStorageDriveTest';
+export * from './askRunStorageDriveTest';

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

@@ -0,0 +1,14 @@
+import { SmokeSuite } from '../../harness/types/SmokeSuite';
+import { askRunCrossServiceStorageDriveTest } from './logic/askRunCrossServiceStorageDriveTest';
+import { askRunStorageDriveTest } from './logic/askRunStorageDriveTest';
+
+/** Every S3 action on the probe drive, from this service and from testa. No config: the drive belongs to the harness. */
+export const storageDriveSmokeSuite: SmokeSuite = {
+  tests: [
+    { name: 'storageDrive', askRun: askRunStorageDriveTest },
+    {
+      name: 'crossServiceStorageDrive',
+      askRun: askRunCrossServiceStorageDriveTest,
+    },
+  ],
+};

package/template/apps/qpqjs/services/test/service/src/smoke/suites/storageDriveEvent/config/defineStorageDriveEventSmoke.ts

@@ -0,0 +1,27 @@
+import { defineStorageDrive, QPQConfig, QpqFunctionRuntime } from 'quidproquo';
+
+import { SMOKE_FILE_EVENT_DRIVE } from '../constants/SMOKE_FILE_EVENT_DRIVE';
+import { SMOKE_SCOPED_FILE_EVENT_DRIVE } from '../constants/SMOKE_SCOPED_FILE_EVENT_DRIVE';
+
+/**
+ * A write or delete on either drive fires the handler, which writes a marker
+ * into the probe store for the test to poll. The scoped drive's events must
+ * arrive with the scope split off.
+ */
+export const defineStorageDriveEventSmoke = (): QPQConfig => {
+  const onSmokeFileEvent: QpqFunctionRuntime = {
+    basePath: __dirname,
+    relativePath: '../entry/storageDrive/onSmokeFileEvent',
+    functionName: 'onSmokeFileEvent',
+  };
+
+  return [
+    defineStorageDrive(SMOKE_FILE_EVENT_DRIVE, {
+      onEvent: { create: onSmokeFileEvent, delete: onSmokeFileEvent },
+    }),
+    defineStorageDrive(SMOKE_SCOPED_FILE_EVENT_DRIVE, {
+      scoped: true,
+      onEvent: { create: onSmokeFileEvent, delete: onSmokeFileEvent },
+    }),
+  ];
+};

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

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

package/template/apps/qpqjs/services/test/service/src/smoke/suites/storageDriveEvent/constants/SMOKE_FILE_EVENT_DRIVE.ts

@@ -0,0 +1,2 @@
+/** The unscoped drive whose create and delete handlers write the markers the file event test polls for. */
+export const SMOKE_FILE_EVENT_DRIVE = 'smoke-file-event';

package/template/apps/qpqjs/services/test/service/src/smoke/suites/storageDriveEvent/constants/SMOKE_SCOPED_FILE_EVENT_DRIVE.ts

@@ -0,0 +1,2 @@
+/** The scoped drive whose events must reach the handler with the scope split off the path. */
+export const SMOKE_SCOPED_FILE_EVENT_DRIVE = 'smoke-scoped-file-event';

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

@@ -0,0 +1,2 @@
+export * from './SMOKE_FILE_EVENT_DRIVE';
+export * from './SMOKE_SCOPED_FILE_EVENT_DRIVE';

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

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

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

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

package/template/apps/qpqjs/services/test/service/src/smoke/{storageDrive → suites/storageDriveEvent/entry/storageDrive}/onSmokeFileEvent.ts

@@ -9,7 +9,7 @@ import {
 import { SMOKE_PROBE_STORE } from '@qpqjs/constants';
 import { SmokeProbeRecord } from '@qpqjs/test-models';
 
-import { smokeFileEventMarkerId } from './smokeFileEventMarkerId';
+import { smokeFileEventMarkerId } from '../../logic/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

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

@@ -0,0 +1,5 @@
+export * from './config';
+export * from './constants';
+export * from './entry';
+export * from './logic';
+export * from './storageDriveEventSmokeSuite';

package/template/apps/qpqjs/services/test/service/src/smoke/{tests/storageDriveEvent → suites/storageDriveEvent/logic}/askRunStorageDriveEventTest.ts

@@ -6,13 +6,11 @@ import {
   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';
+import { askSmokeAssert } from '../../../harness/assert/askSmokeAssert';
+import { askSmokePollForMarker } from '../../../harness/assert/askSmokePollForMarker';
+import { SMOKE_FILE_EVENT_DRIVE } from '../constants/SMOKE_FILE_EVENT_DRIVE';
+import { SMOKE_SCOPED_FILE_EVENT_DRIVE } from '../constants/SMOKE_SCOPED_FILE_EVENT_DRIVE';
+import { smokeFileEventMarkerId } from './smokeFileEventMarkerId';
 
 // 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
@@ -43,7 +41,7 @@ export function* askRunStorageDriveEventTest(): AskResponse<void> {
   );
 
   yield* askFileWriteTextContents(
-    SMOKE_SCOPED_PROBE_DRIVE,
+    SMOKE_SCOPED_FILE_EVENT_DRIVE,
     filepath,
     fileId,
     undefined,
@@ -67,7 +65,7 @@ export function* askRunStorageDriveEventTest(): AskResponse<void> {
     'scoped create handler did not run under the event scope'
   );
 
-  yield* askFileDelete(SMOKE_SCOPED_PROBE_DRIVE, [filepath], scope);
+  yield* askFileDelete(SMOKE_SCOPED_FILE_EVENT_DRIVE, [filepath], scope);
 
   const scopedDeleted = yield* askSmokePollForMarker(
     smokeFileEventMarkerId(filepath, StorageDriveEventType.Delete),

package/template/apps/qpqjs/services/test/service/src/smoke/{tests/storageDriveEvent → suites/storageDriveEvent/logic}/index.ts

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

package/template/apps/qpqjs/services/test/service/src/smoke/suites/storageDriveEvent/storageDriveEventSmokeSuite.ts

@@ -0,0 +1,9 @@
+import { SmokeSuite } from '../../harness/types/SmokeSuite';
+import { defineStorageDriveEventSmoke } from './config/defineStorageDriveEventSmoke';
+import { askRunStorageDriveEventTest } from './logic/askRunStorageDriveEventTest';
+
+/** File create and delete events off an unscoped and a scoped drive. */
+export const storageDriveEventSmokeSuite: SmokeSuite = {
+  defineConfig: defineStorageDriveEventSmoke,
+  tests: [{ name: 'storageDriveEvent', askRun: askRunStorageDriveEventTest }],
+};

package/template/apps/qpqjs/services/testa/models/src/CrossServiceProbePayload.ts

@@ -1,4 +1,4 @@
-// Input to testa's smokeCrossServiceProbe service function.
+// Input to testa's key value store and storage drive probe service functions.
 export type CrossServiceProbePayload = {
   probeId: string;
 };

package/template/apps/qpqjs/services/testa/service/src/infrastructure.ts

@@ -3,7 +3,7 @@ import { defineDevServerOptions } from 'quidproquo-dev-server/config';
 import { QpqjsServiceEnum } from '@qpqjs/constants';
 import { defineQpqjsService } from '@qpqjs/service-utils';
 
-import { defineCrossServiceProbe } from './crossServiceProbe/config/defineCrossServiceProbe';
+import { defineSmokeProbes } from './smoke/config/defineSmokeProbes';
 
 // testa exists to be "the other service" in the smoke suite: it owns nothing
 // of its own and exercises the cross-service (foreign ARN) IAM grants against
@@ -18,5 +18,5 @@ export default [
     '../../../../../../dist/apps/qpqjs/services/testa/service'
   ),
 
-  defineCrossServiceProbe(),
+  defineSmokeProbes(),
 ];

package/template/apps/qpqjs/services/testa/service/src/smoke/config/defineSmokeProbes.ts

@@ -0,0 +1,16 @@
+import { QPQConfig } from 'quidproquo';
+
+import { defineKeyValueStoreSmokeProbe } from '../suites/keyValueStore/config/defineKeyValueStoreSmokeProbe';
+import { defineSigningKeySmokeProbe } from '../suites/signingKey/config/defineSigningKeySmokeProbe';
+import { defineStorageDriveSmokeProbe } from '../suites/storageDrive/config/defineStorageDriveSmokeProbe';
+
+/**
+ * The cross-service half of the test service's smoke suites. Each folder under
+ * suites/ mirrors the test service suite of the same name and exercises that
+ * suite's foreign grant against a resource the test service owns.
+ */
+export const defineSmokeProbes = (): QPQConfig => [
+  defineKeyValueStoreSmokeProbe(),
+  defineStorageDriveSmokeProbe(),
+  defineSigningKeySmokeProbe(),
+];

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

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

package/template/apps/qpqjs/services/{test/service/src/tick → testa/service/src/smoke}/index.ts

@@ -1 +1,2 @@
 export * from './config';
+export * from './suites';

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

@@ -0,0 +1,3 @@
+export * from './keyValueStore';
+export * from './signingKey';
+export * from './storageDrive';

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/keyValueStore/config/defineKeyValueStoreSmokeProbe.ts

@@ -0,0 +1,33 @@
+import {
+  defineKeyValueStore,
+  defineServiceFunction,
+  QPQConfig,
+} from 'quidproquo';
+
+import {
+  QpqjsServiceEnum,
+  SMOKE_CROSS_SERVICE_KEY_VALUE_STORE_PROBE_FUNCTION_NAME,
+  SMOKE_PROBE_STORE,
+} from '@qpqjs/constants';
+import { SmokeProbeRecord } from '@qpqjs/test-models';
+
+/**
+ * The test service's probe store declared FOREIGN (owned by test), which is
+ * what grants this service's role exact-ARN access to it, plus the service
+ * function the test service's crossServiceKeyValueStore test invokes.
+ */
+export const defineKeyValueStoreSmokeProbe = (): QPQConfig => [
+  defineKeyValueStore<SmokeProbeRecord>(SMOKE_PROBE_STORE, 'probeId', [], {
+    indexes: ['category'],
+    owner: { module: QpqjsServiceEnum.Test },
+  }),
+  defineServiceFunction(
+    {
+      basePath: __dirname,
+      relativePath:
+        '../entry/serviceFunction/smokeCrossServiceKeyValueStoreProbe',
+      functionName: 'smokeCrossServiceKeyValueStoreProbe',
+    },
+    { functionName: SMOKE_CROSS_SERVICE_KEY_VALUE_STORE_PROBE_FUNCTION_NAME }
+  ),
+];

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/keyValueStore/config/index.ts

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

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/keyValueStore/entry/serviceFunction/index.ts

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

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/keyValueStore/logic/index.ts

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

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/signingKey/config/defineSigningKeySmokeProbe.ts

@@ -0,0 +1,28 @@
+import { defineServiceFunction, defineSigningKey, QPQConfig } from 'quidproquo';
+
+import {
+  QpqjsServiceEnum,
+  SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME,
+  SMOKE_PROBE_SIGNING_KEY,
+} from '@qpqjs/constants';
+
+/**
+ * The test service's signing key declared FOREIGN (owned by test), plus the
+ * service function the test service's crossServiceSigningKey test invokes.
+ * The one foreign grant that is alias-conditioned rather than exact-ARN: the
+ * owner's alias name is what this declaration must resolve to, or
+ * GetPublicKey is denied.
+ */
+export const defineSigningKeySmokeProbe = (): QPQConfig => [
+  defineSigningKey(SMOKE_PROBE_SIGNING_KEY, {
+    owner: { module: QpqjsServiceEnum.Test },
+  }),
+  defineServiceFunction(
+    {
+      basePath: __dirname,
+      relativePath: '../entry/serviceFunction/smokeCrossServiceSigningKeyProbe',
+      functionName: 'smokeCrossServiceSigningKeyProbe',
+    },
+    { functionName: SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME }
+  ),
+];

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/signingKey/config/index.ts

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

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/signingKey/entry/index.ts

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

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/signingKey/entry/serviceFunction/index.ts

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

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/signingKey/index.ts

@@ -0,0 +1,3 @@
+export * from './config';
+export * from './entry';
+export * from './logic';

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/signingKey/logic/index.ts

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

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/storageDrive/config/defineStorageDriveSmokeProbe.ts

@@ -0,0 +1,31 @@
+import {
+  defineServiceFunction,
+  defineStorageDrive,
+  QPQConfig,
+} from 'quidproquo';
+
+import {
+  QpqjsServiceEnum,
+  SMOKE_CROSS_SERVICE_STORAGE_DRIVE_PROBE_FUNCTION_NAME,
+  SMOKE_PROBE_DRIVE,
+} from '@qpqjs/constants';
+
+/**
+ * The test service's probe drive declared FOREIGN (owned by test), which is
+ * what grants this service's role exact-ARN access to it, plus the service
+ * function the test service's crossServiceStorageDrive test invokes.
+ */
+export const defineStorageDriveSmokeProbe = (): QPQConfig => [
+  defineStorageDrive(SMOKE_PROBE_DRIVE, {
+    owner: { module: QpqjsServiceEnum.Test },
+  }),
+  defineServiceFunction(
+    {
+      basePath: __dirname,
+      relativePath:
+        '../entry/serviceFunction/smokeCrossServiceStorageDriveProbe',
+      functionName: 'smokeCrossServiceStorageDriveProbe',
+    },
+    { functionName: SMOKE_CROSS_SERVICE_STORAGE_DRIVE_PROBE_FUNCTION_NAME }
+  ),
+];

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/storageDrive/config/index.ts

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

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/storageDrive/entry/index.ts

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

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/storageDrive/entry/serviceFunction/index.ts

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

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

@@ -0,0 +1,3 @@
+export * from './config';
+export * from './entry';
+export * from './logic';

package/template/apps/qpqjs/services/testa/service/src/smoke/suites/storageDrive/logic/index.ts

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

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

@@ -53,7 +53,7 @@ function* askKeyValueStoreDelete(
 | --- | --- |
 | `KeyValueStoreDeleteErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreDeleteErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
-| `KeyValueStoreDeleteErrorTypeEnum.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). |
+| `KeyValueStoreDeleteErrorTypeEnum.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 `@@QPQ` marker (reserved on string-pk stores, so unscoped calls reject it too). |
 | `KeyValueStoreDeleteErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.

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

@@ -55,7 +55,7 @@ function* askKeyValueStoreGetAll<Value>(
 | --- | --- |
 | `KeyValueStoreGetAllErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreGetAllErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
-| `KeyValueStoreGetAllErrorTypeEnum.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 a scoped call's partition-key value contains the reserved `@@QPQSCOPE@@` delimiter. |
+| `KeyValueStoreGetAllErrorTypeEnum.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 a scoped call's partition-key value contains the reserved `@@QPQ` marker. |
 | `KeyValueStoreGetAllErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.

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

@@ -57,7 +57,7 @@ function* askKeyValueStoreGet<Value>(
 | --- | --- |
 | `KeyValueStoreGetErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreGetErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
-| `KeyValueStoreGetErrorTypeEnum.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). |
+| `KeyValueStoreGetErrorTypeEnum.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 `@@QPQ` marker (reserved on string-pk stores, so unscoped calls reject it too). |
 | `KeyValueStoreGetErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an object — `{ success: true, result }` on success, or `{ success: false, error }` on failure:

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

@@ -52,6 +52,7 @@ function* askKeyValueStoreQuery<KvsItem>(
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
 | `filter` | `KvsQueryOperation` | – | An extra condition applied to non-key attributes **after** the key match. Filtered-out rows still count against `limit`. |
+| `indexName` | `string` | – | Force the query onto the [index](../../../config/core/key-value-store.md#indexes-gsis) declared with this name, read in its sort order. Without it, the table serves the query if its keys cover the key condition, otherwise the first declared index whose keys do — so an index sharing the table's keys is only reached by naming it here. An undeclared name throws `IndexNotFound`. |
 | `sortAscending` | `boolean` | `true` | Order results by the sort key. `false` returns the newest/highest first. |
 | `limit` | `number` | – | Maximum number of records to return in this page. |
 | `nextPageKey` | `string` | – | Opaque cursor from a previous page's `nextPageKey`; pass it to fetch the following page. |
@@ -118,8 +119,9 @@ When `nextPageKey` is set, pass it back as `options.nextPageKey` to fetch the ne
 | --- | --- |
 | `KeyValueStoreQueryErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreQueryErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
-| `KeyValueStoreQueryErrorTypeEnum.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, a scoped query's key condition does not constrain the partition key (or constrains it with an operator that cannot be scoped), or a partition-key condition value contains the reserved `@@QPQSCOPE@@` delimiter (reserved on string-pk stores, so unscoped queries reject it too). |
+| `KeyValueStoreQueryErrorTypeEnum.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, a scoped query's key condition does not constrain the partition key or an [index](../../../config/core/key-value-store.md#indexes-gsis) partition key (or constrains one with an operator that cannot be scoped: an index partition key only takes `=`), a condition names an attribute containing `@@QPQ`, an index partition-key condition value doesn't match that index's declared type, or a partition-key condition value contains the reserved `@@QPQ` marker (reserved on string-pk stores, so unscoped queries reject it too). |
 | `KeyValueStoreQueryErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
+| `KeyValueStoreQueryErrorTypeEnum.IndexNotFound` | The `indexName` option names an index the store doesn't declare. |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.
 

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

@@ -70,7 +70,7 @@ When `nextPageKey` is set, pass it back as the third argument to fetch the next
 | --- | --- |
 | `KeyValueStoreScanErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreScanErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
-| `KeyValueStoreScanErrorTypeEnum.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 a scoped call's partition-key value contains the reserved `@@QPQSCOPE@@` delimiter. |
+| `KeyValueStoreScanErrorTypeEnum.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, a scoped call's partition-key value contains the reserved `@@QPQ` marker, a scoped call's `filterCondition` names an attribute containing `@@QPQ`, or a scoped `filterCondition`'s partition-key comparison uses an operator that cannot be scoped. |
 | `KeyValueStoreScanErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.

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

@@ -101,7 +101,7 @@ Each `path` is a `KvsAttributePath` — either a top-level attribute name (`'bal
 | --- | --- |
 | `KeyValueStoreUpdateErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
 | `KeyValueStoreUpdateErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
-| `KeyValueStoreUpdateErrorTypeEnum.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). |
+| `KeyValueStoreUpdateErrorTypeEnum.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, the partition-key value contains the reserved `@@QPQ` marker (reserved on string-pk stores, so unscoped calls reject it too), a scoped update names an attribute containing `@@QPQ`, or a scoped update targets an [index](../../../config/core/key-value-store.md#indexes-gsis) partition key with anything other than a whole-value `Set`/`SetIfNotExists`/`Remove` of the declared type (`Increment`, `Add`, `Delete`, and nested paths are refused). |
 | `KeyValueStoreUpdateErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.

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

@@ -61,7 +61,7 @@ function* askKeyValueStoreUpsert<KvsItem>(
 | `KeyValueStoreUpsertErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
 | `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.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, the partition-key value contains the reserved `@@QPQ` marker (reserved on string-pk stores, so unscoped calls reject it too), a scoped item has an attribute name containing `@@QPQ`, or a scoped item's [index](../../../config/core/key-value-store.md#indexes-gsis) partition-key value doesn't match that index's declared type. |
 | `KeyValueStoreUpsertErrorTypeEnum.StoreNotFound` | The key value store is not declared in the qpq config (misconfiguration, e.g. a wrong name or a missing `defineKeyValueStore`). |
 
 Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.

package/template/docusaurus/docs/config/core/key-value-store.md

@@ -83,7 +83,7 @@ defineKeyValueStore('events', kvsKey('deviceId'), [kvsKey('timestamp', 'number')
 
 ## Indexes (GSIs)
 
-Each entry in `options.indexes` is a `CompositeKvsIndex<T>` — either a bare attribute name (a partition-key-only index) or an object with a `partitionKey` and optional `sortKey`:
+Each entry in `options.indexes` is a `CompositeKvsIndex<T>` — either a bare attribute name (a partition-key-only index) or an object with a `partitionKey`, optional `sortKey`, and optional `name`:
 
 ```typescript
 import { defineKeyValueStore, kvsKey } from 'quidproquo-core';
@@ -94,11 +94,21 @@ defineKeyValueStore('orders', 'orderId', [], {
     { partitionKey: 'customerId', sortKey: kvsKey('createdAt', 'number') },
     // Query orders by status (partition-only index)
     'status',
+    // Two indexes on the same partition key need an explicit name
+    { name: 'byStatusAndTotal', partitionKey: 'status', sortKey: kvsKey('total', 'number') },
   ],
 });
 ```
 
-On AWS each index becomes a Global Secondary Index whose name is the index's partition-key attribute (`customerId`, `status` above).
+`name` defaults to the partition-key attribute (`customerId`, `status` above) and is what [askKeyValueStoreQuery](../../actions/core/key-value-store/ask-key-value-store-query.md)'s `indexName` option targets; `defineKeyValueStore` throws if two indexes resolve to the same name. On AWS each index becomes a Global Secondary Index deployed under this name.
+
+A query without `indexName` runs against the table if its keys cover every attribute in the key condition, otherwise the first declared index whose keys do.
+
+### Indexes on a scoped store
+
+A store with `scoped: true` (see [`scoped`](#options--qpqconfigadvancedkeyvaluestoresettingst-optional)) can still declare `indexes`. On AWS, an index whose partition key isn't the table's partition key is keyed on a hidden `@@QPQGSI_<attribute>@@` attribute holding the scope-composed value; the index keeps its declared name and sort key, and stories never see the hidden attribute. A scoped store's index partition key must be a `'string'` or `'number'` key, since a scope can't be composed onto a `'binary'` key — `defineKeyValueStore` throws at config time otherwise.
+
+Adding or removing an index on an already-deployed scoped store needs two deploys: remove the index and deploy, then re-add it and deploy. CloudFormation can't change a GSI's key schema in place, and rows written before the new index exists only appear in it once they're rewritten.
 
 ## Change data capture (`onStream`)
 

package/template/docusaurus/docs/config/features/event-doc.md

@@ -25,7 +25,7 @@ export default [
 
 ## Registering a collection's functions
 
-`functions` is an `EventDocFunctions` object: `{ storeName, type, foldSnapshotViews, foldDocumentState, collectReferences, collectReferencesFromState, validateEvent, render? }`. The object `createEventDocDefinition` returns — given `storeName`/`type` in its config — satisfies this shape directly, so a collection with no service-only render can register its definition verbatim. A collection that needs a render step only service code can perform (resolving linked docs, reading blob-drive assets) layers it on with `extendEventDocFunctions(definition, { render })`, which returns a new object and never mutates the definition itself.
+`functions` is an `EventDocFunctions` object: `{ storeName, type, getSnapshotCacheKey, foldSnapshotViews, foldDocumentState, collectReferences, collectReferencesFromState, validateEvent, render? }`. The object `createEventDocDefinition` returns — given `storeName`/`type` in its config — satisfies this shape directly, so a collection with no service-only render can register its definition verbatim. A collection that needs a render step only service code can perform (resolving linked docs, reading blob-drive assets) layers it on with `extendEventDocFunctions(definition, { render })`, which returns a new object and never mutates the definition itself.
 
 `runtime` is a [`QpqFunctionRuntime`](../core/dynamic-functions.md#runtime--qpqfunctionruntime-required) path to that SAME export — the dynamic-functions pattern: identity is read off the object here at config time, behaviour is loaded from the path by the processors at request time. Both must point at the exact object being registered, or the registration and the runtime will disagree about what the collection can do.
 
@@ -55,6 +55,7 @@ The collection's callable surface, read for its identity (`storeName`, `type`) a
 | --- | --- | --- | --- |
 | `storeName` | `string` | yes | Name of the summary store to create and serve. Also derives the events table and asset bucket names. |
 | `type` | `string` | yes | The document type this collection holds — the store's partition value, so one store can (via the split helpers) hold several types. |
+| `getSnapshotCacheKey` | `() => string` | yes | The key this collection's snapshots are filed under (see [Snapshot cache key](#snapshot-cache-key)). `''` is the legacy layout. A member rather than a value because the data layer reaches a definition only through dynamic functions. |
 | `foldSnapshotViews` | `(events, seedViews?) => Nullable<EventDocSnapshotViews>` | yes | Every view of a log prefix, era-pinned — what a snapshot stores. Invoked by the event store's stream projector (which also writes the summary row from the fold's `summary` view). |
 | `foldDocumentState` | `(events, seedState?) => unknown` | yes | The document view at one point, LATEST-shaped, resumable from a stored snapshot's era-pinned document state. The read side's fold: render, references, as-of reads, and the append hooks' state derivation all go through it. |
 | `collectReferences` | `(events) => EventDocLink[]` | yes | The `EventDocLink`s this doc's whole HISTORY depends on; `[]` for a leaf doc type. Invoked by the transfer manifest walk (it exports the whole history). |
@@ -62,6 +63,26 @@ The collection's callable surface, read for its identity (`storeName`, `type`) a
 | `validateEvent` | `(event, state) => Nullable<string> \| AskResponse<Nullable<string>>` | yes | The append pre-write gate: checked against the state the event will land on, before the write (see [askEventDocEventAppend](../../actions/features/event-doc/ask-event-doc-event-append.md)). Return a rejection reason string to refuse the append, `null` to allow it. A collection with no domain rules can pass `() => null`. |
 | `render` | `(input: EventDocRenderInput) => EventDocRenderResult \| AskResponse<EventDocRenderResult>` | no | Render the resolved, already-folded document state (`input.state`, resolved snapshot-seeded by the route). Omit and `GET {basePath}/{id}/render` 404s as "no renderer configured". Plain function or story — the dynamic-functions processor runs either. |
 
+#### Snapshot cache key
+
+A snapshot is a memo of "fold these events with this seed and reducer". The events are immutable, so the memo stays valid until the fold code changes. A change to the MEANING of existing events is a schema version bump with a migration. An additive change — a new defaulted field in a version's seed, a new event type, a new reducer case — needs no migration, but every stored snapshot is now the output of code you no longer run, and a reader resuming from one would see the old shape (a `undefined` where the new field should be).
+
+`snapshotCacheKey` on `createEventDocDefinition` names the fold code. It is part of the snapshot row's partition key (`docId#viewName#key`) and the offloaded blob's path, so after you change it every reader finds no snapshot, refolds the whole log from the seed, and the stream projector files a fresh snapshot under the new key on the document's next append. The bootstrap base handed to the editor carries the key too, so a workspace snapshot held in the browser across a deploy is refetched rather than trusted. Rows under an old key are left to persist.
+
+```typescript
+export const contentItemEventDoc = createEventDocDefinition({
+  storeName: CONTENT_STORE,
+  type: 'content',
+  schemaVersion: 1,
+  versions: [contentItemV1],
+  // Bump when v1's seed or reducer changes in place; every stored snapshot is then refolded.
+  snapshotCacheKey: '2026-09-23-image-assets',
+  api,
+});
+```
+
+Refolding is lazy: a document pays one whole-log fold per reader until its next append reprojects it. To pay that up front, an admin job can walk each collection's documents (inside each storage scope) and call `askEventDocReprojectHead(docId)`, which re-runs the projector at the log head under the current key.
+
 ### `runtime` — `QpqFunctionRuntime` (required)
 
 A reference to the module exporting `functions`, usually a relative path string of the form `'/path/to/file::exportedObjectName'` — see [defineDynamicFunctions](../core/dynamic-functions.md#runtime--qpqfunctionruntime-required). Must resolve to the SAME object passed as `functions`.