quidproquo-core 0.1.18 → 0.1.20

package/lib/commonjs/actions/keyValueStore/askKeyValueStoreUpsert.d.ts

@@ -10,5 +10,5 @@ export declare const askKeyValueStoreUpsertBase: import("../..").ActionRequester
     keyValueStoreName: string;
     item: KvsItemRecord;
     options: KeyValueStoreUpsertOptions | undefined;
-}, void, "Conflict" | "ResourceNotFound" | "ServiceUnavailable" | "InvalidScope" | "StoreNotFound">;
+}, void, "Conflict" | "ResourceNotFound" | "ServiceUnavailable" | "InvalidScope" | "StoreNotFound" | "WriteContention">;
 export declare function askKeyValueStoreUpsert<KvsItem>(keyValueStoreName: string, item: KvsItem, options?: KeyValueStoreUpsertOptions): AskResponse<void>;

package/lib/commonjs/actions/keyValueStore/askKeyValueStoreUpsert.js

@@ -9,10 +9,14 @@ exports.askKeyValueStoreUpsertBase = (0, createActionRequester_1.createActionReq
     errorTypes: [
         'ServiceUnavailable', // DynamoDB internal error / throttling
         'ResourceNotFound', // the underlying table does not exist
-        // A conditional (ifNotExists) write lost to an existing item. Namespaced —
-        // not ErrorTypeEnum.Conflict — so retry logic can target the write race
+        // A conditional (ifNotExists) write lost to an existing item. Final: the slot is taken.
+        // Namespaced, not ErrorTypeEnum.Conflict, so retry logic can target the write race
         // specifically without also catching domain-level conflicts.
         'Conflict',
+        // Another write (a transaction in flight) holds the item right now. Transient: the item
+        // may still be absent once it settles, so this is a retry, never "already exists".
+        // askKeyValueStoreUpsertWithRetry retries it.
+        'WriteContention',
         'InvalidScope', // scope is malformed or the store's partition key is not string-typed
         'StoreNotFound', // the store is not declared in the qpq config (misconfiguration)
     ],

package/lib/commonjs/actions/keyValueStore/askKeyValueStoreUpsert.js.map

@@ -1 +1 @@
-{"version":3,"file":"askKeyValueStoreUpsert.js","sourceRoot":"","sources":["../../../../src/actions/keyValueStore/askKeyValueStoreUpsert.ts"],"names":[],"mappings":";;;AAkCA,wDAEC;AAnCD,mFAAgF;AAChF,uEAAoE;AAgBvD,QAAA,0BAA0B,GAAG,IAAA,6CAAqB,GAAQ,CAAC;IACtE,UAAU,EAAE,iDAAuB,CAAC,MAAM;IAC1C,UAAU,EAAE;QACV,oBAAoB,EAAE,uCAAuC;QAC7D,kBAAkB,EAAE,sCAAsC;QAC1D,2EAA2E;QAC3E,wEAAwE;QACxE,6DAA6D;QAC7D,UAAU;QACV,cAAc,EAAE,sEAAsE;QACtF,eAAe,EAAE,iEAAiE;KACnF;IACD,UAAU,EAAE,CAAC,iBAAyB,EAAE,IAAmB,EAAE,OAAoC,EAAE,EAAE,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;CAC7I,CAAC,CAAC;AAEH,+EAA+E;AAC/E,QAAe,CAAC,CAAC,sBAAsB,CAAU,iBAAyB,EAAE,IAAa,EAAE,OAAoC;IAC7H,OAAO,KAAK,CAAC,CAAC,IAAA,kCAA0B,EAAC,iBAAiB,EAAE,IAAqB,EAAE,OAAO,CAAC,CAAC;AAC9F,CAAC","sourcesContent":["import { AskResponse } from '../../types/StorySession';\nimport { createActionRequester } from '../../types/utils/createActionRequester';\nimport { KeyValueStoreActionType } from './KeyValueStoreActionType';\nimport { KvsItemRecord } from './types';\n\nexport type KeyValueStoreUpsertOptions = {\n  ttlInSeconds?: number; // Time-to-live in seconds\n\n  // Conditional insert: only write when no item with the same key exists.\n  // A losing concurrent writer gets ErrorTypeEnum.Conflict instead of silently\n  // overwriting — the primitive for optimistic-concurrency schemes (e.g.\n  // append-only event logs where the sort key is a claimed index).\n  ifNotExists?: boolean;\n\n  // Composed into the item's partition key value by the processor; requires a string-typed partition key.\n  scope?: string;\n};\n\nexport const askKeyValueStoreUpsertBase = createActionRequester<void>()({\n  actionType: KeyValueStoreActionType.Upsert,\n  errorTypes: [\n    'ServiceUnavailable', // DynamoDB internal error / throttling\n    'ResourceNotFound', // the underlying table does not exist\n    // A conditional (ifNotExists) write lost to an existing item. Namespaced —\n    // not ErrorTypeEnum.Conflict — so retry logic can target the write race\n    // specifically without also catching domain-level conflicts.\n    'Conflict',\n    'InvalidScope', // scope is malformed or the store's partition key is not string-typed\n    'StoreNotFound', // the store is not declared in the qpq config (misconfiguration)\n  ],\n  getPayload: (keyValueStoreName: string, item: KvsItemRecord, options?: KeyValueStoreUpsertOptions) => ({ keyValueStoreName, item, options }),\n});\n\n// Generic so callers can pin the item shape they are writing at the call site.\nexport function* askKeyValueStoreUpsert<KvsItem>(keyValueStoreName: string, item: KvsItem, options?: KeyValueStoreUpsertOptions): AskResponse<void> {\n  return yield* askKeyValueStoreUpsertBase(keyValueStoreName, item as KvsItemRecord, options);\n}\n"]}
+{"version":3,"file":"askKeyValueStoreUpsert.js","sourceRoot":"","sources":["../../../../src/actions/keyValueStore/askKeyValueStoreUpsert.ts"],"names":[],"mappings":";;;AAsCA,wDAEC;AAvCD,mFAAgF;AAChF,uEAAoE;AAgBvD,QAAA,0BAA0B,GAAG,IAAA,6CAAqB,GAAQ,CAAC;IACtE,UAAU,EAAE,iDAAuB,CAAC,MAAM;IAC1C,UAAU,EAAE;QACV,oBAAoB,EAAE,uCAAuC;QAC7D,kBAAkB,EAAE,sCAAsC;QAC1D,wFAAwF;QACxF,mFAAmF;QACnF,6DAA6D;QAC7D,UAAU;QACV,wFAAwF;QACxF,mFAAmF;QACnF,8CAA8C;QAC9C,iBAAiB;QACjB,cAAc,EAAE,sEAAsE;QACtF,eAAe,EAAE,iEAAiE;KACnF;IACD,UAAU,EAAE,CAAC,iBAAyB,EAAE,IAAmB,EAAE,OAAoC,EAAE,EAAE,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;CAC7I,CAAC,CAAC;AAEH,+EAA+E;AAC/E,QAAe,CAAC,CAAC,sBAAsB,CAAU,iBAAyB,EAAE,IAAa,EAAE,OAAoC;IAC7H,OAAO,KAAK,CAAC,CAAC,IAAA,kCAA0B,EAAC,iBAAiB,EAAE,IAAqB,EAAE,OAAO,CAAC,CAAC;AAC9F,CAAC","sourcesContent":["import { AskResponse } from '../../types/StorySession';\nimport { createActionRequester } from '../../types/utils/createActionRequester';\nimport { KeyValueStoreActionType } from './KeyValueStoreActionType';\nimport { KvsItemRecord } from './types';\n\nexport type KeyValueStoreUpsertOptions = {\n  ttlInSeconds?: number; // Time-to-live in seconds\n\n  // Conditional insert: only write when no item with the same key exists.\n  // A losing concurrent writer gets ErrorTypeEnum.Conflict instead of silently\n  // overwriting — the primitive for optimistic-concurrency schemes (e.g.\n  // append-only event logs where the sort key is a claimed index).\n  ifNotExists?: boolean;\n\n  // Composed into the item's partition key value by the processor; requires a string-typed partition key.\n  scope?: string;\n};\n\nexport const askKeyValueStoreUpsertBase = createActionRequester<void>()({\n  actionType: KeyValueStoreActionType.Upsert,\n  errorTypes: [\n    'ServiceUnavailable', // DynamoDB internal error / throttling\n    'ResourceNotFound', // the underlying table does not exist\n    // A conditional (ifNotExists) write lost to an existing item. Final: the slot is taken.\n    // Namespaced, not ErrorTypeEnum.Conflict, so retry logic can target the write race\n    // specifically without also catching domain-level conflicts.\n    'Conflict',\n    // Another write (a transaction in flight) holds the item right now. Transient: the item\n    // may still be absent once it settles, so this is a retry, never \"already exists\".\n    // askKeyValueStoreUpsertWithRetry retries it.\n    'WriteContention',\n    'InvalidScope', // scope is malformed or the store's partition key is not string-typed\n    'StoreNotFound', // the store is not declared in the qpq config (misconfiguration)\n  ],\n  getPayload: (keyValueStoreName: string, item: KvsItemRecord, options?: KeyValueStoreUpsertOptions) => ({ keyValueStoreName, item, options }),\n});\n\n// Generic so callers can pin the item shape they are writing at the call site.\nexport function* askKeyValueStoreUpsert<KvsItem>(keyValueStoreName: string, item: KvsItem, options?: KeyValueStoreUpsertOptions): AskResponse<void> {\n  return yield* askKeyValueStoreUpsertBase(keyValueStoreName, item as KvsItemRecord, options);\n}\n"]}

package/lib/commonjs/actions/keyValueStore/askKeyValueStoreUpsertMany.d.ts

@@ -2,11 +2,12 @@ import { AskResponse } from '../../types/StorySession';
 import { KeyValueStoreActionType } from './KeyValueStoreActionType';
 import { KvsItemRecord } from './types';
 export type KeyValueStoreUpsertManyOptions = {
+    ifNotExists?: boolean;
     scope?: string;
 };
 export declare const askKeyValueStoreUpsertManyBase: import("../..").ActionRequesterFunction<KeyValueStoreActionType.UpsertMany, [keyValueStoreName: string, items: KvsItemRecord[], options?: KeyValueStoreUpsertManyOptions | undefined], {
     keyValueStoreName: string;
     items: KvsItemRecord[];
     options: KeyValueStoreUpsertManyOptions | undefined;
-}, void, "ResourceNotFound" | "ServiceUnavailable" | "InvalidScope" | "StoreNotFound" | "DuplicateKey">;
+}, void, "Conflict" | "ResourceNotFound" | "ServiceUnavailable" | "InvalidScope" | "StoreNotFound" | "WriteContention" | "DuplicateKey">;
 export declare function askKeyValueStoreUpsertMany<KvsItem>(keyValueStoreName: string, items: KvsItem[], options?: KeyValueStoreUpsertManyOptions): AskResponse<void>;

