quidproquo-core 0.1.24 → 0.1.26

package/lib/commonjs/actions/ai/askAiPrompt.d.ts

@@ -8,6 +8,15 @@ export type AskAiPromptOptions = {
     messages?: AiMessage[];
     reasoning?: AiReasoningConfig;
     caching?: boolean;
+    /** Stop the tool loop between steps once this much wall-clock time has passed. The
+     *  turn then finishes with `toolCalls` if the model still wanted to act, so it can be resumed. */
+    maxDurationMs?: number;
+    /** Cap on model/tool steps in one call. Unset means the loop runs until the model stops
+     *  (or `maxDurationMs` trips); client-side tools still halt it immediately. */
+    maxSteps?: number;
+    /** Output token cap per model call. Unset uses the provider default (8192 on Bedrock), which a
+     *  large tool input plus reasoning can exceed; the step then finishes with `length`. */
+    maxOutputTokens?: number;
 };
 export interface AiPromptActionResult {
     text: string;
@@ -20,4 +29,7 @@ export declare const askAiPrompt: import("../../types").ActionRequesterFunction<
     aiName: string | undefined;
     reasoning: AiReasoningConfig | undefined;
     caching: boolean | undefined;
+    maxDurationMs: number | undefined;
+    maxSteps: number | undefined;
+    maxOutputTokens: number | undefined;
 }, AiPromptActionResult, never>;

package/lib/commonjs/actions/ai/askAiPrompt.js

@@ -13,6 +13,9 @@ exports.askAiPrompt = (0, types_1.createActionRequester)()({
         aiName: options === null || options === void 0 ? void 0 : options.aiName,
         reasoning: options === null || options === void 0 ? void 0 : options.reasoning,
         caching: options === null || options === void 0 ? void 0 : options.caching,
+        maxDurationMs: options === null || options === void 0 ? void 0 : options.maxDurationMs,
+        maxSteps: options === null || options === void 0 ? void 0 : options.maxSteps,
+        maxOutputTokens: options === null || options === void 0 ? void 0 : options.maxOutputTokens,
     }),
 });
 //# sourceMappingURL=askAiPrompt.js.map

package/lib/commonjs/actions/ai/askAiPrompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"askAiPrompt.js","sourceRoot":"","sources":["../../../../src/actions/ai/askAiPrompt.ts"],"names":[],"mappings":";;;AAAA,uCAAoD;AACpD,iDAA8C;AAiBjC,QAAA,WAAW,GAAG,IAAA,6BAAqB,GAAwB,CAAC;IACvE,UAAU,EAAE,2BAAY,CAAC,MAAM;IAC/B,UAAU,EAAE,CAAC,KAAc,EAAE,MAAc,EAAE,OAA4B,EAAE,EAAE,CAAC,CAAC;QAC7E,KAAK;QACL,MAAM;QACN,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;QAC3B,MAAM,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM;QACvB,MAAM,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM;QACvB,SAAS,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS;QAC7B,OAAO,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO;KAC1B,CAAC;CACH,CAAC,CAAC","sourcesContent":["import { createActionRequester } from '../../types';\nimport { AiActionType } from './AiActionType';\nimport { AiMessage } from './AiMessage';\nimport { AiModel } from './AiModel';\nimport { AiReasoningConfig } from './AiReasoningConfig';\n\nexport type AskAiPromptOptions = {\n  system?: string;\n  aiName?: string;\n  messages?: AiMessage[];\n  reasoning?: AiReasoningConfig;\n  caching?: boolean;\n};\n\nexport interface AiPromptActionResult {\n  text: string;\n}\n\nexport const askAiPrompt = createActionRequester<AiPromptActionResult>()({\n  actionType: AiActionType.Prompt,\n  getPayload: (model: AiModel, prompt: string, options?: AskAiPromptOptions) => ({\n    model,\n    prompt,\n    messages: options?.messages,\n    system: options?.system,\n    aiName: options?.aiName,\n    reasoning: options?.reasoning,\n    caching: options?.caching,\n  }),\n});\n"]}
+{"version":3,"file":"askAiPrompt.js","sourceRoot":"","sources":["../../../../src/actions/ai/askAiPrompt.ts"],"names":[],"mappings":";;;AAAA,uCAAoD;AACpD,iDAA8C;AA0BjC,QAAA,WAAW,GAAG,IAAA,6BAAqB,GAAwB,CAAC;IACvE,UAAU,EAAE,2BAAY,CAAC,MAAM;IAC/B,UAAU,EAAE,CAAC,KAAc,EAAE,MAAc,EAAE,OAA4B,EAAE,EAAE,CAAC,CAAC;QAC7E,KAAK;QACL,MAAM;QACN,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;QAC3B,MAAM,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM;QACvB,MAAM,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM;QACvB,SAAS,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS;QAC7B,OAAO,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO;QACzB,aAAa,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,aAAa;QACrC,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;QAC3B,eAAe,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,eAAe;KAC1C,CAAC;CACH,CAAC,CAAC","sourcesContent":["import { createActionRequester } from '../../types';\nimport { AiActionType } from './AiActionType';\nimport { AiMessage } from './AiMessage';\nimport { AiModel } from './AiModel';\nimport { AiReasoningConfig } from './AiReasoningConfig';\n\nexport type AskAiPromptOptions = {\n  system?: string;\n  aiName?: string;\n  messages?: AiMessage[];\n  reasoning?: AiReasoningConfig;\n  caching?: boolean;\n  /** Stop the tool loop between steps once this much wall-clock time has passed. The\n   *  turn then finishes with `toolCalls` if the model still wanted to act, so it can be resumed. */\n  maxDurationMs?: number;\n  /** Cap on model/tool steps in one call. Unset means the loop runs until the model stops\n   *  (or `maxDurationMs` trips); client-side tools still halt it immediately. */\n  maxSteps?: number;\n  /** Output token cap per model call. Unset uses the provider default (8192 on Bedrock), which a\n   *  large tool input plus reasoning can exceed; the step then finishes with `length`. */\n  maxOutputTokens?: number;\n};\n\nexport interface AiPromptActionResult {\n  text: string;\n}\n\nexport const askAiPrompt = createActionRequester<AiPromptActionResult>()({\n  actionType: AiActionType.Prompt,\n  getPayload: (model: AiModel, prompt: string, options?: AskAiPromptOptions) => ({\n    model,\n    prompt,\n    messages: options?.messages,\n    system: options?.system,\n    aiName: options?.aiName,\n    reasoning: options?.reasoning,\n    caching: options?.caching,\n    maxDurationMs: options?.maxDurationMs,\n    maxSteps: options?.maxSteps,\n    maxOutputTokens: options?.maxOutputTokens,\n  }),\n});\n"]}

package/lib/commonjs/actions/ai/askAiPromptStream.d.ts

@@ -10,6 +10,15 @@ export type AskAiPromptStreamOptions = {
     messages?: AiMessage[];
     reasoning?: AiReasoningConfig;
     caching?: boolean;
+    /** Stop the tool loop between steps once this much wall-clock time has passed. The
+     *  turn then finishes with `toolCalls` if the model still wanted to act, so it can be resumed. */
+    maxDurationMs?: number;
+    /** Cap on model/tool steps in one call. Unset means the loop runs until the model stops
+     *  (or `maxDurationMs` trips); client-side tools still halt it immediately. */
+    maxSteps?: number;
+    /** Output token cap per model call. Unset uses the provider default (8192 on Bedrock), which a
+     *  large tool input plus reasoning can exceed; the step then finishes with `length`. */
+    maxOutputTokens?: number;
 };
 export declare const askAiPromptStream: import("../../types").ActionRequesterFunction<AiActionType.PromptStream, [model: AiModel, prompt: string, options?: AskAiPromptStreamOptions | undefined], {
     model: AiModel;
@@ -19,4 +28,7 @@ export declare const askAiPromptStream: import("../../types").ActionRequesterFun
     aiName: string | undefined;
     reasoning: AiReasoningConfig | undefined;
     caching: boolean | undefined;
+    maxDurationMs: number | undefined;
+    maxSteps: number | undefined;
+    maxOutputTokens: number | undefined;
 }, StreamHandle<"json", AiStreamPart>, never>;

package/lib/commonjs/actions/ai/askAiPromptStream.js

@@ -13,6 +13,9 @@ exports.askAiPromptStream = (0, types_1.createActionRequester)()({
         aiName: options === null || options === void 0 ? void 0 : options.aiName,
         reasoning: options === null || options === void 0 ? void 0 : options.reasoning,
         caching: options === null || options === void 0 ? void 0 : options.caching,
+        maxDurationMs: options === null || options === void 0 ? void 0 : options.maxDurationMs,
+        maxSteps: options === null || options === void 0 ? void 0 : options.maxSteps,
+        maxOutputTokens: options === null || options === void 0 ? void 0 : options.maxOutputTokens,
     }),
 });
 //# sourceMappingURL=askAiPromptStream.js.map

package/lib/commonjs/actions/ai/askAiPromptStream.js.map

