create-qpq-app 0.1.5

package/template/docusaurus/docs/config/core/event-bus.md

@@ -0,0 +1,88 @@
+---
+title: defineEventBus
+description: Define an event bus — a named pub/sub topic that stories publish messages to and queues subscribe to.
+---
+
+# defineEventBus
+
+Defines an **event bus**: a named publish/subscribe channel. Stories publish messages to a bus by name with [askEventBusSendMessages](../../actions/core/event-bus/ask-event-bus-send-messages.md); any number of [queues](./queue.md) subscribe to the bus (via their `eventBusSubscriptions` option) and their consumer stories run for each delivered message. Publishers never know who is listening.
+
+- **On AWS:** deploys an **SNS topic** (`QpqCoreEventBusConstruct` in `quidproquo-deploy-awscdk`). The topic allows cross-account subscription and lets CloudWatch alarms publish to it. When `isFifo` is `true` a FIFO SNS topic is created (`.fifo` suffix); content-based deduplication is left off (dedup ids are set explicitly at publish time). Subscriptions are wired up from the subscribing queue's side.
+
+```typescript
+import { defineEventBus } from 'quidproquo-core';
+
+export default [
+  defineEventBus('domain-events'),
+];
+```
+
+## Signature
+
+```typescript
+function defineEventBus(
+  name: string,
+  options?: QPQConfigAdvancedEventBusSettings,
+): EventBusQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The name of the bus. This is the name you pass to [askEventBusSendMessages](../../actions/core/event-bus/ask-event-bus-send-messages.md) and the name queues reference in their `eventBusSubscriptions`. It is the bus's `uniqueKey`, and on AWS it derives the physical topic name (prefixed with application/module/environment so the same config deploys cleanly to multiple environments).
+
+### `options` — `QPQConfigAdvancedEventBusSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `isFifo` | `boolean` | `false` | Creates a **FIFO** event bus that preserves per-group ordering and supports message deduplication. See [FIFO event buses](#fifo-event-buses). |
+| `owner` | `CrossModuleOwner<'eventBusName'>` | – | Declares that this bus is owned by **another** module/service. Use this to publish to a bus deployed elsewhere: the deploy grants this service IAM publish access to the foreign topic instead of creating a new one. `{ module, application, feature, environment, eventBusName }` — all optional; unset parts default to the current service. |
+| `deprecated` | `boolean` | `false` | Marks the bus as deprecated in the config. |
+
+## FIFO event buses
+
+Setting `isFifo: true` deploys a FIFO SNS topic. Ordering and deduplication are then controlled per message when you publish, via the `groupId` and `deduplicationId` fields on each `EventBusMessage` (see [askEventBusSendMessages](../../actions/core/event-bus/ask-event-bus-send-messages.md)):
+
+- Messages with the same `groupId` are delivered in order. If you don't set one, it defaults to the bus name (global ordering across the whole bus).
+- `deduplicationId` suppresses duplicate publishes within SNS's 5-minute window. If you don't set one, a unique id is generated per send (no deduplication).
+
+On the consuming side, a FIFO queue subscribed to a FIFO bus processes records one group at a time using [askProcessEventWithGroupOrdering](../../actions/core/event/ask-process-event.md), so a failed message blocks only its own group.
+
+Note: FIFO SNS topics only support SQS subscriptions — direct email/URL fan-out (`defineEventBusQuickSubscription`, an AWS-specific setting) is rejected at deploy time for a FIFO bus. A FIFO queue may only subscribe to a FIFO bus (validated at deploy).
+
+## Examples
+
+```typescript
+import { defineEventBus, defineQueue } from 'quidproquo-core';
+
+export default [
+  // A standard fan-out bus
+  defineEventBus('domain-events'),
+
+  // A FIFO bus for ordered, per-entity event streams
+  defineEventBus('account-events', { isFifo: true }),
+
+  // Publish to a bus owned by another service
+  defineEventBus('billing-events', {
+    owner: { module: 'billing-service' },
+  }),
+
+  // A queue that consumes from the bus
+  defineQueue('domain-events-consumer', {
+    'user.created': '/entry/queue/onUserCreated::onUserCreated',
+  }, {
+    eventBusSubscriptions: ['domain-events'],
+  }),
+];
+```
+
+## Related
+
+- [askEventBusSendMessages](../../actions/core/event-bus/ask-event-bus-send-messages.md) — publishes messages to a bus declared here.
+- [defineQueue](./queue.md) — declares a queue that subscribes to a bus via `eventBusSubscriptions`.
+- [askProcessEvent](../../actions/core/event/ask-process-event.md) — the pipeline that dispatches delivered messages to consumer stories (and preserves FIFO group ordering).
+- [defineRecurringSchedule](./recurring-schedule.md) and [defineNotifyError](./notify-error.md) — other event sources; a notify-error publishes alarm-state changes to a bus declared here.
+- [defineEventBusQuickSubscription](../config-aws/event-bus-quick-subscription.md) — attach direct SNS email/webhook subscribers to a bus on AWS (no compute), for using it as an alert channel.
+- [defineAwsAlarm](../config-aws/aws-alarm.md) — publishes CloudWatch alarm state to a bus via `onAlarm.publishToEventBus`.
+- **AWS implementation:** `QpqCoreEventBusConstruct` (SNS topic, subscriptions, IAM) in `quidproquo-deploy-awscdk`; the send-message processor in `quidproquo-actionprocessor-awslambda`.

package/template/docusaurus/docs/config/core/federated-module-store.md

@@ -0,0 +1,61 @@
+---
+title: defineFederatedModuleStore
+description: Define a federated module store — opt a service into loading its story code from a storage drive at runtime instead of only from its bundled Lambda zips.
+---
+
+# defineFederatedModuleStore
+
+Defines a **federated module store**: it opts a service into loading its story code as **federated modules** from a [storage drive](./storage-drive.md) at runtime, instead of running only the code statically bundled into its Lambda zips. This lets you publish new story code to the store and have running services pick it up without redeploying the infrastructure — the compute stays fixed while the behaviour is swapped underneath it. Many services can share one store bucket, each namespaced under its own prefix.
+
+- **On AWS:** no new resource of its own — it reuses the referenced storage drive's S3 bucket. At deploy time the service's Lambdas are pointed at `s3://<bucket>/<serviceName>` via environment variables (`federatedCodeStoreUrl`, and `federatedCodeStoreRecheckMs` when set), computed by `getFederatedCodeStoreEnv` in `quidproquo-deploy-awscdk`. Read access comes from the storage drive's own IAM grants — nothing extra is created. If the referenced storage drive doesn't exist, the deploy fails fast. The Lambda's module loader polls the store and falls back to bundled modules when nothing is published (unless `bundleFallback` is `false`).
+
+```typescript
+import { defineStorageDrive, defineFederatedModuleStore } from 'quidproquo-core';
+
+export default [
+  defineStorageDrive('module-store'),
+  defineFederatedModuleStore('module-store'),
+];
+```
+
+## Signature
+
+```typescript
+function defineFederatedModuleStore(
+  storageDrive: string,
+  options?: FederatedModuleStoreOptions,
+): FederatedModuleStoreQPQConfigSetting;
+```
+
+## Parameters
+
+### `storageDrive` — `string` (required)
+
+The name of a [storage drive](./storage-drive.md) the service already declares — either an owned drive or a foreign drive (with `owner` set) to share one bucket across services. The deploy layer resolves that drive's bucket and points the Lambdas at `<bucket>/<serviceName>`, so each service's federated artifacts live under its own service prefix. There is only ever one federated module store per service (its `uniqueKey` is the fixed value `'FederatedModuleStore'`).
+
+### `options` — `FederatedModuleStoreOptions` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `recheckMs` | `number` | `60000` | How often (in ms) a warm Lambda re-checks the store for a newly published version. Lower means faster pickup at the cost of one small S3 GET per container per interval. Set low (e.g. `5000`) while testing to see changes quickly. |
+| `bundleFallback` | `boolean` | `true` | When `true` (default), the service's story code is **also** bundled into the Lambda zip, so an empty or unpublished store falls back to it. Set `false` for a **thin shell**: story code is not bundled (smaller zips) and the service runs only federated code — an unpublished store fails fast instead of silently serving stale bundled code. Thin shells require the federated remote to be published before they work. |
+
+## Examples
+
+```typescript
+import { defineStorageDrive, defineFederatedModuleStore } from 'quidproquo-core';
+
+export default [
+  // Fast pickup while iterating, keeping the bundled code as a fallback
+  defineStorageDrive('module-store'),
+  defineFederatedModuleStore('module-store', { recheckMs: 5000 }),
+
+  // Thin shell: run ONLY published federated code, no bundled fallback
+  defineFederatedModuleStore('module-store', { bundleFallback: false }),
+];
+```
+
+## Related
+
+- [defineStorageDrive](./storage-drive.md) — declares the drive whose bucket backs the federated module store.
+- **AWS implementation:** `getFederatedCodeStoreEnv` (Lambda environment wiring) in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/core/global.md

@@ -0,0 +1,43 @@
+---
+title: defineGlobal
+description: Define a global — a named, typed, constant value baked into the application config and read at runtime.
+---
+
+# defineGlobal
+
+Declares a **global**: a named, typed, constant value stored directly in the application config. Unlike a [secret](./secret.md) or [parameter](./parameter.md) — which live in an external store — a global's value is baked into the resolved config, so reading it involves no network call and works on every runtime, including local JS execution. Stories read it with [askConfigGetGlobal](../../actions/core/config/ask-config-get-global.md).
+
+Use a global for a fixed value that belongs in config rather than hard-coded in a story and never changes at runtime.
+
+```typescript
+import { defineGlobal } from 'quidproquo-core';
+
+export default [
+  defineGlobal('feature-limits', { maxUploadsPerDay: 100 }),
+  defineGlobal('support-email', 'help@example.com'),
+];
+```
+
+## Signature
+
+```typescript
+function defineGlobal<T>(
+  key: string,
+  value: T,
+): GlobalQPQConfigSetting<T>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | The name of the global, and its `uniqueKey` within the config. This is the name you pass to [askConfigGetGlobal](../../actions/core/config/ask-config-get-global.md). |
+| `value` | `T` | The value to store. Any JSON-serializable type — string, number, object, array. `T` is inferred from what you pass and flows through to the read action's return type. |
+
+## Related
+
+- [askConfigGetGlobal](../../actions/core/config/ask-config-get-global.md) — reads the global at runtime.
+- [defineParameter](./parameter.md) — for values that change at runtime.
+- [defineSecret](./secret.md) — for sensitive values.
+- [defineApplicationVersion](./application-version.md) — a specialised global that records the service's version string.
+- [defineWebSocketQueue](../webserver/web-socket-queue.md) — stores its event-bus and user-directory names in globals like these.

package/template/docusaurus/docs/config/core/graph-database.md

@@ -0,0 +1,72 @@
+---
+title: defineGraphDatabase
+description: Define a graph database — a named graph store that stories query with openCypher.
+---
+
+# defineGraphDatabase
+
+Defines a **graph database**: a named graph store that stories query using [openCypher](https://opencypher.org/). Stories never talk to the underlying engine directly — they run queries by name with [askGraphDatabaseExecuteOpenCypherQuery](../../actions/core/graph-database/ask-graph-database-execute-open-cypher-query.md), and the runtime maps the name to the real cluster.
+
+A graph database always lives inside a **virtual network** (VPC). You must declare that network separately and pass its name as the second argument — the database is deployed into it and is only reachable from workloads (lambdas) attached to the same network.
+
+- **On AWS:** deploys an Amazon Neptune Serverless cluster (`QpqCoreApiGraphDatabaseConstruct` in `quidproquo-deploy-awscdk`). The cluster is placed in the private subnets of the named virtual network's VPC, scales serverlessly (1–2.5 NCUs), exports audit logs to CloudWatch (one-week retention), and is reachable only from lambdas carrying the network's workload security group. Data stores are retained via a final **snapshot** on stack teardown unless the service opts into destroy with `defineAwsDataStoreRemovalPolicy`.
+
+```typescript
+import { defineGraphDatabase } from 'quidproquo-core';
+
+export default [
+  defineGraphDatabase('social-graph', 'main-network'),
+];
+```
+
+## Signature
+
+```typescript
+function defineGraphDatabase(
+  name: string,
+  virualNetworkName: string,
+  options?: QPQConfigAdvancedGraphDatabaseSettings,
+): GraphDatabaseQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The name of the graph database. This is the name you pass as the first argument to [askGraphDatabaseExecuteOpenCypherQuery](../../actions/core/graph-database/ask-graph-database-execute-open-cypher-query.md). It is also the database's `uniqueKey` within the config, and on AWS it is used to derive the physical Neptune cluster name (prefixed with application/module/environment, so the same config deploys to multiple environments without collisions).
+
+### `virualNetworkName` — `string` (required)
+
+The name of the **virtual network** (VPC) the database is deployed into. Only workloads attached to this same network can reach the cluster. This must match a virtual network declared for the service.
+
+> **Note:** the parameter is spelled `virualNetworkName` (missing the second "t") in the source. This has no effect on usage — you pass the network name as a plain string — but it is the literal property name on the config setting.
+
+### `options` — `QPQConfigAdvancedGraphDatabaseSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `owner` | `CrossModuleOwner<'graphDatabaseName'>` | – | Declares that this database is owned by **another** module/service. Use this to query a database deployed elsewhere: the deploy grants this service access to the foreign cluster instead of creating a new one. `{ module, application, feature, environment, graphDatabaseName }` — all optional; unset parts default to the current service. |
+
+## Examples
+
+```typescript
+import { defineGraphDatabase } from 'quidproquo-core';
+
+export default [
+  // A graph database in this service's own network
+  defineGraphDatabase('social-graph', 'main-network'),
+
+  // Query a graph database owned by another module
+  defineGraphDatabase('shared-graph', 'main-network', {
+    owner: { module: 'graph-service' },
+  }),
+];
+```
+
+## Related
+
+- [askGraphDatabaseExecuteOpenCypherQuery](../../actions/core/graph-database/ask-graph-database-execute-open-cypher-query.md) — run an openCypher query against a database defined here.
+- [defineVirtualNetwork](./virtual-network.md) — the private network an in-network graph database runs inside.
+- [defineGraphDatabaseNeo4j](../neo4j/graph-database-neo4j.md) — the same graph database action backed by Neo4j instead of Neptune.
+- **AWS tuning:** [defineAwsDataStoreRemovalPolicy](../config-aws/aws-data-store-removal-policy.md) — retain (via a final snapshot) vs destroy the Neptune cluster on teardown.
+- **AWS implementation:** `QpqCoreApiGraphDatabaseConstruct` (Neptune Serverless cluster, VPC placement, IAM grants) in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/core/inline-function.md

@@ -0,0 +1,61 @@
+---
+title: defineInlineFunction
+description: Register a story as a named inline function that other stories can invoke by name with askInlineFunctionExecute.
+---
+
+# defineInlineFunction
+
+Registers a story runtime as a named **inline function**. Once registered, any story can invoke it by name with [askInlineFunctionExecute](../../actions/core/inline-function/ask-inline-function-execute.md) and receive its return value. Inline functions run **in-process** inside the same runtime as the caller (as a nested story, one level deeper) — they are a way to name and reuse a story as a callable unit, not a separate deployed service.
+
+- **On AWS:** deploys **no dedicated infrastructure** of its own. The referenced story is loaded and executed inside whatever Lambda is already running the calling story, sharing its action processors and session context. Registration simply makes the runtime resolvable by name.
+
+```typescript
+import { defineInlineFunction } from 'quidproquo-core';
+
+export default [
+  defineInlineFunction('/entry/functions/calculateTax::calculateTax'),
+];
+```
+
+## Signature
+
+```typescript
+function defineInlineFunction(
+  runtime: QpqFunctionRuntime,
+  options?: QPQConfigAdvancedInlineFunctionSettings,
+): InlineFunctionQPQConfigSetting;
+```
+
+## Parameters
+
+### `runtime` — `QpqFunctionRuntime` (required)
+
+A reference to the story to register, usually a relative path string of the form `'/path/to/file::exportedFunctionName'`. This is the story that runs when the inline function is executed.
+
+### `options` — `QPQConfigAdvancedInlineFunctionSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `functionName` | `string` | derived from `runtime` | The name callers pass to [askInlineFunctionExecute](../../actions/core/inline-function/ask-inline-function-execute.md). If omitted, it is derived from the runtime reference (the story's exported name). This is the config's `uniqueKey`. |
+| `owner` | `CrossModuleOwner<'functionName'>` | – | Declares that the function is owned by **another** module/service, so it can be resolved/invoked across modules. `{ module, application, feature, environment, functionName }` — all optional; unset parts default to the current service. |
+| `deprecated` | `boolean` | `false` | Marks the function as deprecated in the config. |
+
+## Examples
+
+```typescript
+import { defineInlineFunction } from 'quidproquo-core';
+
+export default [
+  // Name derived from the story export ('calculateTax')
+  defineInlineFunction('/entry/functions/calculateTax::calculateTax'),
+
+  // Explicit name
+  defineInlineFunction('/entry/functions/pricing::run', {
+    functionName: 'computePricing',
+  }),
+];
+```
+
+## Related
+
+- [askInlineFunctionExecute](../../actions/core/inline-function/ask-inline-function-execute.md) — invokes a registered inline function by name and returns its result.

package/template/docusaurus/docs/config/core/javascript-runtime.md

@@ -0,0 +1,79 @@
+---
+title: defineJavascriptRuntime
+description: Select the Node.js runtime version and CPU architecture the service's functions run on.
+---
+
+# defineJavascriptRuntime
+
+Selects the **JavaScript runtime version and CPU architecture** for the service's functions. The identifiers are cloud-agnostic; the deploy layer maps them to platform-specific values.
+
+Declare it once per service to pin the Node version and architecture. If you omit it, the service uses the defaults below.
+
+- **On AWS:** does not deploy a resource of its own, but every Lambda the service deploys is configured from it. The deploy layer maps `runtimeVersion` to an `aws_lambda.Runtime` (Node 20/22/24) and `architecture` to an `aws_lambda.Architecture` (`getLambdaRuntime` / `getLambdaArchitecture` in `quidproquo-deploy-awscdk`, via `qpqCoreUtils.getJavascriptRuntimeConfig`).
+
+```typescript
+import { defineJavascriptRuntime, JavascriptRuntimeVersion } from 'quidproquo-core';
+
+export default [
+  defineJavascriptRuntime({ runtimeVersion: JavascriptRuntimeVersion.Node24 }),
+];
+```
+
+## Signature
+
+```typescript
+function defineJavascriptRuntime(
+  options?: QPQConfigAdvancedJavascriptRuntimeSettings,
+): JavascriptRuntimeQPQConfigSetting;
+```
+
+## Parameters
+
+### `options` — `QPQConfigAdvancedJavascriptRuntimeSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `runtimeVersion` | `JavascriptRuntimeVersion` | `Node22` | The Node.js version the functions run on. |
+| `architecture` | `JavascriptRuntimeArchitecture` | `Arm64` | The CPU architecture the functions run on. |
+
+### `JavascriptRuntimeVersion`
+
+| Member | Value | AWS Lambda runtime |
+| --- | --- | --- |
+| `Node20` | `'node20'` | `NODEJS_20_X` |
+| `Node22` | `'node22'` | `NODEJS_22_X` (default) |
+| `Node24` | `'node24'` | `NODEJS_24_X` |
+
+### `JavascriptRuntimeArchitecture`
+
+| Member | Value | AWS Lambda architecture |
+| --- | --- | --- |
+| `Arm64` | `'arm64'` | `ARM_64` (default) |
+| `X86_64` | `'x86_64'` | `X86_64` |
+
+## Notes
+
+- When this setting is absent, the runtime resolver falls back to `defineJavascriptRuntime()` with no options, i.e. Node 22 on Arm64.
+
+## Examples
+
+```typescript
+import {
+  defineJavascriptRuntime,
+  JavascriptRuntimeVersion,
+  JavascriptRuntimeArchitecture,
+} from 'quidproquo-core';
+
+export default [
+  // Pin to Node 24 on x86_64
+  defineJavascriptRuntime({
+    runtimeVersion: JavascriptRuntimeVersion.Node24,
+    architecture: JavascriptRuntimeArchitecture.X86_64,
+  }),
+];
+```
+
+## Related
+
+- [defineApiBuildPath](./api-build-path.md) — the compiled code that runs on this runtime.
+- [defineApplicationModule](./application-module.md) — the identity and build-path settings usually declared alongside.

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

@@ -0,0 +1,135 @@
+---
+title: defineKeyValueStore
+description: Define a key-value store — a DynamoDB-style table with a partition key, optional sort keys, and secondary indexes that KVS actions read from and write to.
+---
+
+# defineKeyValueStore
+
+Defines a **key-value store**: a named, schema-light table addressed by a partition key and optional sort key(s). Stories never talk to DynamoDB directly — they read and write records on a store by name using the [Key-Value Store action requesters](../../actions/core/key-value-store/ask-key-value-store-get.md), and the runtime maps the store to real storage.
+
+- **On AWS:** deploys a DynamoDB table (`QpqCoreKeyValueStoreConstruct` in `quidproquo-deploy-awscdk`). The table uses **on-demand** billing (`PAY_PER_REQUEST`), the `partitionKey` becomes the table's partition (hash) key, the **first** entry in `sortKeys` becomes the table's sort (range) key, and each **additional** sort key becomes a **Local Secondary Index**. Every entry in `indexes` becomes a **Global Secondary Index** (its `indexName` is the index's partition-key attribute name). Point-in-time recovery (35-day continuous backups) is on by default, `ttlAttribute` maps to the table's TTL attribute, and read/write-throttle CloudWatch alarms are attached. The table is retained on stack teardown unless the service opts into destroy via `defineAwsDataStoreRemovalPolicy`.
+
+```typescript
+import { defineKeyValueStore } from 'quidproquo-core';
+
+export default [
+  // Partition key only
+  defineKeyValueStore('users', 'userId'),
+];
+```
+
+## Signature
+
+```typescript
+function defineKeyValueStore<T extends object = any>(
+  keyValueStoreName: string,
+  partitionKey: CompositeKvsKey<T>,
+  sortKeys?: CompositeKvsKey<T>[],
+  options?: QPQConfigAdvancedKeyValueStoreSettings<T>,
+): KeyValueStoreQPQConfigSetting<T>;
+```
+
+## Parameters
+
+### `keyValueStoreName` — `string` (required)
+
+The name of the store. This is the name you pass as the first argument to every KVS action (e.g. `askKeyValueStoreGet('users', ...)`). It is also the store's `uniqueKey` within the config, and on AWS it is used to derive the physical table name (prefixed with application/module/environment, so the same config deploys to multiple environments without collisions).
+
+### `partitionKey` — `CompositeKvsKey<T>` (required)
+
+The partition (hash) key. Every record is addressed primarily by this attribute. See [Keys](#keys-compositekvskey) for the shorthand and full forms.
+
+### `sortKeys` — `CompositeKvsKey<T>[]` (default `[]`)
+
+Zero or more sort keys. The list is significant:
+
+- The **first** sort key becomes the table's sort (range) key — together with the partition key it forms the composite primary key, and it is what [askKeyValueStoreQuery](../../actions/core/key-value-store/ask-key-value-store-query.md) ranges over.
+- Each **additional** sort key becomes a **Local Secondary Index** (same partition key, alternate sort attribute), letting you query the same partition ordered by a different attribute.
+
+### `options` — `QPQConfigAdvancedKeyValueStoreSettings<T>` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `indexes` | `CompositeKvsIndex<T>[]` | `[]` | Global Secondary Indexes — alternate partition/sort key pairs that let you query the store by attributes other than the primary key. See [Indexes (GSIs)](#indexes-gsis). |
+| `global` | `boolean` | `false` | Marks the store as globally accessible across the account rather than private to the owning module. |
+| `owner` | `CrossModuleOwner` | – | Declares that this store is owned by **another** module/service. Use this to read/write a store deployed elsewhere: the deploy grants this service IAM access to the foreign table instead of creating a new one. |
+| `ttlAttribute` | `string` | – | Name of a record attribute holding a Unix-epoch (seconds) timestamp. DynamoDB automatically deletes records once that time passes. |
+| `disablePointInTimeRecovery` | `boolean` | `false` | Point-in-time recovery (35-day continuous backups / restore) is on by default; set this to opt out. |
+| `encryption` | `boolean` | `false` | Enables customer-managed KMS encryption for the table (the KMS key comes from the service's AWS config). When a customer-managed key isn't configured, AWS-managed encryption is used instead; when `false`, DynamoDB's default provider-managed encryption still applies. |
+
+## Keys (`CompositeKvsKey`)
+
+A key can be given in two forms:
+
+```typescript
+// Shorthand: just the attribute name — implies type 'string'
+defineKeyValueStore('users', 'userId');
+
+// Full form: name + explicit type, via the kvsKey() helper
+import { defineKeyValueStore, kvsKey } from 'quidproquo-core';
+
+defineKeyValueStore('events', kvsKey('deviceId'), [kvsKey('timestamp', 'number')]);
+```
+
+`kvsKey(key, type)` builds a `KvsKey` — `{ key, type }`. The `type` is a `KvsKeyType`:
+
+| `KvsKeyType` | Meaning |
+| --- | --- |
+| `'string'` | Textual key (default when using the shorthand form). |
+| `'number'` | Numeric key — sorts and ranges numerically. |
+| `'binary'` | Binary key. |
+
+## 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`:
+
+```typescript
+import { defineKeyValueStore, kvsKey } from 'quidproquo-core';
+
+defineKeyValueStore('orders', 'orderId', [], {
+  indexes: [
+    // Query orders by customer, ordered by createdAt
+    { partitionKey: 'customerId', sortKey: kvsKey('createdAt', 'number') },
+    // Query orders by status (partition-only index)
+    'status',
+  ],
+});
+```
+
+On AWS each index becomes a Global Secondary Index whose name is the index's partition-key attribute (`customerId`, `status` above).
+
+## Examples
+
+```typescript
+import { defineKeyValueStore, kvsKey } from 'quidproquo-core';
+
+export default [
+  // Simple lookup table keyed by id
+  defineKeyValueStore('users', 'userId'),
+
+  // Time-series: partition per device, ranged by numeric timestamp,
+  // with a TTL attribute so old rows expire automatically
+  defineKeyValueStore('device-readings', 'deviceId', [kvsKey('timestamp', 'number')], {
+    ttlAttribute: 'expiresAt',
+  }),
+
+  // Orders with a GSI to query by customer
+  defineKeyValueStore('orders', 'orderId', [], {
+    indexes: [{ partitionKey: 'customerId', sortKey: kvsKey('createdAt', 'number') }],
+  }),
+
+  // Encrypted store using a store owned by another service
+  defineKeyValueStore('billing', 'accountId', [], {
+    encryption: true,
+    owner: { module: 'billing-service' },
+  }),
+];
+```
+
+## Related
+
+- **Read a single record:** [askKeyValueStoreGet](../../actions/core/key-value-store/ask-key-value-store-get.md) · [askKeyValueStoreGetAll](../../actions/core/key-value-store/ask-key-value-store-get-all.md)
+- **Query & scan:** [askKeyValueStoreQuery](../../actions/core/key-value-store/ask-key-value-store-query.md) · [askKeyValueStoreScan](../../actions/core/key-value-store/ask-key-value-store-scan.md)
+- **Write:** [askKeyValueStoreUpsert](../../actions/core/key-value-store/ask-key-value-store-upsert.md) · [askKeyValueStoreUpdate](../../actions/core/key-value-store/ask-key-value-store-update.md) · [askKeyValueStoreDelete](../../actions/core/key-value-store/ask-key-value-store-delete.md)
+- **AWS tuning:** [defineAwsKmsKey](../config-aws/aws-kms-key.md) (customer-managed encryption key for the `encryption` flag), [defineAwsDyanmoOverrideForKvs](../config-aws/aws-dyanmo-override-for-kvs.md) (back the store with a pre-existing DynamoDB table), and [defineAwsDataStoreRemovalPolicy](../config-aws/aws-data-store-removal-policy.md) (retain vs destroy the table on teardown).
+- **AWS implementation:** `QpqCoreKeyValueStoreConstruct` (DynamoDB table, LSIs, GSIs, TTL, PITR, KMS, IAM grants) in `quidproquo-deploy-awscdk`; KVS action processors in `quidproquo-actionprocessor-awslambda`.

package/template/docusaurus/docs/config/core/module-name.md

@@ -0,0 +1,46 @@
+---
+title: defineModule
+description: Define the module name — the second half of a service's identity, used with the application name to scope every deployed resource.
+---
+
+# defineModule
+
+Declares the **module name** for a service. A quidproquo application is composed of one or more modules; the module name, combined with the [application identity](./application-name.md), forms the prefix used to name every resource the service deploys. Two modules of the same application therefore get distinct, non-colliding resource names.
+
+Most services do not call `defineModule` directly — [defineApplicationModule](./application-module.md) is the usual entry point, which declares the application, module, and [API build path](./api-build-path.md) in one step.
+
+- **On AWS:** does not deploy a resource of its own. The name is read by the deploy layer (`qpqCoreUtils.getApplicationModuleName`, via `getFullyQualifiedResourceName`) as the `module` segment of every physical resource name.
+
+```typescript
+import { defineModule } from 'quidproquo-core';
+
+export default [
+  defineModule('web'),
+];
+```
+
+## Signature
+
+```typescript
+function defineModule(
+  moduleName: string,
+): ModuleQPQConfigSetting;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `moduleName` | `string` | The module name, and this setting's `uniqueKey`. Part of every physical resource-name prefix and surfaced to stories via [askConfigGetApplicationInfo](../../actions/core/config/ask-config-get-application-info.md) (`module`). Resolved internally with `qpqCoreUtils.getApplicationModuleName`. |
+
+## Notes
+
+- A module must be declared before [defineServiceSettings](./service-settings.md) can be applied, because service settings are selected by the current module name.
+- Because `moduleName` is the setting's `uniqueKey`, a config should declare exactly one module identity.
+
+## Related
+
+- [defineApplication](./application-name.md) — the application half of the service identity.
+- [defineApplicationModule](./application-module.md) — the convenience that declares application, module, and API build path together.
+- [defineServiceSettings](./service-settings.md) — applies extra settings keyed by module (service) name.
+- [askConfigGetApplicationInfo](../../actions/core/config/ask-config-get-application-info.md) — reads the module name (and the rest of the service identity) from a story.