package/lib/commonjs/actions/keyValueStore/askKeyValueStoreUpsertMany.js

@@ -17,6 +17,13 @@ exports.askKeyValueStoreUpsertManyBase = (0, createActionRequester_1.createActio
         // the later write silently wins), so without this check the outcome would
         // depend on item position and never reproduce locally.
         'DuplicateKey',
+        // A conditional (ifNotExists) batch lost to an existing item; none of the batch was
+        // written. Final: a slot is taken. Namespaced, not ErrorTypeEnum.Conflict, so retry
+        // logic can target the write race specifically without also catching domain-level conflicts.
+        'Conflict',
+        // Another write holds one of the batch's items right now; none of the batch was
+        // written. Transient: retry.
+        'WriteContention',
     ],
     getPayload: (keyValueStoreName, items, options) => ({
         keyValueStoreName,

package/lib/commonjs/actions/keyValueStore/askKeyValueStoreUpsertMany.js.map

@@ -1 +1 @@
-{"version":3,"file":"askKeyValueStoreUpsertMany.js","sourceRoot":"","sources":["../../../../src/actions/keyValueStore/askKeyValueStoreUpsertMany.ts"],"names":[],"mappings":";;;AAgCA,gEAMC;AArCD,mFAAgF;AAChF,uEAAoE;AAQvD,QAAA,8BAA8B,GAAG,IAAA,6CAAqB,GAAQ,CAAC;IAC1E,UAAU,EAAE,iDAAuB,CAAC,UAAU;IAC9C,UAAU,EAAE;QACV,oBAAoB,EAAE,uCAAuC;QAC7D,kBAAkB,EAAE,sCAAsC;QAC1D,cAAc,EAAE,sEAAsE;QACtF,eAAe,EAAE,iEAAiE;QAClF,yEAAyE;QACzE,4EAA4E;QAC5E,8EAA8E;QAC9E,0EAA0E;QAC1E,uDAAuD;QACvD,cAAc;KACf;IACD,UAAU,EAAE,CAAC,iBAAyB,EAAE,KAAsB,EAAE,OAAwC,EAAE,EAAE,CAAC,CAAC;QAC5G,iBAAiB;QACjB,KAAK;QACL,OAAO;KACR,CAAC;CACH,CAAC,CAAC;AAEH,+EAA+E;AAC/E,QAAe,CAAC,CAAC,0BAA0B,CACzC,iBAAyB,EACzB,KAAgB,EAChB,OAAwC;IAExC,OAAO,KAAK,CAAC,CAAC,IAAA,sCAA8B,EAAC,iBAAiB,EAAE,KAAwB,EAAE,OAAO,CAAC,CAAC;AACrG,CAAC","sourcesContent":["import { AskResponse } from '../../types/StorySession';\nimport { createActionRequester } from '../../types/utils/createActionRequester';\nimport { KeyValueStoreActionType } from './KeyValueStoreActionType';\nimport { KvsItemRecord } from './types';\n\nexport type KeyValueStoreUpsertManyOptions = {\n  // Composed into each item's partition key value by the processor; requires a string-typed partition key.\n  scope?: string;\n};\n\nexport const askKeyValueStoreUpsertManyBase = createActionRequester<void>()({\n  actionType: KeyValueStoreActionType.UpsertMany,\n  errorTypes: [\n    'ServiceUnavailable', // DynamoDB internal error / throttling\n    'ResourceNotFound', // the underlying table does not exist\n    'InvalidScope', // scope is malformed or the store's partition key is not string-typed\n    'StoreNotFound', // the store is not declared in the qpq config (misconfiguration)\n    // Two items in one batch share a primary key. Rejected up front on every\n    // runtime, before anything is written: DynamoDB rejects same-key duplicates\n    // only when they land in the same 25-item BatchWriteItem chunk (across chunks\n    // the later write silently wins), so without this check the outcome would\n    // depend on item position and never reproduce locally.\n    'DuplicateKey',\n  ],\n  getPayload: (keyValueStoreName: string, items: KvsItemRecord[], options?: KeyValueStoreUpsertManyOptions) => ({\n    keyValueStoreName,\n    items,\n    options,\n  }),\n});\n\n// Generic so callers can pin the item shape they are writing at the call site.\nexport function* askKeyValueStoreUpsertMany<KvsItem>(\n  keyValueStoreName: string,\n  items: KvsItem[],\n  options?: KeyValueStoreUpsertManyOptions,\n): AskResponse<void> {\n  return yield* askKeyValueStoreUpsertManyBase(keyValueStoreName, items as KvsItemRecord[], options);\n}\n"]}
+{"version":3,"file":"askKeyValueStoreUpsertMany.js","sourceRoot":"","sources":["../../../../src/actions/keyValueStore/askKeyValueStoreUpsertMany.ts"],"names":[],"mappings":";;;AA+CA,gEAMC;AApDD,mFAAgF;AAChF,uEAAoE;AAgBvD,QAAA,8BAA8B,GAAG,IAAA,6CAAqB,GAAQ,CAAC;IAC1E,UAAU,EAAE,iDAAuB,CAAC,UAAU;IAC9C,UAAU,EAAE;QACV,oBAAoB,EAAE,uCAAuC;QAC7D,kBAAkB,EAAE,sCAAsC;QAC1D,cAAc,EAAE,sEAAsE;QACtF,eAAe,EAAE,iEAAiE;QAClF,yEAAyE;QACzE,4EAA4E;QAC5E,8EAA8E;QAC9E,0EAA0E;QAC1E,uDAAuD;QACvD,cAAc;QACd,oFAAoF;QACpF,oFAAoF;QACpF,6FAA6F;QAC7F,UAAU;QACV,gFAAgF;QAChF,6BAA6B;QAC7B,iBAAiB;KAClB;IACD,UAAU,EAAE,CAAC,iBAAyB,EAAE,KAAsB,EAAE,OAAwC,EAAE,EAAE,CAAC,CAAC;QAC5G,iBAAiB;QACjB,KAAK;QACL,OAAO;KACR,CAAC;CACH,CAAC,CAAC;AAEH,+EAA+E;AAC/E,QAAe,CAAC,CAAC,0BAA0B,CACzC,iBAAyB,EACzB,KAAgB,EAChB,OAAwC;IAExC,OAAO,KAAK,CAAC,CAAC,IAAA,sCAA8B,EAAC,iBAAiB,EAAE,KAAwB,EAAE,OAAO,CAAC,CAAC;AACrG,CAAC","sourcesContent":["import { AskResponse } from '../../types/StorySession';\nimport { createActionRequester } from '../../types/utils/createActionRequester';\nimport { KeyValueStoreActionType } from './KeyValueStoreActionType';\nimport { KvsItemRecord } from './types';\n\nexport type KeyValueStoreUpsertManyOptions = {\n  // Conditional batch insert: only write when NO item in the batch has an\n  // existing key, and write ALL of them or none. The batch becomes a\n  // transaction on every runtime (DynamoDB TransactWriteItems, a SQLite\n  // transaction locally), so a losing concurrent writer gets the namespaced\n  // Conflict with nothing landed - the batch primitive for claiming a run of\n  // consecutive slots in an append-only log.\n  ifNotExists?: boolean;\n\n  // Composed into each item's partition key value by the processor; requires a string-typed partition key.\n  scope?: string;\n};\n\nexport const askKeyValueStoreUpsertManyBase = createActionRequester<void>()({\n  actionType: KeyValueStoreActionType.UpsertMany,\n  errorTypes: [\n    'ServiceUnavailable', // DynamoDB internal error / throttling\n    'ResourceNotFound', // the underlying table does not exist\n    'InvalidScope', // scope is malformed or the store's partition key is not string-typed\n    'StoreNotFound', // the store is not declared in the qpq config (misconfiguration)\n    // Two items in one batch share a primary key. Rejected up front on every\n    // runtime, before anything is written: DynamoDB rejects same-key duplicates\n    // only when they land in the same 25-item BatchWriteItem chunk (across chunks\n    // the later write silently wins), so without this check the outcome would\n    // depend on item position and never reproduce locally.\n    'DuplicateKey',\n    // A conditional (ifNotExists) batch lost to an existing item; none of the batch was\n    // written. Final: a slot is taken. Namespaced, not ErrorTypeEnum.Conflict, so retry\n    // logic can target the write race specifically without also catching domain-level conflicts.\n    'Conflict',\n    // Another write holds one of the batch's items right now; none of the batch was\n    // written. Transient: retry.\n    'WriteContention',\n  ],\n  getPayload: (keyValueStoreName: string, items: KvsItemRecord[], options?: KeyValueStoreUpsertManyOptions) => ({\n    keyValueStoreName,\n    items,\n    options,\n  }),\n});\n\n// Generic so callers can pin the item shape they are writing at the call site.\nexport function* askKeyValueStoreUpsertMany<KvsItem>(\n  keyValueStoreName: string,\n  items: KvsItem[],\n  options?: KeyValueStoreUpsertManyOptions,\n): AskResponse<void> {\n  return yield* askKeyValueStoreUpsertManyBase(keyValueStoreName, items as KvsItemRecord[], options);\n}\n"]}

package/lib/commonjs/config/settings/schedule/InvalidScheduleRecurrenceError.d.ts

@@ -0,0 +1,20 @@
+export declare enum InvalidScheduleRecurrenceErrorCode {
+    UnknownRecurrence = "UnknownRecurrence",
+    IntervalDoesNotDivideEvenly = "IntervalDoesNotDivideEvenly",
+    ValueOutOfRange = "ValueOutOfRange"
+}
+/**
+ * A recurrence that cannot be scheduled.
+ *
+ * Thrown from `resolveScheduleFields`, which `defineRecurringSchedule` calls,
+ * so a bad schedule fails while the config is being evaluated - at synth AND
+ * at dev-server boot - rather than at deploy or, worse, silently at the wrong
+ * time of day.
+ *
+ * A named subclass with a code rather than a bare Error, so a caller can tell
+ * these apart from anything else that went wrong while loading config.
+ */
+export declare class InvalidScheduleRecurrenceError extends Error {
+    readonly code: InvalidScheduleRecurrenceErrorCode;
+    constructor(code: InvalidScheduleRecurrenceErrorCode, message: string);
+}

package/lib/commonjs/config/settings/schedule/InvalidScheduleRecurrenceError.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidScheduleRecurrenceError = exports.InvalidScheduleRecurrenceErrorCode = void 0;
+var InvalidScheduleRecurrenceErrorCode;
+(function (InvalidScheduleRecurrenceErrorCode) {
+    InvalidScheduleRecurrenceErrorCode["UnknownRecurrence"] = "UnknownRecurrence";
+    InvalidScheduleRecurrenceErrorCode["IntervalDoesNotDivideEvenly"] = "IntervalDoesNotDivideEvenly";
+    InvalidScheduleRecurrenceErrorCode["ValueOutOfRange"] = "ValueOutOfRange";
+})(InvalidScheduleRecurrenceErrorCode || (exports.InvalidScheduleRecurrenceErrorCode = InvalidScheduleRecurrenceErrorCode = {}));
+/**
+ * A recurrence that cannot be scheduled.
+ *
+ * Thrown from `resolveScheduleFields`, which `defineRecurringSchedule` calls,
+ * so a bad schedule fails while the config is being evaluated - at synth AND
+ * at dev-server boot - rather than at deploy or, worse, silently at the wrong
+ * time of day.
+ *
+ * A named subclass with a code rather than a bare Error, so a caller can tell
+ * these apart from anything else that went wrong while loading config.
+ */
+class InvalidScheduleRecurrenceError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'InvalidScheduleRecurrenceError';
+        this.code = code;
+    }
+}
+exports.InvalidScheduleRecurrenceError = InvalidScheduleRecurrenceError;
+//# sourceMappingURL=InvalidScheduleRecurrenceError.js.map

