@rocicorp/zero 0.25.0-canary.0 → 0.25.0-canary.2

package/out/zql/src/planner/planner-fan-in.d.ts

@@ -0,0 +1,39 @@
+import type { PlannerConstraint } from './planner-constraint.ts';
+import type { PlanDebugger } from './planner-debug.ts';
+import type { CostEstimate, JoinOrConnection, PlannerNode } from './planner-node.ts';
+import type { PlannerTerminus } from './planner-terminus.ts';
+/**
+ * A PlannerFanIn node can either be a normal FanIn or UnionFanIn.
+ *
+ * These have different performance characteristics so we need to distinguish them.
+ *
+ * A normal FanIn only does a single fetch to FanOut, regardless of how many internal
+ * branches / inputs it has.
+ *
+ * A UnionFanIn does a fetch per internal branch / input. This causes an exponential
+ * increase in cost if many UnionFanIns are chained after on another. E.g., `(A or B) AND (C or D)`.
+ *
+ * To capture this cost blow-up, union fan in assigns different branch patterns to their inputs.
+ *
+ * Since UFI will generate a unique branch pattern per input, planner-connection will yield a higher cost
+ * each time a UFI is present. planner-connection will return the sum of the costs of each unique branch pattern.
+ */
+export declare class PlannerFanIn {
+    #private;
+    readonly kind: "fan-in";
+    constructor(inputs: Exclude<PlannerNode, PlannerTerminus>[]);
+    get type(): "FI" | "UFI";
+    closestJoinOrSource(): JoinOrConnection;
+    setOutput(node: PlannerNode): void;
+    get output(): PlannerNode;
+    reset(): void;
+    convertToUFI(): void;
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * Fan-in propagates to all of its inputs.
+     */
+    propagateUnlimitFromFlippedJoin(): void;
+    estimateCost(downstreamChildSelectivity: number, branchPattern: number[], planDebugger?: PlanDebugger): CostEstimate;
+    propagateConstraints(branchPattern: number[], constraint: PlannerConstraint | undefined, from?: PlannerNode, planDebugger?: PlanDebugger): void;
+}
+//# sourceMappingURL=planner-fan-in.d.ts.map

package/out/zql/src/planner/planner-fan-in.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-fan-in.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-fan-in.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;;IACvB,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;gBAKtB,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,eAAe,CAAC,EAAE;IAK3D,IAAI,IAAI,iBAEP;IAED,mBAAmB,IAAI,gBAAgB;IAIvC,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIlC,IAAI,MAAM,IAAI,WAAW,CAGxB;IAED,KAAK;IAIL,YAAY,IAAI,IAAI;IAIpB;;;OAGG;IACH,+BAA+B,IAAI,IAAI;IAavC,YAAY,CACV,0BAA0B,EAAE,MAAM,EAClC,aAAa,EAAE,MAAM,EAAE,EACvB,YAAY,CAAC,EAAE,YAAY,GAC1B,YAAY;IAuGf,oBAAoB,CAClB,aAAa,EAAE,MAAM,EAAE,EACvB,UAAU,EAAE,iBAAiB,GAAG,SAAS,EACzC,IAAI,CAAC,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,YAAY,GAC1B,IAAI;CAyCR"}

package/out/zql/src/planner/planner-fan-in.js

