@relkit/providers-local 0.0.0

package/dist/jobs/queue-operations.js

@@ -0,0 +1,107 @@
+import { normalizeId } from "@relkit/contracts";
+import { acceptance, prepareIdempotency } from "./idempotency.js";
+import { makeEntry, nextEntry, persist } from "./queue-entry.js";
+import { assertTime, JobQueueStateError, transitions, } from "./queue-utils.js";
+import { assertLeaseOwner, leaseTransitionOptions } from "./lease-utils.js";
+import { acquireQueueLease } from "./queue-lease.js";
+import { createJobQueueAdminMutations } from "./queue-admin.js";
+import { orderedQueueEntries, recoverQueueEntries } from "./queue-recovery.js";
+export function createJobQueueMutations(store, state, options) {
+    let tail = Promise.resolve();
+    const serialize = (work) => {
+        const result = tail.then(work);
+        tail = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    const enqueue = (input) => serialize(async () => {
+        const now = options.clock();
+        assertTime(now, "enqueue time");
+        const acceptedAt = input.acceptedAt ?? now;
+        const prepared = prepareIdempotency(input.input, input.idempotency ?? options.idempotency, state.entries.values(), now, acceptedAt);
+        if (prepared.duplicate !== undefined)
+            return prepared.duplicate;
+        const instanceId = normalizeId(input.instanceId ?? options.createInstanceId?.());
+        if (state.entries.has(instanceId))
+            throw new JobQueueStateError(`Job ${instanceId} already exists`);
+        const entry = makeEntry(instanceId, "accepted", input.input, input.profile ?? "default", acceptedAt, state.nextOrder + 1, 0, undefined, undefined, undefined, prepared.record);
+        await persist(store, entry);
+        state.entries.set(instanceId, entry);
+        state.nextOrder = entry.order;
+        return acceptance(entry, false);
+    });
+    const acquire = (instanceId, leaseOptions = {}) => serialize(async () => {
+        const time = options.clock();
+        assertTime(time, "acquisition time");
+        await recoverQueueEntries(store, state.entries, time, false, options.clock);
+        const current = instanceId === undefined
+            ? orderedQueueEntries(state.entries).find((entry) => entry.state === "available" && (entry.availableAt ?? 0) <= time)
+            : state.entries.get(normalizeId(instanceId));
+        if (current === undefined) {
+            if (instanceId === undefined)
+                return undefined;
+            throw new JobQueueStateError(`Job ${instanceId} is unknown`);
+        }
+        if (current.state !== "available" || (current.availableAt ?? 0) > time)
+            throw new JobQueueStateError(`Job ${current.instanceId} is not available`);
+        return acquireQueueLease(store, state.entries, current, time, leaseOptions, current.attempt + 1, options.clock, options.ownerToken, options.leaseDurationMs);
+    });
+    const renew = (instanceId, leaseOptions = {}) => serialize(async () => {
+        const time = options.clock();
+        assertTime(time, "renewal time");
+        await recoverQueueEntries(store, state.entries, time, false, options.clock);
+        const current = state.entries.get(normalizeId(instanceId));
+        if (current === undefined)
+            throw new JobQueueStateError(`Job ${instanceId} is unknown`);
+        if (current.state !== "leased")
+            throw new JobQueueStateError(`Job ${instanceId} is not leased`);
+        assertLeaseOwner(current, options.ownerToken);
+        const next = nextEntry(current, "leased", leaseTransitionOptions(time, options.leaseDurationMs, leaseOptions, options.ownerToken), options.clock);
+        await persist(store, next);
+        state.entries.set(current.instanceId, next);
+        return next;
+    });
+    const transition = (instanceId, target, transitionOptions = {}) => serialize(async () => {
+        const time = options.clock();
+        assertTime(time, "transition time");
+        await recoverQueueEntries(store, state.entries, time, false, options.clock);
+        const current = state.entries.get(normalizeId(instanceId));
+        if (current === undefined)
+            throw new JobQueueStateError(`Job ${instanceId} is unknown`);
+        if (transitionOptions.expectedState !== undefined &&
+            current.state !== transitionOptions.expectedState)
+            throw new JobQueueStateError(`Job ${instanceId} is not ${transitionOptions.expectedState}`);
+        if (!transitions[current.state].includes(target))
+            throw new JobQueueStateError(`Invalid transition ${current.state} -> ${target}`);
+        if (current.state === "leased")
+            assertLeaseOwner(current, options.ownerToken);
+        const next = nextEntry(current, target, target === "leased"
+            ? {
+                ...leaseTransitionOptions(time, options.leaseDurationMs, transitionOptions, options.ownerToken),
+                ...(transitionOptions.attempt === undefined
+                    ? {}
+                    : { attempt: transitionOptions.attempt }),
+            }
+            : transitionOptions, options.clock);
+        await persist(store, next);
+        state.entries.set(current.instanceId, next);
+        return next;
+    });
+    const recover = (time = options.clock()) => serialize(() => recoverQueueEntries(store, state.entries, time, true, options.clock));
+    const expire = (time = options.clock()) => serialize(() => recoverQueueEntries(store, state.entries, time, false, options.clock));
+    const admin = createJobQueueAdminMutations(store, state.entries, {
+        clock: options.clock,
+        serialize,
+    });
+    const ready = recover(options.clock()).then(() => undefined);
+    return {
+        ready: () => ready,
+        enqueue,
+        acquire,
+        renew,
+        transition,
+        ...admin,
+        recover,
+        expire,
+    };
+}
+//# sourceMappingURL=queue-operations.js.map

package/dist/jobs/queue-operations.js.map

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

package/dist/jobs/queue-recovery.d.ts

@@ -0,0 +1,5 @@
+import type { JobStore } from "./store.js";
+import { type JobQueueEntry } from "./queue-utils.js";
+export declare function orderedQueueEntries(entries: Map<string, JobQueueEntry>): JobQueueEntry[];
+export declare function recoverQueueEntries(store: JobStore, entries: Map<string, JobQueueEntry>, time: number, includeAccepted: boolean, clock: () => number): Promise<readonly JobQueueEntry[]>;
+//# sourceMappingURL=queue-recovery.d.ts.map

package/dist/jobs/queue-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-recovery.d.ts","sourceRoot":"","sources":["../../src/jobs/queue-recovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGlE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,aAAa,EAAE,CAIxF;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,OAAO,EACxB,KAAK,EAAE,MAAM,MAAM,GAClB,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAYnC"}

package/dist/jobs/queue-recovery.js

@@ -0,0 +1,22 @@
+import { nextEntry, persist } from "./queue-entry.js";
+import { assertTime } from "./queue-utils.js";
+import { isLeaseExpired } from "./lease-utils.js";
+export function orderedQueueEntries(entries) {
+    return [...entries.values()].sort((a, b) => a.order - b.order || a.instanceId.localeCompare(b.instanceId));
+}
+export async function recoverQueueEntries(store, entries, time, includeAccepted, clock) {
+    assertTime(time, includeAccepted ? "recovery time" : "expiry time");
+    const recovered = [];
+    for (const current of orderedQueueEntries(entries)) {
+        if (current.state !== "accepted" && !isLeaseExpired(current, time))
+            continue;
+        if (!includeAccepted && current.state === "accepted")
+            continue;
+        const next = nextEntry(current, "available", { availableAt: time }, clock);
+        await persist(store, next);
+        entries.set(current.instanceId, next);
+        recovered.push(next);
+    }
+    return Object.freeze(recovered);
+}
+//# sourceMappingURL=queue-recovery.js.map

package/dist/jobs/queue-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-recovery.js","sourceRoot":"","sources":["../../src/jobs/queue-recovery.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAsB,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,UAAU,mBAAmB,CAAC,OAAmC;IACrE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CACxE,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAe,EACf,OAAmC,EACnC,IAAY,EACZ,eAAwB,EACxB,KAAmB;IAEnB,UAAU,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IACpE,MAAM,SAAS,GAAoB,EAAE,CAAC;IACtC,KAAK,MAAM,OAAO,IAAI,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,OAAO,CAAC,KAAK,KAAK,UAAU,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC;YAAE,SAAS;QAC7E,IAAI,CAAC,eAAe,IAAI,OAAO,CAAC,KAAK,KAAK,UAAU;YAAE,SAAS;QAC/D,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC;QAC3E,MAAM,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC3B,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACtC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/dist/jobs/queue-utils.d.ts

@@ -0,0 +1,101 @@
+import type { JsonValue } from "@relkit/contracts";
+export declare const JOB_QUEUE_STATES: readonly ["accepted", "available", "leased", "delayed", "completed", "dead-lettered"];
+export type JobQueueState = (typeof JOB_QUEUE_STATES)[number];
+export type JobState = JobQueueState;
+export interface JobIdempotencyDefinition {
+    readonly key: string;
+    readonly retentionMs: number;
+}
+export interface JobIdempotencyRecord {
+    readonly key: string;
+    readonly expiresAt: number;
+}
+export interface JobQueueEntry {
+    readonly instanceId: string;
+    readonly state: JobQueueState;
+    readonly input: JsonValue;
+    readonly profile: string;
+    readonly attempt: number;
+    readonly acceptedAt: number;
+    readonly order: number;
+    readonly availableAt?: number;
+    readonly leaseOwner?: string;
+    readonly leaseExpiresAt?: number;
+    readonly idempotency?: JobIdempotencyRecord;
+    readonly failure?: JobFailureMetadata;
+}
+/** Durable acceptance information returned by queue admission. */
+export interface JobQueueAcceptance extends JobQueueEntry {
+    readonly accepted: true;
+    readonly duplicate: boolean;
+    readonly idempotencyKey?: string;
+    readonly idempotencyExpiresAt?: number;
+}
+export type JobFailureKind = "application" | "provider" | "cancellation" | "timeout" | "defect";
+export type JobFailureOutcome = "declared-error" | "provider-failure" | "cancelled" | "timeout" | "defect";
+export type JobFailureRetry = "never" | "later";
+/** Public, JSON-safe failure data retained with a delayed or dead-lettered job. */
+export interface JobFailureMetadata {
+    readonly kind: JobFailureKind;
+    readonly outcome: JobFailureOutcome;
+    readonly code: string;
+    readonly message: string;
+    readonly data?: JsonValue;
+    readonly status?: number;
+    readonly retry?: JobFailureRetry;
+    readonly afterMs?: number;
+}
+export interface JobQueueEnqueue {
+    readonly input: JsonValue;
+    readonly profile?: string;
+    readonly instanceId?: string;
+    readonly acceptedAt?: number;
+    readonly idempotency?: JobIdempotencyDefinition;
+}
+export interface JobQueueLeaseOptions {
+    readonly leaseDurationMs?: number;
+    readonly leaseExpiresAt?: number;
+}
+export interface JobQueueTransitionOptions extends JobQueueLeaseOptions {
+    readonly expectedState?: JobQueueState;
+    readonly attempt?: number;
+    readonly availableAt?: number;
+    readonly leaseOwner?: string;
+    readonly failure?: JobFailureMetadata;
+}
+export interface JobQueueAdminRetryOptions {
+    readonly availableAt?: number;
+}
+export type JobQueueCounts = Readonly<Record<JobQueueState, number>>;
+export interface JobQueueOptions {
+    readonly now?: () => number;
+    readonly createInstanceId?: () => string;
+    readonly ownerToken?: string;
+    readonly leaseDurationMs?: number;
+    readonly idempotency?: JobIdempotencyDefinition;
+}
+export interface JobQueue {
+    readonly ownerToken: string;
+    readonly ready: () => Promise<void>;
+    readonly enqueue: (input: JobQueueEnqueue) => Promise<JobQueueAcceptance>;
+    readonly acquire: (instanceId?: string, options?: JobQueueLeaseOptions) => Promise<JobQueueEntry | undefined>;
+    readonly renew: (instanceId: string, options?: JobQueueLeaseOptions) => Promise<JobQueueEntry>;
+    readonly transition: (instanceId: string, state: JobQueueState, options?: JobQueueTransitionOptions) => Promise<JobQueueEntry>;
+    /** Requeues one dead letter as a fresh attempt without widening normal transitions. */
+    readonly adminRetry: (instanceId: string, options?: JobQueueAdminRetryOptions) => Promise<JobQueueEntry>;
+    /** Moves one eligible nonterminal entry to a dead letter with safe metadata. */
+    readonly adminDeadLetter: (instanceId: string, failure: JobFailureMetadata) => Promise<JobQueueEntry>;
+    readonly recover: (now?: number) => Promise<readonly JobQueueEntry[]>;
+    readonly expire: (now?: number) => Promise<readonly JobQueueEntry[]>;
+    readonly selectAvailable: (limit?: number, now?: number) => readonly JobQueueEntry[];
+    readonly get: (instanceId: string) => JobQueueEntry | undefined;
+    readonly counts: () => JobQueueCounts;
+    readonly snapshot: () => readonly JobQueueEntry[];
+}
+export declare class JobQueueStateError extends Error {
+    readonly code: "RELKIT_JOB_QUEUE_STATE_INVALID";
+    constructor(message: string);
+}
+export declare const transitions: Readonly<Record<JobQueueState, readonly JobQueueState[]>>;
+export declare function assertTime(value: number, label: string): void;
+//# sourceMappingURL=queue-utils.d.ts.map

package/dist/jobs/queue-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-utils.d.ts","sourceRoot":"","sources":["../../src/jobs/queue-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,eAAO,MAAM,gBAAgB,uFAOnB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9D,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC;AACrC,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;CACvC;AAED,kEAAkE;AAClE,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,UAAU,GAAG,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAChG,MAAM,MAAM,iBAAiB,GAC3B,gBAAgB,GAAG,kBAAkB,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAC7E,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,CAAC;AAEhD,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AACD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,CAAC;CACjD;AACD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AACD,MAAM,WAAW,yBAA0B,SAAQ,oBAAoB;IACrE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;CACvC;AACD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AACD,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,CAAC;CACjD;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC1E,QAAQ,CAAC,OAAO,EAAE,CAChB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/F,QAAQ,CAAC,UAAU,EAAE,CACnB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,yBAAyB,KAChC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,CACnB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,yBAAyB,KAChC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,eAAe,EAAE,CACxB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,KACxB,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;IACtE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;IACrE,QAAQ,CAAC,eAAe,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,SAAS,aAAa,EAAE,CAAC;IACrF,QAAQ,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,cAAc,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,SAAS,aAAa,EAAE,CAAC;CACnD;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAG,gCAAgC,CAAU;gBAE9C,OAAO,EAAE,MAAM;CAI5B;AAED,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,aAAa,EAAE,CAAC,CAOjF,CAAC;AAEF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAG7D"}

package/dist/jobs/queue-utils.js

@@ -0,0 +1,28 @@
+export const JOB_QUEUE_STATES = [
+    "accepted",
+    "available",
+    "leased",
+    "delayed",
+    "completed",
+    "dead-lettered",
+];
+export class JobQueueStateError extends Error {
+    code = "RELKIT_JOB_QUEUE_STATE_INVALID";
+    constructor(message) {
+        super(message);
+        this.name = "JobQueueStateError";
+    }
+}
+export const transitions = {
+    accepted: ["available"],
+    available: ["leased"],
+    leased: ["leased", "available", "delayed", "completed", "dead-lettered"],
+    delayed: ["available"],
+    completed: [],
+    "dead-lettered": [],
+};
+export function assertTime(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new JobQueueStateError(`${label} is invalid`);
+}
+//# sourceMappingURL=queue-utils.js.map

package/dist/jobs/queue-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-utils.js","sourceRoot":"","sources":["../../src/jobs/queue-utils.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,UAAU;IACV,WAAW;IACX,QAAQ;IACR,SAAS;IACT,WAAW;IACX,eAAe;CACP,CAAC;AAmHX,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,GAAG,gCAAyC,CAAC;IAE1D,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,CAAC,MAAM,WAAW,GAA8D;IACpF,QAAQ,EAAE,CAAC,WAAW,CAAC;IACvB,SAAS,EAAE,CAAC,QAAQ,CAAC;IACrB,MAAM,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,CAAC;IACxE,OAAO,EAAE,CAAC,WAAW,CAAC;IACtB,SAAS,EAAE,EAAE;IACb,eAAe,EAAE,EAAE;CACpB,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,KAAa;IACrD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAC3C,MAAM,IAAI,kBAAkB,CAAC,GAAG,KAAK,aAAa,CAAC,CAAC;AACxD,CAAC"}

package/dist/jobs/queue.d.ts

@@ -0,0 +1,7 @@
+import type { JobStore } from "./store.js";
+import { type JobQueue, type JobQueueOptions } from "./queue-utils.js";
+export { JOB_QUEUE_STATES, JobQueueStateError } from "./queue-utils.js";
+export type * from "./queue-utils.js";
+/** Provides durable queue state plus process-owned leases. */
+export declare function createJobQueue(store: JobStore, options?: JobQueueOptions): JobQueue;
+//# sourceMappingURL=queue.d.ts.map

package/dist/jobs/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/jobs/queue.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,EAKL,KAAK,QAAQ,EAGb,KAAK,eAAe,EAErB,MAAM,kBAAkB,CAAC;AAO1B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,mBAAmB,kBAAkB,CAAC;AAEtC,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAuEvF"}

package/dist/jobs/queue.js

@@ -0,0 +1,70 @@
+import { randomUUID } from "node:crypto";
+import { normalizeId } from "@relkit/contracts";
+import { readEntry } from "./queue-entry.js";
+import { createJobQueueMutations } from "./queue-operations.js";
+import { validateIdempotencyDefinition } from "./idempotency.js";
+import { JOB_QUEUE_STATES, JobQueueStateError, assertTime, transitions, } from "./queue-utils.js";
+import { assertLeaseDuration, DEFAULT_LEASE_DURATION_MS, normalizeOwnerToken, } from "./lease-utils.js";
+export { JOB_QUEUE_STATES, JobQueueStateError } from "./queue-utils.js";
+/** Provides durable queue state plus process-owned leases. */
+export function createJobQueue(store, options = {}) {
+    const clock = options.now ?? Date.now;
+    const ownerToken = normalizeOwnerToken(options.ownerToken ?? randomUUID());
+    const leaseDurationMs = options.leaseDurationMs ?? DEFAULT_LEASE_DURATION_MS;
+    const idempotency = options.idempotency === undefined
+        ? undefined
+        : validateIdempotencyDefinition(options.idempotency);
+    assertLeaseDuration(leaseDurationMs);
+    const state = { entries: new Map(), nextOrder: 0 };
+    for (const record of store.snapshot().records) {
+        const entry = readEntry(record);
+        if (entry === undefined)
+            continue;
+        const prior = state.entries.get(entry.instanceId);
+        if (prior !== undefined &&
+            prior.state !== entry.state &&
+            !transitions[prior.state].includes(entry.state))
+            throw new JobQueueStateError(`Invalid transition ${prior.state} -> ${entry.state}`);
+        state.entries.set(entry.instanceId, entry);
+        state.nextOrder = Math.max(state.nextOrder, entry.order);
+    }
+    const mutations = createJobQueueMutations(store, state, {
+        clock,
+        createInstanceId: options.createInstanceId ?? randomUUID,
+        ownerToken,
+        leaseDurationMs,
+        idempotency,
+    });
+    const ordered = () => [...state.entries.values()].sort((a, b) => a.order - b.order || a.instanceId.localeCompare(b.instanceId));
+    const selectAvailable = (limit = Number.MAX_SAFE_INTEGER, time = clock()) => {
+        assertTime(time, "selection time");
+        if (!Number.isSafeInteger(limit) || limit < 0)
+            throw new JobQueueStateError("Selection limit is invalid");
+        return Object.freeze(ordered()
+            .filter((entry) => entry.state === "available" && (entry.availableAt ?? 0) <= time)
+            .slice(0, limit));
+    };
+    const counts = () => {
+        const result = Object.fromEntries(JOB_QUEUE_STATES.map((state) => [state, 0]));
+        for (const entry of state.entries.values())
+            result[entry.state] += 1;
+        return Object.freeze(result);
+    };
+    return Object.freeze({
+        ownerToken,
+        ready: mutations.ready,
+        enqueue: mutations.enqueue,
+        acquire: mutations.acquire,
+        renew: mutations.renew,
+        transition: mutations.transition,
+        adminRetry: mutations.adminRetry,
+        adminDeadLetter: mutations.adminDeadLetter,
+        recover: mutations.recover,
+        expire: mutations.expire,
+        selectAvailable,
+        get: (instanceId) => state.entries.get(normalizeId(instanceId)),
+        counts,
+        snapshot: () => Object.freeze(ordered()),
+    });
+}
+//# sourceMappingURL=queue.js.map

package/dist/jobs/queue.js.map

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

package/dist/jobs/retry.d.ts

@@ -0,0 +1,25 @@
+import type { RetryPolicy } from "@relkit/jobs";
+import { type JobFailureMetadata, type JobQueue, type JobQueueEntry } from "./queue-utils.js";
+export type RetryClassification = "retryable" | "non-retryable";
+export type RetryState = "delayed" | "dead-lettered";
+export type RandomSource = () => number;
+export interface RetryPlan {
+    readonly classification: RetryClassification;
+    readonly state: RetryState;
+    readonly attempt: number;
+    readonly delayMs: number;
+    readonly failure: JobFailureMetadata;
+}
+export interface RetryOptions {
+    readonly now?: () => number;
+    readonly random?: RandomSource;
+}
+/** Uses the declared error policy; non-declared failures are not retried. */
+export declare function classifyFailure(value: unknown): RetryClassification;
+/** Calculates a bounded, integer delay for a one-based completed attempt. */
+export declare function calculateRetryDelay(policy: RetryPolicy, attempt: number, random?: RandomSource): number;
+export declare function planRetry(policy: RetryPolicy, attempt: number, failure: unknown, options?: Pick<RetryOptions, "random">): RetryPlan;
+/** Applies one leased attempt's retry/dead-letter outcome durably. */
+export declare function applyRetry(queue: Pick<JobQueue, "get" | "transition">, instanceId: string, policy: RetryPolicy, failure: unknown, options?: RetryOptions): Promise<JobQueueEntry>;
+export declare function safeFailureMetadata(value: unknown): JobFailureMetadata;
+//# sourceMappingURL=retry.d.ts.map

package/dist/jobs/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/jobs/retry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,eAAe,CAAC;AAChE,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,eAAe,CAAC;AACrD,MAAM,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC;AAExC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAKnE;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,YAA0B,GACjC,MAAM,CAcR;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAM,GACzC,SAAS,CAcX;AAED,sEAAsE;AACtE,wBAAsB,UAAU,CAC9B,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,GAAG,YAAY,CAAC,EAC3C,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,aAAa,CAAC,CAaxB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAItE"}

package/dist/jobs/retry.js

@@ -0,0 +1,84 @@
+import { canonicalJson, deepFreeze } from "@relkit/contracts";
+import { normalizeFailure, toPublicEnvelope } from "@relkit/runtime-effect";
+import { JobQueueStateError, assertTime, } from "./queue-utils.js";
+/** Uses the declared error policy; non-declared failures are not retried. */
+export function classifyFailure(value) {
+    const failure = normalizeFailure(value);
+    return failure._tag === "ApplicationFailure" && failure.retry === "later"
+        ? "retryable"
+        : "non-retryable";
+}
+/** Calculates a bounded, integer delay for a one-based completed attempt. */
+export function calculateRetryDelay(policy, attempt, random = Math.random) {
+    assertPolicy(policy);
+    assertAttempt(attempt);
+    const exponential = policy.initialDelayMs * Math.pow(policy.multiplier, attempt - 1);
+    const capped = Number.isFinite(exponential)
+        ? Math.min(policy.maxDelayMs, Math.floor(exponential))
+        : policy.maxDelayMs;
+    if (capped === 0 || policy.jitter === "none")
+        return capped;
+    const sample = random();
+    if (!Number.isFinite(sample) || sample < 0 || sample >= 1)
+        throw new TypeError("Retry randomness must be in [0, 1)");
+    return policy.jitter === "full"
+        ? Math.floor(sample * capped)
+        : Math.floor(capped / 2 + sample * (capped / 2));
+}
+export function planRetry(policy, attempt, failure, options = {}) {
+    assertAttempt(attempt);
+    const normalized = normalizeFailure(failure);
+    const classification = classifyFailure(normalized);
+    const retry = classification === "retryable" && attempt < policy.maxAttempts;
+    const policyDelay = retry ? calculateRetryDelay(policy, attempt, options.random) : 0;
+    const errorDelay = normalized._tag === "ApplicationFailure" ? (normalized.afterMs ?? 0) : 0;
+    return deepFreeze({
+        classification,
+        state: retry ? "delayed" : "dead-lettered",
+        attempt,
+        delayMs: retry ? Math.max(policyDelay, errorDelay) : 0,
+        failure: safeFailureMetadata(normalized),
+    });
+}
+/** Applies one leased attempt's retry/dead-letter outcome durably. */
+export async function applyRetry(queue, instanceId, policy, failure, options = {}) {
+    const current = queue.get(instanceId);
+    if (current === undefined)
+        throw new JobQueueStateError(`Job ${instanceId} is unknown`);
+    if (current.state !== "leased")
+        throw new JobQueueStateError(`Job ${instanceId} is not leased`);
+    const plan = planRetry(policy, current.attempt, failure, options);
+    const now = options.now?.() ?? Date.now();
+    assertTime(now, "retry time");
+    const availableAt = plan.state === "delayed" ? addTime(now, plan.delayMs) : undefined;
+    return queue.transition(instanceId, plan.state, {
+        expectedState: "leased",
+        ...(availableAt === undefined ? {} : { availableAt }),
+        failure: plan.failure,
+    });
+}
+export function safeFailureMetadata(value) {
+    return deepFreeze(JSON.parse(canonicalJson(toPublicEnvelope(normalizeFailure(value)))));
+}
+function assertPolicy(policy) {
+    if (!Number.isSafeInteger(policy.maxAttempts) || policy.maxAttempts < 1)
+        throw new TypeError("retry.maxAttempts must be a positive integer");
+    if (!Number.isSafeInteger(policy.initialDelayMs) || policy.initialDelayMs < 0)
+        throw new TypeError("retry.initialDelayMs must be a non-negative integer");
+    if (!Number.isSafeInteger(policy.maxDelayMs) || policy.maxDelayMs < policy.initialDelayMs)
+        throw new TypeError("retry.maxDelayMs must be at least retry.initialDelayMs");
+    if (!Number.isFinite(policy.multiplier) || policy.multiplier < 1)
+        throw new TypeError("retry.multiplier must be a finite number at least 1");
+    if (!["none", "full", "equal"].includes(policy.jitter))
+        throw new TypeError("retry.jitter must be none, full, or equal");
+}
+function assertAttempt(value) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new JobQueueStateError("Retry attempt must be a positive integer");
+}
+function addTime(now, delayMs) {
+    if (delayMs > Number.MAX_SAFE_INTEGER - now)
+        throw new JobQueueStateError("Retry availability time is invalid");
+    return now + delayMs;
+}
+//# sourceMappingURL=retry.js.map