package/lib/commonjs/config/settings/schedule/InvalidScheduleRecurrenceError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvalidScheduleRecurrenceError.js","sourceRoot":"","sources":["../../../../../src/config/settings/schedule/InvalidScheduleRecurrenceError.ts"],"names":[],"mappings":";;;AAAA,IAAY,kCAIX;AAJD,WAAY,kCAAkC;IAC5C,6EAAuC,CAAA;IACvC,iGAA2D,CAAA;IAC3D,yEAAmC,CAAA;AACrC,CAAC,EAJW,kCAAkC,kDAAlC,kCAAkC,QAI7C;AAED;;;;;;;;;;GAUG;AACH,MAAa,8BAA+B,SAAQ,KAAK;IAGvD,YAAY,IAAwC,EAAE,OAAe;QACnE,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AATD,wEASC","sourcesContent":["export enum InvalidScheduleRecurrenceErrorCode {\n  UnknownRecurrence = 'UnknownRecurrence',\n  IntervalDoesNotDivideEvenly = 'IntervalDoesNotDivideEvenly',\n  ValueOutOfRange = 'ValueOutOfRange',\n}\n\n/**\n * A recurrence that cannot be scheduled.\n *\n * Thrown from `resolveScheduleFields`, which `defineRecurringSchedule` calls,\n * so a bad schedule fails while the config is being evaluated - at synth AND\n * at dev-server boot - rather than at deploy or, worse, silently at the wrong\n * time of day.\n *\n * A named subclass with a code rather than a bare Error, so a caller can tell\n * these apart from anything else that went wrong while loading config.\n */\nexport class InvalidScheduleRecurrenceError extends Error {\n  readonly code: InvalidScheduleRecurrenceErrorCode;\n\n  constructor(code: InvalidScheduleRecurrenceErrorCode, message: string) {\n    super(message);\n\n    this.name = 'InvalidScheduleRecurrenceError';\n    this.code = code;\n  }\n}\n"]}