@@ -0,0 +1,167 @@
+import { assert } from "../../../shared/src/asserts.js";
+/**
+ * A PlannerFanIn node can either be a normal FanIn or UnionFanIn.
+ *
+ * These have different performance characteristics so we need to distinguish them.
+ *
+ * A normal FanIn only does a single fetch to FanOut, regardless of how many internal
+ * branches / inputs it has.
+ *
+ * A UnionFanIn does a fetch per internal branch / input. This causes an exponential
+ * increase in cost if many UnionFanIns are chained after on another. E.g., `(A or B) AND (C or D)`.
+ *
+ * To capture this cost blow-up, union fan in assigns different branch patterns to their inputs.
+ *
+ * Since UFI will generate a unique branch pattern per input, planner-connection will yield a higher cost
+ * each time a UFI is present. planner-connection will return the sum of the costs of each unique branch pattern.
+ */
+export class PlannerFanIn {
+    kind = 'fan-in';
+    #type;
+    #output;
+    #inputs;
+    constructor(inputs) {
+        this.#type = 'FI';
+        this.#inputs = inputs;
+    }
+    get type() {
+        return this.#type;
+    }
+    closestJoinOrSource() {
+        return 'join';
+    }
+    setOutput(node) {
+        this.#output = node;
+    }
+    get output() {
+        assert(this.#output !== undefined, 'Output not set');
+        return this.#output;
+    }
+    reset() {
+        this.#type = 'FI';
+    }
+    convertToUFI() {
+        this.#type = 'UFI';
+    }
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * Fan-in propagates to all of its inputs.
+     */
+    propagateUnlimitFromFlippedJoin() {
+        for (const input of this.#inputs) {
+            if ('propagateUnlimitFromFlippedJoin' in input &&
+                typeof input.propagateUnlimitFromFlippedJoin === 'function') {
+                input.propagateUnlimitFromFlippedJoin();
+            }
+        }
+    }
+    estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
+        // FanIn always sums costs of its inputs
+        // But it needs to pass the correct branch pattern to each input
+        let totalCost = {
+            returnedRows: 0,
+            cost: 0,
+            scanEst: 0,
+            startupCost: 0,
+            selectivity: 0,
+            limit: undefined,
+        };
+        if (this.#type === 'FI') {
+            // Normal FanIn: all inputs get the same branch pattern with 0 prepended
+            const updatedPattern = [0, ...branchPattern];
+            let maxrows = 0;
+            let maxRunningCost = 0;
+            let maxStartupCost = 0;
+            let maxScanEst = 0;
+            let noMatchProb = 1.0;
+            for (const input of this.#inputs) {
+                const cost = input.estimateCost(downstreamChildSelectivity, updatedPattern, planDebugger);
+                if (cost.returnedRows > maxrows) {
+                    maxrows = cost.returnedRows;
+                }
+                if (cost.cost > maxRunningCost) {
+                    maxRunningCost = cost.cost;
+                }
+                if (cost.startupCost > maxStartupCost) {
+                    maxStartupCost = cost.startupCost;
+                }
+                if (cost.scanEst > maxScanEst) {
+                    maxScanEst = cost.scanEst;
+                }
+                // OR branches: combine selectivities assuming independent events
+                // P(A OR B) = 1 - (1-A)(1-B)
+                // Track probability of NO match in any branch
+                noMatchProb *= 1 - cost.selectivity;
+                // all inputs should have the same limit.
+                assert(totalCost.limit === undefined || cost.limit === totalCost.limit, 'All FanIn inputs should have the same limit');
+                totalCost.limit = cost.limit;
+            }
+            totalCost.returnedRows = maxrows;
+            totalCost.cost = maxRunningCost;
+            totalCost.selectivity = 1 - noMatchProb;
+            totalCost.startupCost = maxStartupCost;
+            totalCost.scanEst = maxScanEst;
+        }
+        else {
+            // Union FanIn (UFI): each input gets unique branch pattern
+            let i = 0;
+            let noMatchProb = 1.0;
+            for (const input of this.#inputs) {
+                const updatedPattern = [i, ...branchPattern];
+                const cost = input.estimateCost(downstreamChildSelectivity, updatedPattern, planDebugger);
+                totalCost.returnedRows += cost.returnedRows;
+                totalCost.cost += cost.cost;
+                totalCost.scanEst += cost.scanEst;
+                totalCost.startupCost = totalCost.startupCost + cost.startupCost;
+                // OR branches: combine selectivities assuming independent events
+                // P(A OR B) = 1 - (1-A)(1-B)
+                // Track probability of NO match in any branch
+                noMatchProb *= 1 - cost.selectivity;
+                // all inputs should have the same limit.
+                assert(totalCost.limit === undefined || cost.limit === totalCost.limit, 'All FanIn inputs should have the same limit');
+                totalCost.limit = cost.limit;
+                i++;
+            }
+            totalCost.selectivity = 1 - noMatchProb;
+        }
+        planDebugger?.log({
+            type: 'node-cost',
+            nodeType: 'fan-in',
+            node: this.#type,
+            branchPattern,
+            downstreamChildSelectivity,
+            costEstimate: totalCost,
+        });
+        return totalCost;
+    }
+    propagateConstraints(branchPattern, constraint, from, planDebugger) {
+        planDebugger?.log({
+            type: 'node-constraint',
+            nodeType: 'fan-in',
+            node: this.#type,
+            branchPattern,
+            constraint,
+            from: from?.kind ?? 'unknown',
+        });
+        if (this.#type === 'FI') {
+            const updatedPattern = [0, ...branchPattern];
+            /**
+             * All inputs get the same branch pattern.
+             * 1. They cannot contribute differing constraints to their parent inputs because they are not flipped.
+             *    If they were flipped this would be of type UFI.
+             * 2. All inputs need to be called because they could be pinned. If they are pinned they could have constraints
+             *    to send to their children.
+             */
+            for (const input of this.#inputs) {
+                input.propagateConstraints(updatedPattern, constraint, this, planDebugger);
+            }
+            return;
+        }
+        let i = 0;
+        for (const input of this.#inputs) {
+            input.propagateConstraints([i, ...branchPattern], constraint, this, planDebugger);
+            i++;
+        }
+    }
+}
+//# sourceMappingURL=planner-fan-in.js.map