@@ -1 +1 @@
-{"version":3,"file":"askAiPromptStream.js","sourceRoot":"","sources":["../../../../src/actions/ai/askAiPromptStream.ts"],"names":[],"mappings":";;;AAAA,uCAAoD;AAEpD,iDAA8C;AAcjC,QAAA,iBAAiB,GAAG,IAAA,6BAAqB,GAAsC,CAAC;IAC3F,UAAU,EAAE,2BAAY,CAAC,YAAY;IACrC,UAAU,EAAE,CAAC,KAAc,EAAE,MAAc,EAAE,OAAkC,EAAE,EAAE,CAAC,CAAC;QACnF,KAAK;QACL,MAAM;QACN,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;QAC3B,MAAM,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM;QACvB,MAAM,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM;QACvB,SAAS,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS;QAC7B,OAAO,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO;KAC1B,CAAC;CACH,CAAC,CAAC","sourcesContent":["import { createActionRequester } from '../../types';\nimport { StreamHandle } from '../../types/StreamRegistry';\nimport { AiActionType } from './AiActionType';\nimport { AiMessage } from './AiMessage';\nimport { AiModel } from './AiModel';\nimport { AiReasoningConfig } from './AiReasoningConfig';\nimport { AiStreamPart } from './types';\n\nexport type AskAiPromptStreamOptions = {\n  system?: string;\n  aiName?: string;\n  messages?: AiMessage[];\n  reasoning?: AiReasoningConfig;\n  caching?: boolean;\n};\n\nexport const askAiPromptStream = createActionRequester<StreamHandle<'json', AiStreamPart>>()({\n  actionType: AiActionType.PromptStream,\n  getPayload: (model: AiModel, prompt: string, options?: AskAiPromptStreamOptions) => ({\n    model,\n    prompt,\n    messages: options?.messages,\n    system: options?.system,\n    aiName: options?.aiName,\n    reasoning: options?.reasoning,\n    caching: options?.caching,\n  }),\n});\n"]}
+{"version":3,"file":"askAiPromptStream.js","sourceRoot":"","sources":["../../../../src/actions/ai/askAiPromptStream.ts"],"names":[],"mappings":";;;AAAA,uCAAoD;AAEpD,iDAA8C;AAuBjC,QAAA,iBAAiB,GAAG,IAAA,6BAAqB,GAAsC,CAAC;IAC3F,UAAU,EAAE,2BAAY,CAAC,YAAY;IACrC,UAAU,EAAE,CAAC,KAAc,EAAE,MAAc,EAAE,OAAkC,EAAE,EAAE,CAAC,CAAC;QACnF,KAAK;QACL,MAAM;QACN,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;QAC3B,MAAM,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM;QACvB,MAAM,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM;QACvB,SAAS,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS;QAC7B,OAAO,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO;QACzB,aAAa,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,aAAa;QACrC,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;QAC3B,eAAe,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,eAAe;KAC1C,CAAC;CACH,CAAC,CAAC","sourcesContent":["import { createActionRequester } from '../../types';\nimport { StreamHandle } from '../../types/StreamRegistry';\nimport { AiActionType } from './AiActionType';\nimport { AiMessage } from './AiMessage';\nimport { AiModel } from './AiModel';\nimport { AiReasoningConfig } from './AiReasoningConfig';\nimport { AiStreamPart } from './types';\n\nexport type AskAiPromptStreamOptions = {\n  system?: string;\n  aiName?: string;\n  messages?: AiMessage[];\n  reasoning?: AiReasoningConfig;\n  caching?: boolean;\n  /** Stop the tool loop between steps once this much wall-clock time has passed. The\n   *  turn then finishes with `toolCalls` if the model still wanted to act, so it can be resumed. */\n  maxDurationMs?: number;\n  /** Cap on model/tool steps in one call. Unset means the loop runs until the model stops\n   *  (or `maxDurationMs` trips); client-side tools still halt it immediately. */\n  maxSteps?: number;\n  /** Output token cap per model call. Unset uses the provider default (8192 on Bedrock), which a\n   *  large tool input plus reasoning can exceed; the step then finishes with `length`. */\n  maxOutputTokens?: number;\n};\n\nexport const askAiPromptStream = createActionRequester<StreamHandle<'json', AiStreamPart>>()({\n  actionType: AiActionType.PromptStream,\n  getPayload: (model: AiModel, prompt: string, options?: AskAiPromptStreamOptions) => ({\n    model,\n    prompt,\n    messages: options?.messages,\n    system: options?.system,\n    aiName: options?.aiName,\n    reasoning: options?.reasoning,\n    caching: options?.caching,\n    maxDurationMs: options?.maxDurationMs,\n    maxSteps: options?.maxSteps,\n    maxOutputTokens: options?.maxOutputTokens,\n  }),\n});\n"]}

package/lib/commonjs/actions/platform/PlatformActionType.d.ts

@@ -1,3 +1,4 @@
 export declare enum PlatformActionType {
-    Delay = "@quidproquo-core/Platform/Delay"
+    Delay = "@quidproquo-core/Platform/Delay",
+    GetName = "@quidproquo-core/Platform/GetName"
 }

package/lib/commonjs/actions/platform/PlatformActionType.js

@@ -4,5 +4,6 @@ exports.PlatformActionType = void 0;
 var PlatformActionType;
 (function (PlatformActionType) {
     PlatformActionType["Delay"] = "@quidproquo-core/Platform/Delay";
+    PlatformActionType["GetName"] = "@quidproquo-core/Platform/GetName";
 })(PlatformActionType || (exports.PlatformActionType = PlatformActionType = {}));
 //# sourceMappingURL=PlatformActionType.js.map

package/lib/commonjs/actions/platform/PlatformActionType.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlatformActionType.js","sourceRoot":"","sources":["../../../../src/actions/platform/PlatformActionType.ts"],"names":[],"mappings":";;;AAAA,IAAY,kBAEX;AAFD,WAAY,kBAAkB;IAC5B,+DAAyC,CAAA;AAC3C,CAAC,EAFW,kBAAkB,kCAAlB,kBAAkB,QAE7B","sourcesContent":["export enum PlatformActionType {\n  Delay = '@quidproquo-core/Platform/Delay',\n}\n"]}
+{"version":3,"file":"PlatformActionType.js","sourceRoot":"","sources":["../../../../src/actions/platform/PlatformActionType.ts"],"names":[],"mappings":";;;AAAA,IAAY,kBAGX;AAHD,WAAY,kBAAkB;IAC5B,+DAAyC,CAAA;IACzC,mEAA6C,CAAA;AAC/C,CAAC,EAHW,kBAAkB,kCAAlB,kBAAkB,QAG7B","sourcesContent":["export enum PlatformActionType {\n  Delay = '@quidproquo-core/Platform/Delay',\n  GetName = '@quidproquo-core/Platform/GetName',\n}\n"]}

package/lib/commonjs/actions/platform/askDelay.d.ts

@@ -1,4 +1,4 @@
 import { PlatformActionType } from './PlatformActionType';
-export declare const askDelay: import("../../types").ActionRequesterFunction<PlatformActionType, [timeMs: number], {
+export declare const askDelay: import("../../types").ActionRequesterFunction<PlatformActionType.Delay, [timeMs: number], {
     timeMs: number;
 }, void, never>;

package/lib/commonjs/actions/platform/askPlatformGetName.d.ts

@@ -0,0 +1,8 @@
+import { PlatformActionType } from './PlatformActionType';
+/**
+ * The name of the runtime executing the story, as its action processor set declares it.
+ * An opaque string a story compares against a known constant to skip or degrade work a
+ * platform cannot do (a smoke test with no local equivalent, say). Never branch on it
+ * for ordinary logic; that is what action processors are for.
+ */
+export declare const askPlatformGetName: import("../../types").ActionRequesterFunction<PlatformActionType.GetName, [], {}, string, never>;

package/lib/commonjs/actions/platform/askPlatformGetName.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.askPlatformGetName = void 0;
+const types_1 = require("../../types");
+const PlatformActionType_1 = require("./PlatformActionType");
+/**
+ * The name of the runtime executing the story, as its action processor set declares it.
+ * An opaque string a story compares against a known constant to skip or degrade work a
+ * platform cannot do (a smoke test with no local equivalent, say). Never branch on it
+ * for ordinary logic; that is what action processors are for.
+ */
+exports.askPlatformGetName = (0, types_1.createActionRequester)()({
+    actionType: PlatformActionType_1.PlatformActionType.GetName,
+    getPayload: () => ({}),
+});
+//# sourceMappingURL=askPlatformGetName.js.map

package/lib/commonjs/actions/platform/askPlatformGetName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"askPlatformGetName.js","sourceRoot":"","sources":["../../../../src/actions/platform/askPlatformGetName.ts"],"names":[],"mappings":";;;AAAA,uCAAoD;AACpD,6DAA0D;AAE1D;;;;;GAKG;AACU,QAAA,kBAAkB,GAAG,IAAA,6BAAqB,GAAU,CAAC;IAChE,UAAU,EAAE,uCAAkB,CAAC,OAAO;IACtC,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;CACvB,CAAC,CAAC","sourcesContent":["import { createActionRequester } from '../../types';\nimport { PlatformActionType } from './PlatformActionType';\n\n/**\n * The name of the runtime executing the story, as its action processor set declares it.\n * An opaque string a story compares against a known constant to skip or degrade work a\n * platform cannot do (a smoke test with no local equivalent, say). Never branch on it\n * for ordinary logic; that is what action processors are for.\n */\nexport const askPlatformGetName = createActionRequester<string>()({\n  actionType: PlatformActionType.GetName,\n  getPayload: () => ({}),\n});\n"]}

package/lib/commonjs/actions/platform/index.d.ts

@@ -1,2 +1,3 @@
 export * from './askDelay';
+export * from './askPlatformGetName';
 export * from './PlatformActionType';

package/lib/commonjs/actions/platform/index.js

@@ -15,5 +15,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./askDelay"), exports);
+__exportStar(require("./askPlatformGetName"), exports);
 __exportStar(require("./PlatformActionType"), exports);
 //# sourceMappingURL=index.js.map

package/lib/commonjs/actions/platform/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/actions/platform/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,uDAAqC","sourcesContent":["export * from './askDelay';\nexport * from './PlatformActionType';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/actions/platform/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,uDAAqC;AACrC,uDAAqC","sourcesContent":["export * from './askDelay';\nexport * from './askPlatformGetName';\nexport * from './PlatformActionType';\n"]}

package/lib/commonjs/actions/system/SystemActionType.d.ts

@@ -2,5 +2,6 @@ export declare enum SystemActionType {
     Batch = "@quidproquo-core/System/Batch",
     ExecuteStory = "@quidproquo-core/System/ExecuteStory",
     GetRuntimeCorrelation = "@quidproquo-core/System/GetRuntimeCorrelation",
+    GetRuntimeRemainingTime = "@quidproquo-core/System/GetRuntimeRemainingTime",
     TraceStory = "@quidproquo-core/System/TraceStory"
 }

package/lib/commonjs/actions/system/SystemActionType.js

@@ -11,6 +11,7 @@ var SystemActionType;
     SystemActionType["Batch"] = "@quidproquo-core/System/Batch";
     SystemActionType["ExecuteStory"] = "@quidproquo-core/System/ExecuteStory";
     SystemActionType["GetRuntimeCorrelation"] = "@quidproquo-core/System/GetRuntimeCorrelation";
+    SystemActionType["GetRuntimeRemainingTime"] = "@quidproquo-core/System/GetRuntimeRemainingTime";
     // Only node runtimes implement a processor (V8-inspector based log replay tracing)
     SystemActionType["TraceStory"] = "@quidproquo-core/System/TraceStory";
     // This isn't needed as its just a hybrid runtime method for SystemBatch

package/lib/commonjs/actions/system/SystemActionType.js.map