package/lib/commonjs/config/settings/schedule/defineRecurringSchedule.d.ts

@@ -0,0 +1,37 @@
+import { QpqFunctionRuntime } from '../../../types';
+import { QPQConfigAdvancedScheduleSettings } from './types/QPQConfigAdvancedScheduleSettings';
+import { ScheduleQPQConfigSetting } from './types/ScheduleQPQConfigSetting';
+import { ScheduleRecurrence } from './types/ScheduleRecurrence';
+/**
+ * Run a story on a recurring timetable.
+ *
+ * The recurrence is declared as intent, not as a cron string. Deployed, it is
+ * rendered to an AWS EventBridge cron expression; locally, the dev server's
+ * ticker matches the same declaration against the clock. Neither behaviour is
+ * a special case of the other, which is the point.
+ *
+ * **Every time is UTC.** The deployed scheduler evaluates in UTC, so there is
+ * no local-timezone option: a schedule that reads `{ dailyAtUtc: { hour: 17 } }`
+ * is 3am in Brisbane, and saying so in the config is better than a comment
+ * that drifts out of date twice a year.
+ *
+ * ```ts
+ * // every ten minutes
+ * defineRecurringSchedule({ everyMinutes: 10 }, '/entry/schedule/onPoll::onPoll')
+ *
+ * // 5pm UTC daily
+ * defineRecurringSchedule({ dailyAtUtc: { hour: 17, minute: 0 } }, '/entry/schedule/onNightly::onNightly')
+ *
+ * // 2am UTC every Monday
+ * defineRecurringSchedule(
+ *   { weeklyAtUtc: { day: DayOfWeek.Monday, hour: 2, minute: 0 } },
+ *   '/entry/schedule/onDigest::onDigest',
+ * )
+ * ```
+ *
+ * An interval that cannot be scheduled evenly (`{ everyMinutes: 7 }`) throws
+ * an `InvalidScheduleRecurrenceError` here, while the config is being
+ * evaluated, so it fails at synth and at dev-server boot rather than at some
+ * unlucky hour in production.
+ */
+export declare const defineRecurringSchedule: (recurrence: ScheduleRecurrence, runtime: QpqFunctionRuntime, options?: QPQConfigAdvancedScheduleSettings) => ScheduleQPQConfigSetting;

package/lib/commonjs/config/settings/schedule/defineRecurringSchedule.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineRecurringSchedule = void 0;
+const QPQConfig_1 = require("../../QPQConfig");
+const crossModuleUtils_1 = require("../../utils/crossModuleUtils");
+const qpqFunctionRuntimeUtils_1 = require("../../utils/qpqFunctionRuntimeUtils");
+const ScheduleTypeEnum_1 = require("./types/ScheduleTypeEnum");
+const resolveScheduleFields_1 = require("./resolveScheduleFields");
+/**
+ * Run a story on a recurring timetable.
+ *
+ * The recurrence is declared as intent, not as a cron string. Deployed, it is
+ * rendered to an AWS EventBridge cron expression; locally, the dev server's
+ * ticker matches the same declaration against the clock. Neither behaviour is
+ * a special case of the other, which is the point.
+ *
+ * **Every time is UTC.** The deployed scheduler evaluates in UTC, so there is
+ * no local-timezone option: a schedule that reads `{ dailyAtUtc: { hour: 17 } }`
+ * is 3am in Brisbane, and saying so in the config is better than a comment
+ * that drifts out of date twice a year.
+ *
+ * ```ts
+ * // every ten minutes
+ * defineRecurringSchedule({ everyMinutes: 10 }, '/entry/schedule/onPoll::onPoll')
+ *
+ * // 5pm UTC daily
+ * defineRecurringSchedule({ dailyAtUtc: { hour: 17, minute: 0 } }, '/entry/schedule/onNightly::onNightly')
+ *
+ * // 2am UTC every Monday
+ * defineRecurringSchedule(
+ *   { weeklyAtUtc: { day: DayOfWeek.Monday, hour: 2, minute: 0 } },
+ *   '/entry/schedule/onDigest::onDigest',
+ * )
+ * ```
+ *
+ * An interval that cannot be scheduled evenly (`{ everyMinutes: 7 }`) throws
+ * an `InvalidScheduleRecurrenceError` here, while the config is being
+ * evaluated, so it fails at synth and at dev-server boot rather than at some
+ * unlucky hour in production.
+ */
+const defineRecurringSchedule = (recurrence, runtime, options) => {
+    // Resolved and discarded: this is here to validate. Both renderers resolve
+    // it again for themselves, so storing the fields would be a second copy of
+    // the truth that could drift from the declaration beside it.
+    (0, resolveScheduleFields_1.resolveScheduleFields)(recurrence);
+    return {
+        configSettingType: QPQConfig_1.QPQCoreConfigSettingType.schedule,
+        uniqueKey: (0, qpqFunctionRuntimeUtils_1.getStoryNameFromQpqFunctionRuntime)(runtime),
+        scheduleType: ScheduleTypeEnum_1.ScheduleTypeEnum.Recurring,
+        runtime,
+        recurrence,
+        metadata: (options === null || options === void 0 ? void 0 : options.metadata) || {},
+        maxConcurrentExecutions: options === null || options === void 0 ? void 0 : options.maxConcurrentExecutions,
+        owner: (0, crossModuleUtils_1.convertCrossModuleOwnerToGenericResourceNameOverride)(options === null || options === void 0 ? void 0 : options.owner),
+    };
+};
+exports.defineRecurringSchedule = defineRecurringSchedule;
+//# sourceMappingURL=defineRecurringSchedule.js.map