package/out/zql/src/planner/planner-fan-in.js.map

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

package/out/zql/src/planner/planner-fan-out.d.ts

@@ -0,0 +1,23 @@
+import type { PlannerConstraint } from './planner-constraint.ts';
+import type { PlanDebugger } from './planner-debug.ts';
+import type { CostEstimate, JoinOrConnection, PlannerNode } from './planner-node.ts';
+import type { PlannerTerminus } from './planner-terminus.ts';
+export declare class PlannerFanOut {
+    #private;
+    readonly kind: "fan-out";
+    constructor(input: Exclude<PlannerNode, PlannerTerminus>);
+    get type(): "FO" | "UFO";
+    addOutput(node: PlannerNode): void;
+    get outputs(): PlannerNode[];
+    closestJoinOrSource(): JoinOrConnection;
+    propagateConstraints(branchPattern: number[], constraint: PlannerConstraint | undefined, from?: PlannerNode, planDebugger?: PlanDebugger): void;
+    estimateCost(downstreamChildSelectivity: number, branchPattern: number[], planDebugger?: PlanDebugger): CostEstimate;
+    convertToUFO(): void;
+    reset(): void;
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * Fan-out propagates to its input.
+     */
+    propagateUnlimitFromFlippedJoin(): void;
+}
+//# sourceMappingURL=planner-fan-out.d.ts.map

package/out/zql/src/planner/planner-fan-out.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-fan-out.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-fan-out.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D,qBAAa,aAAa;;IACxB,QAAQ,CAAC,IAAI,EAAG,SAAS,CAAU;gBAKvB,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE,eAAe,CAAC;IAKxD,IAAI,IAAI,iBAEP;IAED,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIlC,IAAI,OAAO,IAAI,WAAW,EAAE,CAE3B;IAED,mBAAmB,IAAI,gBAAgB;IAIvC,oBAAoB,CAClB,aAAa,EAAE,MAAM,EAAE,EACvB,UAAU,EAAE,iBAAiB,GAAG,SAAS,EACzC,IAAI,CAAC,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,YAAY,GAC1B,IAAI;IAkBP,YAAY,CACV,0BAA0B,EAAE,MAAM,EAClC,aAAa,EAAE,MAAM,EAAE,EACvB,YAAY,CAAC,EAAE,YAAY,GAC1B,YAAY;IAmBf,YAAY,IAAI,IAAI;IAIpB,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,+BAA+B,IAAI,IAAI;CAUxC"}

package/out/zql/src/planner/planner-fan-out.js

