hikoutei 0.2.0

package/dist/application/sync/outbound/effects/SyncEffectSupervisor.js

@@ -0,0 +1,297 @@
+/**
+ * Keeps the bounded effect worker running until the durable outbox is idle.
+ *
+ * The supervisor provides liveness around `runSyncEffectWorker*()`: one pass
+ * still handles a bounded batch, while this loop starts the next pass and
+ * backs off after failures. It also coalesces manual and background triggers so
+ * one process cannot run two effect passes concurrently.
+ */
+import { randomUUID } from "node:crypto";
+import { NON_NEGATIVE_SAFE_INTEGER_MINIMUM, POSITIVE_SAFE_INTEGER_MINIMUM, } from "../../../../domain/index.js";
+import { runSyncEffectWorkerWithAdapter, } from "./SyncEffectWorker.js";
+const DEFAULT_MAX_EFFECTS = 20;
+const DEFAULT_IDLE_INTERVAL_MS = 1_000;
+const DEFAULT_ERROR_BACKOFF_INITIAL_MS = 1_000;
+const DEFAULT_ERROR_BACKOFF_MAX_MS = 30_000;
+const DEFAULT_JITTER_MAX_MS = 1_000;
+const DEFAULT_RECONCILIATION_INTERVAL_MS = 60_000;
+/**
+ * Runs one bounded effect pass at a time and continues while work is making
+ * progress. `stop()` waits for the current remote call to finish before the
+ * loop exits, so the caller does not close SQLite underneath an active pass.
+ */
+export class SyncEffectWorkerSupervisor {
+    runPass;
+    idleIntervalMs;
+    errorBackoffInitialMs;
+    errorBackoffMaxMs;
+    random;
+    wait;
+    now;
+    reconciliation;
+    reconciliationIntervalMs;
+    onReport;
+    onError;
+    running = false;
+    loopPromise;
+    inFlightPass;
+    inFlightReconciliation;
+    nextReconciliationAt = 0;
+    wakeWaiter;
+    constructor(options) {
+        this.runPass = options.runPass;
+        this.idleIntervalMs = requirePositiveSafeInteger(options.idleIntervalMs ?? DEFAULT_IDLE_INTERVAL_MS, "sync effect supervisor idle interval");
+        this.errorBackoffInitialMs = requirePositiveSafeInteger(options.errorBackoffInitialMs ?? DEFAULT_ERROR_BACKOFF_INITIAL_MS, "sync effect supervisor error backoff");
+        this.errorBackoffMaxMs = requirePositiveSafeInteger(options.errorBackoffMaxMs ?? DEFAULT_ERROR_BACKOFF_MAX_MS, "sync effect supervisor maximum error backoff");
+        if (this.errorBackoffMaxMs < this.errorBackoffInitialMs) {
+            throw new RangeError("sync effect supervisor maximum error backoff must be at least the initial backoff");
+        }
+        this.random = options.random ?? Math.random;
+        this.wait = options.wait ?? defaultWait;
+        this.now = options.now ?? Date.now;
+        this.reconciliation = options.reconciliation;
+        this.reconciliationIntervalMs = requirePositiveSafeInteger(options.reconciliation?.intervalMs ?? DEFAULT_RECONCILIATION_INTERVAL_MS, "sync effect supervisor reconciliation interval");
+        this.onReport = options.onReport;
+        this.onError = options.onError;
+    }
+    /** Starts the background drain loop; repeated calls are harmless. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.nextReconciliationAt = this.now();
+        this.loopPromise = this.runLoop();
+    }
+    /** Returns whether the supervisor is accepting background work. */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Runs one pass or joins the pass already running in this process.
+     * Manual HTTP triggers therefore cannot create a second concurrent worker.
+     */
+    runOnce() {
+        if (this.inFlightPass !== undefined)
+            return this.inFlightPass;
+        const pass = Promise.resolve().then(() => this.runPass());
+        this.inFlightPass = pass;
+        void pass.then(() => this.clearInFlightPass(pass), () => this.clearInFlightPass(pass));
+        return pass;
+    }
+    /** Stops scheduling new passes and waits for the active pass to finish. */
+    async stop() {
+        this.running = false;
+        this.wakeWaiter?.();
+        const loop = this.loopPromise;
+        if (loop !== undefined)
+            await loop;
+        this.loopPromise = undefined;
+    }
+    async runLoop() {
+        let errorBackoff = this.errorBackoffInitialMs;
+        while (this.running) {
+            try {
+                let report = await this.runOnce();
+                this.notifyReport(report);
+                if (!this.running)
+                    break;
+                const reconciliation = await this.runScheduledReconciliation(report);
+                if (reconciliation !== undefined && reconciliation.effectsEnqueued > 0 && this.running) {
+                    // The scan only enqueues corrections. Drain those corrections before
+                    // sleeping so a discovered drift does not wait for another tick.
+                    report = await this.runOnce();
+                    this.notifyReport(report);
+                }
+                if (!this.running)
+                    break;
+                if (hasImmediateProgress(report) ||
+                    (reconciliation !== undefined && reconciliation.effectsEnqueued > 0)) {
+                    if (report.failed > 0) {
+                        const delay = withJitter(errorBackoff, this.random);
+                        await this.waitFor(Math.min(this.errorBackoffMaxMs, delay));
+                        errorBackoff = nextBackoff(errorBackoff, this.errorBackoffMaxMs);
+                    }
+                    else {
+                        errorBackoff = this.errorBackoffInitialMs;
+                    }
+                    continue;
+                }
+                errorBackoff = this.errorBackoffInitialMs;
+                await this.waitFor(this.idleIntervalMs);
+            }
+            catch (error) {
+                this.notifyError(error);
+                if (!this.running)
+                    break;
+                const delay = withJitter(errorBackoff, this.random);
+                await this.waitFor(Math.min(this.errorBackoffMaxMs, delay));
+                errorBackoff = nextBackoff(errorBackoff, this.errorBackoffMaxMs);
+            }
+        }
+    }
+    /** Runs the reconciliation task when its interval has elapsed. */
+    async runScheduledReconciliation(workerReport) {
+        const reconciliation = this.reconciliation;
+        if (reconciliation === undefined || this.now() < this.nextReconciliationAt)
+            return undefined;
+        // Reconciliation is a safety net, not part of the normal write path. Wait
+        // until the just-completed worker pass reports no remaining ready work.
+        if (!isWorkerPassIdle(workerReport))
+            return undefined;
+        this.nextReconciliationAt = this.now() + this.reconciliationIntervalMs;
+        try {
+            if (reconciliation.isOutboxIdle !== undefined && !(await reconciliation.isOutboxIdle())) {
+                return undefined;
+            }
+            const report = await this.runReconciliationOnce(reconciliation);
+            this.notifyReconciliationReport(reconciliation, report);
+            return report;
+        }
+        catch (error) {
+            this.notifyReconciliationError(reconciliation, error);
+            return undefined;
+        }
+    }
+    /** Coalesces a manual/scheduled reconciliation call in this process. */
+    runReconciliationOnce(reconciliation) {
+        if (this.inFlightReconciliation !== undefined)
+            return this.inFlightReconciliation;
+        const pass = Promise.resolve().then(() => reconciliation.run());
+        this.inFlightReconciliation = pass;
+        void pass.then(() => this.clearInFlightReconciliation(pass), () => this.clearInFlightReconciliation(pass));
+        return pass;
+    }
+    notifyReconciliationReport(reconciliation, report) {
+        try {
+            reconciliation.onReport?.(report);
+        }
+        catch (error) {
+            this.notifyError(error);
+        }
+    }
+    notifyReconciliationError(reconciliation, error) {
+        if (reconciliation.onError === undefined) {
+            this.notifyError(error);
+            return;
+        }
+        try {
+            reconciliation.onError(error);
+        }
+        catch (callbackError) {
+            this.notifyError(callbackError);
+        }
+    }
+    notifyReport(report) {
+        try {
+            this.onReport?.(report);
+        }
+        catch (error) {
+            this.notifyError(error);
+        }
+    }
+    notifyError(error) {
+        try {
+            this.onError?.(error);
+        }
+        catch {
+            // Observability callbacks must not terminate the drain loop.
+        }
+    }
+    async waitFor(durationMs) {
+        if (!this.running)
+            return;
+        if (this.wait !== defaultWait) {
+            await this.wait(durationMs);
+            return;
+        }
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                if (this.wakeWaiter === wake)
+                    this.wakeWaiter = undefined;
+                resolve();
+            }, durationMs);
+            const wake = () => {
+                clearTimeout(timer);
+                if (this.wakeWaiter === wake)
+                    this.wakeWaiter = undefined;
+                resolve();
+            };
+            this.wakeWaiter = wake;
+        });
+    }
+    clearInFlightPass(pass) {
+        if (this.inFlightPass === pass)
+            this.inFlightPass = undefined;
+    }
+    clearInFlightReconciliation(pass) {
+        if (this.inFlightReconciliation === pass)
+            this.inFlightReconciliation = undefined;
+    }
+}
+/** Creates a supervisor that supplies a fresh timestamp to every worker pass. */
+export function createSyncEffectWorkerSupervisor(options) {
+    const workerId = options.workerId ?? `sync-effect-worker:${randomUUID()}`;
+    const maxEffects = options.maxEffects ?? DEFAULT_MAX_EFFECTS;
+    const now = options.now ?? Date.now;
+    validateWorkerOptions(workerId, maxEffects);
+    const workerOptions = {
+        storage: options.storage,
+        gateway: options.gateway,
+        workerId,
+        maxEffects,
+        now: now(),
+        ...(options.writerRole === undefined ? {} : { writerRole: options.writerRole }),
+        ...(options.writerLeaseDurationMs === undefined
+            ? {}
+            : { writerLeaseDurationMs: options.writerLeaseDurationMs }),
+        ...(options.effectLeaseDurationMs === undefined
+            ? {}
+            : { effectLeaseDurationMs: options.effectLeaseDurationMs }),
+        ...(options.makeRepairReplan === undefined
+            ? {}
+            : { makeRepairReplan: options.makeRepairReplan }),
+        ...(options.onTiming === undefined ? {} : { onTiming: options.onTiming }),
+    };
+    return new SyncEffectWorkerSupervisor({
+        ...options,
+        now,
+        runPass: () => runSyncEffectWorkerWithAdapter({ ...workerOptions, now: now() }),
+    });
+}
+function hasImmediateProgress(report) {
+    return report.claimed > 0;
+}
+function isWorkerPassIdle(report) {
+    return report.selected === 0 &&
+        report.claimed === 0 &&
+        report.expiredLeasesRecovered === 0 &&
+        report.deferred === 0 &&
+        report.requeued === 0 &&
+        report.replanned === 0;
+}
+function nextBackoff(current, maximum) {
+    return Math.min(maximum, current * 2);
+}
+function withJitter(durationMs, random) {
+    const sample = random();
+    const normalized = Number.isFinite(sample) ? Math.max(0, Math.min(1, sample)) : 0;
+    return durationMs + Math.floor(normalized * DEFAULT_JITTER_MAX_MS);
+}
+function validateWorkerOptions(workerId, maxEffects) {
+    if (workerId.length === NON_NEGATIVE_SAFE_INTEGER_MINIMUM) {
+        throw new RangeError("sync effect supervisor worker ID is required");
+    }
+    if (!Number.isSafeInteger(maxEffects) || maxEffects < POSITIVE_SAFE_INTEGER_MINIMUM) {
+        throw new RangeError("sync effect supervisor maxEffects must be a positive safe integer");
+    }
+}
+function requirePositiveSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < POSITIVE_SAFE_INTEGER_MINIMUM) {
+        throw new RangeError(name + " must be a positive safe integer");
+    }
+    return value;
+}
+function defaultWait(durationMs) {
+    return new Promise((resolve) => setTimeout(resolve, durationMs));
+}
+//# sourceMappingURL=SyncEffectSupervisor.js.map