package/lib/commonjs/config/settings/schedule/defineRecurringSchedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineRecurringSchedule.js","sourceRoot":"","sources":["../../../../../src/config/settings/schedule/defineRecurringSchedule.ts"],"names":[],"mappings":";;;AACA,+CAA2D;AAC3D,mEAAoG;AACpG,iFAAyF;AAIzF,+DAA4D;AAC5D,mEAAgE;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACI,MAAM,uBAAuB,GAAG,CACrC,UAA8B,EAC9B,OAA2B,EAC3B,OAA2C,EACjB,EAAE;IAC5B,2EAA2E;IAC3E,2EAA2E;IAC3E,6DAA6D;IAC7D,IAAA,6CAAqB,EAAC,UAAU,CAAC,CAAC;IAElC,OAAO;QACL,iBAAiB,EAAE,oCAAwB,CAAC,QAAQ;QACpD,SAAS,EAAE,IAAA,4DAAkC,EAAC,OAAO,CAAC;QAEtD,YAAY,EAAE,mCAAgB,CAAC,SAAS;QAExC,OAAO;QAEP,UAAU;QAEV,QAAQ,EAAE,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ,KAAI,EAAE;QAEjC,uBAAuB,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,uBAAuB;QAEzD,KAAK,EAAE,IAAA,uEAAoD,EAAC,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,KAAK,CAAC;KAC5E,CAAC;AACJ,CAAC,CAAC;AA1BW,QAAA,uBAAuB,2BA0BlC","sourcesContent":["import { QpqFunctionRuntime } from '../../../types';\nimport { QPQCoreConfigSettingType } from '../../QPQConfig';\nimport { convertCrossModuleOwnerToGenericResourceNameOverride } from '../../utils/crossModuleUtils';\nimport { getStoryNameFromQpqFunctionRuntime } from '../../utils/qpqFunctionRuntimeUtils';\nimport { QPQConfigAdvancedScheduleSettings } from './types/QPQConfigAdvancedScheduleSettings';\nimport { ScheduleQPQConfigSetting } from './types/ScheduleQPQConfigSetting';\nimport { ScheduleRecurrence } from './types/ScheduleRecurrence';\nimport { ScheduleTypeEnum } from './types/ScheduleTypeEnum';\nimport { resolveScheduleFields } from './resolveScheduleFields';\n\n/**\n * Run a story on a recurring timetable.\n *\n * The recurrence is declared as intent, not as a cron string. Deployed, it is\n * rendered to an AWS EventBridge cron expression; locally, the dev server's\n * ticker matches the same declaration against the clock. Neither behaviour is\n * a special case of the other, which is the point.\n *\n * **Every time is UTC.** The deployed scheduler evaluates in UTC, so there is\n * no local-timezone option: a schedule that reads `{ dailyAtUtc: { hour: 17 } }`\n * is 3am in Brisbane, and saying so in the config is better than a comment\n * that drifts out of date twice a year.\n *\n * ```ts\n * // every ten minutes\n * defineRecurringSchedule({ everyMinutes: 10 }, '/entry/schedule/onPoll::onPoll')\n *\n * // 5pm UTC daily\n * defineRecurringSchedule({ dailyAtUtc: { hour: 17, minute: 0 } }, '/entry/schedule/onNightly::onNightly')\n *\n * // 2am UTC every Monday\n * defineRecurringSchedule(\n *   { weeklyAtUtc: { day: DayOfWeek.Monday, hour: 2, minute: 0 } },\n *   '/entry/schedule/onDigest::onDigest',\n * )\n * ```\n *\n * An interval that cannot be scheduled evenly (`{ everyMinutes: 7 }`) throws\n * an `InvalidScheduleRecurrenceError` here, while the config is being\n * evaluated, so it fails at synth and at dev-server boot rather than at some\n * unlucky hour in production.\n */\nexport const defineRecurringSchedule = (\n  recurrence: ScheduleRecurrence,\n  runtime: QpqFunctionRuntime,\n  options?: QPQConfigAdvancedScheduleSettings,\n): ScheduleQPQConfigSetting => {\n  // Resolved and discarded: this is here to validate. Both renderers resolve\n  // it again for themselves, so storing the fields would be a second copy of\n  // the truth that could drift from the declaration beside it.\n  resolveScheduleFields(recurrence);\n\n  return {\n    configSettingType: QPQCoreConfigSettingType.schedule,\n    uniqueKey: getStoryNameFromQpqFunctionRuntime(runtime),\n\n    scheduleType: ScheduleTypeEnum.Recurring,\n\n    runtime,\n\n    recurrence,\n\n    metadata: options?.metadata || {},\n\n    maxConcurrentExecutions: options?.maxConcurrentExecutions,\n\n    owner: convertCrossModuleOwnerToGenericResourceNameOverride(options?.owner),\n  };\n};\n"]}

package/lib/commonjs/config/settings/schedule/index.d.ts

@@ -0,0 +1,4 @@
+export * from './defineRecurringSchedule';
+export * from './InvalidScheduleRecurrenceError';
+export * from './resolveScheduleFields';
+export * from './types';

package/lib/commonjs/config/settings/schedule/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./defineRecurringSchedule"), exports);
+__exportStar(require("./InvalidScheduleRecurrenceError"), exports);
+__exportStar(require("./resolveScheduleFields"), exports);
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/lib/commonjs/config/settings/schedule/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/config/settings/schedule/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,mEAAiD;AACjD,0DAAwC;AACxC,0CAAwB","sourcesContent":["export * from './defineRecurringSchedule';\nexport * from './InvalidScheduleRecurrenceError';\nexport * from './resolveScheduleFields';\nexport * from './types';\n"]}

package/lib/commonjs/config/settings/schedule/resolveScheduleFields.d.ts

@@ -0,0 +1,12 @@
+import { ScheduleFields } from './types/ScheduleFields';
+import { ScheduleRecurrence } from './types/ScheduleRecurrence';
+/**
+ * Turn a declared recurrence into the concrete field values both renderers
+ * consume, validating it on the way through.
+ *
+ * The single interpreter of ScheduleRecurrence. quidproquo-deploy-awscdk and
+ * quidproquo-dev-server both start from what this returns, which is what makes
+ * "it fires locally exactly when it would fire deployed" a property of one
+ * function rather than of two implementations agreeing.
+ */
+export declare const resolveScheduleFields: (recurrence: ScheduleRecurrence) => ScheduleFields;

package/lib/commonjs/config/settings/schedule/resolveScheduleFields.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveScheduleFields = void 0;
+const DayOfWeek_1 = require("./types/DayOfWeek");
+const InvalidScheduleRecurrenceError_1 = require("./InvalidScheduleRecurrenceError");
+const assertInRange = (label, value, min, max) => {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new InvalidScheduleRecurrenceError_1.InvalidScheduleRecurrenceError(InvalidScheduleRecurrenceError_1.InvalidScheduleRecurrenceErrorCode.ValueOutOfRange, `Schedule ${label} must be a whole number between ${min} and ${max}, got ${value}.`);
+    }
+};
+/**
+ * Reject an interval that does not divide its unit evenly.
+ *
+ * Not pedantry. AWS renders these as `0/n`, which restarts at the top of every
+ * hour (or day), so `everyMinutes: 7` fires at :00 :07 ... :56 and then leaves
+ * a four minute gap. The dev server matching the same field list would agree
+ * with AWS, but neither would be what the author asked for, and the gap only
+ * shows up in production at an awkward hour. An interval that divides evenly
+ * means every consumer of these fields is saying the same thing.
+ */
+const assertDividesEvenly = (label, value, unit) => {
+    assertInRange(label, value, 1, unit);
+    if (unit % value !== 0) {
+        throw new InvalidScheduleRecurrenceError_1.InvalidScheduleRecurrenceError(InvalidScheduleRecurrenceError_1.InvalidScheduleRecurrenceErrorCode.IntervalDoesNotDivideEvenly, `Schedule ${label} must divide ${unit} evenly (got ${value}), or the interval would restart mid-cycle and leave an uneven gap. Valid values: ${everyDivisorOf(unit).join(', ')}.`);
+    }
+};
+const everyDivisorOf = (unit) => Array.from({ length: unit }, (_, i) => i + 1).filter((n) => unit % n === 0);
+// 0, n, 2n ... up to but not including the unit.
+const stepsOf = (interval, unit) => Array.from({ length: unit / interval }, (_, i) => i * interval);
+const EVERY_VALUE = {
+    minutes: [],
+    hours: null,
+    daysOfMonth: null,
+    months: null,
+    daysOfWeek: null,
+};
+/**
+ * Turn a declared recurrence into the concrete field values both renderers
+ * consume, validating it on the way through.
+ *
+ * The single interpreter of ScheduleRecurrence. quidproquo-deploy-awscdk and
+ * quidproquo-dev-server both start from what this returns, which is what makes
+ * "it fires locally exactly when it would fire deployed" a property of one
+ * function rather than of two implementations agreeing.
+ */
+const resolveScheduleFields = (recurrence) => {
+    var _a;
+    if ('everyMinutes' in recurrence) {
+        assertDividesEvenly('everyMinutes', recurrence.everyMinutes, 60);
+        return Object.assign(Object.assign({}, EVERY_VALUE), { minutes: stepsOf(recurrence.everyMinutes, 60) });
+    }
+    if ('everyHours' in recurrence) {
+        assertDividesEvenly('everyHours', recurrence.everyHours, 24);
+        const atMinute = (_a = recurrence.atMinute) !== null && _a !== void 0 ? _a : 0;
+        assertInRange('atMinute', atMinute, 0, 59);
+        return Object.assign(Object.assign({}, EVERY_VALUE), { minutes: [atMinute], hours: stepsOf(recurrence.everyHours, 24) });
+    }
+    if ('dailyAtUtc' in recurrence) {
+        const { hour, minute } = recurrence.dailyAtUtc;
+        assertInRange('hour', hour, 0, 23);
+        assertInRange('minute', minute, 0, 59);
+        return Object.assign(Object.assign({}, EVERY_VALUE), { minutes: [minute], hours: [hour] });
+    }
+    if ('weeklyAtUtc' in recurrence) {
+        const { day, hour, minute } = recurrence.weeklyAtUtc;
+        assertInRange('day', day, DayOfWeek_1.DayOfWeek.Sunday, DayOfWeek_1.DayOfWeek.Saturday);
+        assertInRange('hour', hour, 0, 23);
+        assertInRange('minute', minute, 0, 59);
+        return Object.assign(Object.assign({}, EVERY_VALUE), { minutes: [minute], hours: [hour], daysOfWeek: [day] });
+    }
+    if ('monthlyAtUtc' in recurrence) {
+        const { dayOfMonth, hour, minute } = recurrence.monthlyAtUtc;
+        // 29-31 are allowed and simply do not occur in every month, which is the
+        // same behaviour AWS has. Worth knowing rather than worth refusing.
+        assertInRange('dayOfMonth', dayOfMonth, 1, 31);
+        assertInRange('hour', hour, 0, 23);
+        assertInRange('minute', minute, 0, 59);
+        return Object.assign(Object.assign({}, EVERY_VALUE), { minutes: [minute], hours: [hour], daysOfMonth: [dayOfMonth] });
+    }
+    throw new InvalidScheduleRecurrenceError_1.InvalidScheduleRecurrenceError(InvalidScheduleRecurrenceError_1.InvalidScheduleRecurrenceErrorCode.UnknownRecurrence, `Unrecognised schedule recurrence: ${JSON.stringify(recurrence)}.`);
+};
+exports.resolveScheduleFields = resolveScheduleFields;
+//# sourceMappingURL=resolveScheduleFields.js.map

