@cello-protocol/daemon 0.0.120 → 0.0.122

package/dist/document-engine.js

@@ -0,0 +1,281 @@
+/**
+ * DOD-DOC-ENGINE-1 — the daemon's Y.Doc lifecycle.
+ *
+ * The engine owns HOW to apply; the store (DOD-DOC-STORE-1) owns what to replay and in what
+ * order. `replay` takes whole envelope rows rather than payload bytes so it can tell a
+ * payload-free AUDIT record (a withdrawal or rejection, which is expected and skipped) from a
+ * payload-free PURGED update (an operation whose bytes are gone, which must refuse). That is the
+ * only thing `kind` is read for — `referencesEnvelopeHash` is pure audit at replay time, never
+ * read, because a withdrawal excludes nothing (§16.4; see `replay`).
+ *
+ * EVERY GUARD BELOW IS A RESPONSE TO A MEASUREMENT, not to a guess. DOD-DOC-FUZZ-1 fuzzed
+ * `Y.applyUpdate` and found:
+ *
+ *   - Malformed input THROWS — so a wrapped apply genuinely contains it, and V1 needs no sandbox.
+ *   - But the dangerous class is what Yjs ACCEPTS. An update whose dependencies the receiver
+ *     lacks returns success, contributes nothing, and is RETAINED forever in
+ *     `doc.store.pendingStructs` — a peer streams those until the daemon dies, and a try/catch
+ *     sees only success. Hence the pending-set check after every apply.
+ *   - An empty or one-byte update throws a lib0 DECODER error ("Unexpected end of array"), which
+ *     names Yjs internals rather than a protocol fault. Hence a floor as well as a cap.
+ *   - Yjs does not bound nesting depth at all, and the size cap bounds it poorly (~16 bytes per
+ *     level, so roughly 65,000 levels fit in 1 MiB). Structural limits are DOD-DOC-GATE-1's job;
+ *     the engine's contract is only that a bad update is a typed error, never a crash.
+ *
+ * ONE TYPED REASON PER FAILURE CLASS. A lib0 string like "Integer out of Range" describes where
+ * the decoder gave up, not what the peer did wrong, so it travels as `detail` and never as the
+ * reason an operator or a policy log sees.
+ */
+import * as Y from "yjs";
+/** Thrown by the *OrThrow variants and by `replay`, where returning a verdict would let a caller
+ *  persist a state that was never fully applied. */
+export class DocumentUpdateError extends Error {
+    reason;
+    detail;
+    constructor(reason, detail) {
+        super(detail ? `${reason}: ${detail}` : reason);
+        this.name = "DocumentUpdateError";
+        this.reason = reason;
+        this.detail = detail;
+    }
+}
+/** Pre-parse size cap — bytes are refused on LENGTH before Yjs is invoked at all. */
+const MAX_UPDATE_BYTES = 1024 * 1024;
+/**
+ * The minimum valid update. An empty encoded state is two bytes (`[0,0]`), measured — anything
+ * shorter throws a decoder error that says nothing about the protocol.
+ */
+const MIN_UPDATE_BYTES = 2;
+/** The single root text field a V1 text document uses. */
+const TEXT_ROOT = "content";
+export class DocumentEngine {
+    #logger;
+    constructor(logger) {
+        this.#logger = logger;
+    }
+    /** The pre-parse cap, exposed so callers and tests agree on one number. */
+    get maxUpdateBytes() {
+        return MAX_UPDATE_BYTES;
+    }
+    /**
+     * A fresh live document.
+     *
+     * Yjs mints its own random clientID and NOTHING here touches it (§14). Deriving it from agent
+     * identity, or persisting and restoring one, means two live docs can share it — and
+     * DOD-DOC-FUZZ-1 measured that outcome: the colliding writer silently wins, the honest client's
+     * update is accepted-and-dropped, and the document becomes a splice of two authors with an
+     * empty pending set and no error on any path.
+     */
+    createDocument(startingContent = "") {
+        const doc = new Y.Doc();
+        if (startingContent.length > 0)
+            doc.getText(TEXT_ROOT).insert(0, startingContent);
+        return doc;
+    }
+    /**
+     * Read the single text root a text-typed document uses.
+     *
+     * Named for the root it reads, not for "the document's content". `DocumentRow.documentType`
+     * admits markdown, json and xml; on the latter two the data does not live in this root, and an
+     * unnamed `readText` would return "" — indistinguishable from an empty document. Structured
+     * types get their own accessors when a unit needs them.
+     */
+    readTextRoot(doc) {
+        return doc.getText(TEXT_ROOT).toString();
+    }
+    insertIntoTextRoot(doc, index, text) {
+        doc.getText(TEXT_ROOT).insert(index, text);
+    }
+    /** The full state, or just what a peer holding `sinceStateVector` is missing (§7). */
+    encodeState(doc, sinceStateVector) {
+        return Y.encodeStateAsUpdate(doc, sinceStateVector);
+    }
+    encodeStateVector(doc) {
+        return Y.encodeStateVector(doc);
+    }
+    snapshot(doc) {
+        return { binary: Y.encodeStateAsUpdate(doc), stateVector: Y.encodeStateVector(doc) };
+    }
+    /**
+     * Materialize a document from a snapshot binary.
+     *
+     * The restored document mints a FRESH clientID — the binary carries the operations, never an
+     * identity to resume under. See `createDocument` for what sharing one costs.
+     */
+    restore(binary) {
+        const doc = new Y.Doc();
+        try {
+            Y.applyUpdate(doc, binary);
+        }
+        catch (err) {
+            // This is the one method that reads bytes off disk, and it used to be a bare applyUpdate —
+            // so a corrupt `document_snapshots` row surfaced as "Unexpected end of array", the exact
+            // lib0 string this module says must never be a reason. It named Yjs internals and pointed
+            // an operator at the wrong subsystem.
+            const detail = err instanceof Error ? err.message : String(err);
+            this.#logger.error("document.snapshot.malformed", { detail });
+            throw new DocumentUpdateError("document_snapshot_malformed", detail);
+        }
+        if (doc.store.pendingStructs !== null) {
+            // A snapshot that decodes but is incomplete would otherwise restore SHORT and silent.
+            this.#logger.error("document.snapshot.incomplete", {
+                missing: doc.store.pendingStructs.missing.size,
+            });
+            // Its OWN class. An incomplete snapshot is not "an incoming update depends on absent
+            // structs" — same symptom, different fault, and one reason per class is this module's rule.
+            throw new DocumentUpdateError("document_snapshot_incomplete", `snapshot is missing operations from ${doc.store.pendingStructs.missing.size} client(s)`);
+        }
+        return doc;
+    }
+    /**
+     * Apply one update, with every guard the fuzz pass motivated.
+     *
+     * Never throws and never leaves the document half-integrated: an update that cannot be fully
+     * resolved is applied to a THROWAWAY doc first, so the caller's document is untouched when the
+     * answer is no.
+     */
+    /**
+     * Apply one update to a caller's live document, leaving it untouched if the answer is no.
+     *
+     * The trial runs on a FRESH scratch document every time. Reusing one across calls is unsound:
+     * `Y.applyUpdate` MERGES, it does not reset, so a scratch doc seeded from an empty document
+     * still holds the previous trial's operations — and with that residue present, an update whose
+     * dependencies the target lacks reports an EMPTY pending set. The one guard that catches the
+     * accept class would go green on exactly the input it exists to refuse. (Measured, not
+     * reasoned: a shadow holding "AAA" re-seeded from an empty doc still reads "AAA".)
+     */
+    applyUpdate(doc, update) {
+        return this.#applyChecked(doc, new Y.Doc(), update);
+    }
+    #applyChecked(doc, shadow, update) {
+        if (update.length > MAX_UPDATE_BYTES) {
+            return this.#refuse("document_update_too_large", `${update.length} bytes exceeds the ${MAX_UPDATE_BYTES}-byte cap`, update);
+        }
+        if (update.length < MIN_UPDATE_BYTES) {
+            return this.#refuse("document_update_too_small", `${update.length} bytes is below the ${MIN_UPDATE_BYTES}-byte minimum for a Yjs update`, update);
+        }
+        // Trial it on scratch state first. Yjs has no atomic-apply mode, and an update that resolves
+        // only partially would otherwise leave the caller's document in a state nobody chose.
+        try {
+            Y.applyUpdate(shadow, Y.encodeStateAsUpdate(doc));
+            Y.applyUpdate(shadow, update);
+        }
+        catch (err) {
+            return this.#refuse("document_update_malformed", err instanceof Error ? err.message : String(err), update);
+        }
+        // THE ACCEPT CLASS. Yjs returned success — that is not evidence the update integrated. A
+        // non-empty pending set means it is waiting on structs that never arrived; admitting it would
+        // retain them indefinitely while contributing nothing (measured, DOD-DOC-FUZZ-1).
+        //
+        // PRECONDITION THIS IMPLIES: a sender's envelopes must be delivered in chain order. Yjs would
+        // otherwise BUFFER an out-of-order update and resolve it on the next state-vector exchange;
+        // this refuses instead. That is right for replay, where a gap means a corrupt log — a live
+        // receive path wanting buffer-and-re-request semantics needs its own entry point, not this one.
+        // BOTH pending sets: an update carrying a delete set for structs never seen leaves
+        // pendingStructs null and pendingDs populated, and retains just the same.
+        if (shadow.store.pendingStructs !== null || shadow.store.pendingDs !== null) {
+            return this.#refuse("document_update_unresolved_dependencies", shadow.store.pendingStructs
+                ? `depends on ${shadow.store.pendingStructs.missing.size} client(s) whose earlier operations are absent`
+                : "carries a delete set referring to operations this document has never seen", update);
+        }
+        Y.applyUpdate(doc, update);
+        return { ok: true };
+    }
+    /**
+     * Apply straight to `doc`, checking the pending set afterwards.
+     *
+     * No trial copy, because atomicity buys nothing here: `replay` throws on the first failure and
+     * the half-built document is discarded whole. Trialling each envelope would cost a full
+     * encode/decode of a growing document per envelope — the fold is O(n·|doc|) either way, but
+     * this halves the constant and removes the aliasing hazard entirely.
+     */
+    #applyDirect(doc, update) {
+        if (update.length > MAX_UPDATE_BYTES) {
+            return this.#refuse("document_update_too_large", `${update.length} bytes exceeds the ${MAX_UPDATE_BYTES}-byte cap`, update);
+        }
+        if (update.length < MIN_UPDATE_BYTES) {
+            return this.#refuse("document_update_too_small", `${update.length} bytes is below the ${MIN_UPDATE_BYTES}-byte minimum for a Yjs update`, update);
+        }
+        try {
+            Y.applyUpdate(doc, update);
+        }
+        catch (err) {
+            return this.#refuse("document_update_malformed", err instanceof Error ? err.message : String(err), update);
+        }
+        if (doc.store.pendingStructs !== null || doc.store.pendingDs !== null) {
+            return this.#refuse("document_update_unresolved_dependencies", doc.store.pendingStructs
+                ? `depends on ${doc.store.pendingStructs.missing.size} client(s) whose earlier operations are absent`
+                : "carries a delete set referring to operations this document has never seen", update);
+        }
+        return { ok: true };
+    }
+    /** Every refusal is logged, not merely returned — a return value nobody reads is not observable. */
+    #refuse(reason, detail, update) {
+        this.#logger.warn("document.update.refused", { reason, detail, bytes: update.length });
+        return { ok: false, reason, detail };
+    }
+    /** `applyUpdate` for callers that want the failure to be unmissable. */
+    applyUpdateOrThrow(doc, update) {
+        const res = this.applyUpdate(doc, update);
+        if (!res.ok)
+            throw new DocumentUpdateError(res.reason, res.detail);
+    }
+    /**
+     * Fold an ordered envelope log into a materialized state — the `ReplayFn` the store injects.
+     *
+     * **A WITHDRAWAL EXCLUDES NOTHING.** §16.4 is explicit: withdrawing rolls the change back with
+     * a *Yjs undo* and writes a record "beside the original envelope — marked withdrawn, never
+     * deleted, so the log stays intact". Rejection resolves the same way, by supersession —
+     * "inverses, not erasure" (§3.2). So the undo is itself an ordinary update in the log, and
+     * replay simply applies every payload in order.
+     *
+     * An earlier version of this method excluded the referenced envelope instead, which is
+     * unsound in a CRDT log and was measured to be so: Yjs operations are causally chained, so
+     * dropping any but the LAST envelope leaves every later one depending on structs that never
+     * arrive — the document rebuilds until the next daemon restart and is permanently unopenable
+     * after it. It also let ANY sender suppress ANY other sender's content by appending a
+     * payload-free row, since nothing upstream checks authorship of a reference. Both problems
+     * dissolve when the log is simply replayed, which is what the spec said to do.
+     *
+     * REFUSES rather than skipping. A payload that will not apply means the log is corrupt, and
+     * folding the rest would produce a document that reads as complete while missing operations —
+     * the silent divergence the whole two-layer design exists to prevent.
+     */
+    replay(envelopes) {
+        const doc = new Y.Doc();
+        let applied = 0;
+        for (const e of envelopes) {
+            if (e.payload === null) {
+                // A withdrawal or rejection RECORD legitimately carries no payload — it is audit, not
+                // content. An `update` row with no payload is different: it is a PURGED operation whose
+                // bytes are gone (§16.7-12), and folding around it would produce a document that reads
+                // as complete while missing an operation. Purge is V2, so this cannot happen yet — which
+                // is exactly why it must refuse now rather than become a silent skip later.
+                if (e.kind === "update") {
+                    this.#logger.error("document.replay.failed", {
+                        documentId: e.documentId,
+                        envelopeHash: e.envelopeHash,
+                        reason: "document_envelope_purged",
+                    });
+                    throw new DocumentUpdateError("document_envelope_purged", `envelope ${e.envelopeHash.slice(0, 16)}… is an update whose payload has been purged — ` +
+                        `the document cannot be rebuilt without it`);
+                }
+                continue;
+            }
+            const res = this.#applyDirect(doc, e.payload);
+            if (!res.ok) {
+                this.#logger.error("document.replay.failed", {
+                    documentId: e.documentId,
+                    envelopeHash: e.envelopeHash,
+                    reason: res.reason,
+                    detail: res.detail,
+                });
+                throw new DocumentUpdateError(res.reason, `envelope ${e.envelopeHash.slice(0, 16)}…: ${res.detail ?? ""}`);
+            }
+            applied++;
+        }
+        this.#logger.info("document.replay.completed", { envelopes: envelopes.length, applied });
+        return { binary: Y.encodeStateAsUpdate(doc), stateVector: Y.encodeStateVector(doc) };
+    }
+}
+//# sourceMappingURL=document-engine.js.map

