create-qpq-app 0.1.7 → 0.1.9

package/README.md

@@ -5,12 +5,12 @@ Scaffold a new [quidproquo](https://github.com/joe-coady/quidproquo) app:
 ```bash
 npx create-qpq-app my-app
 cd my-app
-npm run go:dev
+npm run dev
 ```
 
-You get a full QPQ workspace with five services — `admin`, `auth`, `design`,
-`shell` and `todo` — that builds, runs locally on the QPQ dev server, and
-deploys as a single docker image with `npm run go`.
+You get a full QPQ workspace with five services (`admin`, `auth`, `design`,
+`shell` and `todo`) that builds, runs locally on the QPQ dev server, and
+deploys as a single docker image with `npm run deploy`.
 
 ## Options
 

package/lib/commonjs/steps/013_printNextSteps.js

@@ -23,8 +23,8 @@ deploys as a single docker image.
 Next steps:
 
   cd ${answers.appName}
-${install}  npm run go:dev     # api on http://localhost:8080, web on http://localhost:3080
-  npm run go         # build the docker image (then run the printed docker command)
+${install}  npm run dev        # api on http://localhost:8080, web on http://localhost:3080
+  npm run deploy     # build the docker image (then run the printed docker command)
 
 Deploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).
 `);

package/lib/commonjs/steps/013_printNextSteps.js.map

@@ -1 +1 @@
-{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEa,QAAA,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAoB,EAAE,4CAAf,EAAE,OAAO,EAAE;QACrB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,gCAAgC,OAAO,CAAC,MAAM;CAC1F,CAAC,CAAC;IACD,CAAC,CAAA;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services — admin, auth, design, shell and todo — and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run go:dev     # api on http://localhost:8080, web on http://localhost:3080\n  npm run go         # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).\n`);\n  },\n};\n"]}
+{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEa,QAAA,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAoB,EAAE,4CAAf,EAAE,OAAO,EAAE;QACrB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,gCAAgC,OAAO,CAAC,MAAM;CAC1F,CAAC,CAAC;IACD,CAAC,CAAA;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services — admin, auth, design, shell and todo — and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run dev        # api on http://localhost:8080, web on http://localhost:3080\n  npm run deploy     # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).\n`);\n  },\n};\n"]}

package/lib/esm/steps/013_printNextSteps.js

@@ -11,8 +11,8 @@ deploys as a single docker image.
 Next steps:
 
   cd ${answers.appName}
-${install}  npm run go:dev     # api on http://localhost:8080, web on http://localhost:3080
-  npm run go         # build the docker image (then run the printed docker command)
+${install}  npm run dev        # api on http://localhost:8080, web on http://localhost:3080
+  npm run deploy     # build the docker image (then run the printed docker command)
 
 Deploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).
 `);

package/lib/esm/steps/013_printNextSteps.js.map

@@ -1 +1 @@
-{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACzB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,gCAAgC,OAAO,CAAC,MAAM;CAC1F,CAAC,CAAC;IACD,CAAC;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services — admin, auth, design, shell and todo — and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run go:dev     # api on http://localhost:8080, web on http://localhost:3080\n  npm run go         # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).\n`);\n  },\n};\n"]}
+{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACzB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,gCAAgC,OAAO,CAAC,MAAM;CAC1F,CAAC,CAAC;IACD,CAAC;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services — admin, auth, design, shell and todo — and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run dev        # api on http://localhost:8080, web on http://localhost:3080\n  npm run deploy     # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).\n`);\n  },\n};\n"]}

package/package.json

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

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

@@ -8,6 +8,7 @@ import {
   defineBootstrapWaf,
   defineDomainCertificate,
   WafManagedRuleGroup,
+  WafRuleOverrideAction,
 } from 'quidproquo-config-aws';
 import { QpqAppDeployContext } from 'quidproquo-deploy-awscdk';
 
@@ -20,6 +21,11 @@ export default ({ domain, region }: QpqAppDeployContext): QPQConfig => [
       WafManagedRuleGroup.knownBadInputs,
       WafManagedRuleGroup.sqli,
     ],
+    managedRuleOverrides: {
+      [WafManagedRuleGroup.common]: [
+        { name: 'SizeRestrictions_BODY', action: WafRuleOverrideAction.count }, // Disable the 8kb limit
+      ],
+    },
   }),
 
   defineApi('api', domain),

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