package/dist/application/sync/outbound/effects/SyncEffectSupervisor.js.map

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

package/dist/application/sync/outbound/effects/SyncEffectWorker.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Fenced outbox worker for projection effects.
+ *
+ * It owns only claim/result transitions.  Canonical state and any repair
+ * replan payload are supplied by the writer boundary; the gateway is never
+ * allowed to choose a winner or silently retry a response-lost write.
+ */
+import { type Presence } from "../../../../domain/index.js";
+import { type ApplyResultOptions, type ClaimEffectOptions, type ClaimLeaseOptions, type ClaimResult, type FencingContext, type NewEffect, type PendingEffect, type RetryClaimedEffectOptions, type WriterLease, type WriterLeaseClaimResult } from "../../../../infrastructure/storage/index.js";
+import type { SqlStorageAdapter } from "../../../../adapter/persistence/contracts/sql.js";
+import { type SyncEffectPostcondition, type SyncGatewayEffect, type SyncGatewayEffectResult, type SyncEffectWorkerGateway, type SyncEffectWorkerFullGateway } from "../../gateway/syncGateway.js";
+import { type SyncTimingSink } from "../../telemetry/syncTiming.js";
+/** An effect plus evidence supplied to a writer-owned system-repair replanner. */
+export interface RepairReplanRequest {
+    readonly effect: PendingEffect;
+    readonly gatewayResult: Presence<SyncGatewayEffectResult>;
+    readonly postcondition: Presence<SyncEffectPostcondition>;
+}
+/** Callback that creates a fresh effect without mutating the old evidence. */
+export type RepairReplanFactory = (request: RepairReplanRequest) => Presence<NewEffect>;
+/** Shared construction options for a bounded effect-worker pass. */
+export interface SyncEffectWorkerBaseOptions {
+    readonly gateway: SyncEffectWorkerGateway;
+    readonly workerId: string;
+    readonly now: number;
+    readonly maxEffects: number;
+    readonly writerRole?: string;
+    readonly writerLeaseDurationMs?: number;
+    readonly effectLeaseDurationMs?: number;
+    readonly makeRepairReplan?: RepairReplanFactory;
+    /** Optional diagnostics sink for worker and gateway phases. */
+    readonly onTiming?: SyncTimingSink;
+}
+export type SyncEffectWorkerFullOptions = Omit<SyncEffectWorkerBaseOptions, "gateway"> & {
+    readonly gateway: SyncEffectWorkerFullGateway;
+};
+/** Construction options for a worker running through an async storage adapter. */
+export interface SyncEffectWorkerWithAdapterOptions extends SyncEffectWorkerBaseOptions {
+    readonly storage: SqlStorageAdapter;
+}
+/** Counters that make partial results and recovery visible to callers. */
+export interface SyncEffectWorkerReport {
+    readonly lease: Presence<WriterLease>;
+    readonly expiredLeasesRecovered: number;
+    readonly selected: number;
+    readonly claimed: number;
+    readonly applied: number;
+    readonly blockedCandidate: number;
+    readonly superseded: number;
+    readonly conflicted: number;
+    readonly failed: number;
+    readonly deferred: number;
+    readonly requeued: number;
+    readonly replanned: number;
+    readonly responseLossRecovered: number;
+}
+export interface ClaimedEffect {
+    readonly pending: PendingEffect;
+    readonly claimToken: string;
+    readonly gatewayEffect: Presence<SyncGatewayEffect>;
+    readonly invalidPayloadError: Presence<string>;
+}
+/** Persistence operations used by the shared effect-worker state machine. */
+export interface EffectWorkerStorage {
+    claimWriterLease(options: ClaimLeaseOptions): Promise<WriterLeaseClaimResult>;
+    recoverExpiredLeases(fence: FencingContext): Promise<number>;
+    listReadyEffects(limit: number): Promise<readonly PendingEffect[]>;
+    claimEffect(options: ClaimEffectOptions): Promise<ClaimResult>;
+    applyEffectResult(options: ApplyResultOptions): Promise<boolean>;
+    releaseUnprocessedEffect(options: Pick<FencingContext, "role" | "writerEpoch" | "fencingToken" | "now"> & {
+        readonly effectId: string;
+        readonly claimToken: string;
+    }): Promise<boolean>;
+    retryClaimedEffect(options: RetryClaimedEffectOptions): Promise<boolean>;
+    supersedeAndReplan(fence: FencingContext, oldEffectId: string, newEffect: NewEffect): Promise<void>;
+    isUserInputCandidateBlocked(item: ClaimedEffect): Promise<boolean>;
+}
+/**
+ * Processes effects through an adapter-owned SQL connection.
+ *
+ * This is the MikroORM-compatible worker entrypoint. It never opens the
+ * legacy synchronous `node:sqlite` database beside the ORM connection.
+ */
+export declare function runSyncEffectWorkerWithAdapter(options: SyncEffectWorkerWithAdapterOptions): Promise<SyncEffectWorkerReport>;
+export interface MutableReport {
+    lease: Presence<WriterLease>;
+    expiredLeasesRecovered: number;
+    selected: number;
+    claimed: number;
+    applied: number;
+    blockedCandidate: number;
+    superseded: number;
+    conflicted: number;
+    failed: number;
+    deferred: number;
+    requeued: number;
+    replanned: number;
+    responseLossRecovered: number;
+}
+//# sourceMappingURL=SyncEffectWorker.d.ts.map

