@c9up/ream 0.2.8 → 0.2.10

package/dist/scheduler/ScheduleProvider.js

@@ -28,11 +28,13 @@ import { Scheduler } from './Scheduler.js';
 let activeProvider;
 export class ScheduleProvider extends Provider {
     scheduler;
-    #booted = false;
+    /** Task names already registered, so a second pass adds only what is new. */
+    #known = new Set();
     #registered = false;
     constructor(app, options = {}) {
         super(app);
-        this.scheduler = options.scheduler ?? new Scheduler();
+        this.scheduler =
+            options.scheduler ?? new Scheduler(schedulerOptionsFrom(app.config.get('scheduler')));
     }
     /**
      * Phase 1 — bind the scheduler into the IoC container under the
@@ -64,9 +66,42 @@ export class ScheduleProvider extends Provider {
         container.singleton('scheduler', () => scheduler);
         this.#registered = true;
     }
+    /**
+     * Discovery runs at START, not at boot, and that is the whole point.
+     *
+     * `app/modules/**` is auto-loaded during the start phase — after every
+     * provider has booted. A `@Service()` carrying `@Schedule` there, which is
+     * where one naturally lives, was therefore registered into the service
+     * registry AFTER this had already read it. The task was never registered,
+     * and nothing said so: no error, no warning, the application started
+     * normally and the task simply never fired.
+     *
+     * Reading the registry once the modules are in place is what fixes it. A
+     * service declared anywhere earlier — a provider, a preload — is in the
+     * registry by then too, so nothing is lost by waiting.
+     */
     async boot() {
-        if (this.#booted)
-            return;
+        // Anything already in the registry — declared by a provider, or imported
+        // by one. The rest is caught at start().
+        this.#discover();
+    }
+    async start() {
+        this.#discover();
+        if (activeProvider !== undefined && activeProvider !== this) {
+            // A previous app's scheduler is still running — stop it before this one
+            // starts, otherwise every @Schedule task fires twice per tick.
+            activeProvider.scheduler.stop();
+        }
+        activeProvider = this;
+        this.scheduler.start();
+    }
+    /**
+     * Walk the service registry and register every `@Schedule` it declares.
+     *
+     * Idempotent: a second call registers nothing twice, so an application that
+     * restarts its Ignitor does not end up firing everything in duplicate.
+     */
+    #discover() {
         const registry = getServiceRegistry();
         const registered = [];
         try {
@@ -90,6 +125,9 @@ export class ScheduleProvider extends Provider {
                         });
                     }
                     const taskName = `${target.name}.${methodName}`;
+                    // Registered on an earlier pass: skip rather than fire it twice.
+                    if (this.#known.has(taskName))
+                        continue;
                     try {
                         this.scheduler.register(taskName, cronExpr, async () => {
                             // Resolve from the container on every fire so transient
@@ -102,6 +140,7 @@ export class ScheduleProvider extends Provider {
                             await method.call(instance);
                         });
                         registered.push(taskName);
+                        this.#known.add(taskName);
                     }
                     catch (cause) {
                         const inner = cause;
@@ -112,7 +151,6 @@ export class ScheduleProvider extends Provider {
                     }
                 }
             }
-            this.#booted = true;
         }
         catch (err) {
             // Roll back any partial registrations so a retry does not hit
@@ -129,15 +167,6 @@ export class ScheduleProvider extends Provider {
             throw err;
         }
     }
-    async start() {
-        if (activeProvider !== undefined && activeProvider !== this) {
-            // A previous app's scheduler is still running — stop it before this one starts,
-            // otherwise every @Schedule task fires twice per tick.
-            activeProvider.scheduler.stop();
-        }
-        activeProvider = this;
-        this.scheduler.start();
-    }
     async shutdown() {
         if (activeProvider === this)
             activeProvider = undefined;
@@ -146,4 +175,23 @@ export class ScheduleProvider extends Provider {
 }
 // Default export so reamrc's provider loader can `() => import('@c9up/ream/<feature>/provider')` (resolves to { default }), matching events/rpc. Named export above stays.
 export default ScheduleProvider;
+/**
+ * Turn `config/scheduler.ts` into the options the `Scheduler` takes.
+ *
+ * The lock is built here rather than in the config file because that file is
+ * read before the application boots — a Redis connection named in it does not
+ * exist yet, so the helpers hand back a factory and this calls it.
+ */
+function schedulerOptionsFrom(config) {
+    if (config === undefined)
+        return {};
+    const options = {};
+    if (config.lock !== undefined) {
+        options.lockBackend = typeof config.lock === 'function' ? config.lock() : config.lock;
+    }
+    if (config.defaultLockTtlMs !== undefined) {
+        options.defaultLockTtlMs = config.defaultLockTtlMs;
+    }
+    return options;
+}
 //# sourceMappingURL=ScheduleProvider.js.map

package/dist/scheduler/ScheduleProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"ScheduleProvider.js","sourceRoot":"","sources":["../../src/scheduler/ScheduleProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ScheduleProvider.js","sourceRoot":"","sources":["../../src/scheduler/ScheduleProvider.ts"],"names":[],"mappings":"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"}

package/dist/scheduler/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Author-time config for `config/scheduler.ts`.
+ *
+ *   import { defineConfig, locks } from '@c9up/ream/scheduler/config'
+ *
+ *   export default defineConfig({
+ *     lock: locks.redis({ connection: 'main' }),
+ *   })
+ */
+import type { LockBackend } from './locks/LockBackend.js';
+import type { LockBackendFactory } from './locks/locks.js';
+export interface SchedulerConfig {
+    /**
+     * The lock consulted before a task fires, so that only one instance runs
+     * it. Takes a backend, or a factory answering one — which is what the
+     * `locks.*` helpers return, so a config file can name a Redis lock before
+     * the connection exists.
+     *
+     * Left out, the scheduler locks nothing: every instance runs every task.
+     * Correct on one instance, and a duplicate run per replica past that.
+     */
+    lock?: LockBackend | LockBackendFactory;
+    /** How long a lease is held before it expires on its own. Default 60 000. */
+    defaultLockTtlMs?: number;
+}
+export declare function defineConfig(config: SchedulerConfig): SchedulerConfig;
+export type { LockBackend } from './locks/LockBackend.js';
+export { type LockBackendFactory, locks } from './locks/locks.js';
+//# sourceMappingURL=config.d.ts.map

package/dist/scheduler/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/scheduler/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE1D,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,kBAAkB,CAAA;IACvC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAErE;AAED,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/scheduler/config.js

@@ -0,0 +1,14 @@
+/**
+ * Author-time config for `config/scheduler.ts`.
+ *
+ *   import { defineConfig, locks } from '@c9up/ream/scheduler/config'
+ *
+ *   export default defineConfig({
+ *     lock: locks.redis({ connection: 'main' }),
+ *   })
+ */
+export function defineConfig(config) {
+    return config;
+}
+export { locks } from './locks/locks.js';
+//# sourceMappingURL=config.js.map

package/dist/scheduler/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/scheduler/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,MAAM,UAAU,YAAY,CAAC,MAAuB;IAClD,OAAO,MAAM,CAAA;AACf,CAAC;AAGD,OAAO,EAA2B,KAAK,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/scheduler/index.d.ts

@@ -1,5 +1,9 @@
+export type { SchedulerConfig } from './config.js';
+export { defineConfig as defineSchedulerConfig } from './config.js';
 export type { LockBackend } from './locks/LockBackend.js';
+export { type LockBackendFactory, locks } from './locks/locks.js';
 export { MemoryLockBackend } from './locks/MemoryLockBackend.js';
+export { type LockRedisClient, type LockRedisResolver, RedisLockBackend, } from './locks/RedisLockBackend.js';
 export type { ErrorReporter } from './observability/ErrorReporter.js';
 export type { ScheduleEvent, ScheduleTaskCompletedEvent, ScheduleTaskFailedEvent, ScheduleTaskSkippedEvent, ScheduleTaskStartedEvent, } from './observability/ScheduleEvent.js';
 export type { ScheduleEventSink } from './observability/ScheduleEventSink.js';

package/dist/scheduler/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAChE,YAAY,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AACrE,YAAY,EACV,aAAa,EACb,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,kCAAkC,CAAA;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAA;AAC7E,YAAY,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAA;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACpF,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,GACT,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,YAAY,IAAI,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACnE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,gBAAgB,GACjB,MAAM,6BAA6B,CAAA;AACpC,YAAY,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AACrE,YAAY,EACV,aAAa,EACb,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,kCAAkC,CAAA;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAA;AAC7E,YAAY,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAA;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACpF,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,GACT,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/scheduler/index.js

@@ -1,4 +1,7 @@
+export { defineConfig as defineSchedulerConfig } from './config.js';
+export { locks } from './locks/locks.js';
 export { MemoryLockBackend } from './locks/MemoryLockBackend.js';
+export { RedisLockBackend, } from './locks/RedisLockBackend.js';
 export { StatsTracker } from './observability/StatsTracker.js';
 export { getScheduleMetadata, SCHEDULE_METADATA_KEY, Schedule } from './Schedule.js';
 export { ScheduleProvider } from './ScheduleProvider.js';

package/dist/scheduler/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAWhE,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AAE9D,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAEpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAOxD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,IAAI,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEnE,OAAO,EAA2B,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,EAGL,gBAAgB,GACjB,MAAM,6BAA6B,CAAA;AAWpC,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AAE9D,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAEpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAOxD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/scheduler/locks/LockBackend.d.ts

@@ -3,9 +3,12 @@
  *
  * The scheduler consults a `LockBackend` immediately before firing a
  * registered task so that in multi-instance deployments only one
- * instance runs a given task on each tick. Redis, database
- * advisory-lock, and other backends live in user-land — this module
- * ships only the interface and a single-process `MemoryLockBackend`.
+ * instance runs a given task on each tick.
+ *
+ * Two backends ship with it: `MemoryLockBackend`, correct while the
+ * application runs in one process, and `RedisLockBackend`, which is
+ * what a second replica needs — see `locks` for the factories a
+ * config file names.
  *
  * @implements Story 28.3
  */
@@ -34,4 +37,11 @@ export interface LockBackend {
      */
     release(name: string): Promise<void>;
 }
+/**
+ * Reject a TTL that cannot bound anything. A zero or negative lease
+ * expires the instant it is taken, so every instance would acquire the
+ * same lock and run the same task — the exact outcome locking exists to
+ * prevent, arriving silently.
+ */
+export declare function assertValidTtl(ttlMs: number): void;
 //# sourceMappingURL=LockBackend.d.ts.map

package/dist/scheduler/locks/LockBackend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LockBackend.d.ts","sourceRoot":"","sources":["../../../src/scheduler/locks/LockBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEtD;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrC"}
+{"version":3,"file":"LockBackend.d.ts","sourceRoot":"","sources":["../../../src/scheduler/locks/LockBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEtD;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAUlD"}

package/dist/scheduler/locks/LockBackend.js

@@ -3,11 +3,27 @@
  *
  * The scheduler consults a `LockBackend` immediately before firing a
  * registered task so that in multi-instance deployments only one
- * instance runs a given task on each tick. Redis, database
- * advisory-lock, and other backends live in user-land — this module
- * ships only the interface and a single-process `MemoryLockBackend`.
+ * instance runs a given task on each tick.
+ *
+ * Two backends ship with it: `MemoryLockBackend`, correct while the
+ * application runs in one process, and `RedisLockBackend`, which is
+ * what a second replica needs — see `locks` for the factories a
+ * config file names.
  *
  * @implements Story 28.3
  */
-export {};
+import { ReamError } from '../../errors/ReamError.js';
+/**
+ * Reject a TTL that cannot bound anything. A zero or negative lease
+ * expires the instant it is taken, so every instance would acquire the
+ * same lock and run the same task — the exact outcome locking exists to
+ * prevent, arriving silently.
+ */
+export function assertValidTtl(ttlMs) {
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        throw new ReamError('SCHEDULE_INVALID_LOCK_TTL', `Lock TTL must be a finite positive number, got ${ttlMs}`, {
+            hint: 'Use a millisecond value greater than zero (typical range 1_000 - 600_000).',
+        });
+    }
+}
 //# sourceMappingURL=LockBackend.js.map

package/dist/scheduler/locks/LockBackend.js.map

@@ -1 +1 @@
-{"version":3,"file":"LockBackend.js","sourceRoot":"","sources":["../../../src/scheduler/locks/LockBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}
+{"version":3,"file":"LockBackend.js","sourceRoot":"","sources":["../../../src/scheduler/locks/LockBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AA6BrD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,SAAS,CACjB,2BAA2B,EAC3B,kDAAkD,KAAK,EAAE,EACzD;YACE,IAAI,EAAE,4EAA4E;SACnF,CACF,CAAA;IACH,CAAC;AACH,CAAC"}

package/dist/scheduler/locks/MemoryLockBackend.d.ts

@@ -1,11 +1,10 @@
 /**
  * Default single-process lock backend backed by a `Map`.
  *
- * Correct for apps that run in a single Node.js process. For
- * horizontally-scaled deployments, implement `LockBackend` against a
- * shared store (Redis `SET NX PX`, Postgres advisory locks, etc.) —
- * those drivers live in user-land per the project's "agnostic per
- * package" rule.
+ * Correct for apps that run in a single Node.js process, and only
+ * those: two processes each keep their own map, so both acquire the
+ * same name and both run the task. Reach for `RedisLockBackend` the
+ * moment a second replica exists.
  *
  * Expiry is evaluated **lazily** at `acquire` time — no background
  * timer, no `setInterval`. This preserves Story 28.1's
@@ -19,7 +18,7 @@
  *
  * @implements Story 28.3
  */
-import type { LockBackend } from './LockBackend.js';
+import { type LockBackend } from './LockBackend.js';
 export declare class MemoryLockBackend implements LockBackend {
     #private;
     acquire(name: string, ttlMs: number): Promise<boolean>;

package/dist/scheduler/locks/MemoryLockBackend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemoryLockBackend.d.ts","sourceRoot":"","sources":["../../../src/scheduler/locks/MemoryLockBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAgBnD,qBAAa,iBAAkB,YAAW,WAAW;;IAG7C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqBtD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C;;;;;;OAMG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI3D,gEAAgE;IAChE,gBAAgB,IAAI,MAAM;CAG3B"}
+{"version":3,"file":"MemoryLockBackend.d.ts","sourceRoot":"","sources":["../../../src/scheduler/locks/MemoryLockBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAInE,qBAAa,iBAAkB,YAAW,WAAW;;IAG7C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqBtD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C;;;;;;OAMG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI3D,gEAAgE;IAChE,gBAAgB,IAAI,MAAM;CAG3B"}

package/dist/scheduler/locks/MemoryLockBackend.js

@@ -1,11 +1,10 @@
 /**
  * Default single-process lock backend backed by a `Map`.
  *
- * Correct for apps that run in a single Node.js process. For
- * horizontally-scaled deployments, implement `LockBackend` against a
- * shared store (Redis `SET NX PX`, Postgres advisory locks, etc.) —
- * those drivers live in user-land per the project's "agnostic per
- * package" rule.
+ * Correct for apps that run in a single Node.js process, and only
+ * those: two processes each keep their own map, so both acquire the
+ * same name and both run the task. Reach for `RedisLockBackend` the
+ * moment a second replica exists.
  *
  * Expiry is evaluated **lazily** at `acquire` time — no background
  * timer, no `setInterval`. This preserves Story 28.1's
@@ -19,15 +18,8 @@
  *
  * @implements Story 28.3
  */
-import { ReamError } from '../../errors/ReamError.js';
+import { assertValidTtl } from './LockBackend.js';
 const SWEEP_THRESHOLD = 256;
-function assertValidTtl(ttlMs) {
-    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
-        throw new ReamError('SCHEDULE_INVALID_LOCK_TTL', `Lock TTL must be a finite positive number, got ${ttlMs}`, {
-            hint: 'Use a millisecond value greater than zero (typical range 1_000 – 600_000).',
-        });
-    }
-}
 export class MemoryLockBackend {
     #locks = new Map();
     async acquire(name, ttlMs) {

package/dist/scheduler/locks/MemoryLockBackend.js.map

@@ -1 +1 @@
-{"version":3,"file":"MemoryLockBackend.js","sourceRoot":"","sources":["../../../src/scheduler/locks/MemoryLockBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAGrD,MAAM,eAAe,GAAG,GAAG,CAAA;AAE3B,SAAS,cAAc,CAAC,KAAa;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,SAAS,CACjB,2BAA2B,EAC3B,kDAAkD,KAAK,EAAE,EACzD;YACE,IAAI,EAAE,4EAA4E;SACnF,CACF,CAAA;IACH,CAAC;AACH,CAAC;AAED,MAAM,OAAO,iBAAiB;IAC5B,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IAElC,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,KAAa;QACvC,cAAc,CAAC,KAAK,CAAC,CAAA;QACrB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAEtB,8DAA8D;QAC9D,iEAAiE;QACjE,qDAAqD;QACrD,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,eAAe,EAAE,CAAC;YACxC,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBACxC,IAAI,MAAM,IAAI,GAAG;oBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC5C,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACtC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,GAAG,GAAG,EAAE,CAAC;YAC7C,OAAO,KAAK,CAAA;QACd,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,CAAA;QAClC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC1B,CAAC;IAED;;;;;;OAMG;IACH,qBAAqB,CAAC,IAAY,EAAE,QAAgB;QAClD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;IACjC,CAAC;IAED,gEAAgE;IAChE,gBAAgB;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAA;IACzB,CAAC;CACF"}
+{"version":3,"file":"MemoryLockBackend.js","sourceRoot":"","sources":["../../../src/scheduler/locks/MemoryLockBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAoB,MAAM,kBAAkB,CAAA;AAEnE,MAAM,eAAe,GAAG,GAAG,CAAA;AAE3B,MAAM,OAAO,iBAAiB;IAC5B,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IAElC,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,KAAa;QACvC,cAAc,CAAC,KAAK,CAAC,CAAA;QACrB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAEtB,8DAA8D;QAC9D,iEAAiE;QACjE,qDAAqD;QACrD,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,eAAe,EAAE,CAAC;YACxC,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBACxC,IAAI,MAAM,IAAI,GAAG;oBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC5C,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACtC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,GAAG,GAAG,EAAE,CAAC;YAC7C,OAAO,KAAK,CAAA;QACd,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,CAAA;QAClC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC1B,CAAC;IAED;;;;;;OAMG;IACH,qBAAqB,CAAC,IAAY,EAAE,QAAgB;QAClD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;IACjC,CAAC;IAED,gEAAgE;IAChE,gBAAgB;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAA;IACzB,CAAC;CACF"}

package/dist/scheduler/locks/RedisLockBackend.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Redis lock backend — the one a second replica needs.
+ *
+ * Without a shared lock, every instance of an application runs every
+ * scheduled task on every tick: a nightly invoice run goes out N times,
+ * a reminder email arrives N times, and nothing in the logs says so.
+ * `MemoryLockBackend` does not close that gap — each process keeps its
+ * own map — and the scheduler locks nothing at all by default.
+ *
+ * No import of a Redis package. The client is taken structurally — `set`
+ * and `eval` — so this works against a `@c9up/quasar` connection without
+ * ream depending on quasar, which is an optional peer.
+ */
+import { type LockBackend } from './LockBackend.js';
+/** The commands this issues. Any client answering them will do. */
+export interface LockRedisClient {
+    /** `SET key value PX <ttl> NX` — answers null when the key already exists. */
+    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+    /** `EVAL script numKeys ...` — used for the compare-and-delete release. */
+    eval(script: string, numKeys: number, ...args: unknown[]): Promise<unknown>;
+}
+/**
+ * How the backend gets its client: the client itself, or something that
+ * answers with one.
+ *
+ * The resolver form is what a config file needs. `config/scheduler.ts` is
+ * read before the application boots, so the connection does not exist yet
+ * and cannot be awaited there — a function defers the lookup to the first
+ * task that fires.
+ */
+export type LockRedisResolver = LockRedisClient | (() => LockRedisClient | Promise<LockRedisClient>);
+export interface RedisLockBackendOptions {
+    /** Key prefix. Default `"ream:schedule:lock:"`. */
+    prefix?: string;
+}
+export declare class RedisLockBackend implements LockBackend {
+    #private;
+    constructor(client: LockRedisResolver, options?: RedisLockBackendOptions);
+    /**
+     * `SET key token PX ttl NX` — one round trip, atomic on the server, which
+     * is what makes the decision the same for every instance asking at once.
+     *
+     * The TTL is what recovers the lock after a crash: an instance that dies
+     * holding it never releases, and the lease simply expires.
+     */
+    acquire(name: string, ttlMs: number): Promise<boolean>;
+    /**
+     * Idempotent, as the contract requires: releasing a name this instance
+     * never acquired — or one whose lease has since expired — does nothing.
+     */
+    release(name: string): Promise<void>;
+}
+//# sourceMappingURL=RedisLockBackend.d.ts.map

package/dist/scheduler/locks/RedisLockBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisLockBackend.d.ts","sourceRoot":"","sources":["../../../src/scheduler/locks/RedisLockBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnE,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrE,2EAA2E;IAC3E,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC5E;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAA;AAEpG,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAkBD,qBAAa,gBAAiB,YAAW,WAAW;;gBAOtC,MAAM,EAAE,iBAAiB,EAAE,OAAO,GAAE,uBAA4B;IAmB5E;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAY5D;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO3C"}

package/dist/scheduler/locks/RedisLockBackend.js

@@ -0,0 +1,83 @@
+/**
+ * Redis lock backend — the one a second replica needs.
+ *
+ * Without a shared lock, every instance of an application runs every
+ * scheduled task on every tick: a nightly invoice run goes out N times,
+ * a reminder email arrives N times, and nothing in the logs says so.
+ * `MemoryLockBackend` does not close that gap — each process keeps its
+ * own map — and the scheduler locks nothing at all by default.
+ *
+ * No import of a Redis package. The client is taken structurally — `set`
+ * and `eval` — so this works against a `@c9up/quasar` connection without
+ * ream depending on quasar, which is an optional peer.
+ */
+import { randomUUID } from 'node:crypto';
+import { assertValidTtl } from './LockBackend.js';
+/**
+ * Release only a lease we still hold.
+ *
+ * A plain `DEL` is the classic way to break this: a task that outlives its
+ * TTL loses the lock, another instance acquires it and starts running, and
+ * the first one then deletes THAT instance's lease on its way out — leaving
+ * the name free while a task is still running under it. Comparing the token
+ * before deleting makes the release a no-op once the lease is no longer ours.
+ */
+const RELEASE = `
+if redis.call('get', KEYS[1]) == ARGV[1] then
+  return redis.call('del', KEYS[1])
+end
+return 0
+`;
+export class RedisLockBackend {
+    #source;
+    #prefix;
+    #resolved;
+    /** Our token per held name, so a release can prove the lease is ours. */
+    #tokens = new Map();
+    constructor(client, options = {}) {
+        this.#source = client;
+        this.#prefix = options.prefix ?? 'ream:schedule:lock:';
+    }
+    /** The client, resolved once and kept. */
+    #client() {
+        if (!this.#resolved) {
+            this.#resolved = Promise.resolve(typeof this.#source === 'function' ? this.#source() : this.#source);
+        }
+        return this.#resolved;
+    }
+    #key(name) {
+        return `${this.#prefix}${name}`;
+    }
+    /**
+     * `SET key token PX ttl NX` — one round trip, atomic on the server, which
+     * is what makes the decision the same for every instance asking at once.
+     *
+     * The TTL is what recovers the lock after a crash: an instance that dies
+     * holding it never releases, and the lease simply expires.
+     */
+    async acquire(name, ttlMs) {
+        assertValidTtl(ttlMs);
+        const client = await this.#client();
+        const token = randomUUID();
+        // Redis takes an integer number of milliseconds; a fractional TTL is a
+        // protocol error, not a rounding detail.
+        const result = await client.set(this.#key(name), token, 'PX', Math.ceil(ttlMs), 'NX');
+        if (result === null || result === undefined)
+            return false;
+        this.#tokens.set(name, token);
+        return true;
+    }
+    /**
+     * Idempotent, as the contract requires: releasing a name this instance
+     * never acquired — or one whose lease has since expired — does nothing.
+     */
+    async release(name) {
+        const token = this.#tokens.get(name);
+        if (token === undefined)
+            return;
+        this.#tokens.delete(name);
+        const client = await this.#client();
+        await client.eval(RELEASE, 1, this.#key(name), token);
+    }
+}
+//# sourceMappingURL=RedisLockBackend.js.map

package/dist/scheduler/locks/RedisLockBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisLockBackend.js","sourceRoot":"","sources":["../../../src/scheduler/locks/RedisLockBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,cAAc,EAAoB,MAAM,kBAAkB,CAAA;AA0BnE;;;;;;;;GAQG;AACH,MAAM,OAAO,GAAG;;;;;CAKf,CAAA;AAED,MAAM,OAAO,gBAAgB;IAClB,OAAO,CAAmB;IAC1B,OAAO,CAAQ;IACxB,SAAS,CAAsC;IAC/C,yEAAyE;IAChE,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA;IAE5C,YAAY,MAAyB,EAAE,UAAmC,EAAE;QAC1E,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,qBAAqB,CAAA;IACxD,CAAC;IAED,0CAA0C;IAC1C,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,OAAO,CAC9B,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CACnE,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,IAAI,CAAC,IAAY;QACf,OAAO,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAA;IACjC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,KAAa;QACvC,cAAc,CAAC,KAAK,CAAC,CAAA;QACrB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAA;QACnC,MAAM,KAAK,GAAG,UAAU,EAAE,CAAA;QAC1B,uEAAuE;QACvE,yCAAyC;QACzC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAA;QACrF,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,KAAK,CAAA;QACzD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QAC7B,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACpC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAM;QAC/B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAA;QACnC,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAA;IACvD,CAAC;CACF"}

package/dist/scheduler/locks/locks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The lock backends a scheduler config names.
+ *
+ *   // config/scheduler.ts
+ *   import { defineConfig, locks } from '@c9up/ream'
+ *
+ *   export default defineConfig({
+ *     lock: locks.redis({ connection: 'main' }),
+ *   })
+ *
+ * Without a lock the scheduler runs every task on every instance, which is
+ * correct while there is one, and duplicates every run once there are two.
+ *
+ * Factories are lazy: the backend is built when the scheduler is, so naming
+ * a Redis lock in a config that runs single-instance costs nothing until it
+ * is selected.
+ */
+import type { LockBackend } from './LockBackend.js';
+import { type LockRedisResolver } from './RedisLockBackend.js';
+/** A lock backend, built on first use. */
+export type LockBackendFactory = () => LockBackend;
+export declare const locks: {
+    /**
+     * In this process's memory. Two processes each keep their own, so this
+     * bounds nothing across replicas — it is for a single-process deployment
+     * and for tests.
+     */
+    memory(): LockBackendFactory;
+    /**
+     * Redis. `connection` takes a client, a function answering one, or the
+     * NAME of a `@c9up/quasar` connection — the last of which is resolved at
+     * runtime without ream importing quasar, which stays an optional peer.
+     */
+    redis(options: {
+        connection: LockRedisResolver | string;
+        prefix?: string;
+    }): LockBackendFactory;
+};
+//# sourceMappingURL=locks.d.ts.map

package/dist/scheduler/locks/locks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locks.d.ts","sourceRoot":"","sources":["../../../src/scheduler/locks/locks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnD,OAAO,EAAE,KAAK,iBAAiB,EAAoB,MAAM,uBAAuB,CAAA;AAEhF,0CAA0C;AAC1C,MAAM,MAAM,kBAAkB,GAAG,MAAM,WAAW,CAAA;AAElD,eAAO,MAAM,KAAK;IAChB;;;;OAIG;cACO,kBAAkB;IAI5B;;;;OAIG;mBACY;QAAE,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,kBAAkB;CAOhG,CAAA"}

package/dist/scheduler/locks/locks.js

@@ -0,0 +1,42 @@
+/**
+ * The lock backends a scheduler config names.
+ *
+ *   // config/scheduler.ts
+ *   import { defineConfig, locks } from '@c9up/ream'
+ *
+ *   export default defineConfig({
+ *     lock: locks.redis({ connection: 'main' }),
+ *   })
+ *
+ * Without a lock the scheduler runs every task on every instance, which is
+ * correct while there is one, and duplicates every run once there are two.
+ *
+ * Factories are lazy: the backend is built when the scheduler is, so naming
+ * a Redis lock in a config that runs single-instance costs nothing until it
+ * is selected.
+ */
+import { MemoryLockBackend } from './MemoryLockBackend.js';
+import { quasarConnection } from './quasar.js';
+import { RedisLockBackend } from './RedisLockBackend.js';
+export const locks = {
+    /**
+     * In this process's memory. Two processes each keep their own, so this
+     * bounds nothing across replicas — it is for a single-process deployment
+     * and for tests.
+     */
+    memory() {
+        return () => new MemoryLockBackend();
+    },
+    /**
+     * Redis. `connection` takes a client, a function answering one, or the
+     * NAME of a `@c9up/quasar` connection — the last of which is resolved at
+     * runtime without ream importing quasar, which stays an optional peer.
+     */
+    redis(options) {
+        const client = typeof options.connection === 'string'
+            ? quasarConnection(options.connection)
+            : options.connection;
+        return () => new RedisLockBackend(client, { prefix: options.prefix });
+    },
+};
+//# sourceMappingURL=locks.js.map

package/dist/scheduler/locks/locks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locks.js","sourceRoot":"","sources":["../../../src/scheduler/locks/locks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAA0B,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAKhF,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;;;;OAIG;IACH,MAAM;QACJ,OAAO,GAAG,EAAE,CAAC,IAAI,iBAAiB,EAAE,CAAA;IACtC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAoE;QACxE,MAAM,MAAM,GACV,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ;YACpC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,UAAU,CAAC;YACtC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAA;QACxB,OAAO,GAAG,EAAE,CAAC,IAAI,gBAAgB,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACvE,CAAC;CACF,CAAA"}