@@ -1 +1 @@
-{"version":3,"file":"SystemActionType.js","sourceRoot":"","sources":["../../../../src/actions/system/SystemActionType.ts"],"names":[],"mappings":";AAAA,sFAAsF;AACtF,2EAA2E;AAC3E,EAAE;AACF,2BAA2B;AAC3B,EAAE;;;AAEF,IAAY,gBAUX;AAVD,WAAY,gBAAgB;IAC1B,2DAAuC,CAAA;IACvC,yEAAqD,CAAA;IACrD,2FAAuE,CAAA;IAEvE,mFAAmF;IACnF,qEAAiD,CAAA;IAEjD,wEAAwE;IACxE,uDAAuD;AACzD,CAAC,EAVW,gBAAgB,gCAAhB,gBAAgB,QAU3B","sourcesContent":["// NOTE:  The following actions have no platform specific processors and/or requestors\n//        and therefore do not need to implement a SystemActionProcessor.ts\n//\n// * SystemActionType.Batch\n//\n\nexport enum SystemActionType {\n  Batch = '@quidproquo-core/System/Batch',\n  ExecuteStory = '@quidproquo-core/System/ExecuteStory',\n  GetRuntimeCorrelation = '@quidproquo-core/System/GetRuntimeCorrelation',\n\n  // Only node runtimes implement a processor (V8-inspector based log replay tracing)\n  TraceStory = '@quidproquo-core/System/TraceStory',\n\n  // This isn't needed as its just a hybrid runtime method for SystemBatch\n  // RunParallel = '@quidproquo-core/System/RunParallel',\n}\n"]}
+{"version":3,"file":"SystemActionType.js","sourceRoot":"","sources":["../../../../src/actions/system/SystemActionType.ts"],"names":[],"mappings":";AAAA,sFAAsF;AACtF,2EAA2E;AAC3E,EAAE;AACF,2BAA2B;AAC3B,EAAE;;;AAEF,IAAY,gBAWX;AAXD,WAAY,gBAAgB;IAC1B,2DAAuC,CAAA;IACvC,yEAAqD,CAAA;IACrD,2FAAuE,CAAA;IACvE,+FAA2E,CAAA;IAE3E,mFAAmF;IACnF,qEAAiD,CAAA;IAEjD,wEAAwE;IACxE,uDAAuD;AACzD,CAAC,EAXW,gBAAgB,gCAAhB,gBAAgB,QAW3B","sourcesContent":["// NOTE:  The following actions have no platform specific processors and/or requestors\n//        and therefore do not need to implement a SystemActionProcessor.ts\n//\n// * SystemActionType.Batch\n//\n\nexport enum SystemActionType {\n  Batch = '@quidproquo-core/System/Batch',\n  ExecuteStory = '@quidproquo-core/System/ExecuteStory',\n  GetRuntimeCorrelation = '@quidproquo-core/System/GetRuntimeCorrelation',\n  GetRuntimeRemainingTime = '@quidproquo-core/System/GetRuntimeRemainingTime',\n\n  // Only node runtimes implement a processor (V8-inspector based log replay tracing)\n  TraceStory = '@quidproquo-core/System/TraceStory',\n\n  // This isn't needed as its just a hybrid runtime method for SystemBatch\n  // RunParallel = '@quidproquo-core/System/RunParallel',\n}\n"]}

package/lib/commonjs/actions/system/askGetRuntimeRemainingTime.d.ts

@@ -0,0 +1,7 @@
+import { SystemActionType } from './SystemActionType';
+/**
+ * Milliseconds left before the platform kills the current execution. Long loops
+ * (agentic AI turns, batch sweeps) check this between steps and hand off before the
+ * hard cutoff. Runtimes with no execution limit return Number.MAX_SAFE_INTEGER.
+ */
+export declare const askGetRuntimeRemainingTime: import("../../types").ActionRequesterFunction<SystemActionType.GetRuntimeRemainingTime, [], undefined, number, never>;

package/lib/commonjs/actions/system/askGetRuntimeRemainingTime.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.askGetRuntimeRemainingTime = void 0;
+const types_1 = require("../../types");
+const SystemActionType_1 = require("./SystemActionType");
+/**
+ * Milliseconds left before the platform kills the current execution. Long loops
+ * (agentic AI turns, batch sweeps) check this between steps and hand off before the
+ * hard cutoff. Runtimes with no execution limit return Number.MAX_SAFE_INTEGER.
+ */
+exports.askGetRuntimeRemainingTime = (0, types_1.createActionRequester)()({
+    actionType: SystemActionType_1.SystemActionType.GetRuntimeRemainingTime,
+});
+//# sourceMappingURL=askGetRuntimeRemainingTime.js.map

package/lib/commonjs/actions/system/askGetRuntimeRemainingTime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"askGetRuntimeRemainingTime.js","sourceRoot":"","sources":["../../../../src/actions/system/askGetRuntimeRemainingTime.ts"],"names":[],"mappings":";;;AAAA,uCAAoD;AACpD,yDAAsD;AAEtD;;;;GAIG;AACU,QAAA,0BAA0B,GAAG,IAAA,6BAAqB,GAAU,CAAC;IACxE,UAAU,EAAE,mCAAgB,CAAC,uBAAuB;CACrD,CAAC,CAAC","sourcesContent":["import { createActionRequester } from '../../types';\nimport { SystemActionType } from './SystemActionType';\n\n/**\n * Milliseconds left before the platform kills the current execution. Long loops\n * (agentic AI turns, batch sweeps) check this between steps and hand off before the\n * hard cutoff. Runtimes with no execution limit return Number.MAX_SAFE_INTEGER.\n */\nexport const askGetRuntimeRemainingTime = createActionRequester<number>()({\n  actionType: SystemActionType.GetRuntimeRemainingTime,\n});\n"]}

package/lib/commonjs/actions/system/index.d.ts

@@ -1,6 +1,7 @@
 export * from './askBatch';
 export * from './askExecuteStory';
 export * from './askGetRuntimeCorrelation';
+export * from './askGetRuntimeRemainingTime';
 export * from './askParallelDEPRECATED';
 export * from './askTraceStory';
 export * from './SystemActionType';

package/lib/commonjs/actions/system/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./askBatch"), exports);
 __exportStar(require("./askExecuteStory"), exports);
 __exportStar(require("./askGetRuntimeCorrelation"), exports);
+__exportStar(require("./askGetRuntimeRemainingTime"), exports);
 __exportStar(require("./askParallelDEPRECATED"), exports);
 __exportStar(require("./askTraceStory"), exports);
 __exportStar(require("./SystemActionType"), exports);

package/lib/commonjs/actions/system/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/actions/system/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,oDAAkC;AAClC,6DAA2C;AAC3C,0DAAwC;AACxC,kDAAgC;AAChC,qDAAmC","sourcesContent":["export * from './askBatch';\nexport * from './askExecuteStory';\nexport * from './askGetRuntimeCorrelation';\nexport * from './askParallelDEPRECATED';\nexport * from './askTraceStory';\nexport * from './SystemActionType';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/actions/system/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,oDAAkC;AAClC,6DAA2C;AAC3C,+DAA6C;AAC7C,0DAAwC;AACxC,kDAAgC;AAChC,qDAAmC","sourcesContent":["export * from './askBatch';\nexport * from './askExecuteStory';\nexport * from './askGetRuntimeCorrelation';\nexport * from './askGetRuntimeRemainingTime';\nexport * from './askParallelDEPRECATED';\nexport * from './askTraceStory';\nexport * from './SystemActionType';\n"]}

package/lib/commonjs/config/settings/keyValueStore.d.ts

@@ -57,7 +57,8 @@ export interface QPQConfigAdvancedKeyValueStoreSettings<T extends object = any>
     owner?: CrossModuleOwner;
     ttlAttribute?: string;
     disablePointInTimeRecovery?: boolean;
-    encryption?: boolean;
+    cryptoKeyName?: string;
+    scoped?: boolean;
     onStream?: KvsStreamSettings;
 }
 export interface KeyValueStoreQPQConfigSetting<T extends object = any> extends QPQConfigSetting {
@@ -68,7 +69,8 @@ export interface KeyValueStoreQPQConfigSetting<T extends object = any> extends Q
     global: boolean;
     ttlAttribute?: string;
     disablePointInTimeRecovery: boolean;
-    encryption: boolean;
+    cryptoKeyName?: string;
+    scoped: boolean;
     onStream?: KvsStreamSettings;
 }
 export declare const defineKeyValueStore: <T extends object = any>(keyValueStoreName: string, partitionKey: CompositeKvsKey<T>, sortKeys?: CompositeKvsKey<T>[], options?: QPQConfigAdvancedKeyValueStoreSettings<T>) => KeyValueStoreQPQConfigSetting<T>;

package/lib/commonjs/config/settings/keyValueStore.js

@@ -42,7 +42,8 @@ const defineKeyValueStore = (keyValueStoreName, partitionKey, sortKeys = [], opt
         owner: options === null || options === void 0 ? void 0 : options.owner,
         ttlAttribute: options === null || options === void 0 ? void 0 : options.ttlAttribute,
         disablePointInTimeRecovery: (_c = options === null || options === void 0 ? void 0 : options.disablePointInTimeRecovery) !== null && _c !== void 0 ? _c : false,
-        encryption: (_d = options === null || options === void 0 ? void 0 : options.encryption) !== null && _d !== void 0 ? _d : false,
+        cryptoKeyName: options === null || options === void 0 ? void 0 : options.cryptoKeyName,
+        scoped: (_d = options === null || options === void 0 ? void 0 : options.scoped) !== null && _d !== void 0 ? _d : false,
         onStream: options === null || options === void 0 ? void 0 : options.onStream,
     });
 };