@@ -83,9 +83,29 @@ Within a step, text / reasoning / tool-input events arrive as matched `*Start
 | `Raw` (`raw`) | A provider-specific raw chunk, passed through for debugging. |
 | `Custom` (`custom`) | A provider-specific custom event identified by `kind`. |
 
+### `AiStreamFinishReasonEnum`
+
+`Finish.finishReason` and `FinishStep.finishReason` are an `AiStreamFinishReasonEnum` value, not a raw string.
+
+| Member | Wire value | Meaning |
+| --- | --- | --- |
+| `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. |
+| `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. |
+
 ## Errors
 
-Fatal failures throw `ErrorTypeEnum.GenericError`; non-fatal issues that arise mid-stream surface as `Error` (`error`) parts rather than throwing. Wrap the initial call with `askCatch` if the model may be unavailable.
+| Error | When |
+| --- | --- |
+| `ErrorTypeEnum.NotImplemented` | The `model` has no mapping to an underlying provider model id. |
+| `ErrorTypeEnum.NotFound` | `options.aiName` names an AI config that does not exist. |
+| `ErrorTypeEnum.GenericError` | Any failure while setting up the stream. |
+
+Non-fatal issues that arise mid-stream surface as `Error` (`error`) parts rather than throwing. Wrap the initial call with `askCatch` if the model may be unavailable.
 
 ## Related
 

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

@@ -8,7 +8,7 @@ description: Send a prompt to a large language model and get the full text respo
 Sends a prompt to a large language model and resolves with the model's complete text response. This is the buffered, non-streaming call — the story pauses until the model has finished generating, then resumes with the whole answer. If you want to consume tokens as they arrive, use [askAiPromptStream](./ask-ai-prompt-stream.md) instead.
 
 - **Action type:** `AiActionType.Prompt`
-- **On AWS:** runs through the [Vercel AI SDK](https://ai-sdk.dev) (`generateText`) against Amazon Bedrock. Any tools declared on the matching [defineAi](../../../config/core/ai.md) config are made available to the model, and the processor runs up to 10 tool-calling steps before returning.
+- **On AWS:** runs through the [Vercel AI SDK](https://ai-sdk.dev) (`generateText`) against Amazon Bedrock. Any tools declared on the matching [defineAi](../../../config/core/ai.md) config are made available to the model, and the processor runs up to 20 tool-calling steps before returning.
 
 ```typescript
 import { askAiPrompt, AiModel } from 'quidproquo-core';
@@ -85,7 +85,7 @@ type AiToolMessage      = { role: 'tool';      content: AiToolResultPart[] };
 | --- | --- | --- |
 | `text` | `text` | Plain text. |
 | `file` (URL) | `url`, `mediaType`, `filename?` | Attach a file by URL. |
-| `file` (drive) | `drive`, `filepath`, `mediaType`, `filename?` | Attach a file from a [storage drive](../../../config/core/storage-drive.md). The processor resolves the contents at prompt time, so no presigned URL ever lands in logs or session state. |
+| `file` (drive) | `drive`, `filepath`, `scope?`, `mediaType`, `filename?` | Attach a file from a [storage drive](../../../config/core/storage-drive.md). The processor resolves the contents at prompt time, so no presigned URL ever lands in logs or session state. Set `scope` when the file lives under a tenant scope; it is forwarded to the file read. |
 | `tool-call` | `toolCallId`, `toolName`, `input` | An assistant turn's request to call a tool. |
 | `reasoning` | `text`, `providerOptions?` | An assistant turn's thinking block. |
 | `tool-result` | `toolCallId`, `toolName`, `output`, `isError?` | The result you feed back for a tool call (in a `tool` message). |
