@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/client/lifetime.d.ts

@@ -0,0 +1,35 @@
+import type * as Context from "effect/Context";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { type ConnectError, type ConnectionFailure } from "#sdk/errors";
+import type { ClientLogger } from "../logging.js";
+/** Short readable duration for log messages */
+export declare function formatDuration(milliseconds: number): string;
+/** Run every shard loop until one fails permanently, bounded by the group startup deadline until startup completes.
+ * Defects from losing loops, such as socket cleanup failures, are kept in the group's cause
+ */
+export declare function superviseShards<Shard extends {
+    readonly shardId: number;
+}>(options: {
+    readonly shards: readonly Shard[];
+    readonly startupTimeoutMs: number;
+    /** Wrap each shard failure with its shard ID, as configured sharding requires */
+    readonly attributeShards: boolean;
+    /** Completed once every shard is ready */
+    readonly startup: Deferred.Deferred<void, ConnectError>;
+    readonly runShard: (shard: Shard, deadline: number) => Effect.Effect<unknown, ConnectionFailure>;
+}): Effect.Effect<void, ConnectionFailure, never>;
+/** Keep only defects from a set of cleanup exits, as one cause */
+export declare function defectsOnly(exits: readonly Exit.Exit<unknown, unknown>[]): Exit.Exit<void>;
+/** Run service cleanups concurrently and fail with every reason any of them produced */
+export declare function closeAll(services: readonly Effect.Effect<Exit.Exit<unknown, never>>[]): Effect.Effect<void>;
+/** Log the start of shutdown for a client that connected or ran */
+export declare function logShutdownStart(logging: ClientLogger, context: Context.Context<never>, everStarted: boolean, reason: string | undefined): void;
+/** Log each cleanup failure, flush deduplicated records and log completion for a client that connected or ran */
+export declare function logShutdownEnd(logging: ClientLogger, context: Context.Context<never>, options: {
+    readonly everStarted: boolean;
+    readonly startedAt: number;
+    readonly services: Exit.Exit<void, unknown>;
+}): void;
+//# sourceMappingURL=lifetime.d.ts.map

package/dist/internal/client/lifetime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifetime.d.ts","sourceRoot":"","sources":["../../../src/internal/client/lifetime.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AACnC,OAAO,EAAgD,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAGrH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAI3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,SAAS;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE;IACjF,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,iFAAiF;IACjF,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;IACvD,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAA;CACnG,iDA+CA;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAK1F;AAED,wFAAwF;AACxF,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAO3G;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,CAC5B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAC/B,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,MAAM,GAAG,SAAS,QAY7B;AAED,iHAAiH;AACjH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAC/B,OAAO,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;CAAE,QAqCtH"}

package/dist/internal/client/lifetime.js

