@rocicorp/zero 0.24.2025102200 → 0.25.0-canary.1

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

@@ -0,0 +1,301 @@
+import { assert } from "../../../shared/src/asserts.js";
+import { mergeConstraints, } from "./planner-constraint.js";
+/**
+ * Represents a connection to a source (table scan).
+ *
+ * # Dual State Pattern
+ * Like all planner nodes, PlannerConnection separates:
+ * 1. immutable structure: Ordering, filters, cost model (set at construction)
+ * 2. mutable state: Pinned status, constraints (mutated during planning)
+ *
+ * # Cost Estimation
+ * The ordering and filters determine the initial cost. As planning progresses,
+ * constraints from parent joins refine the cost estimate.
+ *
+ * # Constraint Flow
+ * When a connection is pinned as the outer loop, it reveals constraints for
+ * connected joins. These constraints propagate through the graph, allowing
+ * other connections to update their cost estimates.
+ *
+ * Example:
+ *
+ * ```ts
+ * builder.issue.whereExists('assignee', a => a.where('name', 'Alice'))
+ * ```
+ *
+ * ```
+ * [issue]  [assignee]
+ *   |         |
+ *   |         +-- where name = 'Alice'
+ *    \        /
+ *     \      /
+ *      [join]
+ *        |
+ * ```
+ *
+ * - Initial state: Both connections have no constraints, costs are unconstrained
+ * - If `issue` chosen first: Reveals constraint `assignee_id` for assignee connection
+ * - If `assignee` chosen first: Reveals constraint `assignee_id` for issue connection
+ * - Updated costs guide the next selection
+ *
+ * # Lifecycle
+ * 1. Construct with immutable structure (ordering, filters, cost model)
+ * 2. Wire to output node during graph construction
+ * 3. Planning mutates pinned status and accumulates constraints
+ * 4. reset() clears mutable state for replanning
+ */
+export class PlannerConnection {
+    kind = 'connection';
+    // ========================================================================
+    // IMMUTABLE STRUCTURE (set during construction, never changes)
+    // ========================================================================
+    #sort;
+    #filters;
+    #model;
+    table;
+    name; // Human-readable name for debugging (defaults to table name)
+    #baseConstraints; // Constraints from parent correlation
+    #baseLimit; // Original limit from query structure (never modified)
+    selectivity; // Fraction of rows passing filters (1.0 = no filtering)
+    #output; // Set once during graph construction
+    // ========================================================================
+    // MUTABLE PLANNING STATE (changes during plan search)
+    // ========================================================================
+    /**
+     * Current limit during planning. Can be cleared (set to undefined) when a
+     * parent join is flipped, indicating this connection is now in an outer loop
+     * and should not be limited by EXISTS semantics.
+     */
+    limit;
+    /**
+     * Constraints accumulated from parent joins during planning.
+     * Key is a path through the graph (e.g., "0,1" for branch pattern [0,1]).
+     *
+     * Undefined constraints are possible when a FO converts to UFO and only
+     * a single join in the UFO is flipped - other branches report undefined.
+     */
+    #constraints;
+    /**
+     * Cached total cost (sum of all branches) to avoid redundant calculations.
+     * Invalidated when constraints change.
+     */
+    #cachedTotalCost = undefined;
+    /**
+     * Cached per-constraint costs to avoid redundant cost model calls.
+     * Maps constraint key (branch pattern string) to computed cost.
+     * Invalidated when constraints change.
+     */
+    #cachedConstraintCosts = new Map();
+    #costDirty = true;
+    constructor(table, model, sort, filters, baseConstraints, limit, name) {
+        this.table = table;
+        this.name = name ?? table;
+        this.#sort = sort;
+        this.#filters = filters;
+        this.#model = model;
+        this.#baseConstraints = baseConstraints;
+        this.#baseLimit = limit;
+        this.limit = limit;
+        this.#constraints = new Map();
+        // Compute selectivity for EXISTS child connections (baseLimit === 1)
+        // Selectivity = fraction of rows that pass filters
+        if (limit !== undefined && filters) {
+            const costWithFilters = model(table, sort, filters, undefined);
+            const costWithoutFilters = model(table, sort, undefined, undefined);
+            this.selectivity =
+                costWithoutFilters.rows > 0
+                    ? costWithFilters.rows / costWithoutFilters.rows
+                    : 1.0;
+        }
+        else {
+            // Root connections or connections without filters
+            this.selectivity = 1.0;
+        }
+    }
+    setOutput(node) {
+        this.#output = node;
+    }
+    get output() {
+        assert(this.#output !== undefined, 'Output not set');
+        return this.#output;
+    }
+    closestJoinOrSource() {
+        return 'connection';
+    }
+    /**
+     * Constraints are uniquely identified by their path through the
+     * graph.
+     *
+     * FO represents all sub-joins as a single path.
+     * UFO represents each sub-join as a separate path.
+     * The first branch in a UFO will match the path of FO so no re-set needs to happen
+     * when swapping from FO to UFO.
+     *
+     * FO swaps to UFO when a join inside FO-FI gets flipped.
+     *
+     * The max of the last element of the paths is the number of
+     * root branches.
+     */
+    propagateConstraints(path, c) {
+        const key = path.join(',');
+        this.#constraints.set(key, c);
+        // Constraints changed, invalidate cost caches
+        this.#cachedTotalCost = undefined;
+        this.#cachedConstraintCosts.clear();
+        this.#costDirty = true;
+    }
+    estimateCost(branchPattern) {
+        // If no branch pattern specified, return sum of all branches
+        // This is used by getUnpinnedConnectionCosts to get total cost
+        if (branchPattern === undefined) {
+            // Return cached total cost if still valid
+            if (!this.#costDirty && this.#cachedTotalCost !== undefined) {
+                return this.#cachedTotalCost;
+            }
+            // Calculate fresh cost - sum of all branch costs
+            let totalRows = 0;
+            let maxStartupCost = 0;
+            if (this.#constraints.size === 0) {
+                // No constraints - compute unconstrained cost (but still merge base constraints)
+                const key = '';
+                let cost = this.#cachedConstraintCosts.get(key);
+                if (cost === undefined) {
+                    // Merge base constraints even when no propagated constraints
+                    const { startupCost, rows } = this.#model(this.table, this.#sort, this.#filters, this.#baseConstraints);
+                    cost = {
+                        rows,
+                        runningCost: rows,
+                        startupCost,
+                        selectivity: this.selectivity,
+                        limit: this.limit,
+                    };
+                    this.#cachedConstraintCosts.set(key, cost);
+                }
+                totalRows = cost.rows;
+                maxStartupCost = cost.startupCost;
+            }
+            else {
+                // Sum costs for all constraint branches
+                for (const [key, constraint] of this.#constraints.entries()) {
+                    let cost = this.#cachedConstraintCosts.get(key);
+                    if (cost === undefined) {
+                        // Merge base constraints with propagated constraints
+                        const mergedConstraint = mergeConstraints(this.#baseConstraints, constraint);
+                        const { startupCost, rows } = this.#model(this.table, this.#sort, this.#filters, mergedConstraint);
+                        cost = {
+                            rows,
+                            runningCost: rows,
+                            startupCost,
+                            selectivity: this.selectivity,
+                            limit: this.limit,
+                        };
+                        this.#cachedConstraintCosts.set(key, cost);
+                    }
+                    totalRows += cost.rows;
+                    // TODO: if no branch pattern is specified, should we sum startup costs?
+                    maxStartupCost = Math.max(maxStartupCost, cost.startupCost);
+                }
+            }
+            const ret = {
+                rows: totalRows,
+                runningCost: totalRows,
+                startupCost: maxStartupCost,
+                selectivity: this.selectivity,
+                limit: this.limit,
+            };
+            // Cache total and mark as clean
+            this.#cachedTotalCost = ret;
+            this.#costDirty = false;
+            return ret;
+        }
+        // Branch pattern specified - return cost for this specific branch
+        const key = branchPattern.join(',');
+        // Check per-constraint cache first
+        let cost = this.#cachedConstraintCosts.get(key);
+        if (cost !== undefined) {
+            return cost;
+        }
+        // Cache miss - compute and cache
+        const constraint = this.#constraints.get(key);
+        // Merge base constraints with propagated constraints
+        const mergedConstraint = mergeConstraints(this.#baseConstraints, constraint);
+        const { startupCost, rows } = this.#model(this.table, this.#sort, this.#filters, mergedConstraint);
+        cost = {
+            rows,
+            runningCost: rows,
+            startupCost,
+            selectivity: this.selectivity,
+            limit: this.limit,
+        };
+        this.#cachedConstraintCosts.set(key, cost);
+        return cost;
+    }
+    /**
+     * Remove the limit from this connection.
+     * Called when a parent join is flipped, making this connection part of an
+     * outer loop that should produce all rows rather than stopping at the limit.
+     */
+    unlimit() {
+        if (this.limit !== undefined) {
+            this.limit = undefined;
+            // Limit changes do not impact connection costs.
+            // Limit is taken into account at the join level.
+            // Given that, we do not need to invalidate cost caches here.
+        }
+    }
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * For connections, we simply remove the limit.
+     */
+    propagateUnlimitFromFlippedJoin() {
+        this.unlimit();
+    }
+    reset() {
+        this.#constraints.clear();
+        this.limit = this.#baseLimit;
+        // Clear all cost caches
+        this.#cachedTotalCost = undefined;
+        this.#cachedConstraintCosts.clear();
+        this.#costDirty = true;
+    }
+    /**
+     * Capture constraint state for snapshotting.
+     * Used by PlannerGraph to save/restore planning state.
+     */
+    captureConstraints() {
+        return new Map(this.#constraints);
+    }
+    /**
+     * Restore constraint state from a snapshot.
+     * Used by PlannerGraph to restore planning state.
+     */
+    restoreConstraints(constraints) {
+        this.#constraints.clear();
+        for (const [key, value] of constraints) {
+            this.#constraints.set(key, value);
+        }
+        // Constraints changed, invalidate cost caches
+        this.#cachedTotalCost = undefined;
+        this.#cachedConstraintCosts.clear();
+        this.#costDirty = true;
+    }
+    /**
+     * Get current constraints for debugging.
+     * Returns a copy of the constraints map.
+     */
+    getConstraintsForDebug() {
+        return new Map(this.#constraints);
+    }
+    /**
+     * Get estimated cost for each constraint branch.
+     * Returns a map of constraint key to cost estimate.
+     * Forces cost calculation if not already cached.
+     */
+    getConstraintCostsForDebug() {
+        // Trigger cost calculation to populate cache
+        this.estimateCost(undefined);
+        // Return copy of cached costs
+        return new Map(this.#cachedConstraintCosts);
+    }
+}
+//# sourceMappingURL=planner-connection.js.map

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

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

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

@@ -0,0 +1,14 @@
+/**
+ * We do not know the value a constraint will take until runtime.
+ *
+ * However, we do know the column.
+ *
+ * E.g., we know that `issue.assignee_id` will be constrained to typeof issue.assignee_id.
+ */
+export type PlannerConstraint = Record<string, undefined>;
+/**
+ * Multiple flipped joins will contribute extra constraints to a parent join.
+ * These need to be merged.
+ */
+export declare function mergeConstraints(a: PlannerConstraint | undefined, b: PlannerConstraint | undefined): PlannerConstraint | undefined;
+//# sourceMappingURL=planner-constraint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner-constraint.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-constraint.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,iBAAiB,GAAG,SAAS,EAChC,CAAC,EAAE,iBAAiB,GAAG,SAAS,GAC/B,iBAAiB,GAAG,SAAS,CAI/B"}

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

@@ -0,0 +1,12 @@
+/**
+ * Multiple flipped joins will contribute extra constraints to a parent join.
+ * These need to be merged.
+ */
+export function mergeConstraints(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return { ...a, ...b };
+}
+//# sourceMappingURL=planner-constraint.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner-constraint.js","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-constraint.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,CAAgC,EAChC,CAAgC;IAEhC,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,OAAO,EAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAC,CAAC;AACtB,CAAC"}

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

@@ -0,0 +1,118 @@
+import type { PlannerConstraint } from './planner-constraint.ts';
+import type { CostEstimate, JoinType, NodeType } from './planner-node.ts';
+/**
+ * Structured debug events emitted during query planning.
+ * These events can be accumulated, printed, or analyzed to understand
+ * the planner's decision-making process.
+ */
+/**
+ * Starting a new planning attempt with a different root connection.
+ */
+export type AttemptStartEvent = {
+    type: 'attempt-start';
+    attemptNumber: number;
+    totalAttempts: number;
+};
+/**
+ * Snapshot of connection costs before selecting the next connection.
+ */
+export type ConnectionCostsEvent = {
+    type: 'connection-costs';
+    attemptNumber: number;
+    costs: Array<{
+        connection: string;
+        cost: number;
+        costEstimate: CostEstimate;
+        pinned: boolean;
+        constraints: Map<string, PlannerConstraint | undefined>;
+        constraintCosts: Map<string, CostEstimate>;
+    }>;
+};
+/**
+ * A connection was chosen and pinned.
+ */
+export type ConnectionSelectedEvent = {
+    type: 'connection-selected';
+    attemptNumber: number;
+    connection: string;
+    cost: number;
+    isRoot: boolean;
+};
+/**
+ * Constraints have been propagated through the graph.
+ */
+export type ConstraintsPropagatedEvent = {
+    type: 'constraints-propagated';
+    attemptNumber: number;
+    connectionConstraints: Array<{
+        connection: string;
+        constraints: Map<string, PlannerConstraint | undefined>;
+        constraintCosts: Map<string, CostEstimate>;
+    }>;
+};
+/**
+ * A complete plan was found for this attempt.
+ */
+export type PlanCompleteEvent = {
+    type: 'plan-complete';
+    attemptNumber: number;
+    totalCost: number;
+    nodeCosts: Array<{
+        node: string;
+        nodeType: NodeType;
+        costEstimate: CostEstimate;
+    }>;
+    joinStates: Array<{
+        join: string;
+        type: JoinType;
+    }>;
+};
+/**
+ * Planning attempt failed (e.g., unflippable join).
+ */
+export type PlanFailedEvent = {
+    type: 'plan-failed';
+    attemptNumber: number;
+    reason: string;
+};
+/**
+ * The best plan across all attempts was selected.
+ */
+export type BestPlanSelectedEvent = {
+    type: 'best-plan-selected';
+    bestAttemptNumber: number;
+    totalCost: number;
+    joinStates: Array<{
+        join: string;
+        type: JoinType;
+    }>;
+};
+/**
+ * Union of all debug event types.
+ */
+export type PlanDebugEvent = AttemptStartEvent | ConnectionCostsEvent | ConnectionSelectedEvent | ConstraintsPropagatedEvent | PlanCompleteEvent | PlanFailedEvent | BestPlanSelectedEvent;
+/**
+ * Interface for objects that receive debug events during planning.
+ */
+export interface PlanDebugger {
+    log(event: PlanDebugEvent): void;
+}
+/**
+ * Simple accumulator debugger that stores all events.
+ * Useful for tests and debugging.
+ */
+export declare class AccumulatorDebugger implements PlanDebugger {
+    readonly events: PlanDebugEvent[];
+    log(event: PlanDebugEvent): void;
+    /**
+     * Get all events of a specific type.
+     */
+    getEvents<T extends PlanDebugEvent['type']>(type: T): Extract<PlanDebugEvent, {
+        type: T;
+    }>[];
+    /**
+     * Format events as a human-readable string.
+     */
+    format(): string;
+}
+//# sourceMappingURL=planner-debug.d.ts.map

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

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

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

@@ -0,0 +1,125 @@
+/**
+ * Simple accumulator debugger that stores all events.
+ * Useful for tests and debugging.
+ */
+export class AccumulatorDebugger {
+    events = [];
+    log(event) {
+        this.events.push(event);
+    }
+    /**
+     * Get all events of a specific type.
+     */
+    getEvents(type) {
+        return this.events.filter(e => e.type === type);
+    }
+    /**
+     * Format events as a human-readable string.
+     */
+    format() {
+        const lines = [];
+        for (const event of this.events) {
+            lines.push(formatEvent(event));
+        }
+        return lines.join('\n');
+    }
+}
+/**
+ * Format a constraint object as a human-readable string.
+ */
+function formatConstraint(constraint) {
+    if (!constraint)
+        return '{}';
+    const keys = Object.keys(constraint);
+    if (keys.length === 0)
+        return '{}';
+    return '{' + keys.join(', ') + '}';
+}
+/**
+ * Format a single debug event as a human-readable string.
+ */
+function formatEvent(event) {
+    switch (event.type) {
+        case 'attempt-start':
+            return `[Attempt ${event.attemptNumber + 1}/${event.totalAttempts}] Starting planning attempt`;
+        case 'connection-costs': {
+            const lines = [`[Attempt ${event.attemptNumber + 1}] Connection costs:`];
+            for (const c of event.costs) {
+                // Format the main connection info
+                // const limitStr = c.costEstimate.limit !== undefined
+                //   ? c.costEstimate.limit.toString()
+                //   : 'none';
+                lines.push(`  ${c.connection}: cost=${c.cost.toFixed(2)}, `);
+                // Format each branch's constraints with costs
+                if (c.constraints.size === 0) {
+                    const cost = c.constraintCosts.get('');
+                    const costStr = cost ? ` cost=${cost.rows.toFixed(2)}` : '';
+                    lines.push(`    Branch [none]: {}${costStr}`);
+                }
+                else {
+                    for (const [branchKey, constraint] of c.constraints) {
+                        const branchLabel = branchKey === '' ? 'none' : branchKey;
+                        const cost = c.constraintCosts.get(branchKey);
+                        const costStr = cost ? ` cost=${cost.rows.toFixed(2)}` : '';
+                        lines.push(`    Branch [${branchLabel}]: ${formatConstraint(constraint)}${costStr}`);
+                    }
+                }
+            }
+            return lines.join('\n');
+        }
+        case 'connection-selected':
+            return (`[Attempt ${event.attemptNumber + 1}] Selected ${event.isRoot ? 'ROOT' : ''} connection: ` +
+                `${event.connection} (cost=${event.cost.toFixed(2)})`);
+        case 'constraints-propagated': {
+            const lines = [
+                `[Attempt ${event.attemptNumber + 1}] Constraints propagated:`,
+            ];
+            for (const c of event.connectionConstraints) {
+                lines.push(`  ${c.connection}:`);
+                // Format each branch's constraints with costs
+                if (c.constraints.size === 0) {
+                    const cost = c.constraintCosts.get('');
+                    const costStr = cost ? ` cost=${cost.rows.toFixed(2)}` : '';
+                    lines.push(`    Branch [none]: {}${costStr}`);
+                }
+                else {
+                    for (const [branchKey, constraint] of c.constraints) {
+                        const branchLabel = branchKey === '' ? 'none' : branchKey;
+                        const cost = c.constraintCosts.get(branchKey);
+                        const costStr = cost ? ` cost=${cost.rows.toFixed(2)}` : '';
+                        lines.push(`    Branch [${branchLabel}]: ${formatConstraint(constraint)}${costStr}`);
+                    }
+                }
+            }
+            return lines.join('\n');
+        }
+        case 'plan-complete': {
+            const lines = [
+                `[Attempt ${event.attemptNumber + 1}] Plan complete! Total cost: ${event.totalCost.toFixed(2)}`,
+                `  Joins:`,
+            ];
+            for (const j of event.joinStates) {
+                lines.push(`    ${j.join}: ${j.type}`);
+            }
+            lines.push(`  Node costs:`);
+            for (const n of event.nodeCosts) {
+                lines.push(`    ${n.node} (${n.nodeType}): ${n.costEstimate.runningCost.toFixed(2)}`);
+            }
+            return lines.join('\n');
+        }
+        case 'plan-failed':
+            return `[Attempt ${event.attemptNumber + 1}] Plan FAILED: ${event.reason}`;
+        case 'best-plan-selected': {
+            const lines = [
+                `[FINAL] Best plan selected from attempt ${event.bestAttemptNumber + 1}`,
+                `  Total cost: ${event.totalCost.toFixed(2)}`,
+                `  Joins:`,
+            ];
+            for (const j of event.joinStates) {
+                lines.push(`    ${j.join}: ${j.type}`);
+            }
+            return lines.join('\n');
+        }
+    }
+}
+//# sourceMappingURL=planner-debug.js.map

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

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

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

@@ -0,0 +1,37 @@
+import type { PlannerConstraint } from './planner-constraint.ts';
+import type { CostEstimate, JoinOrConnection, PlannerNode } from './planner-node.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: PlannerNode[]);
+    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(branchPattern?: number[]): CostEstimate;
+    propagateConstraints(branchPattern: number[], constraint: PlannerConstraint | undefined, from: PlannerNode): 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,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;;IACvB,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;gBAKtB,MAAM,EAAE,WAAW,EAAE;IAKjC,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,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY;IAmFpD,oBAAoB,CAClB,aAAa,EAAE,MAAM,EAAE,EACvB,UAAU,EAAE,iBAAiB,GAAG,SAAS,EACzC,IAAI,EAAE,WAAW,GAChB,IAAI;CAsBR"}