package/lib/commonjs/config/settings/schedule/resolveScheduleFields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveScheduleFields.js","sourceRoot":"","sources":["../../../../../src/config/settings/schedule/resolveScheduleFields.ts"],"names":[],"mappings":"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","sourcesContent":["import { DayOfWeek } from './types/DayOfWeek';\nimport { ScheduleFields } from './types/ScheduleFields';\nimport { ScheduleRecurrence } from './types/ScheduleRecurrence';\nimport { InvalidScheduleRecurrenceError, InvalidScheduleRecurrenceErrorCode } from './InvalidScheduleRecurrenceError';\n\nconst assertInRange = (label: string, value: number, min: number, max: number): void => {\n  if (!Number.isInteger(value) || value < min || value > max) {\n    throw new InvalidScheduleRecurrenceError(\n      InvalidScheduleRecurrenceErrorCode.ValueOutOfRange,\n      `Schedule ${label} must be a whole number between ${min} and ${max}, got ${value}.`,\n    );\n  }\n};\n\n/**\n * Reject an interval that does not divide its unit evenly.\n *\n * Not pedantry. AWS renders these as `0/n`, which restarts at the top of every\n * hour (or day), so `everyMinutes: 7` fires at :00 :07 ... :56 and then leaves\n * a four minute gap. The dev server matching the same field list would agree\n * with AWS, but neither would be what the author asked for, and the gap only\n * shows up in production at an awkward hour. An interval that divides evenly\n * means every consumer of these fields is saying the same thing.\n */\nconst assertDividesEvenly = (label: string, value: number, unit: number): void => {\n  assertInRange(label, value, 1, unit);\n\n  if (unit % value !== 0) {\n    throw new InvalidScheduleRecurrenceError(\n      InvalidScheduleRecurrenceErrorCode.IntervalDoesNotDivideEvenly,\n      `Schedule ${label} must divide ${unit} evenly (got ${value}), or the interval would restart mid-cycle and leave an uneven gap. Valid values: ${everyDivisorOf(unit).join(', ')}.`,\n    );\n  }\n};\n\nconst everyDivisorOf = (unit: number): number[] => Array.from({ length: unit }, (_, i) => i + 1).filter((n) => unit % n === 0);\n\n// 0, n, 2n ... up to but not including the unit.\nconst stepsOf = (interval: number, unit: number): number[] => Array.from({ length: unit / interval }, (_, i) => i * interval);\n\nconst EVERY_VALUE: ScheduleFields = {\n  minutes: [],\n  hours: null,\n  daysOfMonth: null,\n  months: null,\n  daysOfWeek: null,\n};\n\n/**\n * Turn a declared recurrence into the concrete field values both renderers\n * consume, validating it on the way through.\n *\n * The single interpreter of ScheduleRecurrence. quidproquo-deploy-awscdk and\n * quidproquo-dev-server both start from what this returns, which is what makes\n * \"it fires locally exactly when it would fire deployed\" a property of one\n * function rather than of two implementations agreeing.\n */\nexport const resolveScheduleFields = (recurrence: ScheduleRecurrence): ScheduleFields => {\n  if ('everyMinutes' in recurrence) {\n    assertDividesEvenly('everyMinutes', recurrence.everyMinutes, 60);\n\n    return { ...EVERY_VALUE, minutes: stepsOf(recurrence.everyMinutes, 60) };\n  }\n\n  if ('everyHours' in recurrence) {\n    assertDividesEvenly('everyHours', recurrence.everyHours, 24);\n\n    const atMinute = recurrence.atMinute ?? 0;\n    assertInRange('atMinute', atMinute, 0, 59);\n\n    return { ...EVERY_VALUE, minutes: [atMinute], hours: stepsOf(recurrence.everyHours, 24) };\n  }\n\n  if ('dailyAtUtc' in recurrence) {\n    const { hour, minute } = recurrence.dailyAtUtc;\n    assertInRange('hour', hour, 0, 23);\n    assertInRange('minute', minute, 0, 59);\n\n    return { ...EVERY_VALUE, minutes: [minute], hours: [hour] };\n  }\n\n  if ('weeklyAtUtc' in recurrence) {\n    const { day, hour, minute } = recurrence.weeklyAtUtc;\n    assertInRange('day', day, DayOfWeek.Sunday, DayOfWeek.Saturday);\n    assertInRange('hour', hour, 0, 23);\n    assertInRange('minute', minute, 0, 59);\n\n    return { ...EVERY_VALUE, minutes: [minute], hours: [hour], daysOfWeek: [day] };\n  }\n\n  if ('monthlyAtUtc' in recurrence) {\n    const { dayOfMonth, hour, minute } = recurrence.monthlyAtUtc;\n\n    // 29-31 are allowed and simply do not occur in every month, which is the\n    // same behaviour AWS has. Worth knowing rather than worth refusing.\n    assertInRange('dayOfMonth', dayOfMonth, 1, 31);\n    assertInRange('hour', hour, 0, 23);\n    assertInRange('minute', minute, 0, 59);\n\n    return { ...EVERY_VALUE, minutes: [minute], hours: [hour], daysOfMonth: [dayOfMonth] };\n  }\n\n  throw new InvalidScheduleRecurrenceError(\n    InvalidScheduleRecurrenceErrorCode.UnknownRecurrence,\n    `Unrecognised schedule recurrence: ${JSON.stringify(recurrence)}.`,\n  );\n};\n"]}