@@ -0,0 +1,109 @@
+/**
+ * Client lifetime helpers: The shard group under one startup deadline, service cleanup that keeps every defect, and
+ * shutdown records.
+ * Invariant: The group awaits every assigned shard for initial readiness under one deadline, a healthy shard's work
+ * stays independent of another shard's transient gap, and terminal supervision preserves sibling cleanup failures.
+ * Shutdown shares cleanup across callers and reports completion only after owned resources are released.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import * as Cause from "effect/Cause";
+import * as Clock from "effect/Clock";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { ConnectionTimeoutError, ShardConnectionError } from "#sdk/errors";
+import { nowMs } from "../clock.js";
+import { mapFailureCause, withDeadline } from "../effect-failures.js";
+/** Short readable duration for log messages */
+export function formatDuration(milliseconds) {
+    if (milliseconds < 1_000)
+        return `${Math.max(0, Math.round(milliseconds))} ms`;
+    if (milliseconds < 60_000)
+        return `${(milliseconds / 1_000).toFixed(1)} s`;
+    return `${Math.floor(milliseconds / 60_000)} min ${Math.round((milliseconds % 60_000) / 1_000)} s`;
+}
+/** Run every shard loop until one fails permanently, bounded by the group startup deadline until startup completes.
+ * Defects from losing loops, such as socket cleanup failures, are kept in the group's cause
+ */
+export function superviseShards(options) {
+    const { shards, startupTimeoutMs, attributeShards, startup, runShard } = options;
+    return Effect.suspend(() => {
+        const exits = [];
+        const sessions = Effect.gen(function* () {
+            const clock = yield* Clock.Clock;
+            const deadline = nowMs(clock) + startupTimeoutMs;
+            return yield* Effect.forEach(shards, (shard) => runShard(shard, deadline).pipe(mapFailureCause((failure) => attributeShards && !(failure instanceof ShardConnectionError)
+                ? new ShardConnectionError(shard.shardId, failure)
+                : failure), Effect.onExit((exit) => Effect.sync(() => {
+                exits.push(exit);
+            }))), { concurrency: "unbounded", discard: true });
+        });
+        const startupGuard = Deferred.await(startup).pipe(
+        // allow-silent: The startup outcome itself is observed through the startup deferred
+        Effect.ignore, withDeadline(startupTimeoutMs, () => new ConnectionTimeoutError(startupTimeoutMs)), Effect.andThen(Effect.never));
+        return Effect.raceFirst(sessions, startupGuard).pipe(
+        // A losing session may defect during socket cleanup. Keep those causes across the race boundary
+        Effect.onExit((outcome) => {
+            const missing = exits.flatMap((exit) => Exit.isFailure(exit)
+                ? exit.cause.reasons.filter((reason) => reason._tag !== "Interrupt" &&
+                    (!Exit.isFailure(outcome) || !outcome.cause.reasons.includes(reason)))
+                : []);
+            return missing.length ? Effect.failCause(Cause.fromReasons(missing)) : Effect.void;
+        }));
+    });
+}
+/** Keep only defects from a set of cleanup exits, as one cause */
+export function defectsOnly(exits) {
+    const reasons = exits.flatMap((exit) => Exit.isFailure(exit) ? exit.cause.reasons.filter((reason) => reason._tag === "Die") : []);
+    return reasons.length ? Exit.failCause(Cause.fromReasons(reasons)) : Exit.void;
+}
+/** Run service cleanups concurrently and fail with every reason any of them produced */
+export function closeAll(services) {
+    return Effect.all(services, { concurrency: "unbounded" }).pipe(Effect.flatMap((exits) => {
+        const reasons = exits.flatMap((exit) => (Exit.isFailure(exit) ? exit.cause.reasons : []));
+        return reasons.length ? Effect.failCause(Cause.fromReasons(reasons)) : Effect.void;
+    }));
+}
+/** Log the start of shutdown for a client that connected or ran */
+export function logShutdownStart(logging, context, everStarted, reason) {
+    if (!everStarted)
+        return;
+    logging.log({
+        level: "info",
+        category: "lifecycle",
+        code: "lifecycle.shutdown",
+        message: reason === undefined ? "Shutting down" : `Shutting down because ${reason}`,
+    }, context);
+}
+/** Log each cleanup failure, flush deduplicated records and log completion for a client that connected or ran */
+export function logShutdownEnd(logging, context, options) {
+    const { everStarted, startedAt, services } = options;
+    const durationMs = Date.now() - startedAt;
+    let failedSteps = 0;
+    if (Exit.isFailure(services)) {
+        const faults = services.cause.reasons.filter((reason) => reason._tag !== "Interrupt");
+        failedSteps = Math.max(1, faults.length);
+        logging.count("cleanupFailures", failedSteps);
+        faults.forEach((reason, index) => logging.log({
+            level: "error",
+            category: "lifecycle",
+            code: "lifecycle.cleanupFailed",
+            message: `Cleanup step ${index + 1} of ${faults.length} failed during shutdown`,
+            error: reason._tag === "Fail" ? reason.error : reason._tag === "Die" ? reason.defect : undefined,
+            cause: Cause.fromReasons([reason]),
+        }, context));
+    }
+    logging.flush(context);
+    if (!everStarted)
+        return;
+    logging.log({
+        level: "info",
+        category: "lifecycle",
+        code: "lifecycle.shutdownComplete",
+        message: Exit.isFailure(services)
+            ? `Shutdown finished in ${formatDuration(durationMs)}, but ${failedSteps} cleanup step${failedSteps === 1 ? "" : "s"} failed`
+            : `Shutdown complete in ${formatDuration(durationMs)}`,
+        durationMs,
+    }, context);
+}
+//# sourceMappingURL=lifetime.js.map

package/dist/internal/client/lifetime.js.map

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

package/dist/internal/client/shard-loop.d.ts