@@ -0,0 +1,62 @@
+export class PlannerFanOut {
+    kind = 'fan-out';
+    #type;
+    #outputs = [];
+    #input;
+    constructor(input) {
+        this.#type = 'FO';
+        this.#input = input;
+    }
+    get type() {
+        return this.#type;
+    }
+    addOutput(node) {
+        this.#outputs.push(node);
+    }
+    get outputs() {
+        return this.#outputs;
+    }
+    closestJoinOrSource() {
+        return this.#input.closestJoinOrSource();
+    }
+    propagateConstraints(branchPattern, constraint, from, planDebugger) {
+        planDebugger?.log({
+            type: 'node-constraint',
+            nodeType: 'fan-out',
+            node: 'FO',
+            branchPattern,
+            constraint,
+            from: from?.kind ?? 'unknown',
+        });
+        this.#input.propagateConstraints(branchPattern, constraint, this, planDebugger);
+    }
+    estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
+        const ret = this.#input.estimateCost(downstreamChildSelectivity, branchPattern, planDebugger);
+        planDebugger?.log({
+            type: 'node-cost',
+            nodeType: 'fan-out',
+            node: 'FO',
+            branchPattern,
+            downstreamChildSelectivity,
+            costEstimate: ret,
+        });
+        return ret;
+    }
+    convertToUFO() {
+        this.#type = 'UFO';
+    }
+    reset() {
+        this.#type = 'FO';
+    }
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * Fan-out propagates to its input.
+     */
+    propagateUnlimitFromFlippedJoin() {
+        if ('propagateUnlimitFromFlippedJoin' in this.#input &&
+            typeof this.#input.propagateUnlimitFromFlippedJoin === 'function') {
+            this.#input.propagateUnlimitFromFlippedJoin();
+        }
+    }
+}
+//# sourceMappingURL=planner-fan-out.js.map

package/out/zql/src/planner/planner-fan-out.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-fan-out.js","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-fan-out.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,aAAa;IACf,IAAI,GAAG,SAAkB,CAAC;IACnC,KAAK,CAAe;IACX,QAAQ,GAAkB,EAAE,CAAC;IAC7B,MAAM,CAAwC;IAEvD,YAAY,KAA4C;QACtD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,SAAS,CAAC,IAAiB;QACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,mBAAmB;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC3C,CAAC;IAED,oBAAoB,CAClB,aAAuB,EACvB,UAAyC,EACzC,IAAkB,EAClB,YAA2B;QAE3B,YAAY,EAAE,GAAG,CAAC;YAChB,IAAI,EAAE,iBAAiB;YACvB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,IAAI;YACV,aAAa;YACb,UAAU;YACV,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,SAAS;SAC9B,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAC9B,aAAa,EACb,UAAU,EACV,IAAI,EACJ,YAAY,CACb,CAAC;IACJ,CAAC;IAED,YAAY,CACV,0BAAkC,EAClC,aAAuB,EACvB,YAA2B;QAE3B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAClC,0BAA0B,EAC1B,aAAa,EACb,YAAY,CACb,CAAC;QAEF,YAAY,EAAE,GAAG,CAAC;YAChB,IAAI,EAAE,WAAW;YACjB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,IAAI;YACV,aAAa;YACb,0BAA0B;YAC1B,YAAY,EAAE,GAAG;SAClB,CAAC,CAAC;QAEH,OAAO,GAAG,CAAC;IACb,CAAC;IAED,YAAY;QACV,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,+BAA+B;QAC7B,IACE,iCAAiC,IAAI,IAAI,CAAC,MAAM;YAChD,OAAO,IAAI,CAAC,MAAM,CAAC,+BAA+B,KAAK,UAAU,EACjE,CAAC;YAEC,IAAI,CAAC,MACN,CAAC,+BAA+B,EAAE,CAAC;QACtC,CAAC;IACH,CAAC;CACF"}

package/out/zql/src/planner/planner-graph.d.ts