package/lib/commonjs/config/settings/schedule/types/DayOfWeek.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A day of the week, numbered the way JavaScript numbers them
+ * (`Date.getUTCDay()`), because the canonical schedule fields are matched
+ * against a real clock in the dev server.
+ *
+ * AWS numbers day-of-week 1-7 for SUN-SAT, so the cron renderer adds one. That
+ * offset lives in the renderer, which is the only place that should know
+ * anything about the AWS dialect.
+ */
+export declare enum DayOfWeek {
+    Sunday = 0,
+    Monday = 1,
+    Tuesday = 2,
+    Wednesday = 3,
+    Thursday = 4,
+    Friday = 5,
+    Saturday = 6
+}

package/lib/commonjs/config/settings/schedule/types/DayOfWeek.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DayOfWeek = void 0;
+/**
+ * A day of the week, numbered the way JavaScript numbers them
+ * (`Date.getUTCDay()`), because the canonical schedule fields are matched
+ * against a real clock in the dev server.
+ *
+ * AWS numbers day-of-week 1-7 for SUN-SAT, so the cron renderer adds one. That
+ * offset lives in the renderer, which is the only place that should know
+ * anything about the AWS dialect.
+ */
+var DayOfWeek;
+(function (DayOfWeek) {
+    DayOfWeek[DayOfWeek["Sunday"] = 0] = "Sunday";
+    DayOfWeek[DayOfWeek["Monday"] = 1] = "Monday";
+    DayOfWeek[DayOfWeek["Tuesday"] = 2] = "Tuesday";
+    DayOfWeek[DayOfWeek["Wednesday"] = 3] = "Wednesday";
+    DayOfWeek[DayOfWeek["Thursday"] = 4] = "Thursday";
+    DayOfWeek[DayOfWeek["Friday"] = 5] = "Friday";
+    DayOfWeek[DayOfWeek["Saturday"] = 6] = "Saturday";
+})(DayOfWeek || (exports.DayOfWeek = DayOfWeek = {}));
+//# sourceMappingURL=DayOfWeek.js.map

package/lib/commonjs/config/settings/schedule/types/DayOfWeek.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DayOfWeek.js","sourceRoot":"","sources":["../../../../../../src/config/settings/schedule/types/DayOfWeek.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,IAAY,SAQX;AARD,WAAY,SAAS;IACnB,6CAAU,CAAA;IACV,6CAAU,CAAA;IACV,+CAAW,CAAA;IACX,mDAAa,CAAA;IACb,iDAAY,CAAA;IACZ,6CAAU,CAAA;IACV,iDAAY,CAAA;AACd,CAAC,EARW,SAAS,yBAAT,SAAS,QAQpB","sourcesContent":["/**\n * A day of the week, numbered the way JavaScript numbers them\n * (`Date.getUTCDay()`), because the canonical schedule fields are matched\n * against a real clock in the dev server.\n *\n * AWS numbers day-of-week 1-7 for SUN-SAT, so the cron renderer adds one. That\n * offset lives in the renderer, which is the only place that should know\n * anything about the AWS dialect.\n */\nexport enum DayOfWeek {\n  Sunday = 0,\n  Monday = 1,\n  Tuesday = 2,\n  Wednesday = 3,\n  Thursday = 4,\n  Friday = 5,\n  Saturday = 6,\n}\n"]}

package/lib/commonjs/config/settings/schedule/types/QPQConfigAdvancedScheduleSettings.d.ts

@@ -0,0 +1,7 @@
+import { CrossModuleOwner } from '../../../../types';
+import { QPQConfigAdvancedSettings } from '../../../QPQConfig';
+export interface QPQConfigAdvancedScheduleSettings extends QPQConfigAdvancedSettings {
+    metadata?: Record<string, any>;
+    owner?: CrossModuleOwner<'recurringSchedule'>;
+    maxConcurrentExecutions?: number;
+}

package/lib/commonjs/config/settings/schedule/types/QPQConfigAdvancedScheduleSettings.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=QPQConfigAdvancedScheduleSettings.js.map