package/dist/jobs/retry.js.map

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

package/dist/jobs/scheduler.d.ts

@@ -0,0 +1,52 @@
+import { type JsonValue, type MaybePromise } from "@relkit/contracts";
+import type { ScheduleDefinition, ScheduleOverlap } from "@relkit/jobs";
+export declare class ScheduleValidationError extends TypeError {
+    readonly code: "RELKIT_SCHEDULE_INVALID";
+    constructor(message: string);
+}
+export interface CompiledSchedule {
+    readonly id: string;
+    readonly cron: string;
+    readonly timezone: string;
+    readonly input: JsonValue;
+    readonly overlap: ScheduleOverlap;
+    readonly nextFireAt: Date;
+    readonly nextFire: (currentDate: Date) => Date;
+}
+export interface ScheduleEnqueueContext {
+    readonly scheduleId: string;
+    readonly fireAt: Date;
+}
+/** The scheduler only emits work through the common job enqueue/invocation seam. */
+export type ScheduleEnqueue = (input: JsonValue, context: ScheduleEnqueueContext) => MaybePromise<unknown>;
+export interface SchedulerRegistration {
+    readonly schedule: ScheduleDefinition;
+    readonly enqueue: ScheduleEnqueue;
+}
+export interface SchedulerClock {
+    readonly now: () => Date | number;
+}
+export interface SchedulerOptions {
+    readonly clock?: SchedulerClock;
+    readonly now?: () => Date | number;
+    readonly schedules?: readonly SchedulerRegistration[];
+}
+export interface ScheduleRun {
+    readonly scheduleId: string;
+    readonly fireAt: Date;
+    readonly status: "enqueued" | "skipped";
+    readonly result?: unknown;
+}
+export interface Scheduler {
+    readonly register: (schedule: ScheduleDefinition, enqueue: ScheduleEnqueue) => CompiledSchedule;
+    readonly nextFire: (scheduleId: string) => Date | undefined;
+    readonly runDue: (currentDate?: Date | number) => Promise<readonly ScheduleRun[]>;
+    readonly tick: (currentDate?: Date | number) => Promise<readonly ScheduleRun[]>;
+}
+/** Validates a static schedule and hides the cron parser behind native dates. */
+export declare function compileSchedule(schedule: ScheduleDefinition, options?: {
+    readonly currentDate?: Date;
+}): CompiledSchedule;
+/** Runs due schedules against an injected clock without owning or calling handlers. */
+export declare function createScheduler(options?: SchedulerOptions): Scheduler;
+//# sourceMappingURL=scheduler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/jobs/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAExE,qBAAa,uBAAwB,SAAQ,SAAS;IACpD,QAAQ,CAAC,IAAI,EAAG,yBAAyB,CAAU;gBAEvC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,IAAI,KAAK,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;CACvB;AAED,oFAAoF;AACpF,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,sBAAsB,KAC5B,YAAY,CAAC,OAAO,CAAC,CAAC;AAE3B,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,IAAI,GAAG,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACvD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AASD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,kBAAkB,EAAE,OAAO,EAAE,eAAe,KAAK,gBAAgB,CAAC;IAChG,QAAQ,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,MAAM,EAAE,CAAC,WAAW,CAAC,EAAE,IAAI,GAAG,MAAM,KAAK,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IAClF,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,IAAI,GAAG,MAAM,KAAK,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;CACjF;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CAAA;CAAO,GAC5C,gBAAgB,CA2BlB;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS,CA6DzE"}