ppef 1.0.0 → 1.0.1

package/dist/executor/checkpoint-storage.js

@@ -0,0 +1,370 @@
+/**
+ * Checkpoint Storage Backends
+ *
+ * Pluggable storage for experiment checkpoints:
+ * - FileStorage: JSON files in local filesystem (fast, no git required)
+ * - GitStorage: Git notes attached to commits (version controlled, shareable)
+ *
+ * Dependency Injection:
+ * - FileSystem interface enables mocking for tests
+ * - Lock interface enables pluggable concurrency control
+ *
+ * Usage:
+ * ```typescript
+ * // File-based (default)
+ * const fileStorage = new FileStorage("results/execute/checkpoint.json");
+ *
+ * // Git-based (stores as git notes)
+ * const gitStorage = new GitStorage("results-execute");
+ *
+ * // With mock file system for testing
+ * const mockFs = new MockFileSystem();
+ * const fileStorage = new FileStorage("checkpoint.json", mockFs);
+ *
+ * // Auto-detect based on mode
+ * const storage = createCheckpointStorage("file", "results/execute/checkpoint.json");
+ * const storage = createCheckpointStorage("git", "results-execute");
+ * ```
+ */
+import { execSync } from "node:child_process";
+import { mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+/**
+ * Production file system implementation using node:fs/promises.
+ */
+export class NodeFileSystem {
+    async readFile(path) {
+        return readFile(path, "utf-8");
+    }
+    async writeFile(path, content) {
+        await writeFile(path, content, "utf-8");
+    }
+    async mkdir(path, options) {
+        await mkdir(path, options);
+    }
+    async unlink(path) {
+        await unlink(path);
+    }
+    async access(path) {
+        const { constants } = await import("node:fs/promises");
+        const { access } = await import("node:fs/promises");
+        await access(path, constants.F_OK);
+    }
+    async readdir(path) {
+        return readdir(path);
+    }
+}
+/**
+ * In-memory lock for single-process use.
+ * Provides queue-based locking for concurrent saves within a process.
+ */
+export class InMemoryLock {
+    locked = false;
+    queue = [];
+    async acquire() {
+        return new Promise((resolve) => {
+            if (this.locked) {
+                this.queue.push(resolve);
+            }
+            else {
+                this.locked = true;
+                resolve();
+            }
+        });
+    }
+    release() {
+        const next = this.queue.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this.locked = false;
+        }
+    }
+}
+/**
+ * File-based checkpoint storage.
+ * Stores checkpoints as JSON files in the local filesystem.
+ *
+ * Supports dependency injection of FileSystem for testing.
+ */
+export class FileStorage {
+    type = "file";
+    path;
+    fs;
+    constructor(path, fs) {
+        this.path = resolve(path);
+        this.fs = fs ?? new NodeFileSystem();
+    }
+    async load() {
+        try {
+            const content = await this.fs.readFile(this.path);
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    async save(data) {
+        try {
+            await this.fs.mkdir(dirname(this.path), { recursive: true });
+            data.updatedAt = new Date().toISOString();
+            const content = JSON.stringify(data, null, 2);
+            await this.fs.writeFile(this.path, content);
+        }
+        catch (error) {
+            console.warn(`Failed to save checkpoint to ${this.path}: ${String(error)}`);
+            throw error;
+        }
+    }
+    async delete() {
+        try {
+            await this.fs.unlink(this.path);
+        }
+        catch {
+            // Ignore if file doesn't exist
+        }
+    }
+    async exists() {
+        try {
+            const content = await this.fs.readFile(this.path);
+            const data = JSON.parse(content);
+            return data !== null && typeof data === "object";
+        }
+        catch {
+            return false;
+        }
+    }
+    getPath() {
+        return this.path;
+    }
+    /**
+     * Find all worker checkpoint shard files in a directory.
+     * Looks for files matching the pattern "checkpoint-worker-*.json".
+     *
+     * @param baseDir - Directory to search for shard files
+     * @param fs - FileSystem implementation (defaults to NodeFileSystem)
+     * @returns Sorted array of shard file paths
+     */
+    static async findShards(baseDir, fs) {
+        const fileSystem = fs ?? new NodeFileSystem();
+        const shardFiles = [];
+        try {
+            const entries = await fileSystem.readdir(baseDir);
+            for (const entry of entries) {
+                if (entry.startsWith("checkpoint-worker-") && entry.endsWith(".json")) {
+                    shardFiles.push(resolve(baseDir, entry));
+                }
+            }
+        }
+        catch {
+            // Directory doesn't exist or is not readable
+            return [];
+        }
+        // Sort by worker index (extract numeric part for proper ordering)
+        return shardFiles.sort((a, b) => {
+            const aMatch = /checkpoint-worker-(\d+)\.json/.exec(a);
+            const bMatch = /checkpoint-worker-(\d+)\.json/.exec(b);
+            const aIndex = aMatch ? Number.parseInt(aMatch[1], 10) : -1;
+            const bIndex = bMatch ? Number.parseInt(bMatch[1], 10) : -1;
+            return aIndex - bIndex;
+        });
+    }
+    /**
+     * Generate a shard file path for a specific worker.
+     *
+     * @param baseDir - Base directory for checkpoints
+     * @param workerIndex - Worker index (0-based)
+     * @returns Path to the shard checkpoint file
+     */
+    static shardPath(baseDir, workerIndex) {
+        return resolve(baseDir, `checkpoint-worker-${String(workerIndex).padStart(2, "0")}.json`);
+    }
+}
+/**
+ * Git-based checkpoint storage using git notes.
+ *
+ * Checkpoints are stored as git notes attached to the current HEAD.
+ * This provides:
+ * - Version control: Checkpoints tracked in git history
+ * - Shareability: Team members can access each other's checkpoints
+ * - Reproducibility: Linked to specific commits
+ * - Safety: No accidental deletion through git clean
+ *
+ * Each checkpoint is stored as a note with a unique ref based on the namespace.
+ */
+export class GitStorage {
+    type = "git";
+    namespace;
+    repoRoot;
+    constructor(namespace, repoRoot = process.cwd()) {
+        this.namespace = namespace;
+        this.repoRoot = repoRoot;
+    }
+    /**
+     * Get the full notes ref for this checkpoint.
+     */
+    getNotesRef() {
+        return `refs/notes/checkpoints/${this.namespace}`;
+    }
+    /**
+     * Check if git is available and we're in a git repo.
+     */
+    checkGitAvailable() {
+        try {
+            execSync("git rev-parse --git-dir", {
+                cwd: this.repoRoot,
+                stdio: "pipe",
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    load() {
+        if (!this.checkGitAvailable()) {
+            console.warn("Git not available, falling back to null checkpoint");
+            return null;
+        }
+        try {
+            // Get the note content
+            const content = execSync(`git --work-tree="${this.repoRoot}" notes --ref=${this.getNotesRef()} show 2>/dev/null || echo ""`, { encoding: "utf-8", cwd: this.repoRoot });
+            if (!content.trim()) {
+                return null;
+            }
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    async save(data) {
+        if (!this.checkGitAvailable()) {
+            console.warn("Git not available, skipping checkpoint save");
+            return;
+        }
+        try {
+            data.updatedAt = new Date().toISOString();
+            // Write to a temp file first
+            const temporaryPath = resolve(this.repoRoot, ".git", "checkpoint-tmp.json");
+            await writeFile(temporaryPath, JSON.stringify(data, null, 2), "utf-8");
+            // Add the note using the temp file
+            execSync(`git --work-tree="${this.repoRoot}" notes --ref=${this.getNotesRef()} add -F "${temporaryPath}"`, { stdio: "pipe", cwd: this.repoRoot });
+            // Clean up temp file
+            await unlink(temporaryPath).catch(() => undefined);
+        }
+        catch (error) {
+            console.warn(`Failed to save git checkpoint: ${String(error)}`);
+            throw error;
+        }
+    }
+    delete() {
+        if (!this.checkGitAvailable()) {
+            return undefined;
+        }
+        try {
+            execSync(`git --work-tree="${this.repoRoot}" notes --ref=${this.getNotesRef()} remove`, {
+                stdio: "pipe",
+                cwd: this.repoRoot,
+            });
+        }
+        catch {
+            // Ignore if note doesn't exist
+        }
+        return undefined;
+    }
+    exists() {
+        const data = this.load();
+        return data !== null;
+    }
+    /**
+     * List all checkpoints for this namespace across git history.
+     * Returns a map of commit SHA to checkpoint metadata.
+     */
+    listHistory() {
+        if (!this.checkGitAvailable()) {
+            return [];
+        }
+        try {
+            // Get all commits that have notes for this namespace
+            const output = execSync(`git --work-tree="${this.repoRoot}" notes --ref=${this.getNotesRef()} list`, { encoding: "utf-8", cwd: this.repoRoot });
+            const lines = output.trim().split("\n");
+            const results = [];
+            for (const line of lines) {
+                const [commitSha] = line.split(/\s+/);
+                try {
+                    const content = execSync(`git --work-tree="${this.repoRoot}" notes --ref=${this.getNotesRef()} show ${commitSha}`, { encoding: "utf-8", cwd: this.repoRoot });
+                    const checkpoint = JSON.parse(content);
+                    results.push({ commit: commitSha, checkpoint });
+                }
+                catch {
+                    // Skip invalid entries
+                }
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Restore checkpoint from a specific commit.
+     * @param commitSha
+     */
+    restoreFromCommit(commitSha) {
+        if (!this.checkGitAvailable()) {
+            return null;
+        }
+        try {
+            const content = execSync(`git --work-tree="${this.repoRoot}" notes --ref=${this.getNotesRef()} show ${commitSha}`, { encoding: "utf-8", cwd: this.repoRoot });
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Create a checkpoint storage instance based on mode.
+ * @param mode - Storage mode ("file", "git", or "auto")
+ * @param pathOrNamespace - File path or git namespace
+ * @param repoRoot - Git repository root (for git storage)
+ */
+export const createCheckpointStorage = (mode, pathOrNamespace, repoRoot) => {
+    const effectiveMode = mode === "auto" ? detectPreferredMode() : mode;
+    if (effectiveMode === "git") {
+        return new GitStorage(pathOrNamespace, repoRoot);
+    }
+    return new FileStorage(pathOrNamespace);
+};
+/**
+ * Detect preferred checkpoint mode based on environment.
+ * Returns "git" if in a git repo with commits, otherwise "file".
+ */
+const detectPreferredMode = () => {
+    try {
+        // Check if we're in a git repo with commits
+        execSync("git rev-parse --git-dir > /dev/null 2>&1", { stdio: "pipe" });
+        // Check if there are any commits
+        try {
+            execSync("git rev-parse HEAD > /dev/null 2>&1", { stdio: "pipe" });
+            return "git";
+        }
+        catch {
+            // Git repo but no commits yet
+            return "file";
+        }
+    }
+    catch {
+        // Not a git repo
+        return "file";
+    }
+};
+/**
+ * Get default checkpoint namespace for git storage.
+ * Based on results directory path.
+ * @param resultsDir
+ */
+export const getGitNamespace = (resultsDir) => resultsDir.replace(/[/\\]/g, "-").replace(/^\./, "").replace(/^\/+/, "");
+//# sourceMappingURL=checkpoint-storage.js.map

package/dist/executor/checkpoint-storage.js.map

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

package/dist/executor/checkpoint-types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Checkpoint Types
+ *
+ * Central type definitions for the checkpoint system.
+ * Separated from implementation files for clarity and testability.
+ */
+import type { CheckpointStorage, Lock } from "./checkpoint-storage.js";
+/**
+ * Checkpoint manager configuration options.
+ */
+export interface CheckpointConfig {
+    /** Storage backend for checkpoint data */
+    storage: CheckpointStorage;
+    /** Concurrency lock for checkpoint saves */
+    lock?: Lock;
+    /** Worker identity for sharded mode */
+    workerIndex?: number;
+    /** Total number of workers in sharded mode */
+    totalWorkers?: number;
+    /** Base checkpoint path (for sharding) */
+    basePath?: string;
+}
+/**
+ * Worker identity for sharded checkpoint execution.
+ */
+export interface WorkerIdentity {
+    /** Index of this worker (0-based) */
+    index: number;
+    /** Total number of workers */
+    total: number;
+    /** Human-readable name */
+    name: string;
+}
+/**
+ * Checkpoint shard information.
+ */
+export interface CheckpointShard {
+    /** Path to this shard's checkpoint file */
+    path: string;
+    /** Worker index that owns this shard */
+    workerIndex: number;
+    /** Number of completed runs in this shard */
+    completedCount: number;
+    /** Whether this shard exists and is valid */
+    valid: boolean;
+}
+export { type Lock } from "./checkpoint-storage.js";
+//# sourceMappingURL=checkpoint-types.d.ts.map

package/dist/executor/checkpoint-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-types.d.ts","sourceRoot":"","sources":["../../src/executor/checkpoint-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAIvE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,0CAA0C;IAC1C,OAAO,EAAE,iBAAiB,CAAC;IAE3B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,IAAI,CAAC;IAEZ,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IAEd,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IAEd,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IAEb,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IAEpB,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IAEvB,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAC;CACf;AAED,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/executor/checkpoint-types.js

@@ -0,0 +1,8 @@
+/**
+ * Checkpoint Types
+ *
+ * Central type definitions for the checkpoint system.
+ * Separated from implementation files for clarity and testability.
+ */
+export {};
+//# sourceMappingURL=checkpoint-types.js.map

package/dist/executor/checkpoint-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-types.js","sourceRoot":"","sources":["../../src/executor/checkpoint-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/executor/executor.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Experiment Executor
+ *
+ * Orchestrates experiment execution across SUTs and cases.
+ * Handles error isolation, progress reporting, and result collection.
+ */
+import type { CaseDefinition } from "../types/case.js";
+import type { EvaluationResult } from "../types/result.js";
+import type { SutDefinition } from "../types/sut.js";
+/**
+ * Configuration for experiment execution.
+ */
+export interface ExecutorConfig {
+    /** Continue execution if a single run fails */
+    continueOnError: boolean;
+    /** Number of repetitions per case (for statistical analysis) */
+    repetitions: number;
+    /** Random seed base (incremented per repetition) */
+    seedBase: number;
+    /** Timeout per run in milliseconds (0 = no timeout) */
+    timeoutMs: number;
+    /** Whether to collect provenance information */
+    collectProvenance: boolean;
+    /** Number of concurrent runs (1 = sequential) */
+    concurrency?: number;
+    /** Progress callback */
+    onProgress?: (progress: ExecutionProgress) => void;
+    /** Per-run callback (can be async) */
+    onResult?: (result: EvaluationResult) => void | Promise<void>;
+    /** Enable memory monitoring (default: true) */
+    monitorMemory?: boolean;
+    /** Memory warning threshold in MB (default: 1024) */
+    memoryWarningThresholdMb?: number;
+    /** Memory critical threshold in MB (default: 2048) */
+    memoryCriticalThresholdMb?: number;
+    /** Abort execution at critical memory level (default: false) */
+    abortOnMemoryCritical?: boolean;
+}
+/**
+ * Default executor configuration.
+ */
+export declare const DEFAULT_EXECUTOR_CONFIG: ExecutorConfig;
+/**
+ * Execution progress report.
+ */
+export interface ExecutionProgress {
+    /** Total planned runs */
+    total: number;
+    /** Completed runs */
+    completed: number;
+    /** Failed runs */
+    failed: number;
+    /** Current SUT */
+    currentSut?: string;
+    /** Current case */
+    currentCase?: string;
+    /** Current repetition */
+    currentRepetition?: number;
+    /** Elapsed time in milliseconds */
+    elapsedMs: number;
+}
+/**
+ * Execution summary returned after completion.
+ */
+export interface ExecutionSummary {
+    /** Total runs attempted */
+    totalRuns: number;
+    /** Successful runs */
+    successfulRuns: number;
+    /** Failed runs */
+    failedRuns: number;
+    /** Total elapsed time */
+    elapsedMs: number;
+    /** Results collected */
+    results: EvaluationResult[];
+    /** Errors encountered */
+    errors: {
+        runId: string;
+        error: string;
+    }[];
+}
+/**
+ * Execution plan for a single run.
+ */
+export interface PlannedRun {
+    /** Deterministic run ID */
+    runId: string;
+    /** SUT to execute */
+    sutId: string;
+    /** Case to run against */
+    caseId: string;
+    /** Repetition number */
+    repetition: number;
+    /** Random seed */
+    seed: number;
+    /** Configuration overrides */
+    config?: Record<string, unknown>;
+}
+/**
+ * Experiment executor.
+ *
+ * @template TInput - The resource type (e.g., Graph, Dataset)
+ * @template TInputs - The algorithm inputs type
+ * @template TResult - The algorithm result type
+ */
+export declare class Executor<TInput = unknown, TInputs = unknown, TResult = unknown> {
+    private readonly config;
+    private readonly inputCache;
+    private readonly memoryMonitor?;
+    constructor(config?: Partial<ExecutorConfig>);
+    /**
+     * Plan execution runs without executing.
+     *
+     * @param suts - SUTs to execute
+     * @param cases - Cases to run against
+     * @returns Array of planned runs
+     */
+    plan(suts: SutDefinition<TInputs, TResult>[], cases: CaseDefinition<TInput, TInputs>[]): PlannedRun[];
+    /**
+     * Execute all planned runs.
+     *
+     * @param suts - SUTs to execute
+     * @param cases - Cases to run against
+     * @param metricsExtractor - Function to extract metrics from result
+     * @param plannedRuns - Optional pre-filtered planned runs (for parallel workers)
+     * @returns Execution summary with all results
+     */
+    execute(suts: SutDefinition<TInputs, TResult>[], cases: CaseDefinition<TInput, TInputs>[], metricsExtractor: (result: TResult) => Record<string, number>, plannedRuns?: PlannedRun[]): Promise<ExecutionSummary>;
+    /**
+     * Execute runs sequentially (original behavior).
+     * @param plannedRuns
+     * @param sutMap
+     * @param caseMap
+     * @param metricsExtractor
+     * @param startTime
+     * @internal
+     */
+    private executeSequential;
+    /**
+     * Execute runs in parallel with a concurrency limit.
+     * @param plannedRuns
+     * @param sutMap
+     * @param caseMap
+     * @param metricsExtractor
+     * @param startTime
+     * @param concurrency
+     * @internal
+     */
+    private executeParallel;
+    /**
+     * Execute a single run.
+     * @param run
+     * @param sutDef
+     * @param caseDef
+     * @param metricsExtractor
+     */
+    private executeRun;
+}
+/**
+ * Create a default executor with standard configuration.
+ * @param config
+ */
+export declare const createExecutor: <TInput = unknown, TInputs = unknown, TResult = unknown>(config?: Partial<ExecutorConfig>) => Executor<TInput, TInputs, TResult>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/executor/executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAa,MAAM,kBAAkB,CAAC;AAClE,OAAO,KAAK,EAAqB,gBAAgB,EAAc,MAAM,oBAAoB,CAAC;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIrD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,+CAA+C;IAC/C,eAAe,EAAE,OAAO,CAAC;IAEzB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IAEpB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IAEjB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAElB,gDAAgD;IAChD,iBAAiB,EAAE,OAAO,CAAC;IAE3B,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,wBAAwB;IACxB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAEnD,sCAAsC;IACtC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D,+CAA+C;IAC/C,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,qDAAqD;IACrD,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAElC,sDAAsD;IACtD,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC,gEAAgE;IAChE,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,cAMrC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IAEd,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAElB,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IAEf,kBAAkB;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,yBAAyB;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAElB,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IAEvB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IAEnB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAElB,wBAAwB;IACxB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAE5B,yBAAyB;IACzB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IAEd,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IAEd,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IAEf,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IAEnB,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IAEb,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAwCD;;;;;;GAMG;AACH,qBAAa,QAAQ,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC3E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAgB;gBAEnC,MAAM,GAAE,OAAO,CAAC,cAAc,CAAM;IAyBhD;;;;;;OAMG;IACH,IAAI,CACH,IAAI,EAAE,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EACvC,KAAK,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GACtC,UAAU,EAAE;IA4Bf;;;;;;;;OAQG;IACG,OAAO,CACZ,IAAI,EAAE,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EACvC,KAAK,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7D,WAAW,CAAC,EAAE,UAAU,EAAE,GACxB,OAAO,CAAC,gBAAgB,CAAC;IAgC5B;;;;;;;;OAQG;YACW,iBAAiB;IAqE/B;;;;;;;;;OASG;YACW,eAAe;IAwG7B;;;;;;OAMG;YACW,UAAU;CAkHxB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EACpF,SAAS,OAAO,CAAC,cAAc,CAAC,KAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAyB,CAAC"}