package/dist/document-engine.js.map

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

package/dist/document-gate.d.ts

@@ -0,0 +1,139 @@
+/**
+ * DOD-DOC-GATE-1 — the validation gate (§3.2).
+ *
+ *   arrive → shadow-apply → validate the PROJECTED DIFF → admit or quarantine
+ *
+ * The shadow document is rebuilt from ACCEPTED state and discarded. Validation asks a question;
+ * admitting is a separate, explicit act, so a refused update never touches the live document.
+ *
+ * ── WHY THE RULES ARE WHAT THEY ARE ───────────────────────────────────────────────────────────
+ *
+ * Every rule here answers something DOD-DOC-FUZZ-1 MEASURED against real Yjs, and six of the nine
+ * are the ACCEPT class — input `Y.applyUpdate` returns SUCCESS for. That matters because the V1
+ * posture is "cap, catch, contain" (§16.7-7), and none of its three legs catches an accept: the
+ * size cap sees a small update, the try/catch sees success, and "structural limits on the shadow"
+ * has nothing to measure because the shadow looks fine. Measured, in order:
+ *
+ *   (a) an update whose dependencies never arrive is ACCEPTED and RETAINED forever — a peer
+ *       streams those until the daemon dies, and a try/catch sees only success;
+ *   (b) an update carries NO document identity, so one built on a different document merges
+ *       silently — binding is out-of-band work the gate must do;
+ *   (c) V2-format bytes are accepted by the v1 decoder and silently drop all content;
+ *   (d) trailing bytes past the decoder's cursor are ignored, so unlimited byte strings decode to
+ *       identical state — which makes an update's hash a poor identifier for what it says, and
+ *       that hash becomes a `0x04` leaf;
+ *   (h) authorship IS the clientID, so a colliding one silently wins and the honest client's
+ *       update is then accepted-and-dropped, leaving a splice of two authors with an EMPTY
+ *       pending set — the (a) rule cannot see this, which is why (h) is separate;
+ *   (i) a ten-byte well-formed update deletes a document's entire content. Structural limits are
+ *       UPPER bounds, so a shrinking update passes every one of them.
+ *
+ * The remaining three are the throw class: a size floor (e) because an empty update throws a lib0
+ * decoder string rather than a protocol fault, one typed reason per throw (g), and a nesting-depth
+ * limit (f) because Yjs bounds depth not at all and the size cap bounds it poorly — ~16 bytes per
+ * level, so roughly 65,000 levels fit inside 1 MiB.
+ *
+ * ── QUARANTINE, NEVER DISCARD ─────────────────────────────────────────────────────────────────
+ *
+ * A refused update is HELD. Every path out of this gate — including an unexpected failure inside
+ * a rule — produces a verdict and an event. A gate that admitted on internal error would be
+ * strictly worse than one with no rules at all, and one that dropped silently would diverge the
+ * two copies permanently and invisibly (§3.2).
+ */
+import * as Y from "yjs";
+import type { DocumentEngine } from "./document-engine.js";
+import type { Logger } from "./types.js";
+/** The one accepted update encoding (§16.7-8 pins it in the protocol types). */
+export declare const UPDATE_ENCODING_V1 = "yjs-v1";
+export interface GateLimits {
+    /** Pre-parse cap: bytes are refused on LENGTH before Yjs is invoked. */
+    maxUpdateBytes: number;
+    /** The document's size AFTER the update would apply. */
+    maxDocumentBytes: number;
+    /** Yjs bounds nesting not at all, and the size cap bounds it poorly. */
+    maxNestingDepth: number;
+    /** Per sender, per rolling minute. */
+    maxUpdatesPerMinute: number;
+}
+/** Published so a peer can discover them — a receiver-local limit nobody can learn is not a protocol. */
+export declare const DEFAULT_GATE_LIMITS: GateLimits;
+/** What the update WOULD do to the document — the only form in which a policy can judge it. */
+export interface ProjectedDiff {
+    inserted: string;
+    deletedChars: number;
+    /** Keys a JSON-shaped update would touch. */
+    changedKeys: string[];
+    /** The document's size if this were admitted. */
+    resultingBytes: number;
+    maxDepth: number;
+}
+export interface GateContext {
+    documentId: string;
+    senderAgentId: string;
+    /** clientIDs this peer is KNOWN to write under — the out-of-band binding (h) requires. */
+    senderClientIds: number[];
+    /**
+     * The document the ENVELOPE says this update belongs to (§14). Declared, never inferred: an
+     * update carries no document identity, so a well-formed one built on an unrelated document
+     * merges silently and no property of the bytes can reveal it. Absent is a refusal.
+     *
+     * REQUIRED rather than optional so a caller cannot forget it — and the runtime refusal stays
+     * for the untyped boundary. **These fields carry no security on their own: they are only as
+     * trustworthy as the envelope signature that covers them.** DOD-DOC-ENVELOPE-1 owes a blocking
+     * AC that `documentId`, the encoding, and the sender's clientID are inside the signed TBS.
+     */
+    declaredDocumentId: string | undefined;
+    /**
+     * The update encoding the ENVELOPE declares (§16.7-8 pins it). Declared rather than sniffed
+     * because the byte-level signatures overlap: a v2 update begins `[0, 0, …]` and a legitimate
+     * pure-delete v1 delta begins `[0, 1, …]`, so a first-byte heuristic refuses real deletions.
+     * Absent is a refusal.
+     */
+    declaredEncoding: string | undefined;
+    appendOnly?: boolean;
+}
+/** A pluggable rule. Returns null to allow. DOD-DOC-SCREEN-1 registers here. */
+export type GateRule = (diff: ProjectedDiff, context: GateContext) => {
+    reason: string;
+    detail?: string;
+} | null;
+/** Machine-readable, so a peer's daemon can act without parsing prose (§16.7-6). */
+export interface GateLimitBreach {
+    name: string;
+    limit: number;
+    actual: number;
+}
+export interface GateQuarantine {
+    admit: false;
+    reason: string;
+    detail?: string;
+    limit?: GateLimitBreach;
+    /** The pluggable rule that refused, when one did. */
+    rule?: string;
+    /**
+     * THE UPDATE ITSELF. §3.2: a quarantined update is HELD — never admitted, never discarded — so
+     * the caller can persist it, reference it from a `0x05` leaf, and resolve it by supersession
+     * (DOD-DOC-REJECT-1). Returning only a reason would have made "never discarded" a comment
+     * rather than a property: the bytes would die with this stack frame.
+     */
+    quarantined: Uint8Array;
+}
+export type GateVerdict = {
+    admit: true;
+    projectedDiff: ProjectedDiff;
+} | GateQuarantine;
+export declare class DocumentGate {
+    #private;
+    constructor(engine: DocumentEngine, limits: Partial<GateLimits>, logger: Logger);
+    limits(): GateLimits;
+    /** Register a pluggable rule. The screening rule (DOD-DOC-SCREEN-1) plugs in here. */
+    addRule(name: string, rule: GateRule): void;
+    /**
+     * Validate an incoming update against the accepted state.
+     *
+     * Never mutates `accepted`. Never throws — every failure, including an unexpected one inside a
+     * rule, becomes a quarantine verdict.
+     */
+    validate(accepted: Y.Doc, update: Uint8Array, context: GateContext, now?: number): GateVerdict;
+}
+//# sourceMappingURL=document-gate.d.ts.map

package/dist/document-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-gate.d.ts","sourceRoot":"","sources":["../src/document-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAE3C,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,gBAAgB,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,eAAe,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,yGAAyG;AACzG,eAAO,MAAM,mBAAmB,EAAE,UAOjC,CAAC;AAEF,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,0FAA0F;IAC1F,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;;;OASG;IACH,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,gFAAgF;AAChF,MAAM,MAAM,QAAQ,GAAG,CACrB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,WAAW,KACjB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC;AAEhD,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,aAAa,EAAE,aAAa,CAAA;CAAE,GAAG,cAAc,CAAC;AAEzF,qBAAa,YAAY;;gBAQX,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM;IAQ/E,MAAM,IAAI,UAAU;IAIpB,sFAAsF;IACtF,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI;IAI3C;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,SAAa,GAAG,WAAW;CA4SnG"}