package/lib/commonjs/config/settings/keyValueStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"keyValueStore.js","sourceRoot":"","sources":["../../../../src/config/settings/keyValueStore.ts"],"names":[],"mappings":";;;AACA,4CAAqG;AAmB9F,MAAM,MAAM,GAAG,CAAyB,GAAa,EAAE,OAAmB,QAAQ,EAAa,EAAE,CAAC,CAAC;IACxG,GAAG;IACH,IAAI;CACL,CAAC,CAAC;AAHU,QAAA,MAAM,UAGhB;AAWH,MAAM,8BAA8B,GAAG,CAAyB,eAAmC,EAAa,EAAE;IAChH,oBAAoB;IACpB,IAAI,OAAO,eAAe,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,IAAA,cAAM,EAAI,eAA2B,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED,sBAAsB;IACtB,OAAO,eAA4B,CAAC;AACtC,CAAC,CAAC;AAEF,MAAM,8CAA8C,GAAG,CACrD,iBAAuC,EACa,EAAE;IACtD,OAAO,OAAO,iBAAiB,KAAK,QAAQ,CAAC;AAC/C,CAAC,CAAC;AAEF,MAAM,kCAAkC,GAAG,CAAyB,iBAAuC,EAAe,EAAE;IAC1H,IAAI,CAAC,8CAA8C,CAAI,iBAAiB,CAAC,EAAE,CAAC;QAC1E,OAAO;YACL,YAAY,EAAE,IAAA,cAAM,EAAI,iBAAiB,EAAE,QAAQ,CAAC;SACrD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,YAAY,EAAE,8BAA8B,CAAI,iBAAiB,CAAC,YAAY,CAAC;QAC/E,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,8BAA8B,CAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;KAC9G,CAAC;AACJ,CAAC,CAAC;AA+EK,MAAM,mBAAmB,GAAG,CACjC,iBAAyB,EAEzB,YAAgC,EAChC,WAAiC,EAAE,EAEnC,OAAmD,EACjB,EAAE;;IAAC,OAAA,CAAC;QACtC,iBAAiB,EAAE,oCAAwB,CAAC,aAAa;QACzD,SAAS,EAAE,iBAAiB;QAE5B,iBAAiB;QAEjB,YAAY,EAAE,8BAA8B,CAAI,YAAY,CAAC;QAC7D,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAA,8BAAiC,CAAA,CAAC;QAEzD,OAAO,EAAE,CAAC,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,mCAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAA,kCAAqC,CAAA,CAAC;QAE5E,MAAM,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,mCAAI,KAAK;QAEhC,KAAK,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,KAAK;QAErB,YAAY,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,YAAY;QAEnC,0BAA0B,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,0BAA0B,mCAAI,KAAK;QAExE,UAAU,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,UAAU,mCAAI,KAAK;QAExC,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;KAC5B,CAAC,CAAA;CAAA,CAAC;AA7BU,QAAA,mBAAmB,uBA6B7B","sourcesContent":["import { CrossModuleOwner, KeyOf, QpqFunctionRuntime } from '../../types';\nimport { QPQConfigAdvancedSettings, QPQConfigSetting, QPQCoreConfigSettingType } from '../QPQConfig';\n\n// TODO: When we put validation on the QPQConfig, we need to make sure\n// Key Length and Data Type: DynamoDB has limitations on key length and data type.\n// Your KvsKeyType only supports 'string', 'number', and 'binary' types. Make sure\n// that you're validating these in convertKvsKeyToDynamodbAttribute function and\n// also ensure that key length is within DynamoDB's specified limits.\n\nexport type KvsKeyType = 'string' | 'number' | 'binary';\nexport type KvsKey<T extends object = any> = {\n  key: KeyOf<T>;\n  type: KvsKeyType;\n};\n\nexport type KvsIndex<T extends object = any> = {\n  partitionKey: KvsKey<T>;\n  sortKey?: KvsKey<T>;\n};\n\nexport const kvsKey = <T extends object = any>(key: KeyOf<T>, type: KvsKeyType = 'string'): KvsKey<T> => ({\n  key,\n  type,\n});\n\ntype CompositeKvsKey<T extends object = any> = KvsKey<T> | KeyOf<T>;\n\ntype CompositeCompositeKvsIndex<T extends object = any> = {\n  partitionKey: CompositeKvsKey<T>;\n  sortKey?: CompositeKvsKey<T>;\n};\n\nexport type CompositeKvsIndex<T extends object = any> = KeyOf<T> | CompositeCompositeKvsIndex<T>;\n\nconst convertCompositeKvsKeyToKvsKey = <T extends object = any>(compositeKvsKey: CompositeKvsKey<T>): KvsKey<T> => {\n  // Must be a keyof T\n  if (typeof compositeKvsKey === 'string') {\n    return kvsKey<T>(compositeKvsKey as KeyOf<T>, 'string');\n  }\n\n  // must be a KvsKey<T>\n  return compositeKvsKey as KvsKey<T>;\n};\n\nconst isCompositeKvsIndexACompositeCompositeKvsIndex = <T extends object = any>(\n  compositeKvsIndex: CompositeKvsIndex<T>,\n): compositeKvsIndex is CompositeCompositeKvsIndex<T> => {\n  return typeof compositeKvsIndex !== 'string';\n};\n\nconst convertCompositeKvsIndexToKvsIndex = <T extends object = any>(compositeKvsIndex: CompositeKvsIndex<T>): KvsIndex<T> => {\n  if (!isCompositeKvsIndexACompositeCompositeKvsIndex<T>(compositeKvsIndex)) {\n    return {\n      partitionKey: kvsKey<T>(compositeKvsIndex, 'string'),\n    };\n  }\n\n  return {\n    partitionKey: convertCompositeKvsKeyToKvsKey<T>(compositeKvsIndex.partitionKey),\n    sortKey: compositeKvsIndex.sortKey ? convertCompositeKvsKeyToKvsKey<T>(compositeKvsIndex.sortKey) : undefined,\n  };\n};\n\n/**\n * Change data capture on a store: the table gets a stream (NEW_AND_OLD_IMAGES) and\n * `runtime` is invoked with the changes.\n *\n * Records arrive in order PER PARTITION KEY, and different partition keys are processed\n * concurrently. A stream handler therefore gets one-writer-per-item serialisation for\n * free, which is what makes a stream the natural place to maintain a projection of a table\n * you only ever append to — no queue, no extra write on the append path, and no trigger to\n * lose, because the record exists precisely because the write happened.\n *\n * Mirrors defineStorageDrive's `onEvent`.\n */\nexport type KvsStreamSettings = {\n  runtime: QpqFunctionRuntime;\n\n  /**\n   * Collapse each delivered batch down to ONE record per partition key, keeping the latest.\n   *\n   * Off by default: a generic consumer (audit trail, change notifications) needs to see\n   * every change, and the framework should never silently drop records.\n   *\n   * On for a PROJECTION, where the payload that matters is \"this key changed\" and the\n   * handler re-derives from source anyway. Without it, the batch is fanned back out into\n   * one story run per record and the batching bought nothing: 500 appends to one document\n   * would mean 500 re-derivations, each reading a log that grows as it goes. With it, that\n   * batch is a single re-derivation.\n   */\n  coalesceByPartitionKey?: boolean;\n\n  /** Records per invocation. DynamoDB streams allow up to 1000; the mapping default is 100. */\n  batchSize?: number;\n\n  /**\n   * How long to wait accumulating records before invoking, 0 to 300 seconds. Trades\n   * projection latency for far fewer invocations, and gives coalescing more to collapse.\n   */\n  maximumBatchingWindowInSeconds?: number;\n};\n\nexport interface QPQConfigAdvancedKeyValueStoreSettings<T extends object = any> extends QPQConfigAdvancedSettings {\n  indexes?: CompositeKvsIndex<T>[];\n\n  global?: boolean;\n\n  owner?: CrossModuleOwner;\n\n  ttlAttribute?: string;\n\n  // Point-in-time recovery (35-day continuous backups) is on by default; set this to opt out.\n  disablePointInTimeRecovery?: boolean;\n\n  encryption?: boolean;\n\n  // Turn on change data capture — see KvsStreamSettings. Absent means no stream is\n  // created at all.\n  onStream?: KvsStreamSettings;\n}\n\nexport interface KeyValueStoreQPQConfigSetting<T extends object = any> extends QPQConfigSetting {\n  keyValueStoreName: string;\n\n  partitionKey: KvsKey<T>;\n  sortKeys: KvsKey<T>[];\n\n  indexes: KvsIndex<T>[];\n\n  global: boolean;\n\n  ttlAttribute?: string;\n\n  disablePointInTimeRecovery: boolean;\n\n  encryption: boolean;\n\n  onStream?: KvsStreamSettings;\n}\n\nexport const defineKeyValueStore = <T extends object = any>(\n  keyValueStoreName: string,\n\n  partitionKey: CompositeKvsKey<T>,\n  sortKeys: CompositeKvsKey<T>[] = [],\n\n  options?: QPQConfigAdvancedKeyValueStoreSettings<T>,\n): KeyValueStoreQPQConfigSetting<T> => ({\n  configSettingType: QPQCoreConfigSettingType.keyValueStore,\n  uniqueKey: keyValueStoreName,\n\n  keyValueStoreName,\n\n  partitionKey: convertCompositeKvsKeyToKvsKey<T>(partitionKey),\n  sortKeys: sortKeys.map(convertCompositeKvsKeyToKvsKey<T>),\n\n  indexes: (options?.indexes ?? []).map(convertCompositeKvsIndexToKvsIndex<T>),\n\n  global: options?.global ?? false,\n\n  owner: options?.owner,\n\n  ttlAttribute: options?.ttlAttribute,\n\n  disablePointInTimeRecovery: options?.disablePointInTimeRecovery ?? false,\n\n  encryption: options?.encryption ?? false,\n\n  onStream: options?.onStream,\n});\n"]}
+{"version":3,"file":"keyValueStore.js","sourceRoot":"","sources":["../../../../src/config/settings/keyValueStore.ts"],"names":[],"mappings":";;;AACA,4CAAqG;AAmB9F,MAAM,MAAM,GAAG,CAAyB,GAAa,EAAE,OAAmB,QAAQ,EAAa,EAAE,CAAC,CAAC;IACxG,GAAG;IACH,IAAI;CACL,CAAC,CAAC;AAHU,QAAA,MAAM,UAGhB;AAWH,MAAM,8BAA8B,GAAG,CAAyB,eAAmC,EAAa,EAAE;IAChH,oBAAoB;IACpB,IAAI,OAAO,eAAe,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,IAAA,cAAM,EAAI,eAA2B,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED,sBAAsB;IACtB,OAAO,eAA4B,CAAC;AACtC,CAAC,CAAC;AAEF,MAAM,8CAA8C,GAAG,CACrD,iBAAuC,EACa,EAAE;IACtD,OAAO,OAAO,iBAAiB,KAAK,QAAQ,CAAC;AAC/C,CAAC,CAAC;AAEF,MAAM,kCAAkC,GAAG,CAAyB,iBAAuC,EAAe,EAAE;IAC1H,IAAI,CAAC,8CAA8C,CAAI,iBAAiB,CAAC,EAAE,CAAC;QAC1E,OAAO;YACL,YAAY,EAAE,IAAA,cAAM,EAAI,iBAAiB,EAAE,QAAQ,CAAC;SACrD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,YAAY,EAAE,8BAA8B,CAAI,iBAAiB,CAAC,YAAY,CAAC;QAC/E,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,8BAA8B,CAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;KAC9G,CAAC;AACJ,CAAC,CAAC;AAuFK,MAAM,mBAAmB,GAAG,CACjC,iBAAyB,EAEzB,YAAgC,EAChC,WAAiC,EAAE,EAEnC,OAAmD,EACjB,EAAE;;IAAC,OAAA,CAAC;QACtC,iBAAiB,EAAE,oCAAwB,CAAC,aAAa;QACzD,SAAS,EAAE,iBAAiB;QAE5B,iBAAiB;QAEjB,YAAY,EAAE,8BAA8B,CAAI,YAAY,CAAC;QAC7D,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAA,8BAAiC,CAAA,CAAC;QAEzD,OAAO,EAAE,CAAC,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,mCAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAA,kCAAqC,CAAA,CAAC;QAE5E,MAAM,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,mCAAI,KAAK;QAEhC,KAAK,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,KAAK;QAErB,YAAY,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,YAAY;QAEnC,0BAA0B,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,0BAA0B,mCAAI,KAAK;QAExE,aAAa,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,aAAa;QACrC,MAAM,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,mCAAI,KAAK;QAEhC,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;KAC5B,CAAC,CAAA;CAAA,CAAC;AA9BU,QAAA,mBAAmB,uBA8B7B","sourcesContent":["import { CrossModuleOwner, KeyOf, QpqFunctionRuntime } from '../../types';\nimport { QPQConfigAdvancedSettings, QPQConfigSetting, QPQCoreConfigSettingType } from '../QPQConfig';\n\n// TODO: When we put validation on the QPQConfig, we need to make sure\n// Key Length and Data Type: DynamoDB has limitations on key length and data type.\n// Your KvsKeyType only supports 'string', 'number', and 'binary' types. Make sure\n// that you're validating these in convertKvsKeyToDynamodbAttribute function and\n// also ensure that key length is within DynamoDB's specified limits.\n\nexport type KvsKeyType = 'string' | 'number' | 'binary';\nexport type KvsKey<T extends object = any> = {\n  key: KeyOf<T>;\n  type: KvsKeyType;\n};\n\nexport type KvsIndex<T extends object = any> = {\n  partitionKey: KvsKey<T>;\n  sortKey?: KvsKey<T>;\n};\n\nexport const kvsKey = <T extends object = any>(key: KeyOf<T>, type: KvsKeyType = 'string'): KvsKey<T> => ({\n  key,\n  type,\n});\n\ntype CompositeKvsKey<T extends object = any> = KvsKey<T> | KeyOf<T>;\n\ntype CompositeCompositeKvsIndex<T extends object = any> = {\n  partitionKey: CompositeKvsKey<T>;\n  sortKey?: CompositeKvsKey<T>;\n};\n\nexport type CompositeKvsIndex<T extends object = any> = KeyOf<T> | CompositeCompositeKvsIndex<T>;\n\nconst convertCompositeKvsKeyToKvsKey = <T extends object = any>(compositeKvsKey: CompositeKvsKey<T>): KvsKey<T> => {\n  // Must be a keyof T\n  if (typeof compositeKvsKey === 'string') {\n    return kvsKey<T>(compositeKvsKey as KeyOf<T>, 'string');\n  }\n\n  // must be a KvsKey<T>\n  return compositeKvsKey as KvsKey<T>;\n};\n\nconst isCompositeKvsIndexACompositeCompositeKvsIndex = <T extends object = any>(\n  compositeKvsIndex: CompositeKvsIndex<T>,\n): compositeKvsIndex is CompositeCompositeKvsIndex<T> => {\n  return typeof compositeKvsIndex !== 'string';\n};\n\nconst convertCompositeKvsIndexToKvsIndex = <T extends object = any>(compositeKvsIndex: CompositeKvsIndex<T>): KvsIndex<T> => {\n  if (!isCompositeKvsIndexACompositeCompositeKvsIndex<T>(compositeKvsIndex)) {\n    return {\n      partitionKey: kvsKey<T>(compositeKvsIndex, 'string'),\n    };\n  }\n\n  return {\n    partitionKey: convertCompositeKvsKeyToKvsKey<T>(compositeKvsIndex.partitionKey),\n    sortKey: compositeKvsIndex.sortKey ? convertCompositeKvsKeyToKvsKey<T>(compositeKvsIndex.sortKey) : undefined,\n  };\n};\n\n/**\n * Change data capture on a store: the table gets a stream (NEW_AND_OLD_IMAGES) and\n * `runtime` is invoked with the changes.\n *\n * Records arrive in order PER PARTITION KEY, and different partition keys are processed\n * concurrently. A stream handler therefore gets one-writer-per-item serialisation for\n * free, which is what makes a stream the natural place to maintain a projection of a table\n * you only ever append to — no queue, no extra write on the append path, and no trigger to\n * lose, because the record exists precisely because the write happened.\n *\n * Mirrors defineStorageDrive's `onEvent`.\n */\nexport type KvsStreamSettings = {\n  runtime: QpqFunctionRuntime;\n\n  /**\n   * Collapse each delivered batch down to ONE record per partition key, keeping the latest.\n   *\n   * Off by default: a generic consumer (audit trail, change notifications) needs to see\n   * every change, and the framework should never silently drop records.\n   *\n   * On for a PROJECTION, where the payload that matters is \"this key changed\" and the\n   * handler re-derives from source anyway. Without it, the batch is fanned back out into\n   * one story run per record and the batching bought nothing: 500 appends to one document\n   * would mean 500 re-derivations, each reading a log that grows as it goes. With it, that\n   * batch is a single re-derivation.\n   */\n  coalesceByPartitionKey?: boolean;\n\n  /** Records per invocation. DynamoDB streams allow up to 1000; the mapping default is 100. */\n  batchSize?: number;\n\n  /**\n   * How long to wait accumulating records before invoking, 0 to 300 seconds. Trades\n   * projection latency for far fewer invocations, and gives coalescing more to collapse.\n   */\n  maximumBatchingWindowInSeconds?: number;\n};\n\nexport interface QPQConfigAdvancedKeyValueStoreSettings<T extends object = any> extends QPQConfigAdvancedSettings {\n  indexes?: CompositeKvsIndex<T>[];\n\n  global?: boolean;\n\n  owner?: CrossModuleOwner;\n\n  ttlAttribute?: string;\n\n  // Point-in-time recovery (35-day continuous backups) is on by default; set this to opt out.\n  disablePointInTimeRecovery?: boolean;\n\n  // Encrypt the table with the named defineCryptoKey instead of the provider's own managed\n  // encryption, which always applies. The key must be declared in the same config, owned or\n  // foreign; a foreign key's owning service must be deployed first.\n  cryptoKeyName?: string;\n\n  // Every action on this store must carry a scope; an unscoped call is refused rather\n  // than hitting the unpartitioned rows. askKeyValueStoreScanAllScopes is exempt.\n  scoped?: boolean;\n\n  // Turn on change data capture — see KvsStreamSettings. Absent means no stream is\n  // created at all.\n  onStream?: KvsStreamSettings;\n}\n\nexport interface KeyValueStoreQPQConfigSetting<T extends object = any> extends QPQConfigSetting {\n  keyValueStoreName: string;\n\n  partitionKey: KvsKey<T>;\n  sortKeys: KvsKey<T>[];\n\n  indexes: KvsIndex<T>[];\n\n  global: boolean;\n\n  ttlAttribute?: string;\n\n  disablePointInTimeRecovery: boolean;\n\n  cryptoKeyName?: string;\n  scoped: boolean;\n\n  onStream?: KvsStreamSettings;\n}\n\nexport const defineKeyValueStore = <T extends object = any>(\n  keyValueStoreName: string,\n\n  partitionKey: CompositeKvsKey<T>,\n  sortKeys: CompositeKvsKey<T>[] = [],\n\n  options?: QPQConfigAdvancedKeyValueStoreSettings<T>,\n): KeyValueStoreQPQConfigSetting<T> => ({\n  configSettingType: QPQCoreConfigSettingType.keyValueStore,\n  uniqueKey: keyValueStoreName,\n\n  keyValueStoreName,\n\n  partitionKey: convertCompositeKvsKeyToKvsKey<T>(partitionKey),\n  sortKeys: sortKeys.map(convertCompositeKvsKeyToKvsKey<T>),\n\n  indexes: (options?.indexes ?? []).map(convertCompositeKvsIndexToKvsIndex<T>),\n\n  global: options?.global ?? false,\n\n  owner: options?.owner,\n\n  ttlAttribute: options?.ttlAttribute,\n\n  disablePointInTimeRecovery: options?.disablePointInTimeRecovery ?? false,\n\n  cryptoKeyName: options?.cryptoKeyName,\n  scoped: options?.scoped ?? false,\n\n  onStream: options?.onStream,\n});\n"]}