package/lib/commonjs/config/settings/schedule/types/QPQConfigAdvancedScheduleSettings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QPQConfigAdvancedScheduleSettings.js","sourceRoot":"","sources":["../../../../../../src/config/settings/schedule/types/QPQConfigAdvancedScheduleSettings.ts"],"names":[],"mappings":"","sourcesContent":["import { CrossModuleOwner } from '../../../../types';\nimport { QPQConfigAdvancedSettings } from '../../../QPQConfig';\n\nexport interface QPQConfigAdvancedScheduleSettings extends QPQConfigAdvancedSettings {\n  metadata?: Record<string, any>;\n  owner?: CrossModuleOwner<'recurringSchedule'>;\n\n  // Cap (and guarantee) on this schedule's concurrent executions: never\n  // throttled below it, never scales above it. Free, but carved out of the\n  // deploy account's shared concurrency pool.\n  maxConcurrentExecutions?: number;\n}\n"]}

package/lib/commonjs/config/settings/schedule/types/ScheduleFields.d.ts

@@ -0,0 +1,23 @@
+import { Nullable } from '../../../../types';
+/**
+ * A resolved recurrence, as concrete field values.
+ *
+ * The one shape both renderers consume: quidproquo-deploy-awscdk turns it into
+ * an EventBridge cron expression, the dev server asks whether it matches a
+ * given UTC minute. Adding a ScheduleRecurrence variant means teaching
+ * resolveScheduleFields about it and nothing else.
+ *
+ * `null` means "every", which is not the same as listing every value: it is
+ * what lets the cron renderer emit `*`, and what tells it which of
+ * day-of-month / day-of-week should become AWS's `?`.
+ *
+ * `minutes` is never null, because a schedule that fires every minute of every
+ * hour still fires ON a minute.
+ */
+export type ScheduleFields = {
+    minutes: number[];
+    hours: Nullable<number[]>;
+    daysOfMonth: Nullable<number[]>;
+    months: Nullable<number[]>;
+    daysOfWeek: Nullable<number[]>;
+};

package/lib/commonjs/config/settings/schedule/types/ScheduleFields.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ScheduleFields.js.map

package/lib/commonjs/config/settings/schedule/types/ScheduleFields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleFields.js","sourceRoot":"","sources":["../../../../../../src/config/settings/schedule/types/ScheduleFields.ts"],"names":[],"mappings":"","sourcesContent":["import { Nullable } from '../../../../types';\n\n/**\n * A resolved recurrence, as concrete field values.\n *\n * The one shape both renderers consume: quidproquo-deploy-awscdk turns it into\n * an EventBridge cron expression, the dev server asks whether it matches a\n * given UTC minute. Adding a ScheduleRecurrence variant means teaching\n * resolveScheduleFields about it and nothing else.\n *\n * `null` means \"every\", which is not the same as listing every value: it is\n * what lets the cron renderer emit `*`, and what tells it which of\n * day-of-month / day-of-week should become AWS's `?`.\n *\n * `minutes` is never null, because a schedule that fires every minute of every\n * hour still fires ON a minute.\n */\nexport type ScheduleFields = {\n  // 0-59\n  minutes: number[];\n\n  // 0-23\n  hours: Nullable<number[]>;\n\n  // 1-31\n  daysOfMonth: Nullable<number[]>;\n\n  // 1-12\n  months: Nullable<number[]>;\n\n  // 0-6, Sunday first (see DayOfWeek)\n  daysOfWeek: Nullable<number[]>;\n};\n"]}

package/lib/commonjs/config/settings/schedule/types/ScheduleQPQConfigSetting.d.ts

@@ -0,0 +1,12 @@
+import { CrossModuleOwner, QpqFunctionRuntime } from '../../../../types';
+import { QPQConfigSetting } from '../../../QPQConfig';
+import { ScheduleRecurrence } from './ScheduleRecurrence';
+import { ScheduleTypeEnum } from './ScheduleTypeEnum';
+export interface ScheduleQPQConfigSetting extends QPQConfigSetting {
+    scheduleType: ScheduleTypeEnum;
+    runtime: QpqFunctionRuntime;
+    recurrence: ScheduleRecurrence;
+    metadata: Record<string, any>;
+    maxConcurrentExecutions?: number;
+    owner?: CrossModuleOwner;
+}

package/lib/commonjs/config/settings/schedule/types/ScheduleQPQConfigSetting.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ScheduleQPQConfigSetting.js.map

package/lib/commonjs/config/settings/schedule/types/ScheduleQPQConfigSetting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleQPQConfigSetting.js","sourceRoot":"","sources":["../../../../../../src/config/settings/schedule/types/ScheduleQPQConfigSetting.ts"],"names":[],"mappings":"","sourcesContent":["import { CrossModuleOwner, QpqFunctionRuntime } from '../../../../types';\nimport { QPQConfigSetting } from '../../../QPQConfig';\nimport { ScheduleRecurrence } from './ScheduleRecurrence';\nimport { ScheduleTypeEnum } from './ScheduleTypeEnum';\n\nexport interface ScheduleQPQConfigSetting extends QPQConfigSetting {\n  scheduleType: ScheduleTypeEnum;\n\n  runtime: QpqFunctionRuntime;\n\n  // Platform-neutral. The AWS cron string is rendered from this at deploy\n  // time; it is deliberately not stored.\n  recurrence: ScheduleRecurrence;\n\n  metadata: Record<string, any>;\n\n  maxConcurrentExecutions?: number;\n\n  owner?: CrossModuleOwner;\n}\n"]}

package/lib/commonjs/config/settings/schedule/types/ScheduleRecurrence.d.ts

@@ -0,0 +1,54 @@
+import { DayOfWeek } from './DayOfWeek';
+/**
+ * How often a recurring schedule runs, declared as intent rather than as a
+ * cron string.
+ *
+ * Deliberately platform-neutral: an AWS EventBridge cron expression is one
+ * RENDERING of this, produced in quidproquo-deploy-awscdk, and the dev server
+ * matches the same declaration against the clock. Nothing here knows what a
+ * `?` is.
+ *
+ * Every time is UTC. There is no local-timezone variant on purpose: the
+ * deployed scheduler evaluates in UTC, so offering one would be a promise the
+ * platform cannot keep.
+ *
+ * Deliberately absent, so the next reader does not take either for an
+ * oversight:
+ *
+ * - **A year.** A recurrence pinned to a year is not recurring, it is a
+ *   schedule with an expiry, and it fails by going quiet rather than by
+ *   erroring. A one-shot at a date wants its own ScheduleTypeEnum member and
+ *   its own define, not a field every existing caller has to leave as "any".
+ * - **A month.** ScheduleFields carries `months` and both renderers honour it,
+ *   but nothing here sets it yet - `yearlyAtUtc` is the obvious next variant
+ *   and lands as a resolveScheduleFields change alone. Left out until
+ *   something asks for it.
+ *
+ * This union is a closed set, which is the cost of dropping the raw cron
+ * string: a consumer who needs something it cannot say has no local workaround
+ * and has to wait for a release. Adding a variant is additive and cheap, so
+ * add one rather than making anybody wait long.
+ */
+export type ScheduleRecurrence = {
+    everyMinutes: number;
+} | {
+    everyHours: number;
+    atMinute?: number;
+} | {
+    dailyAtUtc: {
+        hour: number;
+        minute: number;
+    };
+} | {
+    weeklyAtUtc: {
+        day: DayOfWeek;
+        hour: number;
+        minute: number;
+    };
+} | {
+    monthlyAtUtc: {
+        dayOfMonth: number;
+        hour: number;
+        minute: number;
+    };
+};

package/lib/commonjs/config/settings/schedule/types/ScheduleRecurrence.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ScheduleRecurrence.js.map

package/lib/commonjs/config/settings/schedule/types/ScheduleRecurrence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleRecurrence.js","sourceRoot":"","sources":["../../../../../../src/config/settings/schedule/types/ScheduleRecurrence.ts"],"names":[],"mappings":"","sourcesContent":["import { DayOfWeek } from './DayOfWeek';\n\n/**\n * How often a recurring schedule runs, declared as intent rather than as a\n * cron string.\n *\n * Deliberately platform-neutral: an AWS EventBridge cron expression is one\n * RENDERING of this, produced in quidproquo-deploy-awscdk, and the dev server\n * matches the same declaration against the clock. Nothing here knows what a\n * `?` is.\n *\n * Every time is UTC. There is no local-timezone variant on purpose: the\n * deployed scheduler evaluates in UTC, so offering one would be a promise the\n * platform cannot keep.\n *\n * Deliberately absent, so the next reader does not take either for an\n * oversight:\n *\n * - **A year.** A recurrence pinned to a year is not recurring, it is a\n *   schedule with an expiry, and it fails by going quiet rather than by\n *   erroring. A one-shot at a date wants its own ScheduleTypeEnum member and\n *   its own define, not a field every existing caller has to leave as \"any\".\n * - **A month.** ScheduleFields carries `months` and both renderers honour it,\n *   but nothing here sets it yet - `yearlyAtUtc` is the obvious next variant\n *   and lands as a resolveScheduleFields change alone. Left out until\n *   something asks for it.\n *\n * This union is a closed set, which is the cost of dropping the raw cron\n * string: a consumer who needs something it cannot say has no local workaround\n * and has to wait for a release. Adding a variant is additive and cheap, so\n * add one rather than making anybody wait long.\n */\nexport type ScheduleRecurrence =\n  // Must divide 60 - see resolveScheduleFields for why an awkward interval is\n  // rejected rather than approximated.\n  | { everyMinutes: number }\n\n  // Must divide 24. `atMinute` defaults to 0.\n  | { everyHours: number; atMinute?: number }\n  | { dailyAtUtc: { hour: number; minute: number } }\n  | { weeklyAtUtc: { day: DayOfWeek; hour: number; minute: number } }\n  | { monthlyAtUtc: { dayOfMonth: number; hour: number; minute: number } };\n"]}

package/lib/commonjs/config/settings/schedule/types/ScheduleTypeEnum.d.ts

@@ -0,0 +1,3 @@
+export declare enum ScheduleTypeEnum {
+    Recurring = "Recurring"
+}