@@ -0,0 +1,103 @@
+import type { PlannerJoin } from './planner-join.ts';
+import type { PlannerFanOut } from './planner-fan-out.ts';
+import type { PlannerFanIn } from './planner-fan-in.ts';
+import type { PlannerConnection } from './planner-connection.ts';
+import type { PlannerTerminus } from './planner-terminus.ts';
+import { PlannerSource, type ConnectionCostModel } from './planner-source.ts';
+import type { PlannerConstraint } from './planner-constraint.ts';
+import type { PlanDebugger } from './planner-debug.ts';
+/**
+ * Captured state of a plan for comparison and restoration.
+ */
+type PlanState = {
+    connections: Array<{
+        limit: number | undefined;
+    }>;
+    joins: Array<{
+        type: 'semi' | 'flipped';
+    }>;
+    fanOuts: Array<{
+        type: 'FO' | 'UFO';
+    }>;
+    fanIns: Array<{
+        type: 'FI' | 'UFI';
+    }>;
+    connectionConstraints: Array<Map<string, PlannerConstraint | undefined>>;
+};
+export declare class PlannerGraph {
+    #private;
+    joins: PlannerJoin[];
+    fanOuts: PlannerFanOut[];
+    fanIns: PlannerFanIn[];
+    connections: PlannerConnection[];
+    /**
+     * Reset all planning state back to initial values for another planning pass.
+     * Resets only mutable planning state - graph structure is unchanged.
+     *
+     * This allows replanning the same query graph with different strategies.
+     */
+    resetPlanningState(): void;
+    /**
+     * Create and register a source (table) in the graph.
+     */
+    addSource(name: string, model: ConnectionCostModel): PlannerSource;
+    /**
+     * Get a source by table name.
+     */
+    getSource(name: string): PlannerSource;
+    /**
+     * Check if a source exists by table name.
+     */
+    hasSource(name: string): boolean;
+    /**
+     * Set the terminus (final output) node of the graph.
+     * Constraint propagation starts from this node.
+     */
+    setTerminus(terminus: PlannerTerminus): void;
+    /**
+     * Initiate constraint propagation from the terminus node.
+     * This sends constraints up through the graph to update
+     * connection cost estimates.
+     */
+    propagateConstraints(planDebugger?: PlanDebugger): void;
+    /**
+     * Calculate total cost of the current plan.
+     * Total cost includes both startup cost (one-time, e.g., sorting) and running cost.
+     */
+    getTotalCost(planDebugger?: PlanDebugger): number;
+    /**
+     * Capture a lightweight snapshot of the current planning state.
+     * Used for backtracking during multi-start greedy search.
+     *
+     * Captures mutable state including pinned flags, join types, and
+     * constraint maps to avoid needing repropagation on restore.
+     *
+     * @returns A snapshot that can be restored via restorePlanningSnapshot()
+     */
+    capturePlanningSnapshot(): PlanState;
+    /**
+     * Restore planning state from a previously captured snapshot.
+     * Used for backtracking when a planning attempt fails.
+     *
+     * Restores pinned flags, join types, and constraint maps, eliminating
+     * the need for repropagation.
+     *
+     * @param state - Snapshot created by capturePlanningSnapshot()
+     */
+    restorePlanningSnapshot(state: PlanState): void;
+    /**
+     * Main planning algorithm using exhaustive join flip enumeration.
+     *
+     * Enumerates all possible flip patterns for flippable joins (2^n for n flippable joins).
+     * Each pattern represents a different query execution plan. We evaluate the cost of each
+     * plan and select the one with the lowest cost.
+     *
+     * Connections are used only for cost estimation - the flip patterns determine the plan.
+     * FanOut/FanIn states (FO/UFO and FI/UFI) are automatically derived from join flip states.
+     *
+     * @param planDebugger - Optional debugger to receive structured events during planning
+     */
+    plan(planDebugger?: PlanDebugger): void;
+}
+export {};
+//# sourceMappingURL=planner-graph.d.ts.map

package/out/zql/src/planner/planner-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-graph.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAC,aAAa,EAAE,KAAK,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAErD;;GAEG;AACH,KAAK,SAAS,GAAG;IACf,WAAW,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAAC,CAAC;IAChD,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAAC,CAAC;IACzC,OAAO,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAA;KAAC,CAAC,CAAC;IACrC,MAAM,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAA;KAAC,CAAC,CAAC;IACpC,qBAAqB,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC,CAAC,CAAC;CAC1E,CAAC;AAkBF,qBAAa,YAAY;;IAQvB,KAAK,EAAE,WAAW,EAAE,CAAM;IAC1B,OAAO,EAAE,aAAa,EAAE,CAAM;IAC9B,MAAM,EAAE,YAAY,EAAE,CAAM;IAC5B,WAAW,EAAE,iBAAiB,EAAE,CAAM;IAEtC;;;;;OAKG;IACH,kBAAkB;IAOlB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,aAAa;IAUlE;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAMtC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAI5C;;;;OAIG;IACH,oBAAoB,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAQvD;;;OAGG;IACH,YAAY,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,MAAM;IAKjD;;;;;;;;OAQG;IACH,uBAAuB,IAAI,SAAS;IAYpC;;;;;;;;OAQG;IACH,uBAAuB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAkF/C;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;CAsIxC"}