@adonis-agora/durable 0.1.0

package/dist/src/transports/queue.d.ts

@@ -0,0 +1,84 @@
+import type { AdapterFactory } from '@adonisjs/queue/types';
+import { type ControlMessage, type ControlPlane, type Heartbeat, type RemoteTask, type StepResult, type Transport } from '../interfaces.js';
+import { type StepHandler } from '../protocol.js';
+/**
+ * The wire payloads carried as a queue job's `payload`. Everything that crosses the queue is plain
+ * JSON — a `RemoteTask` (engine → worker), a `StepResult` / `Heartbeat` (worker → engine) and a
+ * `ControlMessage` (best-effort). The adapter stores `payload: any`, so these helpers round-trip
+ * through `JSON.stringify`/`JSON.parse` to guarantee that only JSON-safe values survive (functions,
+ * symbols, `undefined` members are dropped exactly as a real broker would drop them).
+ */
+/** Serialize a value to a JSON-safe clone. Throws on a non-serializable value (e.g. a cycle). */
+export declare function toJson<T>(value: T): T;
+/** Parse a job payload that we previously wrote with {@link toJson}. */
+export declare function fromJson<T>(value: unknown): T;
+export type TaskPayload = RemoteTask;
+export type ResultPayload = StepResult;
+export type HeartbeatPayload = Heartbeat;
+export type ControlPayload = ControlMessage;
+/**
+ * Map the engine's per-call `priority` (higher = more urgent, default/absent = unprioritised) onto an
+ * `@adonisjs/queue` job `priority` (lower = more urgent). Returns `undefined` for an absent priority so
+ * the default FIFO path is untouched.
+ */
+export declare function toBrokerPriority(priority?: number): number | undefined;
+export interface QueueTransportOptions {
+    /**
+     * Factory for the `@adonisjs/queue` adapter this transport reads/writes. The same kind of factory
+     * you hand `@adonisjs/queue`'s `defineConfig` (e.g. `redis(...)`, `knex(...)`, or `FakeAdapter`).
+     * One adapter instance is created per transport and reused for every queue.
+     */
+    adapter: AdapterFactory;
+    /**
+     * The worker group this instance serves. Required to register {@link QueueTransport.handle}
+     * consumers — the task poll loop pulls from this group's task queue. Omit on an engine-only
+     * instance that just dispatches + consumes results.
+     */
+    group?: string;
+    /** Queue-name prefix so several apps can share one backend without colliding. Default `durable`. */
+    prefix?: string;
+    /** Poll interval (ms) for the result/task/heartbeat/control loops. Default 200ms. */
+    pollIntervalMs?: number;
+    /** Stable id for this process (stamped on heartbeats / control `from`). Default a random id. */
+    instanceId?: string;
+}
+/**
+ * A `@adonisjs/queue`-backed {@link Transport}. Remote steps are dispatched to a per-group task
+ * queue; the worker side runs the registered handler via {@link runStepHandler} and pushes the
+ * {@link StepResult} onto a results queue the engine consumes. Heartbeats ride their own queue.
+ *
+ * `@adonisjs/queue` v0.6 is a one-directional job queue (dispatch → a separate `Worker` process
+ * runs `job.execute()`), with no built-in way to await a job's result. This transport instead
+ * drives the underlying queue **adapter** directly (`pushOn` / `popFrom` / `completeJob`), so both
+ * directions are plain point-to-point queues we fully control. Notably the {@link ControlPlane} here
+ * is single-consumer (point-to-point), so it is correct for a single engine instance but does NOT
+ * fan out to every pod the way a real pub/sub does.
+ *
+ * Run one instance engine-side (`onResult` + `dispatch`) and one per worker process (`handle()`).
+ * The wire payloads are the documented `RemoteTask`/`StepResult` JSON, so non-Node workers on the
+ * same queues interoperate.
+ *
+ * Usually you don't construct this directly: `config/durable.ts` selects it via
+ * `transports.queue({ ... })` and the provider builds it for you.
+ */
+export declare class QueueTransport implements Transport, ControlPlane {
+    #private;
+    constructor(options: QueueTransportOptions);
+    /** Stable id stamped on heartbeats and control `from`. */
+    get instanceId(): string;
+    dispatch(task: RemoteTask): Promise<void>;
+    /**
+     * Register a step handler (worker side). Starts this group's task poll loop on the first call —
+     * each task it pops runs through {@link runStepHandler} and its result is pushed to the engine.
+     */
+    handle(name: string, fn: StepHandler): void;
+    /** Worker side: publish a liveness heartbeat for an in-flight long step. */
+    heartbeat(beat: Heartbeat): Promise<void>;
+    onResult(handler: (result: StepResult) => Promise<void>): void;
+    onHeartbeat(handler: (beat: Heartbeat) => Promise<void>): void;
+    publishControl(msg: ControlMessage): Promise<void>;
+    onControl(handler: (msg: ControlMessage) => void): void;
+    /** Stop every poll loop and destroy the adapter so the process can exit. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/src/transports/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../src/transports/queue.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAwB,cAAc,EAAW,MAAM,uBAAuB,CAAC;AAC3F,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAElE;;;;;;GAMG;AAEH,iGAAiG;AACjG,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAErC;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAO7C;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC;AACrC,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC;AACvC,MAAM,MAAM,gBAAgB,GAAG,SAAS,CAAC;AACzC,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC;AAc5C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAItE;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,CAAC;IACxB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,cAAe,YAAW,SAAS,EAAE,YAAY;;gBAUhD,OAAO,EAAE,qBAAqB;IAW1C,0DAA0D;IAC1D,IAAI,UAAU,IAAI,MAAM,CAEvB;IAmCK,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAW/C;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI;IAe3C,4EAA4E;IACtE,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/C,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAM9D,WAAW,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAUxD,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI;IAsCvD,4EAA4E;IACtE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}

package/dist/src/transports/queue.js

@@ -0,0 +1,210 @@
+import { randomUUID } from 'node:crypto';
+import { Pollers } from '../pollers.js';
+import { runStepHandler } from '../protocol.js';
+/**
+ * The wire payloads carried as a queue job's `payload`. Everything that crosses the queue is plain
+ * JSON — a `RemoteTask` (engine → worker), a `StepResult` / `Heartbeat` (worker → engine) and a
+ * `ControlMessage` (best-effort). The adapter stores `payload: any`, so these helpers round-trip
+ * through `JSON.stringify`/`JSON.parse` to guarantee that only JSON-safe values survive (functions,
+ * symbols, `undefined` members are dropped exactly as a real broker would drop them).
+ */
+/** Serialize a value to a JSON-safe clone. Throws on a non-serializable value (e.g. a cycle). */
+export function toJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/** Parse a job payload that we previously wrote with {@link toJson}. */
+export function fromJson(value) {
+    // The adapter already gives us a structured value; if a driver hands back a raw string
+    // (some persist `payload` as text), decode it. Otherwise pass it straight through.
+    if (typeof value === 'string') {
+        return JSON.parse(value);
+    }
+    return value;
+}
+/** How often the engine-side / worker-side poll loops ask the adapter for the next job. */
+const DEFAULT_POLL_INTERVAL_MS = 200;
+// `@adonisjs/queue` job priority is the INVERSE of the durable engine's: a queue job runs the LOWEST
+// number first (1..10, default 5), while the engine's admission `priority` is "higher wins". We map
+// so one convention ("higher = more urgent") holds end-to-end. `BASELINE - p` keeps relative order (a
+// higher `p` yields a lower — more urgent — broker number), clamped into the adapter's valid range.
+// Centred on the default so callers have headroom both above and below it.
+const BROKER_PRIORITY_MIN = 1;
+const BROKER_PRIORITY_MAX = 10;
+const BROKER_PRIORITY_BASELINE = 5;
+/**
+ * Map the engine's per-call `priority` (higher = more urgent, default/absent = unprioritised) onto an
+ * `@adonisjs/queue` job `priority` (lower = more urgent). Returns `undefined` for an absent priority so
+ * the default FIFO path is untouched.
+ */
+export function toBrokerPriority(priority) {
+    if (priority == null)
+        return undefined;
+    const mapped = Math.round(BROKER_PRIORITY_BASELINE - priority);
+    return Math.min(BROKER_PRIORITY_MAX, Math.max(BROKER_PRIORITY_MIN, mapped));
+}
+/**
+ * A `@adonisjs/queue`-backed {@link Transport}. Remote steps are dispatched to a per-group task
+ * queue; the worker side runs the registered handler via {@link runStepHandler} and pushes the
+ * {@link StepResult} onto a results queue the engine consumes. Heartbeats ride their own queue.
+ *
+ * `@adonisjs/queue` v0.6 is a one-directional job queue (dispatch → a separate `Worker` process
+ * runs `job.execute()`), with no built-in way to await a job's result. This transport instead
+ * drives the underlying queue **adapter** directly (`pushOn` / `popFrom` / `completeJob`), so both
+ * directions are plain point-to-point queues we fully control. Notably the {@link ControlPlane} here
+ * is single-consumer (point-to-point), so it is correct for a single engine instance but does NOT
+ * fan out to every pod the way a real pub/sub does.
+ *
+ * Run one instance engine-side (`onResult` + `dispatch`) and one per worker process (`handle()`).
+ * The wire payloads are the documented `RemoteTask`/`StepResult` JSON, so non-Node workers on the
+ * same queues interoperate.
+ *
+ * Usually you don't construct this directly: `config/durable.ts` selects it via
+ * `transports.queue({ ... })` and the provider builds it for you.
+ */
+export class QueueTransport {
+    #adapter;
+    #group;
+    #prefix;
+    #pollIntervalMs;
+    #instanceId;
+    #handlers = new Map();
+    #pollers;
+    #taskLoop;
+    constructor(options) {
+        this.#adapter = options.adapter();
+        this.#group = options.group;
+        this.#prefix = options.prefix ?? 'durable';
+        this.#pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.#instanceId = options.instanceId ?? randomUUID();
+        // pop()/popFrom() require a worker id be set on the adapter before consuming.
+        this.#adapter.setWorkerId(this.#instanceId);
+        this.#pollers = new Pollers(this.#pollIntervalMs);
+    }
+    /** Stable id stamped on heartbeats and control `from`. */
+    get instanceId() {
+        return this.#instanceId;
+    }
+    #tasksQueue(group) {
+        return `${this.#prefix}:tasks:${group}`;
+    }
+    #resultsQueue() {
+        return `${this.#prefix}:results`;
+    }
+    #heartbeatsQueue() {
+        return `${this.#prefix}:heartbeats`;
+    }
+    #controlQueue() {
+        return `${this.#prefix}:control`;
+    }
+    /**
+     * Build the adapter `JobData` envelope for a JSON-safe payload. A translated `priority` is added
+     * only when set, so the default FIFO path is untouched for unprioritised dispatches.
+     */
+    #job(name, payload, priority) {
+        const brokerPriority = toBrokerPriority(priority);
+        return {
+            id: randomUUID(),
+            name,
+            payload: toJson(payload),
+            attempts: 0,
+            createdAt: Date.now(),
+            ...(brokerPriority != null ? { priority: brokerPriority } : {}),
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // engine → worker
+    // ---------------------------------------------------------------------------
+    async dispatch(task) {
+        await this.#adapter.pushOn(this.#tasksQueue(task.group), this.#job('task', task, task.priority));
+    }
+    // ---------------------------------------------------------------------------
+    // worker side — register a step handler, run it, push the result back
+    // ---------------------------------------------------------------------------
+    /**
+     * Register a step handler (worker side). Starts this group's task poll loop on the first call —
+     * each task it pops runs through {@link runStepHandler} and its result is pushed to the engine.
+     */
+    handle(name, fn) {
+        if (!this.#group) {
+            throw new Error('QueueTransport needs a `group` option to register handlers');
+        }
+        this.#handlers.set(name, fn);
+        if (!this.#taskLoop) {
+            const group = this.#group;
+            this.#taskLoop = this.#startLoop(this.#tasksQueue(group), async (job) => {
+                const task = fromJson(job.payload);
+                const result = await runStepHandler(task, this.#handlers.get(task.name));
+                await this.#adapter.pushOn(this.#resultsQueue(), this.#job('result', result));
+            });
+        }
+    }
+    /** Worker side: publish a liveness heartbeat for an in-flight long step. */
+    async heartbeat(beat) {
+        await this.#adapter.pushOn(this.#heartbeatsQueue(), this.#job('heartbeat', beat));
+    }
+    // ---------------------------------------------------------------------------
+    // worker → engine — the engine consumes results + heartbeats
+    // ---------------------------------------------------------------------------
+    onResult(handler) {
+        this.#startLoop(this.#resultsQueue(), async (job) => {
+            await handler(fromJson(job.payload));
+        });
+    }
+    onHeartbeat(handler) {
+        this.#startLoop(this.#heartbeatsQueue(), async (job) => {
+            await handler(fromJson(job.payload));
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // control plane (best-effort, point-to-point)
+    // ---------------------------------------------------------------------------
+    async publishControl(msg) {
+        const stamped = msg.from ? msg : { ...msg, from: this.#instanceId };
+        await this.#adapter.pushOn(this.#controlQueue(), this.#job('control', stamped));
+    }
+    onControl(handler) {
+        this.#startLoop(this.#controlQueue(), async (job) => {
+            handler(fromJson(job.payload));
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // poll loop
+    // ---------------------------------------------------------------------------
+    /**
+     * Poll `queue`, handing each popped job to `onJob` then marking it complete. A throwing `onJob`
+     * fails the job (so it is not silently lost) and polling continues. One job is popped per tick;
+     * core's {@link Pollers} drains a burst (re-ticking while a job was found) before sleeping, and
+     * owns the stop-all bookkeeping. Returns a handle that stops just this loop.
+     */
+    #startLoop(queue, onJob) {
+        return this.#pollers.start(async () => {
+            let job;
+            try {
+                job = await this.#adapter.popFrom(queue);
+            }
+            catch {
+                // A transient adapter error: treat as "no work", retry on the next tick.
+                return false;
+            }
+            if (!job)
+                return false;
+            try {
+                await onJob(job);
+                await this.#adapter.completeJob(job.id, queue);
+            }
+            catch (err) {
+                await this.#adapter
+                    .failJob(job.id, queue, err instanceof Error ? err : new Error(String(err)))
+                    .catch(() => { });
+            }
+            return true;
+        });
+    }
+    /** Stop every poll loop and destroy the adapter so the process can exit. */
+    async close() {
+        this.#pollers.stopAll();
+        this.#taskLoop = undefined;
+        await this.#adapter.destroy();
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/src/transports/queue.js.map

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

package/dist/src/workflow-ctx.d.ts

@@ -0,0 +1,64 @@
+import type { RemoteStepDef, StateStore, StepCheckpoint, StepError, StepEvent, StepInvocation, StepKind, WorkflowCtx } from './interfaces.js';
+/** A saga undo registered by a completed step, kept with its step name for visibility on failure. */
+export interface Compensation {
+    name: string;
+    fn: () => Promise<void>;
+}
+/** A finished local step the host should checkpoint and announce (completed or failed). */
+export interface StepRecord {
+    runId: string;
+    seq: number;
+    name: string;
+    kind: StepKind;
+    input?: unknown;
+    events?: StepEvent[] | undefined;
+    attempts: number;
+    enqueuedAt: Date;
+    startedAt: Date;
+    workerGroup?: string | undefined;
+}
+/**
+ * The narrow surface {@link createWorkflowCtx} needs from the engine — the seam between the
+ * authoring API (this module) and the orchestrator (the engine owns lifecycle: emitting events,
+ * suspending/resuming runs, dispatching remote steps).
+ */
+export interface CtxHost {
+    readonly store: StateStore;
+    /**
+     * Per-execution checkpoint snapshot, loaded ONCE at execution start (the completed prefix this
+     * replay walks). Lets each primitive read the prefix from memory instead of a per-call DB SELECT
+     * (the O(N²) replay-reads fix). A seq ABSENT from the map is NOT cached — the primitive falls back
+     * to the live store, so the checkpoint this resume is waking on (signal/timer/child, written after
+     * the snapshot) is always read fresh. New checkpoints written during this execution are inserted
+     * into the map so any later same-execution read sees them. Undefined ⇒ always hit the store.
+     */
+    readonly replay?: Map<number, StepCheckpoint> | undefined;
+    clock(): number;
+    webhookUrl?: ((token: string) => string) | undefined;
+    /** Mark a local step's body as started — emits `step.started` and (optionally) a `running` checkpoint. */
+    startStep(step: StepRecord): Promise<void>;
+    completeStep(step: StepRecord & {
+        output: unknown;
+    }): Promise<void>;
+    failStep(step: StepRecord & {
+        error: StepError;
+    }): Promise<void>;
+    callRemote<TInput, TOutput>(runId: string, seq: number, step: RemoteStepDef<TInput, TOutput>, input: TInput, queue?: string, transport?: string, admission?: {
+        priority?: number | undefined;
+        fairnessKey?: string | undefined;
+    }): Promise<TOutput>;
+    /** Start a child run once, deferred so it can't reentrantly resume a still-running parent. */
+    startChild(workflow: string, input: unknown, id: string, priority?: number): void;
+    /** Deliver an op to a durable entity (deferred), optionally with a `reply` token for the result. */
+    signalEntity?(name: string, key: string, op: string, arg: unknown, reply?: string): void;
+    /** Run a local step body through the registered step interceptors (identity if none). */
+    interceptStep?<T>(invocation: StepInvocation, body: () => Promise<T>): Promise<T>;
+}
+/**
+ * Build the {@link WorkflowCtx} handed to a workflow body. Every primitive is a closure over the
+ * position counter (the per-run logical position) and the saga `compensations` stack, so `task`/
+ * `child` compose `step`/`waitForSignal` directly. All durability goes through {@link CtxHost}, so
+ * the workflow body stays deterministic.
+ */
+export declare function createWorkflowCtx(host: CtxHost, runId: string, compensations: Compensation[], workflow?: string): WorkflowCtx;
+//# sourceMappingURL=workflow-ctx.d.ts.map

package/dist/src/workflow-ctx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-ctx.d.ts","sourceRoot":"","sources":["../../src/workflow-ctx.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAGV,aAAa,EACb,UAAU,EACV,cAAc,EACd,SAAS,EACT,SAAS,EACT,cAAc,EACd,QAAQ,EAGR,WAAW,EACZ,MAAM,iBAAiB,CAAC;AAUzB,qGAAqG;AACrG,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,2FAA2F;AAC3F,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,CAAC;IAC1D,KAAK,IAAI,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;IACrD,0GAA0G;IAC1G,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG;QAAE,KAAK,EAAE,SAAS,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,UAAU,CAAC,MAAM,EAAE,OAAO,EACxB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAC9E,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,8FAA8F;IAC9F,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClF,oGAAoG;IACpG,YAAY,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzF,yFAAyF;IACzF,aAAa,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACnF;AAcD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,YAAY,EAAE,EAC7B,QAAQ,SAAK,GACZ,WAAW,CAgeb"}