@@ -0,0 +1,93 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import type { ConnectionState } from "#sdk/client";
+import { type ConnectError, type ConnectionFailure } from "#sdk/errors";
+import type { MessageCore } from "#sdk/messages";
+import type { SessionStore } from "#sdk/sharding";
+import type { Configuration } from "../configuration.js";
+import type { CountOwner } from "../counts.js";
+import type { EventBus } from "../events.js";
+import { AttemptFailure, type Session } from "../gateway.js";
+import { type InstanceResolver } from "../instance.js";
+import type { ClientLogger } from "../logging.js";
+import type { MemberChunkOwner } from "../member-chunks.js";
+import type { PresenceOwner } from "../presence.js";
+import type { SocketFactory } from "../transport/index.js";
+import type { IdentifyFields, SubmitFailure } from "../gateway/commands.js";
+import { type ShardPlan } from "../sharding.js";
+import { type ClientCaches } from "./intake.js";
+/** Observable per-shard state, owned by the client and updated by this loop */
+export interface ShardRuntime {
+    readonly shardId: number;
+    state: ConnectionState;
+    latency: number | null;
+    recovery: {
+        phase: "startup" | "recovery";
+        attempt: number;
+        retryDelayMs: number | null;
+    } | null;
+    session: Session;
+    /** Paced gateway.send path of the current ready session, or undefined while the shard is not ready */
+    submit: ((op: number, d: unknown, sent?: () => void) => Effect.Effect<void, SubmitFailure>) | undefined;
+    /** Gateway URL this shard's sessions use, known after discovery and recorded in saved session snapshots */
+    gatewayUrl: string | undefined;
+}
+/** What the shard loop needs from its client */
+export interface ShardLoopHost<M extends MessageCore> {
+    readonly logging: ClientLogger;
+    readonly instance: InstanceResolver;
+    readonly caches: ClientCaches<M>;
+    readonly events: EventBus<M>;
+    readonly presence: PresenceOwner;
+    readonly counts: CountOwner;
+    readonly memberChunks: MemberChunkOwner;
+    readonly sockets: SocketFactory;
+    /** The client's aggregate state */
+    readonly state: () => ConnectionState;
+    /** Record a shard transition and recompute the client state */
+    readonly setShardState: (shard: ShardRuntime, state: ConnectionState) => void;
+    /** Release a shard's guild-scoped cache entries once an established or restored session needs a new session, and
+     * again when that session is ready, because partial replay and reads stored during the outage may be stale
+     */
+    readonly newSession?: (shardId: number) => void;
+    /** Pace a fresh Identify for this shard, or undefined when Identify needs no coordination */
+    readonly identify: ((shardId: number, send: () => void) => Effect.Effect<void, AttemptFailure>) | undefined;
+    /** Optional Identify fields, computed when this shard sends Identify */
+    readonly identifyFields: (shardId: number) => IdentifyFields;
+    /** Configured session persistence, loaded once at the first attempt */
+    readonly sessions: SessionStore | undefined;
+    /** Whether shutdown will save this shard's session after its socket closes */
+    readonly saveSessionOnClose: (shardId: number) => boolean;
+    /** Observe each accepted READY body, which carries the bot's own user and the shard's communities */
+    readonly readyUser?: (body: unknown, shardId: number) => void;
+    /**
+     * Offer a 4011 (sharding required) closure to automatic sharding. True means the client moves every shard to a
+     * larger plan, so this loop ends without logging a permanent failure. A string explains why it does not
+     */
+    readonly reshard?: (shardId: number) => true | string;
+    /** Note that this shard resumed a session loaded from the session store, so its guild caches start empty */
+    readonly restored?: (shardId: number) => void;
+    /** Note that this shard resumed a session, after Fluxer replayed the missed dispatches it retained */
+    readonly resumed?: (shardId: number) => void;
+}
+/** One loop's inputs */
+export interface ShardLoopOptions<M extends MessageCore> {
+    readonly host: ShardLoopHost<M>;
+    readonly configuration: Configuration<M>;
+    /** Completed once every assigned shard is ready */
+    readonly startup: Deferred.Deferred<void, ConnectError>;
+    readonly shard: ShardRuntime;
+    /** The client's known shard plan */
+    readonly plan: ShardPlan;
+    /** Logical group startup deadline, including Identify waits */
+    readonly deadline: number;
+    /** The group's startup budget that the deadline was derived from, reported when startup times out */
+    readonly startupTimeoutMs: number;
+    /** Whether the group was ready before this loop started, as after a move to a larger plan, so failures recover */
+    readonly established?: boolean;
+    /** Whether to offer the session store's snapshot, default true. A move to a larger plan starts new sessions */
+    readonly loadSessions?: boolean;
+}
+/** Run one shard until its connection fails permanently. The loop never succeeds */
+export declare function runShardLoop<M extends MessageCore>(options: ShardLoopOptions<M>): Effect.Effect<never, ConnectionFailure, never>;
+//# sourceMappingURL=shard-loop.d.ts.map

package/dist/internal/client/shard-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-loop.d.ts","sourceRoot":"","sources":["../../../src/internal/client/shard-loop.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAE3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAKvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAKH,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACzB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAE5C,OAAO,EAAE,cAAc,EAAqB,KAAK,OAAO,EAAE,MAAM,eAAe,CAAA;AAC/E,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAClE,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,eAAe,CAAA;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3E,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE9D,OAAO,EAA+C,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAI5F,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,KAAK,EAAE,eAAe,CAAA;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,QAAQ,EAAE;QAAE,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;IAChG,OAAO,EAAE,OAAO,CAAA;IAChB,sGAAsG;IACtG,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,GAAG,SAAS,CAAA;IACvG,2GAA2G;IAC3G,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACjC;AAED,gDAAgD;AAChD,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,WAAW;IAChD,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,eAAe,CAAA;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;IAC7E;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/C,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,GAAG,SAAS,CAAA;IAC3G,wEAAwE;IACxE,QAAQ,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,cAAc,CAAA;IAC5D,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAA;IAC3C,8EAA8E;IAC9E,QAAQ,CAAC,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAA;IACzD,qGAAqG;IACrG,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7D;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAA;IACrD,4GAA4G;IAC5G,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7C,sGAAsG;IACtG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/C;AAED,wBAAwB;AACxB,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,WAAW;IACnD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IACxC,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;IACvD,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,qGAAqG;IACrG,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,kHAAkH;IAClH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,+GAA+G;IAC/G,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAClC;AAwFD,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,kDAuX/E"}