@@ -104,7 +104,13 @@ interface AiReasoningConfig {
 
 ## Errors
 
-On any failure the processor throws `ErrorTypeEnum.GenericError` with the underlying provider message. Catch it with `askCatch`, which returns an `EitherActionResult` — `{ success: true, result }` or `{ success: false, error }`:
+| Error | When |
+| --- | --- |
+| `ErrorTypeEnum.NotImplemented` | The `model` has no mapping to an underlying provider model id. |
+| `ErrorTypeEnum.NotFound` | `options.aiName` names an AI config that does not exist. |
+| `ErrorTypeEnum.GenericError` | Any failure while generating, with the underlying provider message. |
+
+Catch failures with `askCatch`, which returns an `EitherActionResult` — `{ success: true, result }` or `{ success: false, error }`:
 
 ```typescript
 import { askCatch, askAiPrompt, AiModel } from 'quidproquo-core';

package/template/docusaurus/docs/actions/core/array/ask-flat-map-parallel-batch.md

@@ -47,7 +47,7 @@ function* askFlatMapParallelBatch<T, R>(
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
 | `items` | `T[]` | — | The array to iterate. |
-| `numBatch` | `number` | — | Batch size — the maximum number of items that run **concurrently** at once. |
+| `numBatch` | `number` | — | Batch size — the maximum number of items that run **concurrently** at once. Must be at least `1`; anything lower (including `NaN`) throws an `InvalidBatchSizeError` (code `notPositive`). |
 | `askCallback` | `(item: T, index: number, srcArray: T[]) => AskResponse<R[]>` | — | A generator called once per item. Receives the item, its zero-based index, and the source array, and returns an **array** of results. |
 | `delayAfterEachBatchMs` | `number` | `0` | Optional pause (in milliseconds) inserted after every batch, including the last — passed straight through to [askMapParallelBatch](./ask-map-parallel-batch.md). |
 

package/template/docusaurus/docs/actions/core/array/ask-map-parallel-batch.md

@@ -45,8 +45,8 @@ function* askMapParallelBatch<T, R>(
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
 | `items` | `T[]` | — | The array to iterate. |
-| `numBatch` | `number` | — | Batch size — the maximum number of items that run **concurrently** at once. The array is consumed `numBatch` items at a time; each slice runs in parallel and must finish before the next slice begins. |
-| `askCallback` | `(item: T, index: number, srcArray: T[]) => AskResponse<R>` | — | A generator called once per item. Receives the item, its zero-based index, and the source array. |
+| `numBatch` | `number` | — | Batch size — the maximum number of items that run **concurrently** at once. The array is consumed `numBatch` items at a time; each slice runs in parallel and must finish before the next slice begins. Must be at least `1`; anything lower (including `NaN`) throws an `InvalidBatchSizeError` (code `notPositive`) rather than looping forever. |
+| `askCallback` | `(item: T, index: number, srcArray: T[]) => AskResponse<R>` | — | A generator called once per item. Receives the item, its zero-based index in the **original** `items` array, and the original array itself (not the batch slice). |
 | `delayAfterEachBatchMs` | `number` | `0` | Optional pause (in milliseconds) inserted **after every batch**, including the last. When greater than `0`, the helper `yield*`s [askDelay](../platform/ask-delay.md) between batches — useful for spacing out calls to a throttled service. |
 
 ## Returns

package/template/docusaurus/docs/actions/core/date/date-time-math.md

@@ -20,7 +20,7 @@ export function* askSevenDaysFromNow() {
 ```
 
 :::note
-Pass a negative amount to move backward in time, e.g. `addDaysToTDateIso(now, -7)` returns the timestamp seven days ago. All helpers accept and return a plain `string`; the returned value is always normalised to UTC (`...Z`) by `toISOString()`.
+Pass a negative amount to move backward in time, e.g. `addDaysToTDateIso(now, -7)` returns the timestamp seven days ago. All helpers accept and return a plain `string`; the returned value is always normalised to UTC (`...Z`) by `toISOString()`. The arithmetic itself uses the UTC `Date` accessors, so the result never depends on the server's local timezone or its DST transitions.
 :::
 
 ## addMillisecondsToTDateIso
@@ -66,7 +66,7 @@ function addMonthsToTDateIso(startDate: string, numMonths: number): string;
 | `startDate` | `string` | The ISO-8601 timestamp to shift from. |
 | `numMonths` | `number` | Months to add (negative to subtract). |
 
-Returns a `string` — the shifted timestamp in UTC ISO-8601 form. Uses JavaScript's `Date.setMonth`, so day-of-month overflow rolls over: adding one month to `2026-01-31` yields early March, since February has no 31st.
+Returns a `string` — the shifted timestamp in UTC ISO-8601 form. Uses JavaScript's `Date.setUTCMonth`, so day-of-month overflow rolls over: adding one month to `2026-01-31` yields early March, since February has no 31st.
 
 ## addYearsToTDateIso
 

package/template/docusaurus/docs/actions/core/event/ask-process-event.md

@@ -65,7 +65,7 @@ Instead of processing records in parallel, it walks them **one at a time**. When
 
 ## The pipeline actions
 
-The individual `askEvent*` actions above are **extension points**, not story-author API — each service type implements them in its action-processor package (e.g. the HTTP API event processors in `quidproquo-webserver`). You compose stories that get *matched and executed* by this pipeline; you don't yield these actions directly. Related transform hooks used by specific service types include `askEventTransformEventParams`, `askEventTransformEventRecord`, and `askEventResolveCaughtError`.
+The individual `askEvent*` actions above are **extension points**, not story-author API — each service type implements them in its action-processor package (e.g. the HTTP API event processors in `quidproquo-webserver`). You compose stories that get *matched and executed* by this pipeline; you don't yield these actions directly. Related transform hooks used by specific service types include `askEventTransformEventParams`, `askEventTransformEventRecord`, `askEventTransformEventRecordResponse`, and `askEventResolveCaughtError`.
 
 ## Related
 

package/template/docusaurus/docs/actions/core/file/ask-file-delete.md

@@ -24,6 +24,7 @@ export function* askRemoveOldExports() {
 function* askFileDelete(
   drive: string,
   filepaths: string[],
+  scope?: string,
 ): AskResponse<string[]>;
 ```
 
@@ -33,6 +34,7 @@ function* askFileDelete(
 | --- | --- | --- |
 | `drive` | `string` | Name of the storage drive to delete from — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
 | `filepaths` | `string[]` | The paths of the files to delete within the drive, forward-slash delimited. Pass one path or many in a single call. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor deletes `{scope}/{filepath}` for every path in `filepaths`, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 ## Returns
 
@@ -44,6 +46,7 @@ function* askFileDelete(
 | --- | --- |
 | `FileDeleteErrorTypeEnum.AccessDenied` | The caller lacks permission to delete from this drive (e.g. a foreign drive shared without write access). |
 | `FileDeleteErrorTypeEnum.DriveNotFound` | No storage drive with that name exists in the deployed config. |
+| `FileDeleteErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or one of the scoped `filepaths` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

package/template/docusaurus/docs/actions/core/file/ask-file-exists.md

@@ -28,6 +28,7 @@ export function* askEnsureSeedFile() {
 function* askFileExists(
   drive: string,
   filepath: string,
+  scope?: string,
 ): AskResponse<boolean>;
 ```
 
@@ -37,6 +38,7 @@ function* askFileExists(
 | --- | --- | --- |
 | `drive` | `string` | Name of the storage drive to check — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
 | `filepath` | `string` | Path of the file within the drive, forward-slash delimited, e.g. `'uploads/avatar.png'`. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor checks `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 ## Returns
 
@@ -47,6 +49,7 @@ function* askFileExists(
 | Error | Meaning |
 | --- | --- |
 | `FileExistsErrorTypeEnum.AccessDenied` | The caller lacks permission to check existence on this drive. |
+| `FileExistsErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

package/template/docusaurus/docs/actions/core/file/ask-file-generate-temporary-secure-url.md

@@ -27,6 +27,7 @@ function* askFileGenerateTemporarySecureUrl(
   drive: string,
   filepath: string,
   expirationMs: number,
+  scope?: string,
 ): AskResponse<string>;
 ```
 
@@ -37,6 +38,7 @@ function* askFileGenerateTemporarySecureUrl(
 | `drive` | `string` | Name of the storage drive the file lives on — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
 | `filepath` | `string` | Path of the file within the drive, forward-slash delimited. |
 | `expirationMs` | `number` | How long the URL stays valid, in milliseconds. Must not exceed 7 days (`604800000` ms). |
+| `scope` | `string` | Optional storage-scope segment. When set, the signed URL targets `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 ## Returns
 
@@ -47,6 +49,7 @@ function* askFileGenerateTemporarySecureUrl(
 | Error | Meaning |
 | --- | --- |
 | `FileGenerateTemporarySecureUrlErrorTypeEnum.ExpirationTooLong` | The requested `expirationMs` exceeds the 7 day maximum for signed URLs. |
+| `FileGenerateTemporarySecureUrlErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

package/template/docusaurus/docs/actions/core/file/ask-file-generate-temporary-upload-secure-url.md

@@ -35,6 +35,7 @@ function* askFileGenerateTemporaryUploadSecureUrl(
   advancedOptions?: {
     contentType?: string;
   },
+  scope?: string,
 ): AskResponse<string>;
 ```
 
@@ -46,6 +47,7 @@ function* askFileGenerateTemporaryUploadSecureUrl(
 | `filepath` | `string` | Destination path within the drive the client is allowed to write to, forward-slash delimited. |
 | `expirationMs` | `number` | How long the URL stays valid, in milliseconds. Must not exceed 7 days (`604800000` ms). |
 | `advancedOptions` | `object` | Optional upload options — see below. |
+| `scope` | `string` | Optional storage-scope segment. When set, the signed URL targets `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 ### `advancedOptions`
 
@@ -62,6 +64,7 @@ function* askFileGenerateTemporaryUploadSecureUrl(
 | Error | Meaning |
 | --- | --- |
 | `FileGenerateTemporaryUploadSecureUrlErrorTypeEnum.ExpirationTooLong` | The requested `expirationMs` exceeds the 7 day maximum for signed URLs. |
+| `FileGenerateTemporaryUploadSecureUrlErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

package/template/docusaurus/docs/actions/core/file/ask-file-is-cold-storage.md

@@ -31,6 +31,7 @@ export function* askReadArchivableReport(filepath: string) {
 function* askFileIsColdStorage(
   drive: string,
   filepath: string,
+  scope?: string,
 ): AskResponse<boolean>;
 ```
 
@@ -40,6 +41,7 @@ function* askFileIsColdStorage(
 | --- | --- | --- |
 | `drive` | `string` | Name of the storage drive the file lives on — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
 | `filepath` | `string` | Path of the file within the drive, forward-slash delimited. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor checks `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 ## Returns
 
@@ -52,6 +54,7 @@ function* askFileIsColdStorage(
 | `FileIsColdStorageErrorTypeEnum.AccessDenied` | The caller lacks permission to read the file's metadata. |
 | `FileIsColdStorageErrorTypeEnum.FileNotFound` | No file exists at the given path. |
 | `FileIsColdStorageErrorTypeEnum.DriveNotFound` | No storage drive with that name exists in the deployed config. |
+| `FileIsColdStorageErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

package/template/docusaurus/docs/actions/core/file/ask-file-list-directory.md

@@ -32,6 +32,7 @@ function* askFileListDirectory(
   folderPath: string,
   maxFiles?: number,
   pageToken?: string,
+  scope?: string,
 ): AskResponse<DirectoryList>;
 ```
 
@@ -43,6 +44,7 @@ function* askFileListDirectory(
 | `folderPath` | `string` | The folder prefix to list under, forward-slash delimited, e.g. `'exports/'`. |
 | `maxFiles` | `number` | Maximum entries to return in this page. Defaults to `1000`. |
 | `pageToken` | `string` | Token returned by a previous call to fetch the next page. Omit for the first page. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor lists under `{scope}/{folderPath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Returned `filepath`s are relative to the scope, matching what you would pass back in. Must be a single path segment: no separators, `..`, or null bytes. |
 
 ## Returns
 
@@ -72,6 +74,7 @@ When `pageToken` is `undefined`, the last page has been returned.
 | `FileListDirectoryErrorTypeEnum.DirectoryNotFound` | No directory exists at the given `folderPath`. |
 | `FileListDirectoryErrorTypeEnum.NotADirectory` | The `folderPath` points at a file rather than a directory. |
 | `FileListDirectoryErrorTypeEnum.DriveNotFound` | No storage drive with that name exists in the deployed config. |
+| `FileListDirectoryErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `folderPath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 
@@ -87,7 +90,7 @@ if (outcome.success) {
 
 ## Notes
 
-- To pull **every** page in one call, use `askFileListAllDirectory(drive, folderPath)` — a companion requester exported from quidproquo-core that loops internally and returns a flat `FileInfo[]`. Prefer paging with `askFileListDirectory` for large directories.
+- To pull **every** page in one call, use `askFileListAllDirectory(drive, folderPath, scope?)` — a companion requester exported from quidproquo-core that loops internally and returns a flat `FileInfo[]`. Prefer paging with `askFileListDirectory` for large directories.
 
 ## Related
 

package/template/docusaurus/docs/actions/core/file/ask-file-read-binary-contents.md

@@ -26,6 +26,7 @@ export function* askGetLogo() {
 function* askFileReadBinaryContents(
   drive: string,
   filepath: string,
+  scope?: string,
 ): AskResponse<QPQBinaryData>;
 ```
 
@@ -35,6 +36,7 @@ function* askFileReadBinaryContents(
 | --- | --- | --- |
 | `drive` | `string` | Name of the storage drive to read from — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
 | `filepath` | `string` | Path of the file within the drive, forward-slash delimited. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor reads `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 ## Returns
 
@@ -55,6 +57,7 @@ interface QPQBinaryData {
 | --- | --- |
 | `FileReadBinaryContentsErrorTypeEnum.InvalidStorageClass` | The file is in a cold storage tier and cannot be read directly. Check first with [askFileIsColdStorage](./ask-file-is-cold-storage.md). |
 | `FileReadBinaryContentsErrorTypeEnum.FileNotFound` | No file exists at the given path. |
+| `FileReadBinaryContentsErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

package/template/docusaurus/docs/actions/core/file/ask-file-read-object-json.md

@@ -30,6 +30,7 @@ export function* askGetSettings() {
 function* askFileReadObjectJson<T extends object>(
   drive: string,
   filepath: string,
+  scope?: string,
 ): AskResponse<T>;
 ```
 
@@ -39,6 +40,7 @@ function* askFileReadObjectJson<T extends object>(
 | --- | --- | --- |
 | `drive` | `string` | Name of the storage drive to read from — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
 | `filepath` | `string` | Path of the JSON file within the drive, forward-slash delimited. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor reads `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 The type parameter `T` is the shape you expect the parsed JSON to have. It is a compile-time annotation only — the contents are not validated against it at runtime.
 
@@ -51,6 +53,9 @@ The type parameter `T` is the shape you expect the parsed JSON to have. It is a
 | Error | Meaning |
 | --- | --- |
 | `FileReadObjectJsonErrorTypeEnum.InvalidStorageClass` | The file is in a cold storage tier and cannot be read directly. Check first with [askFileIsColdStorage](./ask-file-is-cold-storage.md). |
+| `FileReadObjectJsonErrorTypeEnum.FileNotFound` | No file exists at the given `filepath` on the drive. |
+| `FileReadObjectJsonErrorTypeEnum.InvalidJson` | The file exists but its contents are not parseable JSON. |
+| `FileReadObjectJsonErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

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

@@ -24,6 +24,7 @@ export function* askGetWelcomeMessage() {
 function* askFileReadTextContents(
   drive: string,
   filepath: string,
+  scope?: string,
 ): AskResponse<string>;
 ```
 
@@ -33,6 +34,7 @@ function* askFileReadTextContents(
 | --- | --- | --- |
 | `drive` | `string` | Name of the storage drive to read from — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
 | `filepath` | `string` | Path of the file within the drive. Always use forward slashes, e.g. `'reports/2026/summary.txt'`. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor reads `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 ## Returns
 
@@ -43,6 +45,8 @@ function* askFileReadTextContents(
 | Error | Meaning |
 | --- | --- |
 | `FileReadTextContentsErrorTypeEnum.InvalidStorageClass` | The file is in a cold storage tier and cannot be read directly. Check first with `askFileIsColdStorage`. |
+| `FileReadTextContentsErrorTypeEnum.FileNotFound` | No file exists at the given `filepath` on the drive. |
+| `FileReadTextContentsErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

package/template/docusaurus/docs/actions/core/file/ask-file-stream-open.md

@@ -42,6 +42,7 @@ function* askFileStreamOpen<E extends StreamEncoding = 'text'>(
   filepath: string,
   encoding?: E,
   chunkSize?: number,
+  scope?: string,
 ): AskResponse<StreamHandle<E>>;
 ```
 
@@ -53,6 +54,7 @@ function* askFileStreamOpen<E extends StreamEncoding = 'text'>(
 | `filepath` | `string` | Path of the file within the drive, forward-slash delimited. |
 | `encoding` | `StreamEncoding` | How each chunk is decoded when you read it. `'text'` (default) yields `string`, `'binary'` yields `Uint8Array`, `'json'` parses each chunk. |
 | `chunkSize` | `number` | Bytes per chunk. Defaults to `65536` (64 KiB) in the AWS runtime. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor opens `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 `StreamEncoding` is `'text' | 'binary' | 'json'`.
 
@@ -75,6 +77,7 @@ The handle's `encoding` type parameter flows through to `askStreamRead`, so a `'
 | --- | --- |
 | `FileStreamOpenErrorTypeEnum.InvalidStorageClass` | The file is in a cold storage tier and cannot be streamed directly. Check first with [askFileIsColdStorage](./ask-file-is-cold-storage.md). |
 | `FileStreamOpenErrorTypeEnum.FileNotFound` | No file exists at the given path. |
+| `FileStreamOpenErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

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

@@ -30,6 +30,7 @@ function* askFileWriteBinaryContents(
   filepath: string,
   data: QPQBinaryData,
   storageDriveAdvancedWriteOptions?: StorageDriveAdvancedWriteOptions,
+  scope?: string,
 ): AskResponse<void>;
 ```
 
@@ -41,6 +42,7 @@ function* askFileWriteBinaryContents(
 | `filepath` | `string` | Destination path within the drive, forward-slash delimited. Parent "directories" are implicit — no need to create them. |
 | `data` | `QPQBinaryData` | The binary payload to write — see below. |
 | `storageDriveAdvancedWriteOptions` | `StorageDriveAdvancedWriteOptions` | Optional write options — see below. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor writes `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 ### `QPQBinaryData`
 
@@ -69,6 +71,7 @@ interface QPQBinaryData {
 | --- | --- |
 | `FileWriteBinaryContentsErrorTypeEnum.AccessDenied` | The caller lacks permission to write to this drive (e.g. a foreign drive shared without write access). |
 | `FileWriteBinaryContentsErrorTypeEnum.DriveNotFound` | No storage drive with that name exists in the deployed config. |
+| `FileWriteBinaryContentsErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

package/template/docusaurus/docs/actions/core/file/ask-file-write-object-json.md

@@ -31,6 +31,7 @@ function* askFileWriteObjectJson<T extends object>(
   filepath: string,
   data: T,
   storageDriveAdvancedWriteOptions?: StorageDriveAdvancedWriteOptions,
+  scope?: string,
 ): AskResponse<void>;
 ```
 
@@ -42,6 +43,7 @@ function* askFileWriteObjectJson<T extends object>(
 | `filepath` | `string` | Destination path within the drive, forward-slash delimited. Parent "directories" are implicit — no need to create them. |
 | `data` | `T` | The object to serialize and write. It is stored as `JSON.stringify(data)`. |
 | `storageDriveAdvancedWriteOptions` | `StorageDriveAdvancedWriteOptions` | Optional write options — see below. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor writes `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 ### `StorageDriveAdvancedWriteOptions`
 
@@ -59,6 +61,7 @@ function* askFileWriteObjectJson<T extends object>(
 | --- | --- |
 | `FileWriteObjectJsonErrorTypeEnum.AccessDenied` | The caller lacks permission to write to this drive (e.g. a foreign drive shared without write access). |
 | `FileWriteObjectJsonErrorTypeEnum.DriveNotFound` | No storage drive with that name exists in the deployed config. |
+| `FileWriteObjectJsonErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

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

@@ -25,6 +25,7 @@ function* askFileWriteTextContents(
   filepath: string,
   data: string,
   storageDriveAdvancedWriteOptions?: StorageDriveAdvancedWriteOptions,
+  scope?: string,
 ): AskResponse<void>;
 ```
 
@@ -36,6 +37,7 @@ function* askFileWriteTextContents(
 | `filepath` | `string` | Destination path within the drive, forward-slash delimited. Parent "directories" are implicit — no need to create them. |
 | `data` | `string` | The text content to write. |
 | `storageDriveAdvancedWriteOptions` | `StorageDriveAdvancedWriteOptions` | Optional write options — see below. |
+| `scope` | `string` | Optional storage-scope segment. When set, the processor writes `{scope}/{filepath}` instead, partitioning the drive (used by tenant/scoped features such as the event-doc `scopeResolver`). Must be a single path segment: no separators, `..`, or null bytes. |
 
 ### `StorageDriveAdvancedWriteOptions`
 
@@ -53,6 +55,7 @@ function* askFileWriteTextContents(
 | --- | --- |
 | `FileWriteTextContentsErrorTypeEnum.AccessDenied` | The caller lacks permission to write to this drive (e.g. a foreign drive shared without write access). |
 | `FileWriteTextContentsErrorTypeEnum.DriveNotFound` | No storage drive with that name exists in the deployed config. |
+| `FileWriteTextContentsErrorTypeEnum.InvalidScope` | The `scope` is not a valid single path segment (empty, `.`, too long, or contains separators, `..`, `:`, or null bytes), or the scoped `filepath` is absolute or contains `..` segments or null bytes. |
 
 ## Notes
 

package/template/docusaurus/docs/actions/core/graph-database/ask-graph-database-internal-field-names.md

@@ -44,7 +44,7 @@ None.
 
 ## Returns
 
-`GraphDatabaseInternalFieldNames` — a map of the engine's internal field-name tokens:
+`GraphDatabaseInternalFieldNames` (importable from quidproquo-core) — a map of the engine's internal field-name tokens:
 
 ```typescript
 type GraphDatabaseInternalFieldNames = {

package/template/docusaurus/docs/actions/core/json/ask-decode-json.md

@@ -56,6 +56,7 @@ The generic `T` is the expected shape of the decoded value; it is applied as a c
 | --- | --- |
 | The input is not valid JSON (`JSON.parse` throws). | `ErrorTypeEnum.Invalid` — the error text includes the underlying parser message. |
 | `validateObject` is supplied and returns `false`. | `ErrorTypeEnum.Invalid` — the error text notes the JSON parsed but failed structural validation. |
+| `validateObject` is supplied and throws. | `ErrorTypeEnum.Invalid`: the error text notes the JSON parsed but the validation function threw, and includes the thrown message. |
 
 Because these are thrown through the qpq error mechanism, catch them with `askCatch` from quidproquo-core, which returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
 

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

@@ -35,7 +35,13 @@ function* askKeyValueStoreDelete(
 | `keyValueStoreName` | `string` | Name of the store — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md) (or one shared via its `owner` option). |
 | `key` | `KvsCoreDataType` | Partition key value of the record to delete (`string \| number`). |
 | `sortKey` | `KvsCoreDataType` | Sort key value, required only if the store declares a sort key (`string \| number`). |
-| `options` | `KeyValueStoreDeleteOptions` | Reserved for future delete options; currently empty. |
+| `options` | `KeyValueStoreDeleteOptions` | Optional delete options (see below). |
+
+### `KeyValueStoreDeleteOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `scope` | `string` | – | Optional storage scope. The processor composes it into the partition key value, so the delete only addresses the record written under that scope (used by tenant/scoped features). Requires the store's partition key to be string-typed. |
 
 ## Returns
 
@@ -47,6 +53,8 @@ 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.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 }`.