@loomwork/event-runtime 0.0.0-stage → 0.1.0

package/dist/CoalescingEventStore.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoalescingEventStore = void 0;
+const installOptional_1 = require("./installOptional");
+const types_1 = require("./types");
+/**
+ * Merges concurrent appends **across executions** into one `appendBatch` (ADR 0074 D2).
+ *
+ * Why a decorator and not the journal: `ExecutionJournal` is per-execution, so a
+ * journal-side batcher can only ever hold one execution's envelopes — a 1-step flow emits
+ * four, and with a realistic slow effect the serial tail drains between `STEP_STARTED` and
+ * `STEP_COMPLETED`, so it collects one. Measured; it is ADR 0065's own gate-2 case. A store
+ * decorator sees every live execution at once and can actually fill a batch.
+ *
+ * **Ordering.** Each `ExecutionJournal` still serializes its own execution (D3 unchanged) —
+ * it awaits each `append` before issuing the next, so this store never holds two envelopes
+ * of one execution concurrently through the normal path. Should it anyway (a second writer,
+ * a caller not using the journal), the queue is FIFO and `appendBatch` is specified to
+ * apply in array order, so arrival order is preserved regardless.
+ *
+ * **Durability.** An `append` promise resolves only once its batch has committed. Nothing
+ * resolves early, so every `drain()` barrier keeps exactly the meaning it has today. This
+ * is the property that distinguishes coalescing from the durability classes ADR 0065
+ * rejected on invariants.
+ *
+ * **Failure.** A batch rejection rejects every caller in that batch, so a partial write can
+ * never look like success. Combined with `appendBatch`'s all-or-nothing contract, a failed
+ * flush leaves the log untouched and every writer informed — **but only when the inner store
+ * implements `appendBatch`**. Over a store without it, `appendBatchOf` falls back to a
+ * sequential `append` loop, which is not atomic: envelopes ahead of the failing one are
+ * already durable while their writers are told the batch failed. Every decorator between
+ * this one and the backend must therefore carry `appendBatch` down (ADR 0074 Amendment —
+ * `runEventStoreDecoratorConformance` checks it).
+ *
+ * **Blast radius.** One stale-fence zombie in a batch rejects the whole batch, so every
+ * healthy writer coalesced with it is told "failed" too (nothing of theirs lands; they abort
+ * and recovery re-drives them from the log). Coalescing widens a fencing rejection from one
+ * execution to up to `maxBatch` of them — a price worth paying while fencing is rare.
+ *
+ * Inert unless wired: compose it explicitly in `storage`, outermost-but-one (sharding
+ * outside it, since routing must pick a shard before a batch is formed for that shard).
+ */
+class CoalescingEventStore {
+    inner;
+    head;
+    readRange;
+    acquireFence;
+    acquireFenceIf;
+    appendIfUnchanged;
+    storeNow;
+    sealingCapability;
+    readAtRest;
+    copyPrefix;
+    deleteExecution;
+    deleteThrough;
+    truncatePrefix;
+    truncatePrefixKeeping;
+    listExecutions;
+    listExecutionsPage;
+    maxBatch;
+    maxLingerMs;
+    queue = [];
+    flushScheduled = false;
+    timer;
+    /** Serializes flushes so two batches can never be in flight against the inner store. */
+    tail = Promise.resolve();
+    closed = false;
+    constructor(inner, options = {}) {
+        this.inner = inner;
+        this.maxBatch = Math.max(1, options.maxBatch ?? 16);
+        this.maxLingerMs = Math.max(0, options.maxLingerMs ?? 0);
+        // Pass through every optional capability the inner store has, so wrapping never
+        // silently downgrades a backend (a missing `readRange` would push callers onto the
+        // slow fallback for no reason). `appendBatch` is this class's own method — batching is
+        // what it is for — so the plan covers every other optional method.
+        const plan = {
+            head: "forward",
+            readRange: "forward",
+            acquireFence: "forward",
+            acquireFenceIf: "forward",
+            appendIfUnchanged: "forward",
+            storeNow: "forward",
+            sealingCapability: "forward",
+            readAtRest: "forward",
+            copyPrefix: "forward",
+            deleteExecution: "forward",
+            deleteThrough: "forward",
+            truncatePrefix: "forward",
+            truncatePrefixKeeping: "forward",
+            listExecutions: "forward",
+            listExecutionsPage: "forward",
+        };
+        (0, installOptional_1.installOptional)(this, inner, plan);
+    }
+    append(envelope) {
+        if (this.closed)
+            return Promise.reject(new Error("CoalescingEventStore is closed"));
+        return new Promise((resolve, reject) => {
+            this.queue.push({ envelope, resolve, reject });
+            if (this.queue.length >= this.maxBatch)
+                this.flushNow();
+            else
+                this.scheduleFlush();
+        });
+    }
+    /**
+     * A caller that already has a batch skips the queue entirely — it is by definition
+     * already coalesced, and threading it through the queue would only risk splitting it.
+     */
+    appendBatch(envelopes) {
+        if (envelopes.length === 0)
+            return Promise.resolve();
+        if (this.closed)
+            return Promise.reject(new Error("CoalescingEventStore is closed"));
+        return this.enqueueFlush(() => (0, types_1.appendBatchOf)(this.inner, envelopes));
+    }
+    scheduleFlush() {
+        if (this.flushScheduled)
+            return;
+        this.flushScheduled = true;
+        if (this.maxLingerMs === 0) {
+            // Next microtask: collects everything enqueued in this turn — which under concurrency
+            // is the whole in-flight set — without deferring to a timer.
+            queueMicrotask(() => this.flushNow());
+        }
+        else {
+            this.timer = setTimeout(() => this.flushNow(), this.maxLingerMs);
+        }
+    }
+    flushNow() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.flushScheduled = false;
+        if (this.queue.length === 0)
+            return;
+        const batch = this.queue;
+        this.queue = [];
+        void this.enqueueFlush(async () => {
+            await (0, types_1.appendBatchOf)(this.inner, batch.map((p) => p.envelope));
+        }).then(() => {
+            for (const p of batch)
+                p.resolve();
+        }, (err) => {
+            // Every writer in a failed batch learns it failed — a partial write must never be
+            // reported as success.
+            for (const p of batch)
+                p.reject(err);
+        });
+    }
+    /** Chain onto the serial tail so batches commit one at a time, in enqueue order. */
+    enqueueFlush(run) {
+        const result = this.tail.then(run);
+        // The tail itself must never reject, or every later flush would inherit the failure.
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    read(executionId) {
+        return this.inner.read(executionId);
+    }
+    readFrom(executionId, fromSequence) {
+        return this.inner.readFrom(executionId, fromSequence);
+    }
+    subscribe(executionId, handler) {
+        return this.inner.subscribe(executionId, handler);
+    }
+    /** Flush anything queued and wait for in-flight batches. Safe to call repeatedly. */
+    async drain() {
+        this.flushNow();
+        await this.tail;
+    }
+    async close() {
+        await this.drain();
+        this.closed = true;
+        await this.inner.close();
+    }
+}
+exports.CoalescingEventStore = CoalescingEventStore;
+//# sourceMappingURL=CoalescingEventStore.js.map