package/dist/application/sync/outbound/effects/SyncEffectWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncEffectWorker.d.ts","sourceRoot":"","sources":["../../../../../src/application/sync/outbound/effects/SyncEffectWorker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAUL,KAAK,QAAQ,EACd,MAAM,6BAA6B,CAAC;AAOrC,OAAO,EAUL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,yBAAyB,EAC9B,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC5B,MAAM,6CAA6C,CAAC;AAMrD,OAAO,KAAK,EAAe,iBAAiB,EAAE,MAAM,kDAAkD,CAAC;AACvG,OAAO,EAKL,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAE5B,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EACjC,MAAM,8BAA8B,CAAC;AAStC,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,+BAA+B,CAAC;AAsDvC,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,uBAAuB,CAAC,CAAC;IAC1D,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,uBAAuB,CAAC,CAAC;CAC3D;AAED,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,mBAAmB,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAC;AAExF,oEAAoE;AACpE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,mBAAmB,CAAC;IAChD,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;CACpC;AAED,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAAC,2BAA2B,EAAE,SAAS,CAAC,GAAG;IACvF,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC;CAC/C,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,kCAAmC,SAAQ,2BAA2B;IACrF,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACtC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IACpD,QAAQ,CAAC,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAChD;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC9E,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;IACnE,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/D,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,wBAAwB,CACtB,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,KAAK,CAAC,GAAG;QAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,GACA,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,CAChB,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,2BAA2B,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpE;AAED;;;;;GAKG;AACH,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,kCAAkC,GAC1C,OAAO,CAAC,sBAAsB,CAAC,CAEjC;AA+UD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC7B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;CAC/B"}