@optimystic/db-p2p 0.13.5 → 0.14.0

package/dist/src/reactivity/push-state-gossip.js

@@ -0,0 +1,231 @@
+/**
+ * Reactivity — `PushState` intra-cohort gossip driver (`docs/reactivity.md` §Replay window,
+ * §Forwarder-cohort state).
+ *
+ * The forwarder-cohort replay ring + dedupe window are the substrate that makes the doc's "**any** cohort
+ * member — not just the primary — can serve a replay/backfill" property real: a member that missed an
+ * origin dial still ends up holding the entry, so a backfill (12.4) survives a primary failover. The
+ * db-core {@link PushState} already owns the codec ({@link encodePushStateGossipV1} /
+ * {@link decodePushStateGossipV1}, {@link PushState.serializeGossip} / {@link PushState.mergeGossip}); this
+ * driver is the **replication** layer that actually broadcasts and merges that state over libp2p on a
+ * periodic cadence — the backstop to the live fan-out ({@link import("./forwarder-host.js")}).
+ *
+ * **Transport reuse.** Rather than stand up a new transport, this rides the cohort gossip transport's
+ * {@link import("../cohort-topic/cohort-gossip-transport.js").FretCohortGossipTransport.broadcastOver}
+ * seam — the same one the promote-notice broadcast reuses — so the cohort peer resolution, self-exclusion,
+ * and per-peer failure swallowing are shared. Frames ride the dedicated
+ * {@link PROTOCOL_REACTIVITY_PUSH_STATE_GOSSIP} (one-way), fanned to the FRET-assembled cohort around each
+ * served collection's cohort coord. Inbound frames arrive on this node's `push-state-gossip` protocol
+ * handler (registered by the node-wiring ticket) and route to {@link ReactivityPushStateGossipDriver.deliver}.
+ *
+ * **Cadence.** Its own unref'd timer (parallel to the cohort host's single `setInterval`), reusing
+ * {@link DEFAULT_GOSSIP_INTERVAL_MS} and the host's re-entrancy / `stopped` / `unref` discipline verbatim.
+ * Reactivity collections are not 1:1 with the host's per-`CoordEngine` tick and the forwarder host owns the
+ * live {@link PushState} set, so a separate timer is the clean seam now; a future consolidation could fold
+ * this into the host tick via a hook, but a separate unref'd timer cannot pin an idle process.
+ *
+ * The **driver** touches neither the libp2p node assembly nor FRET cohort assembly — it depends only on the
+ * `broadcastOver` seam + db-core codec, so it is unit-testable with a fake transport and real `PushState`s.
+ * The co-located {@link registerPushStateGossipHandler} (the inbound protocol-handler registration) does
+ * bind libp2p, mirroring {@link import("./notify-transport.js").registerNotifyHandler} — the driver class
+ * stays pure; only that one helper reaches the node.
+ */
+import { encodePushStateGossipV1, decodePushStateGossipV1, } from "@optimystic/db-core";
+import { readAllBounded } from "p2p-fret";
+import { DEFAULT_GOSSIP_INTERVAL_MS } from "../cohort-topic/cohort-gossip-driver.js";
+import { DEFAULT_STREAM_MAX_BYTES } from "../cohort-topic/stream-util.js";
+import { PROTOCOL_REACTIVITY_PUSH_STATE_GOSSIP } from "./protocols.js";
+import { createLogger } from "../logger.js";
+const log = createLogger("reactivity-push-state-gossip");
+/** Encode a probe frame with no size ceiling so the driver can measure its true length before bounding. */
+const NO_FRAME_LIMIT = Number.MAX_SAFE_INTEGER;
+/**
+ * Drives {@link PushState} convergence across a forwarder cohort: each round it broadcasts every live
+ * collection's serialized push-state to the cohort (clipped to the frame bound), and each inbound frame is
+ * gated, resolved to the owning collection, and merged. Build one per node and bind its inbound
+ * {@link ReactivityPushStateGossipDriver.deliver} to the `push-state-gossip` protocol handler.
+ */
+export class ReactivityPushStateGossipDriver {
+    gossipTransport;
+    liveCollections;
+    pushStateForGossip;
+    isCohortMember;
+    intervalMs;
+    maxBytes;
+    onTruncate;
+    timer;
+    stopped = false;
+    /** Re-entrancy guard mirroring the host tick: skip a round that overlaps a slow prior one. */
+    rounding = false;
+    constructor(deps) {
+        this.gossipTransport = deps.gossipTransport;
+        this.liveCollections = deps.liveCollections;
+        this.pushStateForGossip = deps.pushStateForGossip;
+        this.isCohortMember = deps.isCohortMember;
+        this.intervalMs = deps.intervalMs ?? DEFAULT_GOSSIP_INTERVAL_MS;
+        this.maxBytes = deps.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+        this.onTruncate = deps.onTruncate;
+    }
+    /** Begin the unref'd cadence timer. Idempotent; a no-op once {@link stop} has run. */
+    start() {
+        if (this.stopped || this.timer !== undefined) {
+            return;
+        }
+        const timer = setInterval(() => {
+            this.round();
+        }, this.intervalMs);
+        // Node timers keep the event loop alive; push-state gossip must not pin a process that is otherwise idle.
+        timer.unref?.();
+        this.timer = timer;
+    }
+    /**
+     * One round: broadcast each live collection's serialized {@link PushState} to its cohort, clipped to the
+     * frame bound. Per-collection isolated (one collection's fault never skips the rest) and `stopped`-gated
+     * mid-loop, mirroring the host tick.
+     */
+    round() {
+        if (this.stopped || this.rounding) {
+            return;
+        }
+        this.rounding = true;
+        try {
+            for (const { pushState, cohortCoord } of this.liveCollections()) {
+                if (this.stopped) {
+                    break;
+                }
+                try {
+                    this.broadcastOne(pushState, cohortCoord);
+                }
+                catch (err) {
+                    log("push-state gossip round failed for a collection (isolated): %o", err);
+                }
+            }
+        }
+        finally {
+            this.rounding = false;
+        }
+    }
+    /**
+     * Inbound handler body: decode → membership gate → resolve owning collection → merge. Never throws on a
+     * bad frame (a malformed/forged/foreign frame is logged and dropped), so a stream handler can call it
+     * directly. `mergeGossip` independently guards a collection/topic mismatch, so the resolve step is a fast
+     * pre-filter, not the only line of defense.
+     */
+    deliver(fromPeerId, frame) {
+        let g;
+        try {
+            g = decodePushStateGossipV1(frame, this.maxBytes);
+        }
+        catch (err) {
+            log("dropped an undecodable push-state gossip frame from %s: %o", fromPeerId, err);
+            return;
+        }
+        if (this.isCohortMember !== undefined && !this.isCohortMember(fromPeerId, g)) {
+            log("dropped push-state gossip from non-member %s for collection=%s topic=%s", fromPeerId, g.collectionId, g.topicId);
+            return;
+        }
+        const pushState = this.pushStateForGossip(g);
+        if (pushState === undefined) {
+            return; // gossip for a collection this node does not serve — nothing to merge into.
+        }
+        try {
+            pushState.mergeGossip(g);
+        }
+        catch (err) {
+            log("push-state mergeGossip threw (isolated) for collection=%s: %o", g.collectionId, err);
+        }
+    }
+    /** Stop the cadence: short-circuit any in-flight/future round and clear the timer. */
+    stop() {
+        this.stopped = true;
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /** Serialize one collection, clip to the frame bound, and broadcast to its cohort. */
+    broadcastOne(pushState, cohortCoord) {
+        const g = pushState.serializeGossip();
+        const { frame, kept, total } = this.boundedFrame(g);
+        if (kept < total) {
+            // "No silent caps" (AGENTS.md): a clipped ring is always surfaced. Convergence still completes —
+            // each entry replicates while it is within the most-recent window across successive rounds, and
+            // `mergeGossip` unions ring entries so a partial frame loses nothing already held by a peer.
+            log("push-state gossip frame clipped for collection=%s: kept %d/%d most-recent replay entries to fit maxBytes=%d", g.collectionId, kept, total, this.maxBytes);
+            this.onTruncate?.({ collectionId: g.collectionId, topicId: g.topicId, kept, total, frameBytes: frame.length, maxBytes: this.maxBytes });
+        }
+        this.gossipTransport.broadcastOver(PROTOCOL_REACTIVITY_PUSH_STATE_GOSSIP, cohortCoord, frame);
+    }
+    /**
+     * Build the broadcast frame for one serialized push-state, kept within {@link maxBytes}.
+     *
+     * The whole replay ring (`W` up to 256 full `NotificationV1`s) can exceed the frame bound. When it does,
+     * keep the full (small) dedupe window and the **most-recent-N** replay entries that fit — sliced from the
+     * high-revision end, since a lagging subscriber backfills the newest gap first and older revisions roll
+     * to the parent checkpoint anyway. Frame size is monotone in the entry count, so binary-search the
+     * high-water N rather than re-encoding per entry.
+     */
+    boundedFrame(g) {
+        const total = g.replayBuffer.entries.length;
+        const full = encodePushStateGossipV1(g, NO_FRAME_LIMIT);
+        if (full.length <= this.maxBytes) {
+            return { frame: full, kept: total, total };
+        }
+        // Largest most-recent-N replay slice whose frame still fits. `encodeSlice(g, 0)` (dedupe window only)
+        // is the floor we ship if even that overruns the bound (pathological — the dedupe window is small).
+        let lo = 0;
+        let hi = total;
+        let bestN = 0;
+        let bestFrame = this.encodeSlice(g, 0);
+        while (lo <= hi) {
+            const mid = (lo + hi) >>> 1;
+            const frame = this.encodeSlice(g, mid);
+            if (frame.length <= this.maxBytes) {
+                bestN = mid;
+                bestFrame = frame;
+                lo = mid + 1;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        return { frame: bestFrame, kept: bestN, total };
+    }
+    /** Encode `g` with only its most-recent `keep` replay entries retained (the full dedupe window is kept). */
+    encodeSlice(g, keep) {
+        const entries = g.replayBuffer.entries;
+        const kept = keep >= entries.length ? entries : entries.slice(entries.length - keep);
+        const sliced = {
+            ...g,
+            replayBuffer: { capacity: g.replayBuffer.capacity, entries: kept },
+        };
+        return encodePushStateGossipV1(sliced, NO_FRAME_LIMIT);
+    }
+}
+/**
+ * Register the inbound push-state-gossip protocol handler: read one bounded frame and hand it to
+ * {@link ReactivityPushStateGossipDriver.deliver} (which decodes, membership-gates, and merges), then close.
+ * One-way — no reply frame, matching the cohort-topic gossip handlers. A read error aborts the stream and
+ * {@link ReactivityPushStateGossipDriver.deliver} swallows a decode/forge/foreign failure, so the handler
+ * never throws on the stream. Mirrors {@link import("./notify-transport.js").registerNotifyHandler}.
+ */
+export function registerPushStateGossipHandler(node, protocol, driver, maxBytes = DEFAULT_STREAM_MAX_BYTES) {
+    void node.handle(protocol, (stream, connection) => {
+        void (async () => {
+            try {
+                const frame = await readAllBounded(stream, maxBytes);
+                driver.deliver(connection.remotePeer.toString(), frame);
+                await stream.close();
+            }
+            catch {
+                try {
+                    stream.abort(new Error("reactivity push-state gossip stream handler error"));
+                }
+                catch {
+                    /* already aborted */
+                }
+            }
+        })();
+    });
+}
+//# sourceMappingURL=push-state-gossip.js.map

package/dist/src/reactivity/push-state-gossip.js.map

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

package/dist/src/reactivity/recover-transport.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Reactivity recover RPC transport — the live libp2p backfill/resume recovery protocol
+ * (`docs/reactivity.md` §Backfill RPC, §Resume).
+ *
+ * This is the **pull** companion to the one-way notify transport: a subscriber that detected a gap (or
+ * woke from sleep) asks a serving cohort member "what did I miss?" and is brought current. The protocol is
+ * **request-reply** — one {@link RecoverRequestV1} frame out, one {@link RecoverReplyV1} frame back over a
+ * single stream — so it rides the cohort-topic {@link requestResponse} / {@link handleRequestResponse}
+ * helpers (NOT the one-way notify helpers, which would desync the dialer).
+ *
+ * Two pieces live here, both decoupled from the live node assembly so they unit-test in isolation:
+ *
+ *  - {@link Libp2pReactivityRecoverTransport} — the **outbound** side. Supplies the two db-core seams
+ *    (`BackfillTransport` / `ResumeTransport`) against one node: pick a target (sticky cohort-hint primary
+ *    first for the one-RT happy path, else a cohort-walk member), frame the request, exchange it over the
+ *    recover protocol, and return the inner reply. The wire exchange is injected as a {@link RecoverDialer}
+ *    so the target-selection + framing logic tests without a real socket; {@link createLibp2pRecoverDialer}
+ *    is the production libp2p-backed implementation.
+ *  - {@link createRecoverRequestHandler} / {@link registerRecoverHandler} — the **inbound** serve handler.
+ *    Decode (bounded) → verify the request's peer-key signature against the dialing peer → reject a
+ *    replay/stale request → resolve the live `PushState` → `serveBackfill` / `serveResume` → reply. Any
+ *    failure produces **no reply** (the stream aborts) rather than throwing out of the handler.
+ *
+ * ## Dial-target encoding bridge (load-bearing)
+ *
+ * The sticky {@link import("@optimystic/db-core").ReactivityCohortHint}`.primary` is **base64url of
+ * cohort member-id bytes** (`base64url(utf8(peerIdString))`), per its db-core JSDoc, whereas
+ * {@link requestResponse} needs a `peerIdFromString`-parseable peer-id **string**. Feeding the raw
+ * base64url straight to `peerIdFromString` throws → the dial is swallowed → recovery silently never
+ * reaches the cohort. {@link decodeCohortHintTarget} pins the conversion
+ * (`bytesToPeerIdString(b64urlToBytes(primary))`); the `resolveCohort` walk, by contrast, already returns
+ * peer-id strings (the cohort-topic `CohortPeerResolver` space) and is used as-is.
+ */
+import type { Libp2p } from "libp2p";
+import type { PeerId, PrivateKey } from "@libp2p/interface";
+import { type BackfillSignable, type ResumeSignable, type BackfillTransport, type PushState, type StickyCohortHintCache, type CorrelationReplayGuard, type RotationRedirectV1 } from "@optimystic/db-core";
+import type { ResumeTransport } from "./subscription-manager.js";
+/**
+ * Decode a sticky-cohort-hint `primary` (base64url of member-id bytes = `base64url(utf8(peerIdString))`)
+ * back to the dialable peer-id string. The inverse trap of feeding the raw value to `peerIdFromString`
+ * (which expects a peer-id string, not base64url-of-its-utf8) — pinned by the dial-target encoding test.
+ */
+export declare function decodeCohortHintTarget(primary: string): string;
+/**
+ * The synchronous request-signing seam the production subscribe factory feeds a
+ * {@link import("./subscription-manager.js").ReactivitySubscriptionManager}: it builds a
+ * {@link BackfillV1} / {@link ResumeV1} signature (base64url) over the unsigned image.
+ */
+export interface RecoverRequestSigners {
+    /** Sign a {@link BackfillV1} over {@link backfillSigningPayload} of its unsigned image. */
+    readonly signBackfill: (unsigned: BackfillSignable) => string;
+    /** Sign a {@link ResumeV1} over {@link resumeSigningPayload} of its unsigned image. */
+    readonly signResume: (unsigned: ResumeSignable) => string;
+}
+/**
+ * Build the subscriber's recover request signers from the node's libp2p Ed25519 private key.
+ *
+ * This resolves the recover wiring's one design point: the subscription-manager `signBackfill` /
+ * `signResume` ports are **synchronous** (`(unsigned) => string`) — the db-core driver builds the
+ * unsigned image internally, so a pre-signed value is impossible — but libp2p `PrivateKey.sign` is
+ * **async**. Rather than make the seam (and `createBackfillRequester`'s `sign`, a db-core change) async,
+ * sign with the synchronous {@link signPeerSig} (noble, over the raw Ed25519 seed) over db-core's
+ * canonical signing payloads. The produced signature verifies on the serving side under
+ * {@link verifyPeerSig} over the same bytes (both noble, RFC8032), so the round trip is symmetric.
+ */
+export declare function createRecoverRequestSigners(privateKey: PrivateKey): RecoverRequestSigners;
+/**
+ * Thrown out of {@link Libp2pReactivityRecoverTransport.backfillTransport} / `resumeTransport` when the
+ * dialed cohort answered with a `kind: "rotated"` recover reply: the outgoing tail this request reached has
+ * rotated and is draining, so it bounced the request to the new tree (`docs/reactivity.md` §Tail rotation).
+ * It carries the {@link RotationRedirectV1} so the subscription manager can move itself to the successor.
+ *
+ * A `kind: "rotated"` reply is **terminal** for the cohort-walk — the dialed member spoke authoritatively for
+ * the cohort, so the transport stops rather than falling through to the next target (contrast a *dial
+ * failure*, which still falls through). The subscriber honors it like a notification-driven rotation.
+ */
+export declare class RotationRedirectError extends Error {
+    /** The drain-window redirect the serving cohort returned (`newTailId` / `newTopicId` / `effectiveAtRevision`). */
+    readonly redirect: RotationRedirectV1;
+    constructor(redirect: RotationRedirectV1);
+}
+/** The wire exchange seam: open the recover protocol to `target`, send `frame`, return the bounded reply. */
+export interface RecoverDialer {
+    /** Exchange one request frame for one reply frame with `target` (peer-id string). Rejects on a dial failure. */
+    exchange(target: string, frame: Uint8Array): Promise<Uint8Array>;
+}
+/** Build the production libp2p-backed {@link RecoverDialer} over {@link requestResponse}. */
+export declare function createLibp2pRecoverDialer(node: Libp2p, recoverProtocol?: string, maxBytes?: number): RecoverDialer;
+/** Construction inputs for a {@link Libp2pReactivityRecoverTransport}. */
+export interface Libp2pReactivityRecoverTransportOptions {
+    /** Wire exchange (e.g. {@link createLibp2pRecoverDialer} over the live node). */
+    readonly dialer: RecoverDialer;
+    /** This node's peer-id string (`node.peerId.toString()`); never dialed — a co-located serve is the node wiring's. */
+    readonly selfPeerId: string;
+    /** Sticky cohort-hint cache, shared with the subscription manager (the one-RT primary for the happy path). */
+    readonly cohortHintCache: StickyCohortHintCache;
+    /** FRET cohort-walk fallback: a topic id → dialable cohort member peer-id strings. */
+    readonly resolveCohort: (topicId: Uint8Array) => string[];
+    /** Per-frame ceiling for encode/decode; default {@link DEFAULT_STREAM_MAX_BYTES}. */
+    readonly maxBytes?: number;
+}
+/**
+ * The outbound recover transport: one instance per node, exposing the two db-core function seams against it.
+ * Each returned transport dials the **sticky primary first** (one round trip after a brief flap), falling
+ * back to a **cohort-walk** member on a dial failure (any member that holds the topic's gossiped `PushState`
+ * can answer). A kind mismatch or all-targets-failed surfaces as a rejection so the caller's retry/escalation
+ * policy (the subscription manager's backfill escalation, or `manager.resume()`'s caller) takes over.
+ */
+export declare class Libp2pReactivityRecoverTransport {
+    private readonly dialer;
+    private readonly selfPeerId;
+    private readonly cohortHintCache;
+    private readonly resolveCohort;
+    private readonly maxBytes;
+    constructor(options: Libp2pReactivityRecoverTransportOptions);
+    /** The db-core {@link BackfillTransport} for `(topicId, collectionId)` — frames + dials a signed {@link BackfillV1}. */
+    backfillTransport(topicId: Uint8Array, collectionId: string): BackfillTransport;
+    /** The {@link ResumeTransport} for `(topicId, collectionId)` — frames + dials a signed {@link ResumeV1}. */
+    resumeTransport(topicId: Uint8Array, collectionId: string): ResumeTransport;
+    /**
+     * Exchange one recover frame with the first reachable target: sticky primary, then each cohort-walk
+     * member. A **dial failure** falls through to the next candidate; a successful dial is **terminal** (the
+     * member answered for the cohort) — a `kind: "rotated"` redirect throws {@link RotationRedirectError}, and
+     * a reply decoding to the wrong `kind` is a protocol error. Throws when no candidate succeeds.
+     */
+    private exchange;
+    /**
+     * Ordered dial candidates for a recover: the sticky primary (decoded from its base64url-of-bytes form)
+     * first, then the cohort-walk members. Self is never dialed (a co-located serve is the node wiring's
+     * concern), and duplicates collapse.
+     */
+    private selectTargets;
+}
+/** Live `PushState` resolvers + replay guard the recover serve handler dispatches against. */
+export interface RecoverServeDeps {
+    /** Resolve the served `PushState` for an exact reactivity topic id (resume's stale-tail lookup). */
+    readonly pushStateFor: (topicId: Uint8Array) => PushState | undefined;
+    /** Resolve the served `PushState` for a collection id — the current tail (backfill, and rotated resume). */
+    readonly pushStateForCollection: (collectionId: string) => PushState | undefined;
+    /** Node-level freshness + anti-replay gate keyed on the request signature bytes. */
+    readonly replayGuard: CorrelationReplayGuard;
+    /**
+     * The drain-window redirect for a request that reached an **outgoing (rotated)** tail still in its drain
+     * window, or `undefined` if the resolved topic never rotated / has drained. The node wiring binds this to
+     * `ReactivityForwarderHost.rotationRedirectFor`, resolving the old topic from the request: for **resume**
+     * the request carries `topicId = reactivityTopicId(latestKnownTailId)`; for **backfill** (no `topicId`)
+     * the binding resolves the collection's current served topic. When it returns a redirect the serve replies
+     * `kind: "rotated"` instead of serving data, moving the subscriber to the new tree. Absent ⇒ never redirect.
+     */
+    readonly rotationFor?: (req: {
+        topicId?: Uint8Array;
+        collectionId: string;
+    }, now: number) => RotationRedirectV1 | undefined;
+    /** Unix-ms clock for the replay-guard window. Default `Date.now`. */
+    readonly clock?: () => number;
+    /** Per-frame decode ceiling; default {@link DEFAULT_STREAM_MAX_BYTES}. */
+    readonly maxBytes?: number;
+}
+/**
+ * Build the recover serve callback for {@link handleRequestResponse}: it returns the reply frame, or
+ * `undefined` for **no reply** (a decode/verify/replay/resolve failure aborts the stream). It never throws
+ * out of the handler.
+ */
+export declare function createRecoverRequestHandler(deps: RecoverServeDeps): (frame: Uint8Array, fromPeer: PeerId) => Promise<Uint8Array | undefined>;
+/** Register the inbound recover protocol handler on `node` (request-reply over the recover protocol). */
+export declare function registerRecoverHandler(node: Libp2p, protocol: string, deps: RecoverServeDeps): void;
+//# sourceMappingURL=recover-transport.d.ts.map

package/dist/src/reactivity/recover-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover-transport.d.ts","sourceRoot":"","sources":["../../../src/reactivity/recover-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAcN,KAAK,gBAAgB,EAErB,KAAK,cAAc,EAGnB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAKjE;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAID;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACrC,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,MAAM,CAAC;IAC9D,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,MAAM,CAAC;CAC1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,UAAU,GAAG,qBAAqB,CAKzF;AAID;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC/C,kHAAkH;IAClH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;gBAC1B,QAAQ,EAAE,kBAAkB;CAKxC;AAED,6GAA6G;AAC7G,MAAM,WAAW,aAAa;IAC7B,gHAAgH;IAChH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACjE;AAED,6FAA6F;AAC7F,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,GAAE,MAAoC,EAAE,QAAQ,GAAE,MAAiC,GAAG,aAAa,CAIzK;AAED,0EAA0E;AAC1E,MAAM,WAAW,uCAAuC;IACvD,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,qHAAqH;IACrH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8GAA8G;IAC9G,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;IAChD,sFAAsF;IACtF,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,MAAM,EAAE,CAAC;IAC1D,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,qBAAa,gCAAgC;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAClE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,OAAO,EAAE,uCAAuC;IAQ5D,wHAAwH;IACxH,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,iBAAiB;IAW/E,4GAA4G;IAC5G,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,eAAe;IAW3E;;;;;OAKG;YACW,QAAQ;IA6BtB;;;;OAIG;IACH,OAAO,CAAC,aAAa;CAuBrB;AAID,8FAA8F;AAC9F,MAAM,WAAW,gBAAgB;IAChC,oGAAoG;IACpG,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,SAAS,GAAG,SAAS,CAAC;IACtE,4GAA4G;IAC5G,QAAQ,CAAC,sBAAsB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAC;IACjF,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,OAAO,CAAC,EAAE,UAAU,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,EAAE,MAAM,KAAK,kBAAkB,GAAG,SAAS,CAAC;IAC5H,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AA0ED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,gBAAgB,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CA2B5I;AAED,yGAAyG;AACzG,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAGnG"}