package/dist/CoalescingEventStore.js.map

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

package/dist/InMemoryArchiveStore.d.ts

@@ -0,0 +1,19 @@
+import { type ArchiveExecutionPage, type ArchiveSegment, type ArchiveSegmentHeader, type ArchiveStore } from "./archiveSpi";
+/** In-memory {@link ArchiveStore}: for tests, the memory storage kind and in-memory event stores. */
+export declare class InMemoryArchiveStore implements ArchiveStore {
+    private readonly byExecution;
+    append(executionId: string, segment: ArchiveSegment): Promise<void>;
+    headers(executionId: string): Promise<ArchiveSegmentHeader[]>;
+    listExecutions(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<ArchiveExecutionPage>;
+    read(executionId: string, range?: {
+        readonly from?: number;
+        readonly through?: number;
+    }): Promise<ArchiveSegment[]>;
+    replaceSegments(executionId: string, expected: readonly ArchiveSegmentHeader[], next: readonly ArchiveSegment[]): Promise<void>;
+    deleteExecution(executionId: string): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=InMemoryArchiveStore.d.ts.map

package/dist/InMemoryArchiveStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryArchiveStore.d.ts","sourceRoot":"","sources":["../src/InMemoryArchiveStore.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EAIlB,MAAM,cAAc,CAAC;AAGtB,qGAAqG;AACrG,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IAE7D,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnE,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAI7D,cAAc,CAClB,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC7C,OAAO,CAAC,oBAAoB,CAAC;IAQ1B,IAAI,CACR,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAChE,OAAO,CAAC,cAAc,EAAE,CAAC;IAUtB,eAAe,CACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,SAAS,oBAAoB,EAAE,EACzC,IAAI,EAAE,SAAS,cAAc,EAAE,GAC9B,OAAO,CAAC,IAAI,CAAC;IAQV,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAC7B"}

package/dist/InMemoryArchiveStore.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryArchiveStore = void 0;
+const archive_1 = require("./archive");
+const archiveSpi_1 = require("./archiveSpi");
+const executionIdOrder_1 = require("./executionIdOrder");
+/** In-memory {@link ArchiveStore}: for tests, the memory storage kind and in-memory event stores. */
+class InMemoryArchiveStore {
+    byExecution = new Map();
+    async append(executionId, segment) {
+        const stored = this.byExecution.get(executionId) ?? [];
+        if ((0, archiveSpi_1.classifyAppend)(executionId, stored, segment) === "noop")
+            return;
+        // A copy through JSON, as a durable backend would hold it: the caller's objects never alias.
+        const copy = JSON.parse(JSON.stringify(segment));
+        this.byExecution.set(executionId, [...stored, copy]);
+    }
+    async headers(executionId) {
+        return (this.byExecution.get(executionId) ?? []).map(archiveSpi_1.headerOf);
+    }
+    async listExecutions(opts = {}) {
+        const ids = [...this.byExecution.entries()]
+            .filter(([, segs]) => segs.length > 0)
+            .map(([id]) => id)
+            .sort(executionIdOrder_1.compareExecutionIds);
+        return (0, archive_1.pageIds)(ids, opts);
+    }
+    async read(executionId, range = {}) {
+        return (this.byExecution.get(executionId) ?? [])
+            .filter((s) => (range.from === undefined || s.through >= range.from) &&
+            (range.through === undefined || s.from <= range.through))
+            .map((s) => JSON.parse(JSON.stringify(s)));
+    }
+    async replaceSegments(executionId, expected, next) {
+        const stored = this.byExecution.get(executionId) ?? [];
+        (0, archiveSpi_1.assertReplaceable)(executionId, stored.map(archiveSpi_1.headerOf), expected, next);
+        const copy = JSON.parse(JSON.stringify(next));
+        if (copy.length === 0)
+            this.byExecution.delete(executionId);
+        else
+            this.byExecution.set(executionId, copy);
+    }
+    async deleteExecution(executionId) {
+        this.byExecution.delete(executionId);
+    }
+    async close() { }
+}
+exports.InMemoryArchiveStore = InMemoryArchiveStore;
+//# sourceMappingURL=InMemoryArchiveStore.js.map

package/dist/InMemoryArchiveStore.js.map

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

package/dist/InMemoryAsyncEventStore.d.ts

@@ -0,0 +1,111 @@
+import type { EventEnvelope } from "@loomwork/core";
+import type { AcquireFenceIfResult, AppendIfUnchangedResult, EventStore, TipObservation } from "./types";
+export interface InMemoryAsyncEventStoreOptions {
+    /** Artificial per-operation delay (ms) to model network latency. Default 0. */
+    latencyMs?: number;
+    /**
+     * If provided and it returns true for an envelope, `append` rejects with the
+     * given/derived error instead of storing it — for exercising the durable-write
+     * failure path. Default: never fails.
+     */
+    failAppendWhen?: (envelope: EventEnvelope) => boolean | string | Error;
+}
+/**
+ * Reference **async** EventStore: a genuine Promise-returning backend (unlike the
+ * synchronous SQLite/in-memory stores, which merely satisfy the async interface).
+ * Use it as a starting point for a real network backend, or in tests to exercise
+ * the runtime's async write pipeline, ordering, and failure handling.
+ */
+export declare class InMemoryAsyncEventStore implements EventStore {
+    private readonly log;
+    /**
+     * The executionIds in SPI order (code point), built lazily by `listExecutionsPage` and
+     * dropped only when the SET of executions changes (a new one, or a delete). A full paged
+     * walk is then one O(n log n) sort plus O(log n) per page, not a re-sort per page.
+     */
+    private sortedIds;
+    /**
+     * #309 — every envelope id in the store, the index behind the `id` PRIMARY KEY both SQL
+     * backends have. GLOBAL, not per-execution, because that is what the SQL constraint is:
+     * two executions may not share an envelope id either.
+     *
+     * It has to be maintained everywhere the log changes, not just on append — a stale entry
+     * after a delete would refuse a legitimate re-append forever, and an un-removed one is a
+     * leak in a store whose whole job is to be re-created cheaply in tests. The removal side
+     * is only correct BECAUSE the invariant holds: an id belongs to exactly one envelope, so
+     * dropping the ids of the events being dropped cannot orphan someone else's claim.
+     *
+     * Costs one hash-table slot per event; the id strings themselves are already retained by
+     * the envelopes in `log`, so this is not a second copy of the data.
+     */
+    private readonly ids;
+    private readonly subscribers;
+    private readonly fences;
+    /**
+     * ADR 0129 — the store-assigned incarnation of each execution, taken from a store-wide
+     * monotonic counter when its sequence 0 first lands and dropped with the log. Store metadata
+     * only: never in an envelope, a fold, a snapshot or a hash, so replay stays byte-identical.
+     */
+    private readonly incarnations;
+    private nextIncarnation;
+    private readonly latencyMs;
+    private readonly failAppendWhen;
+    constructor(options?: InMemoryAsyncEventStoreOptions);
+    private tick;
+    append(envelope: EventEnvelope): Promise<void>;
+    /**
+     * ADR 0074 D1 — the reference implementation of the `appendBatch` contract, and what a
+     * bring-your-own backend can read to see what it has to honour.
+     *
+     * One `tick()` for the whole batch, because the point of the method is one round-trip.
+     * Atomicity is why validation is a separate pass: EVERY envelope is checked before ANY
+     * is committed, so a fenced-out or rejected envelope leaves the log exactly as it was
+     * rather than half-applied. Fencing is checked per envelope, since a batch may span
+     * executions.
+     */
+    appendBatch(envelopes: readonly EventEnvelope[]): Promise<void>;
+    /**
+     * Throws if this envelope may not land: a duplicate `(executionId, sequence)`, a
+     * duplicate envelope `id`, K9.4 fencing, or an injected failure.
+     */
+    private assertAppendable;
+    /** Insert into the execution's log, keeping it sorted by sequence. */
+    private commit;
+    read(executionId: string): Promise<EventEnvelope[]>;
+    readFrom(executionId: string, fromSequence: number): Promise<EventEnvelope[]>;
+    head(executionId: string): Promise<number | null>;
+    readRange(executionId: string, fromSequence: number, toSequence: number): Promise<EventEnvelope[]>;
+    copyPrefix(fromExecutionId: string, toExecutionId: string, throughSequence: number, metadata: Record<string, unknown>): Promise<void>;
+    acquireFence(executionId: string): Promise<number>;
+    /**
+     * ADR 0118 D1 — one synchronous step after the tick, so it cannot interleave with an append's
+     * own check-and-commit (which is also synchronous after ITS tick): the token compare-and-set
+     * plus a scan of the tail past `parkSeq`, which is short (the events appended since the park).
+     */
+    acquireFenceIf(executionId: string, expect: {
+        fence: number;
+        parkSeq: number;
+    }): Promise<AcquireFenceIfResult>;
+    /**
+     * SPI 2.2.0 (ADR 0116 amendment) — one synchronous step after the tick, so the existence,
+     * head and token checks and the commit cannot interleave with any other append, acquire or
+     * delete. The token is compared, never presented: the fence rule is deliberately skipped.
+     */
+    appendIfUnchanged(executionId: string, event: EventEnvelope | null, expect?: TipObservation): Promise<AppendIfUnchangedResult>;
+    deleteExecution(executionId: string): Promise<void>;
+    deleteThrough(executionId: string, through: number): Promise<void>;
+    private setLog;
+    listExecutions(): Promise<string[]>;
+    listExecutionsPage(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        executionIds: string[];
+        nextCursor?: string;
+    }>;
+    truncatePrefix(executionId: string, throughSequence: number): Promise<void>;
+    truncatePrefixKeeping(executionId: string, throughSequence: number, keepEventTypes: readonly string[]): Promise<void>;
+    subscribe(executionId: string, handler: (event: EventEnvelope) => void): Promise<() => void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=InMemoryAsyncEventStore.d.ts.map

package/dist/InMemoryAsyncEventStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryAsyncEventStore.d.ts","sourceRoot":"","sources":["../src/InMemoryAsyncEventStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMpD,OAAO,KAAK,EACV,oBAAoB,EACpB,uBAAuB,EACvB,UAAU,EACV,cAAc,EACf,MAAM,SAAS,CAAC;AAGjB,MAAM,WAAW,8BAA8B;IAC7C,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;CACxE;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,YAAW,UAAU;IACxD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsC;IAC1D;;;;OAIG;IACH,OAAO,CAAC,SAAS,CAAuB;IACxC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAEjB;gBAEF,OAAO,GAAE,8BAAmC;YAK1C,IAAI;IAKZ,MAAM,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD;;;;;;;;;OASG;IACG,WAAW,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BrE;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAoCxB,sEAAsE;IACtE,OAAO,CAAC,MAAM;IAiBR,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAMnD,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAM7E,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMjD,SAAS,CACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,EAAE,CAAC;IAKrB,UAAU,CACd,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC;IAiCV,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOxD;;;;OAIG;IACG,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC,oBAAoB,CAAC;IAYhC;;;;OAIG;IACG,iBAAiB,CACrB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,aAAa,GAAG,IAAI,EAC3B,MAAM,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,uBAAuB,CAAC;IA8B7B,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnD,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBxE,OAAO,CAAC,MAAM;IAQR,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKnC,kBAAkB,CAAC,IAAI,CAAC,EAAE;QAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAyBtD,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3E,qBAAqB,CACzB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,OAAO,CAAC,IAAI,CAAC;IAkBV,SAAS,CACb,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GACtC,OAAO,CAAC,MAAM,IAAI,CAAC;IAKhB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}