package/lib/commonjs/config/settings/storageDrive.d.ts

@@ -77,7 +77,9 @@ export interface QPQConfigAdvancedStorageDriveSettings extends QPQConfigAdvanced
     global?: boolean;
     onEvent?: StorageDriveEvents;
     lifecycleRules?: StorageDriveLifecycleRule[];
-    encryption?: boolean;
+    cryptoKeyName?: string;
+    scoped?: boolean;
+    lockedDown?: boolean;
     owner?: CrossModuleOwner<'storageDriveName'>;
 }
 export interface StorageDriveQPQConfigSetting extends QPQConfigSetting {
@@ -86,6 +88,8 @@ export interface StorageDriveQPQConfigSetting extends QPQConfigSetting {
     global: boolean;
     onEvent?: StorageDriveEvents;
     lifecycleRules?: StorageDriveLifecycleRule[];
-    encryption: boolean;
+    cryptoKeyName?: string;
+    scoped: boolean;
+    lockedDown: boolean;
 }
 export declare const defineStorageDrive: (storageDrive: string, options?: QPQConfigAdvancedStorageDriveSettings) => StorageDriveQPQConfigSetting;

package/lib/commonjs/config/settings/storageDrive.js

@@ -56,8 +56,13 @@ var StorageDriveTier;
     StorageDriveTier["SMART_TIERING"] = "SMART_TIERING";
 })(StorageDriveTier || (exports.StorageDriveTier = StorageDriveTier = {}));
 const defineStorageDrive = (storageDrive, options) => {
-    var _a, _b;
-    return ({
+    var _a, _b, _c;
+    // copyPath content is deployed straight to the bucket root, outside every
+    // scope, so it can never coexist with a scoped drive.
+    if ((options === null || options === void 0 ? void 0 : options.scoped) && options.copyPath) {
+        throw new Error(`Storage drive '${storageDrive}' cannot be both scoped and have a copyPath`);
+    }
+    return {
         configSettingType: QPQConfig_1.QPQCoreConfigSettingType.storageDrive,
         uniqueKey: storageDrive,
         storageDrive,
@@ -65,9 +70,11 @@ const defineStorageDrive = (storageDrive, options) => {
         global: (_a = options === null || options === void 0 ? void 0 : options.global) !== null && _a !== void 0 ? _a : false,
         onEvent: options === null || options === void 0 ? void 0 : options.onEvent,
         lifecycleRules: options === null || options === void 0 ? void 0 : options.lifecycleRules,
-        encryption: (_b = options === null || options === void 0 ? void 0 : options.encryption) !== null && _b !== void 0 ? _b : false,
+        cryptoKeyName: options === null || options === void 0 ? void 0 : options.cryptoKeyName,
+        scoped: (_b = options === null || options === void 0 ? void 0 : options.scoped) !== null && _b !== void 0 ? _b : false,
+        lockedDown: (_c = options === null || options === void 0 ? void 0 : options.lockedDown) !== null && _c !== void 0 ? _c : false,
         owner: (0, crossModuleUtils_1.convertCrossModuleOwnerToGenericResourceNameOverride)(options === null || options === void 0 ? void 0 : options.owner),
-    });
+    };
 };
 exports.defineStorageDrive = defineStorageDrive;
 //# sourceMappingURL=storageDrive.js.map

package/lib/commonjs/config/settings/storageDrive.js.map

@@ -1 +1 @@
-{"version":3,"file":"storageDrive.js","sourceRoot":"","sources":["../../../../src/config/settings/storageDrive.ts"],"names":[],"mappings":";;;AACA,4CAAqG;AACrG,gEAAiG;AAEjG;;GAEG;AACH,IAAY,gBAqDX;AArDD,WAAY,gBAAgB;IAC1B;;;OAGG;IACH,uCAAmB,CAAA;IAEnB;;;;;OAKG;IACH,2DAAuC,CAAA;IAEvC;;;;OAIG;IACH,mFAA+D,CAAA;IAE/D;;;;;OAKG;IACH,iDAA6B,CAAA;IAE7B;;;;;OAKG;IACH,+EAA2D,CAAA;IAE3D;;;;;OAKG;IACH,2DAAuC,CAAA;IAEvC;;;;;OAKG;IACH,mDAA+B,CAAA;AACjC,CAAC,EArDW,gBAAgB,gCAAhB,gBAAgB,QAqD3B;AAuDM,MAAM,kBAAkB,GAAG,CAAC,YAAoB,EAAE,OAA+C,EAAgC,EAAE;;IAAC,OAAA,CAAC;QAC1I,iBAAiB,EAAE,oCAAwB,CAAC,YAAY;QACxD,SAAS,EAAE,YAAY;QAEvB,YAAY;QAEZ,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;QAE3B,MAAM,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,mCAAI,KAAK;QAEhC,OAAO,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO;QAEzB,cAAc,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,cAAc;QAEvC,UAAU,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,UAAU,mCAAI,KAAK;QAExC,KAAK,EAAE,IAAA,uEAAoD,EAAC,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,KAAK,CAAC;KAC5E,CAAC,CAAA;CAAA,CAAC;AAjBU,QAAA,kBAAkB,sBAiB5B","sourcesContent":["import { CrossModuleOwner, QpqFunctionRuntime } from '../../types';\nimport { QPQConfigAdvancedSettings, QPQConfigSetting, QPQCoreConfigSettingType } from '../QPQConfig';\nimport { convertCrossModuleOwnerToGenericResourceNameOverride } from '../utils/crossModuleUtils';\n\n/**\n * Represents different storage tiers for a \"storageDrive\".\n */\nexport enum StorageDriveTier {\n  /**\n   * Standard storage tier suitable for frequently accessed data.\n   * (Reference: AWS S3 Standard)\n   */\n  REGULAR = 'REGULAR',\n\n  /**\n   * Storage tier optimized for data that is accessed less frequently,\n   * but requires rapid access when needed. Lower availability compared\n   * to the REGULAR tier.\n   * (Reference: AWS S3 Infrequent Access)\n   */\n  OCCASIONAL_ACCESS = 'OCCASIONAL_ACCESS',\n\n  /**\n   * Optimized for infrequently accessed data stored in a single zone.\n   * Lower availability compared to OCCASIONAL_ACCESS tier.\n   * (Reference: AWS S3 One Zone-Infrequent Access)\n   */\n  SINGLE_ZONE_OCCASIONAL_ACCESS = 'SINGLE_ZONE_OCCASIONAL_ACCESS',\n\n  /**\n   * Cold storage tier suitable for long-term archival. Data retrieval\n   * can take between minutes to hours. A cost-effective solution for\n   * archival purposes where prompt data retrieval isn't crucial.\n   * (Reference: AWS S3 Glacier)\n   */\n  COLD_STORAGE = 'COLD_STORAGE',\n\n  /**\n   * Cold storage tier optimized for long-term archival, but with the advantage\n   * of immediate data access (in milliseconds). Ideal for data that might be\n   * accessed once or twice per quarter.\n   * (Reference: AWS S3 Glacier Instant Retrieval)\n   */\n  COLD_STORAGE_INSTANT_ACCESS = 'COLD_STORAGE_INSTANT_ACCESS',\n\n  /**\n   * Extremely cold storage suitable for data that's rarely accessed.\n   * Data retrieval might take up to 12 hours. This offers the lowest\n   * storage cost at the expense of retrieval time.\n   * (Reference: AWS S3 Glacier Deep Archive)\n   */\n  DEEP_COLD_STORAGE = 'DEEP_COLD_STORAGE',\n\n  /**\n   * Dynamic storage tier designed to auto-optimize costs by moving data\n   * between frequently and infrequently accessed tiers based on access patterns.\n   * Ideal for long-lived data with unpredictable access patterns.\n   * (Reference: AWS S3 Intelligent Tiering)\n   */\n  SMART_TIERING = 'SMART_TIERING',\n}\n\nexport type StorageDriveTransition = { storageDriveTier: StorageDriveTier } & (\n  | {\n      transitionAfterDays: number;\n      transitionDate?: never;\n    }\n  | {\n      transitionAfterDays?: never;\n      transitionDate: string;\n    }\n);\n\nexport type StorageDriveLifecycleRule = {\n  prefix?: string;\n  transitions?: StorageDriveTransition[];\n  deleteAfterDays?: number;\n  fileSizeLessThan?: number;\n  fileSizeGreaterThan?: number;\n  enabled?: boolean;\n\n  // TODO: If we ever add versions\n  // add noncurrentVersionExpiration / noncurrentVersionTransitions support\n};\n\nexport interface StorageDriveEvents {\n  create?: QpqFunctionRuntime;\n  delete?: QpqFunctionRuntime;\n}\n\nexport interface QPQConfigAdvancedStorageDriveSettings extends QPQConfigAdvancedSettings {\n  copyPath?: string;\n  global?: boolean;\n\n  onEvent?: StorageDriveEvents;\n\n  lifecycleRules?: StorageDriveLifecycleRule[];\n\n  encryption?: boolean;\n\n  owner?: CrossModuleOwner<'storageDriveName'>;\n}\n\nexport interface StorageDriveQPQConfigSetting extends QPQConfigSetting {\n  storageDrive: string;\n  copyPath?: string;\n  global: boolean;\n\n  onEvent?: StorageDriveEvents;\n\n  lifecycleRules?: StorageDriveLifecycleRule[];\n\n  encryption: boolean;\n}\n\nexport const defineStorageDrive = (storageDrive: string, options?: QPQConfigAdvancedStorageDriveSettings): StorageDriveQPQConfigSetting => ({\n  configSettingType: QPQCoreConfigSettingType.storageDrive,\n  uniqueKey: storageDrive,\n\n  storageDrive,\n\n  copyPath: options?.copyPath,\n\n  global: options?.global ?? false,\n\n  onEvent: options?.onEvent,\n\n  lifecycleRules: options?.lifecycleRules,\n\n  encryption: options?.encryption ?? false,\n\n  owner: convertCrossModuleOwnerToGenericResourceNameOverride(options?.owner),\n});\n"]}
+{"version":3,"file":"storageDrive.js","sourceRoot":"","sources":["../../../../src/config/settings/storageDrive.ts"],"names":[],"mappings":";;;AACA,4CAAqG;AACrG,gEAAiG;AAEjG;;GAEG;AACH,IAAY,gBAqDX;AArDD,WAAY,gBAAgB;IAC1B;;;OAGG;IACH,uCAAmB,CAAA;IAEnB;;;;;OAKG;IACH,2DAAuC,CAAA;IAEvC;;;;OAIG;IACH,mFAA+D,CAAA;IAE/D;;;;;OAKG;IACH,iDAA6B,CAAA;IAE7B;;;;;OAKG;IACH,+EAA2D,CAAA;IAE3D;;;;;OAKG;IACH,2DAAuC,CAAA;IAEvC;;;;;OAKG;IACH,mDAA+B,CAAA;AACjC,CAAC,EArDW,gBAAgB,gCAAhB,gBAAgB,QAqD3B;AAoEM,MAAM,kBAAkB,GAAG,CAAC,YAAoB,EAAE,OAA+C,EAAgC,EAAE;;IACxI,0EAA0E;IAC1E,sDAAsD;IACtD,IAAI,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,KAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,kBAAkB,YAAY,6CAA6C,CAAC,CAAC;IAC/F,CAAC;IAED,OAAO;QACL,iBAAiB,EAAE,oCAAwB,CAAC,YAAY;QACxD,SAAS,EAAE,YAAY;QAEvB,YAAY;QAEZ,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;QAE3B,MAAM,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,mCAAI,KAAK;QAEhC,OAAO,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO;QAEzB,cAAc,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,cAAc;QAEvC,aAAa,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,aAAa;QACrC,MAAM,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,mCAAI,KAAK;QAChC,UAAU,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,UAAU,mCAAI,KAAK;QAExC,KAAK,EAAE,IAAA,uEAAoD,EAAC,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,KAAK,CAAC;KAC5E,CAAC;AACJ,CAAC,CAAC;AA3BW,QAAA,kBAAkB,sBA2B7B","sourcesContent":["import { CrossModuleOwner, QpqFunctionRuntime } from '../../types';\nimport { QPQConfigAdvancedSettings, QPQConfigSetting, QPQCoreConfigSettingType } from '../QPQConfig';\nimport { convertCrossModuleOwnerToGenericResourceNameOverride } from '../utils/crossModuleUtils';\n\n/**\n * Represents different storage tiers for a \"storageDrive\".\n */\nexport enum StorageDriveTier {\n  /**\n   * Standard storage tier suitable for frequently accessed data.\n   * (Reference: AWS S3 Standard)\n   */\n  REGULAR = 'REGULAR',\n\n  /**\n   * Storage tier optimized for data that is accessed less frequently,\n   * but requires rapid access when needed. Lower availability compared\n   * to the REGULAR tier.\n   * (Reference: AWS S3 Infrequent Access)\n   */\n  OCCASIONAL_ACCESS = 'OCCASIONAL_ACCESS',\n\n  /**\n   * Optimized for infrequently accessed data stored in a single zone.\n   * Lower availability compared to OCCASIONAL_ACCESS tier.\n   * (Reference: AWS S3 One Zone-Infrequent Access)\n   */\n  SINGLE_ZONE_OCCASIONAL_ACCESS = 'SINGLE_ZONE_OCCASIONAL_ACCESS',\n\n  /**\n   * Cold storage tier suitable for long-term archival. Data retrieval\n   * can take between minutes to hours. A cost-effective solution for\n   * archival purposes where prompt data retrieval isn't crucial.\n   * (Reference: AWS S3 Glacier)\n   */\n  COLD_STORAGE = 'COLD_STORAGE',\n\n  /**\n   * Cold storage tier optimized for long-term archival, but with the advantage\n   * of immediate data access (in milliseconds). Ideal for data that might be\n   * accessed once or twice per quarter.\n   * (Reference: AWS S3 Glacier Instant Retrieval)\n   */\n  COLD_STORAGE_INSTANT_ACCESS = 'COLD_STORAGE_INSTANT_ACCESS',\n\n  /**\n   * Extremely cold storage suitable for data that's rarely accessed.\n   * Data retrieval might take up to 12 hours. This offers the lowest\n   * storage cost at the expense of retrieval time.\n   * (Reference: AWS S3 Glacier Deep Archive)\n   */\n  DEEP_COLD_STORAGE = 'DEEP_COLD_STORAGE',\n\n  /**\n   * Dynamic storage tier designed to auto-optimize costs by moving data\n   * between frequently and infrequently accessed tiers based on access patterns.\n   * Ideal for long-lived data with unpredictable access patterns.\n   * (Reference: AWS S3 Intelligent Tiering)\n   */\n  SMART_TIERING = 'SMART_TIERING',\n}\n\nexport type StorageDriveTransition = { storageDriveTier: StorageDriveTier } & (\n  | {\n      transitionAfterDays: number;\n      transitionDate?: never;\n    }\n  | {\n      transitionAfterDays?: never;\n      transitionDate: string;\n    }\n);\n\nexport type StorageDriveLifecycleRule = {\n  prefix?: string;\n  transitions?: StorageDriveTransition[];\n  deleteAfterDays?: number;\n  fileSizeLessThan?: number;\n  fileSizeGreaterThan?: number;\n  enabled?: boolean;\n\n  // TODO: If we ever add versions\n  // add noncurrentVersionExpiration / noncurrentVersionTransitions support\n};\n\nexport interface StorageDriveEvents {\n  create?: QpqFunctionRuntime;\n  delete?: QpqFunctionRuntime;\n}\n\nexport interface QPQConfigAdvancedStorageDriveSettings extends QPQConfigAdvancedSettings {\n  copyPath?: string;\n  global?: boolean;\n\n  onEvent?: StorageDriveEvents;\n\n  lifecycleRules?: StorageDriveLifecycleRule[];\n\n  // Encrypt the drive with the named defineCryptoKey instead of the provider's own managed\n  // encryption, which always applies. The key must be declared in the same config, owned or\n  // foreign; a foreign key's owning service must be deployed first.\n  cryptoKeyName?: string;\n\n  // Every file action on this drive must carry a scope; an unscoped call is refused\n  // rather than written to the bare path. Incompatible with copyPath.\n  scoped?: boolean;\n\n  // Only the owning service's runtime role may read objects. Every other principal in the\n  // account, humans included, is denied at the bucket; writes and listing are unaffected.\n  lockedDown?: boolean;\n\n  owner?: CrossModuleOwner<'storageDriveName'>;\n}\n\nexport interface StorageDriveQPQConfigSetting extends QPQConfigSetting {\n  storageDrive: string;\n  copyPath?: string;\n  global: boolean;\n\n  onEvent?: StorageDriveEvents;\n\n  lifecycleRules?: StorageDriveLifecycleRule[];\n\n  cryptoKeyName?: string;\n  scoped: boolean;\n  lockedDown: boolean;\n}\n\nexport const defineStorageDrive = (storageDrive: string, options?: QPQConfigAdvancedStorageDriveSettings): StorageDriveQPQConfigSetting => {\n  // copyPath content is deployed straight to the bucket root, outside every\n  // scope, so it can never coexist with a scoped drive.\n  if (options?.scoped && options.copyPath) {\n    throw new Error(`Storage drive '${storageDrive}' cannot be both scoped and have a copyPath`);\n  }\n\n  return {\n    configSettingType: QPQCoreConfigSettingType.storageDrive,\n    uniqueKey: storageDrive,\n\n    storageDrive,\n\n    copyPath: options?.copyPath,\n\n    global: options?.global ?? false,\n\n    onEvent: options?.onEvent,\n\n    lifecycleRules: options?.lifecycleRules,\n\n    cryptoKeyName: options?.cryptoKeyName,\n    scoped: options?.scoped ?? false,\n    lockedDown: options?.lockedDown ?? false,\n\n    owner: convertCrossModuleOwnerToGenericResourceNameOverride(options?.owner),\n  };\n};\n"]}

package/lib/commonjs/logic/scope/InvalidScopeError.d.ts

@@ -4,7 +4,9 @@ export declare enum InvalidScopeErrorCode {
     tooLong = "tooLong",
     unsafePath = "unsafePath",
     queryMissingPartitionKey = "queryMissingPartitionKey",
-    reservedDelimiter = "reservedDelimiter"
+    reservedDelimiter = "reservedDelimiter",
+    scopeRequired = "scopeRequired",
+    notScoped = "notScoped"
 }
 export declare class InvalidScopeError extends Error {
     readonly code: InvalidScopeErrorCode;

package/lib/commonjs/logic/scope/InvalidScopeError.js

@@ -23,6 +23,14 @@ var InvalidScopeErrorCode;
     // A raw partition-key value containing the scope delimiter: storing it would
     // make the row indistinguishable from another scope's composed data.
     InvalidScopeErrorCode["reservedDelimiter"] = "reservedDelimiter";
+    // The resource is declared `scoped` in config but the call carried no scope.
+    // On a drive that would land the object beside every tenant's prefix; on a
+    // store it would read or write the unpartitioned rows.
+    InvalidScopeErrorCode["scopeRequired"] = "scopeRequired";
+    // The call carried a scope but the resource is not declared `scoped` in
+    // config: the data would land under a prefix nothing else on that resource
+    // expects, invisible to every unscoped reader.
+    InvalidScopeErrorCode["notScoped"] = "notScoped";
 })(InvalidScopeErrorCode || (exports.InvalidScopeErrorCode = InvalidScopeErrorCode = {}));
 class InvalidScopeError extends Error {
     constructor(code, message) {

package/lib/commonjs/logic/scope/InvalidScopeError.js.map

@@ -1 +1 @@
-{"version":3,"file":"InvalidScopeError.js","sourceRoot":"","sources":["../../../../src/logic/scope/InvalidScopeError.ts"],"names":[],"mappings":";;;AAAA,8EAA8E;AAC9E,4EAA4E;AAC5E,uEAAuE;AACvE,6EAA6E;AAC7E,mBAAmB;AACnB,IAAY,qBAgBX;AAhBD,WAAY,qBAAqB;IAC/B,kCAAkC;IAClC,wCAAe,CAAA;IACf,mDAAmD;IACnD,8DAAqC,CAAA;IACrC,kEAAkE;IAClE,4CAAmB,CAAA;IACnB,uEAAuE;IACvE,yCAAyC;IACzC,kDAAyB,CAAA;IACzB,0EAA0E;IAC1E,0EAA0E;IAC1E,8EAAqD,CAAA;IACrD,6EAA6E;IAC7E,qEAAqE;IACrE,gEAAuC,CAAA;AACzC,CAAC,EAhBW,qBAAqB,qCAArB,qBAAqB,QAgBhC;AAED,MAAa,iBAAkB,SAAQ,KAAK;IAC1C,YACkB,IAA2B,EAC3C,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAuB;QAI3C,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AARD,8CAQC","sourcesContent":["// Raised when a scope segment fails validation. Scope is an opaque identifier\n// (supplied by a higher-level data-partitioning feature) that gets embedded\n// into file paths and kvs partition keys, so a malformed one is always\n// rejected outright - never normalized - to make escaping a scope impossible\n// by construction.\nexport enum InvalidScopeErrorCode {\n  // Empty or whitespace-only scope.\n  empty = 'empty',\n  // Contains a path separator, '..', or a null byte.\n  unsafeCharacters = 'unsafeCharacters',\n  // Longer than the allowed maximum (scopes are ids, not payloads).\n  tooLong = 'tooLong',\n  // A filepath composed under a scope could traverse out of it (absolute\n  // path, a '..' segment, or a null byte).\n  unsafePath = 'unsafePath',\n  // A scoped query whose key condition never constrains the partition key -\n  // on value-composed backends (dynamo) it would silently span every scope.\n  queryMissingPartitionKey = 'queryMissingPartitionKey',\n  // A raw partition-key value containing the scope delimiter: storing it would\n  // make the row indistinguishable from another scope's composed data.\n  reservedDelimiter = 'reservedDelimiter',\n}\n\nexport class InvalidScopeError extends Error {\n  constructor(\n    public readonly code: InvalidScopeErrorCode,\n    message: string,\n  ) {\n    super(message);\n    this.name = 'InvalidScopeError';\n  }\n}\n"]}
+{"version":3,"file":"InvalidScopeError.js","sourceRoot":"","sources":["../../../../src/logic/scope/InvalidScopeError.ts"],"names":[],"mappings":";;;AAAA,8EAA8E;AAC9E,4EAA4E;AAC5E,uEAAuE;AACvE,6EAA6E;AAC7E,mBAAmB;AACnB,IAAY,qBAwBX;AAxBD,WAAY,qBAAqB;IAC/B,kCAAkC;IAClC,wCAAe,CAAA;IACf,mDAAmD;IACnD,8DAAqC,CAAA;IACrC,kEAAkE;IAClE,4CAAmB,CAAA;IACnB,uEAAuE;IACvE,yCAAyC;IACzC,kDAAyB,CAAA;IACzB,0EAA0E;IAC1E,0EAA0E;IAC1E,8EAAqD,CAAA;IACrD,6EAA6E;IAC7E,qEAAqE;IACrE,gEAAuC,CAAA;IACvC,6EAA6E;IAC7E,2EAA2E;IAC3E,uDAAuD;IACvD,wDAA+B,CAAA;IAC/B,wEAAwE;IACxE,2EAA2E;IAC3E,+CAA+C;IAC/C,gDAAuB,CAAA;AACzB,CAAC,EAxBW,qBAAqB,qCAArB,qBAAqB,QAwBhC;AAED,MAAa,iBAAkB,SAAQ,KAAK;IAC1C,YACkB,IAA2B,EAC3C,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAuB;QAI3C,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AARD,8CAQC","sourcesContent":["// Raised when a scope segment fails validation. Scope is an opaque identifier\n// (supplied by a higher-level data-partitioning feature) that gets embedded\n// into file paths and kvs partition keys, so a malformed one is always\n// rejected outright - never normalized - to make escaping a scope impossible\n// by construction.\nexport enum InvalidScopeErrorCode {\n  // Empty or whitespace-only scope.\n  empty = 'empty',\n  // Contains a path separator, '..', or a null byte.\n  unsafeCharacters = 'unsafeCharacters',\n  // Longer than the allowed maximum (scopes are ids, not payloads).\n  tooLong = 'tooLong',\n  // A filepath composed under a scope could traverse out of it (absolute\n  // path, a '..' segment, or a null byte).\n  unsafePath = 'unsafePath',\n  // A scoped query whose key condition never constrains the partition key -\n  // on value-composed backends (dynamo) it would silently span every scope.\n  queryMissingPartitionKey = 'queryMissingPartitionKey',\n  // A raw partition-key value containing the scope delimiter: storing it would\n  // make the row indistinguishable from another scope's composed data.\n  reservedDelimiter = 'reservedDelimiter',\n  // The resource is declared `scoped` in config but the call carried no scope.\n  // On a drive that would land the object beside every tenant's prefix; on a\n  // store it would read or write the unpartitioned rows.\n  scopeRequired = 'scopeRequired',\n  // The call carried a scope but the resource is not declared `scoped` in\n  // config: the data would land under a prefix nothing else on that resource\n  // expects, invisible to every unscoped reader.\n  notScoped = 'notScoped',\n}\n\nexport class InvalidScopeError extends Error {\n  constructor(\n    public readonly code: InvalidScopeErrorCode,\n    message: string,\n  ) {\n    super(message);\n    this.name = 'InvalidScopeError';\n  }\n}\n"]}

package/lib/commonjs/logic/scope/fileScopeGate.d.ts

@@ -0,0 +1,8 @@
+import { QPQConfig } from '../../config';
+export declare const assertStorageDriveScopeRequirementOrThrow: (qpqConfig: QPQConfig, drive: string, scope: string | undefined) => void;
+/**
+ * Gate then compose: the path a key-based backend (s3) stores under. Throws
+ * InvalidScopeError when the drive is scoped and no scope was given, or when
+ * the scope or filepath fails validation.
+ */
+export declare const composeStorageDriveFilePathOrThrow: (qpqConfig: QPQConfig, drive: string, scope: string | undefined, filepath: string) => string;

package/lib/commonjs/logic/scope/fileScopeGate.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeStorageDriveFilePathOrThrow = exports.assertStorageDriveScopeRequirementOrThrow = void 0;
+const qpqCoreUtils_1 = require("../../qpqCoreUtils");
+const composeScopedFilePath_1 = require("./composeScopedFilePath");
+const InvalidScopeError_1 = require("./InvalidScopeError");
+// THE shared scope gate for every file backend (s3, node fs, ...). The drive's
+// `scoped` flag and the call's scope must agree: a scoped drive refuses a call
+// without one, an unscoped drive refuses a call with one, so a mismatch is an
+// error rather than a different path. An unknown drive is left for the backend
+// to report as its own DriveNotFound.
+const assertStorageDriveScopeRequirementOrThrow = (qpqConfig, drive, scope) => {
+    const driveConfig = (0, qpqCoreUtils_1.getStorageDriveByName)(drive, qpqConfig);
+    if (!driveConfig) {
+        return;
+    }
+    if (driveConfig.scoped && scope === undefined) {
+        throw new InvalidScopeError_1.InvalidScopeError(InvalidScopeError_1.InvalidScopeErrorCode.scopeRequired, `Storage drive '${drive}' is scoped; every file action must carry a scope.`);
+    }
+    if (!driveConfig.scoped && scope !== undefined) {
+        throw new InvalidScopeError_1.InvalidScopeError(InvalidScopeError_1.InvalidScopeErrorCode.notScoped, `Storage drive '${drive}' is not scoped; declare it scoped or drop the scope.`);
+    }
+};
+exports.assertStorageDriveScopeRequirementOrThrow = assertStorageDriveScopeRequirementOrThrow;
+/**
+ * Gate then compose: the path a key-based backend (s3) stores under. Throws
+ * InvalidScopeError when the drive is scoped and no scope was given, or when
+ * the scope or filepath fails validation.
+ */
+const composeStorageDriveFilePathOrThrow = (qpqConfig, drive, scope, filepath) => {
+    (0, exports.assertStorageDriveScopeRequirementOrThrow)(qpqConfig, drive, scope);
+    return (0, composeScopedFilePath_1.composeScopedFilePath)(scope, filepath);
+};
+exports.composeStorageDriveFilePathOrThrow = composeStorageDriveFilePathOrThrow;
+//# sourceMappingURL=fileScopeGate.js.map

package/lib/commonjs/logic/scope/fileScopeGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileScopeGate.js","sourceRoot":"","sources":["../../../../src/logic/scope/fileScopeGate.ts"],"names":[],"mappings":";;;AACA,qDAA2D;AAC3D,mEAAgE;AAChE,2DAA+E;AAE/E,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,sCAAsC;AAC/B,MAAM,yCAAyC,GAAG,CAAC,SAAoB,EAAE,KAAa,EAAE,KAAyB,EAAQ,EAAE;IAChI,MAAM,WAAW,GAAG,IAAA,oCAAqB,EAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAE5D,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO;IACT,CAAC;IAED,IAAI,WAAW,CAAC,MAAM,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9C,MAAM,IAAI,qCAAiB,CAAC,yCAAqB,CAAC,aAAa,EAAE,kBAAkB,KAAK,oDAAoD,CAAC,CAAC;IAChJ,CAAC;IAED,IAAI,CAAC,WAAW,CAAC,MAAM,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/C,MAAM,IAAI,qCAAiB,CAAC,yCAAqB,CAAC,SAAS,EAAE,kBAAkB,KAAK,uDAAuD,CAAC,CAAC;IAC/I,CAAC;AACH,CAAC,CAAC;AAdW,QAAA,yCAAyC,6CAcpD;AAEF;;;;GAIG;AACI,MAAM,kCAAkC,GAAG,CAAC,SAAoB,EAAE,KAAa,EAAE,KAAyB,EAAE,QAAgB,EAAU,EAAE;IAC7I,IAAA,iDAAyC,EAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAEnE,OAAO,IAAA,6CAAqB,EAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC,CAAC;AAJW,QAAA,kCAAkC,sCAI7C","sourcesContent":["import { QPQConfig } from '../../config';\nimport { getStorageDriveByName } from '../../qpqCoreUtils';\nimport { composeScopedFilePath } from './composeScopedFilePath';\nimport { InvalidScopeError, InvalidScopeErrorCode } from './InvalidScopeError';\n\n// THE shared scope gate for every file backend (s3, node fs, ...). The drive's\n// `scoped` flag and the call's scope must agree: a scoped drive refuses a call\n// without one, an unscoped drive refuses a call with one, so a mismatch is an\n// error rather than a different path. An unknown drive is left for the backend\n// to report as its own DriveNotFound.\nexport const assertStorageDriveScopeRequirementOrThrow = (qpqConfig: QPQConfig, drive: string, scope: string | undefined): void => {\n  const driveConfig = getStorageDriveByName(drive, qpqConfig);\n\n  if (!driveConfig) {\n    return;\n  }\n\n  if (driveConfig.scoped && scope === undefined) {\n    throw new InvalidScopeError(InvalidScopeErrorCode.scopeRequired, `Storage drive '${drive}' is scoped; every file action must carry a scope.`);\n  }\n\n  if (!driveConfig.scoped && scope !== undefined) {\n    throw new InvalidScopeError(InvalidScopeErrorCode.notScoped, `Storage drive '${drive}' is not scoped; declare it scoped or drop the scope.`);\n  }\n};\n\n/**\n * Gate then compose: the path a key-based backend (s3) stores under. Throws\n * InvalidScopeError when the drive is scoped and no scope was given, or when\n * the scope or filepath fails validation.\n */\nexport const composeStorageDriveFilePathOrThrow = (qpqConfig: QPQConfig, drive: string, scope: string | undefined, filepath: string): string => {\n  assertStorageDriveScopeRequirementOrThrow(qpqConfig, drive, scope);\n\n  return composeScopedFilePath(scope, filepath);\n};\n"]}

package/lib/commonjs/logic/scope/index.d.ts

@@ -1,10 +1,12 @@
 export * from './composeScopedFilePath';
+export * from './fileScopeGate';
 export * from './InvalidScopeError';
 export * from './kvsScopeGate';
 export * from './KvsStoreNotFoundError';
 export * from './scopedKvsQueryOperation';
 export * from './scopedKvsTranslator';
 export * from './scopedKvsValue';
+export * from './splitScopedFilePath';
 export * from './storageScopeContext';
 export * from './stripScopedFilePath';
 export * from './validateScopeSegment';

package/lib/commonjs/logic/scope/index.js

@@ -15,12 +15,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./composeScopedFilePath"), exports);
+__exportStar(require("./fileScopeGate"), exports);
 __exportStar(require("./InvalidScopeError"), exports);
 __exportStar(require("./kvsScopeGate"), exports);
 __exportStar(require("./KvsStoreNotFoundError"), exports);
 __exportStar(require("./scopedKvsQueryOperation"), exports);
 __exportStar(require("./scopedKvsTranslator"), exports);
 __exportStar(require("./scopedKvsValue"), exports);
+__exportStar(require("./splitScopedFilePath"), exports);
 __exportStar(require("./storageScopeContext"), exports);
 __exportStar(require("./stripScopedFilePath"), exports);
 __exportStar(require("./validateScopeSegment"), exports);

package/lib/commonjs/logic/scope/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/logic/scope/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0DAAwC;AACxC,sDAAoC;AACpC,iDAA+B;AAC/B,0DAAwC;AACxC,4DAA0C;AAC1C,wDAAsC;AACtC,mDAAiC;AACjC,wDAAsC;AACtC,wDAAsC;AACtC,yDAAuC","sourcesContent":["export * from './composeScopedFilePath';\nexport * from './InvalidScopeError';\nexport * from './kvsScopeGate';\nexport * from './KvsStoreNotFoundError';\nexport * from './scopedKvsQueryOperation';\nexport * from './scopedKvsTranslator';\nexport * from './scopedKvsValue';\nexport * from './storageScopeContext';\nexport * from './stripScopedFilePath';\nexport * from './validateScopeSegment';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/logic/scope/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0DAAwC;AACxC,kDAAgC;AAChC,sDAAoC;AACpC,iDAA+B;AAC/B,0DAAwC;AACxC,4DAA0C;AAC1C,wDAAsC;AACtC,mDAAiC;AACjC,wDAAsC;AACtC,wDAAsC;AACtC,wDAAsC;AACtC,yDAAuC","sourcesContent":["export * from './composeScopedFilePath';\nexport * from './fileScopeGate';\nexport * from './InvalidScopeError';\nexport * from './kvsScopeGate';\nexport * from './KvsStoreNotFoundError';\nexport * from './scopedKvsQueryOperation';\nexport * from './scopedKvsTranslator';\nexport * from './scopedKvsValue';\nexport * from './splitScopedFilePath';\nexport * from './storageScopeContext';\nexport * from './stripScopedFilePath';\nexport * from './validateScopeSegment';\n"]}

package/lib/commonjs/logic/scope/kvsScopeGate.d.ts

@@ -2,6 +2,7 @@ import { KvsCoreDataType, KvsQueryOperation } from '../../actions/keyValueStore/
 import { KeyValueStoreQPQConfigSetting, QPQConfig } from '../../config';
 import { ScopedKvsTranslator } from './scopedKvsTranslator';
 export declare const resolveKvsStoreConfigOrThrow: (qpqConfig: QPQConfig, keyValueStoreName: string) => KeyValueStoreQPQConfigSetting;
+export declare const assertKvsScopeRequirementOrThrow: (qpqConfig: QPQConfig, keyValueStoreName: string, scope: string | undefined) => void;
 export declare const getScopedKvsTranslatorOrThrow: (qpqConfig: QPQConfig, keyValueStoreName: string, scope: string | undefined) => ScopedKvsTranslator;
 export declare const resolveScopedPkAttributeOrThrow: (qpqConfig: QPQConfig, keyValueStoreName: string, scope: string) => string;
 export declare const validateScopedKvsKeyOrThrow: (qpqConfig: QPQConfig, keyValueStoreName: string, scope: string | undefined, key: KvsCoreDataType) => void;