mcard-js 2.1.12 → 2.1.13

package/dist/storage/schema.d.ts

@@ -0,0 +1,162 @@
+/**
+ * MCard Database Schema Loader for JavaScript/TypeScript
+ *
+ * Singleton implementation that loads all schemas from:
+ *   schema/mcard_schema.sql (SINGLE SOURCE OF TRUTH)
+ *
+ * This ensures schema consistency between Python and JavaScript runtimes.
+ *
+ * Usage:
+ *   import { MCardSchema } from './schema';
+ *
+ *   const schema = MCardSchema.getInstance();
+ *   const cardSchema = schema.getTable('card');
+ *   schema.initAllTables(db);
+ *
+ * Architecture Layers:
+ *   Layer 1: Core Content Storage (card)
+ *   Layer 2: Handle System (handle_registry, handle_history)
+ *   Layer 3: Vector Storage (mcard_vector_metadata, mcard_embeddings)
+ *   Layer 4: Semantic Versioning (handle_version_vectors, similarity_cache)
+ *   Layer 5: Knowledge Graph (entities, relationships, communities)
+ *
+ * See: docs/architecture/Handle_Vector_Similarity_Design.md
+ */
+export type SchemaLayer = 'core' | 'handle' | 'vector' | 'semantic' | 'graph' | 'metadata';
+/**
+ * Singleton class for MCard database schema management.
+ *
+ * Ensures all schema definitions come from the single source of truth:
+ * schema/mcard_schema.sql
+ */
+export declare class MCardSchema {
+    private static instance;
+    private schemaPath;
+    private rawSql;
+    private statements;
+    private tables;
+    private indexes;
+    private loaded;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     */
+    static getInstance(): MCardSchema;
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance(): void;
+    private load;
+    private parseStatements;
+    private extractName;
+    getSchemaPath(): string;
+    getTable(tableName: string): string | undefined;
+    getIndex(indexName: string): string | undefined;
+    getAllTables(): Map<string, string>;
+    getAllIndexes(): Map<string, string>;
+    getAllStatements(): string[];
+    getTablesByLayer(layer: SchemaLayer): string[];
+    getLayerStatements(layer: SchemaLayer): string[];
+    private execStatements;
+    initLayer(db: {
+        exec: (sql: string) => void;
+    }, layer: SchemaLayer): number;
+    initCoreTables(db: {
+        exec: (sql: string) => void;
+    }): number;
+    initHandleTables(db: {
+        exec: (sql: string) => void;
+    }): number;
+    initVectorTables(db: {
+        exec: (sql: string) => void;
+    }, enableFts?: boolean): number;
+    initSemanticTables(db: {
+        exec: (sql: string) => void;
+    }): number;
+    initGraphTables(db: {
+        exec: (sql: string) => void;
+    }): number;
+    initAllTables(db: {
+        exec: (sql: string) => void;
+    }, options?: {
+        enableFts?: boolean;
+        enableGraph?: boolean;
+        enableSemantic?: boolean;
+    }): number;
+    initVec0Table(db: {
+        exec: (sql: string) => void;
+    }, dimensions: number): void;
+}
+export declare const CARD_TABLE_SCHEMA: string;
+export declare const HANDLE_REGISTRY_SCHEMA: string;
+export declare const HANDLE_HISTORY_SCHEMA: string;
+export declare const HANDLE_INDEX_SCHEMA: string;
+export declare const VECTOR_METADATA_SCHEMA: string;
+export declare const VECTOR_METADATA_INDEX: string;
+export declare const VECTOR_EMBEDDINGS_SCHEMA: string;
+export declare const VECTOR_FTS_SCHEMA: string;
+export declare const HANDLE_VERSION_VECTORS_SCHEMA: string;
+export declare const HANDLE_VERSION_VECTORS_INDEXES: string;
+export declare const VERSION_SIMILARITY_CACHE_SCHEMA: string;
+export declare const VERSION_SIMILARITY_CACHE_INDEX: string;
+export declare const GRAPH_ENTITY_SCHEMA: string;
+export declare const GRAPH_ENTITY_INDEX_NAME: string;
+export declare const GRAPH_ENTITY_INDEX_TYPE: string;
+export declare const GRAPH_ENTITY_INDEX_SOURCE: string;
+export declare const GRAPH_RELATIONSHIP_SCHEMA: string;
+export declare const GRAPH_RELATIONSHIP_INDEX_SOURCE: string;
+export declare const GRAPH_RELATIONSHIP_INDEX_TARGET: string;
+export declare const GRAPH_COMMUNITY_SCHEMA: string;
+export declare const GRAPH_COMMUNITY_INDEX_LEVEL: string;
+export declare const GRAPH_EXTRACTION_SCHEMA: string;
+export declare const CORE_SCHEMAS: {
+    card: string;
+    handleRegistry: string;
+    handleHistory: string;
+    handleIndex: string;
+};
+export declare const VECTOR_SCHEMAS: {
+    metadata: string;
+    metadataIndex: string;
+    embeddings: string;
+    fts: string;
+};
+export declare const SEMANTIC_SCHEMAS: {
+    handleVersionVectors: string;
+    handleVersionVectorsIndexes: string;
+    similarityCache: string;
+    similarityCacheIndex: string;
+};
+export declare const GRAPH_SCHEMAS: {
+    entities: string;
+    entityIndexName: string;
+    entityIndexType: string;
+    entityIndexSource: string;
+    relationships: string;
+    relIndexSource: string;
+    relIndexTarget: string;
+    communities: string;
+    communityIndexLevel: string;
+    extractions: string;
+};
+export declare function initCoreSchemas(db: {
+    exec: (sql: string) => void;
+}): void;
+export declare function initVectorSchemas(db: {
+    exec: (sql: string) => void;
+}, enableFts?: boolean): void;
+export declare function initSemanticSchemas(db: {
+    exec: (sql: string) => void;
+}): void;
+export declare function initGraphSchemas(db: {
+    exec: (sql: string) => void;
+}): void;
+export declare function initAllSchemas(db: {
+    exec: (sql: string) => void;
+}, options?: {
+    enableFts?: boolean;
+    enableGraph?: boolean;
+    enableSemantic?: boolean;
+}): void;
+export declare function getVec0Schema(dimensions: number): string;
+//# sourceMappingURL=schema.d.ts.map

package/dist/storage/schema.d.ts.map

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

package/dist/storage/schema.js

@@ -0,0 +1,373 @@
+/**
+ * MCard Database Schema Loader for JavaScript/TypeScript
+ *
+ * Singleton implementation that loads all schemas from:
+ *   schema/mcard_schema.sql (SINGLE SOURCE OF TRUTH)
+ *
+ * This ensures schema consistency between Python and JavaScript runtimes.
+ *
+ * Usage:
+ *   import { MCardSchema } from './schema';
+ *
+ *   const schema = MCardSchema.getInstance();
+ *   const cardSchema = schema.getTable('card');
+ *   schema.initAllTables(db);
+ *
+ * Architecture Layers:
+ *   Layer 1: Core Content Storage (card)
+ *   Layer 2: Handle System (handle_registry, handle_history)
+ *   Layer 3: Vector Storage (mcard_vector_metadata, mcard_embeddings)
+ *   Layer 4: Semantic Versioning (handle_version_vectors, similarity_cache)
+ *   Layer 5: Knowledge Graph (entities, relationships, communities)
+ *
+ * See: docs/architecture/Handle_Vector_Similarity_Design.md
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+// ESM compatibility: get __dirname equivalent
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// ─────────────────────────────────────────────────────────────────────────────
+// Schema File Location
+// ─────────────────────────────────────────────────────────────────────────────
+function findSchemaPath() {
+    const pathsToTry = [
+        join(__dirname, '..', '..', '..', 'schema', 'mcard_schema.sql'),
+        join(__dirname, '..', '..', 'schema', 'mcard_schema.sql'),
+        join(process.cwd(), 'schema', 'mcard_schema.sql'),
+    ];
+    for (const path of pathsToTry) {
+        const resolved = resolve(path);
+        if (existsSync(resolved)) {
+            return resolved;
+        }
+    }
+    throw new Error(`Could not find schema/mcard_schema.sql. Tried: ${pathsToTry.join(', ')}`);
+}
+function findVectorSchemaPath() {
+    const pathsToTry = [
+        join(__dirname, '..', '..', '..', 'schema', 'mcard_vector_schema.sql'),
+        join(__dirname, '..', '..', 'schema', 'mcard_vector_schema.sql'),
+        join(process.cwd(), 'schema', 'mcard_vector_schema.sql'),
+    ];
+    for (const path of pathsToTry) {
+        const resolved = resolve(path);
+        if (existsSync(resolved)) {
+            return resolved;
+        }
+    }
+    return null;
+}
+const TABLE_LAYERS = {
+    // Layer 1: Core
+    'card': 'core',
+    // Layer 2: Handle System
+    'handle_registry': 'handle',
+    'handle_history': 'handle',
+    // Layer 3: Vector Storage
+    'mcard_vector_metadata': 'vector',
+    'mcard_embeddings': 'vector',
+    'mcard_fts': 'vector',
+    // Layer 4: Semantic Versioning
+    'handle_version_vectors': 'semantic',
+    'version_similarity_cache': 'semantic',
+    // Layer 5: Knowledge Graph
+    'graph_entities': 'graph',
+    'graph_relationships': 'graph',
+    'graph_communities': 'graph',
+    'graph_extractions': 'graph',
+    // Metadata
+    'schema_version': 'metadata',
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Singleton Schema Manager
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Singleton class for MCard database schema management.
+ *
+ * Ensures all schema definitions come from the single source of truth:
+ * schema/mcard_schema.sql
+ */
+export class MCardSchema {
+    static instance = null;
+    schemaPath = '';
+    rawSql = '';
+    statements = [];
+    tables = new Map();
+    indexes = new Map();
+    loaded = false;
+    constructor() { }
+    /**
+     * Get the singleton instance.
+     */
+    static getInstance() {
+        if (!MCardSchema.instance) {
+            MCardSchema.instance = new MCardSchema();
+            MCardSchema.instance.load();
+        }
+        return MCardSchema.instance;
+    }
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance() {
+        MCardSchema.instance = null;
+    }
+    load() {
+        if (this.loaded)
+            return;
+        this.schemaPath = findSchemaPath();
+        this.rawSql = readFileSync(this.schemaPath, 'utf-8');
+        // Load vector schema if available
+        const vectorSchemaPath = findVectorSchemaPath();
+        if (vectorSchemaPath) {
+            const vectorSql = readFileSync(vectorSchemaPath, 'utf-8');
+            this.rawSql += "\n\n" + vectorSql;
+        }
+        this.statements = this.parseStatements(this.rawSql);
+        for (const stmt of this.statements) {
+            const name = this.extractName(stmt);
+            if (name) {
+                const upper = stmt.toUpperCase();
+                if (upper.includes('CREATE TABLE') || upper.includes('CREATE VIRTUAL TABLE')) {
+                    this.tables.set(name.toLowerCase(), stmt);
+                }
+                else if (upper.includes('CREATE INDEX')) {
+                    this.indexes.set(name.toLowerCase(), stmt);
+                }
+            }
+        }
+        this.loaded = true;
+    }
+    parseStatements(sql) {
+        // Remove block comments
+        sql = sql.replace(/\/\*[\s\S]*?\*\//g, '');
+        const statements = [];
+        let current = [];
+        for (const line of sql.split('\n')) {
+            // Skip line comments
+            const stripped = line.split('--')[0].trim();
+            if (!stripped)
+                continue;
+            current.push(stripped);
+            if (stripped.endsWith(';')) {
+                const statement = current.join(' ');
+                // Skip INSERT statements
+                if (!statement.trim().toUpperCase().startsWith('INSERT')) {
+                    statements.push(statement);
+                }
+                current = [];
+            }
+        }
+        return statements.filter(s => s.trim());
+    }
+    extractName(statement) {
+        // Handle CREATE TABLE
+        let match = statement.match(/CREATE\s+(?:VIRTUAL\s+)?TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+)/i);
+        if (match)
+            return match[1];
+        // Handle CREATE INDEX
+        match = statement.match(/CREATE\s+INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+)/i);
+        if (match)
+            return match[1];
+        return null;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Schema Access
+    // ─────────────────────────────────────────────────────────────────────────
+    getSchemaPath() {
+        return this.schemaPath;
+    }
+    getTable(tableName) {
+        return this.tables.get(tableName.toLowerCase());
+    }
+    getIndex(indexName) {
+        return this.indexes.get(indexName.toLowerCase());
+    }
+    getAllTables() {
+        return new Map(this.tables);
+    }
+    getAllIndexes() {
+        return new Map(this.indexes);
+    }
+    getAllStatements() {
+        return [...this.statements];
+    }
+    getTablesByLayer(layer) {
+        return Object.entries(TABLE_LAYERS)
+            .filter(([_, l]) => l === layer)
+            .map(([name, _]) => name);
+    }
+    getLayerStatements(layer) {
+        const statements = [];
+        const tables = this.getTablesByLayer(layer);
+        // Add tables
+        for (const table of tables) {
+            const stmt = this.getTable(table);
+            if (stmt)
+                statements.push(stmt);
+        }
+        // Add indexes for these tables
+        for (const [_, stmt] of this.indexes) {
+            const match = stmt.match(/ON\s+(\w+)/i);
+            if (match && tables.includes(match[1].toLowerCase())) {
+                statements.push(stmt);
+            }
+        }
+        return statements;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Database Initialization
+    // ─────────────────────────────────────────────────────────────────────────
+    execStatements(db, statements) {
+        for (const stmt of statements) {
+            db.exec(stmt);
+        }
+        return statements.length;
+    }
+    initLayer(db, layer) {
+        return this.execStatements(db, this.getLayerStatements(layer));
+    }
+    initCoreTables(db) {
+        return this.initLayer(db, 'core');
+    }
+    initHandleTables(db) {
+        return this.initLayer(db, 'handle');
+    }
+    initVectorTables(db, enableFts = true) {
+        const statements = this.getLayerStatements('vector')
+            .filter(s => enableFts || !s.toLowerCase().includes('fts'));
+        return this.execStatements(db, statements);
+    }
+    initSemanticTables(db) {
+        return this.initLayer(db, 'semantic');
+    }
+    initGraphTables(db) {
+        return this.initLayer(db, 'graph');
+    }
+    initAllTables(db, options = {}) {
+        const { enableFts = true, enableGraph = true, enableSemantic = true } = options;
+        let count = 0;
+        count += this.initCoreTables(db);
+        count += this.initHandleTables(db);
+        count += this.initVectorTables(db, enableFts);
+        if (enableSemantic) {
+            count += this.initSemanticTables(db);
+        }
+        if (enableGraph) {
+            count += this.initGraphTables(db);
+        }
+        return count;
+    }
+    initVec0Table(db, dimensions) {
+        db.exec(`
+            CREATE VIRTUAL TABLE IF NOT EXISTS mcard_vec USING vec0(
+                metadata_id INTEGER PRIMARY KEY,
+                embedding float[${dimensions}]
+            )
+        `);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Convenience Exports (Backward Compatibility)
+// ─────────────────────────────────────────────────────────────────────────────
+// These are lazy-loaded from the singleton
+let _cachedSchemas = {};
+function getSchemaInstance() {
+    return MCardSchema.getInstance();
+}
+// Core schemas
+export const CARD_TABLE_SCHEMA = getSchemaInstance().getTable('card') || '';
+export const HANDLE_REGISTRY_SCHEMA = getSchemaInstance().getTable('handle_registry') || '';
+export const HANDLE_HISTORY_SCHEMA = getSchemaInstance().getTable('handle_history') || '';
+export const HANDLE_INDEX_SCHEMA = getSchemaInstance().getIndex('idx_handle_current_hash') || '';
+// Vector schemas
+export const VECTOR_METADATA_SCHEMA = getSchemaInstance().getTable('mcard_vector_metadata') || '';
+export const VECTOR_METADATA_INDEX = getSchemaInstance().getIndex('idx_vector_metadata_hash') || '';
+export const VECTOR_EMBEDDINGS_SCHEMA = getSchemaInstance().getTable('mcard_embeddings') || '';
+export const VECTOR_FTS_SCHEMA = getSchemaInstance().getTable('mcard_fts') || '';
+// Semantic versioning schemas
+export const HANDLE_VERSION_VECTORS_SCHEMA = getSchemaInstance().getTable('handle_version_vectors') || '';
+export const HANDLE_VERSION_VECTORS_INDEXES = [
+    getSchemaInstance().getIndex('idx_hvv_handle'),
+    getSchemaInstance().getIndex('idx_hvv_hash'),
+    getSchemaInstance().getIndex('idx_hvv_current'),
+    getSchemaInstance().getIndex('idx_hvv_parent'),
+].filter(Boolean).join('; ');
+export const VERSION_SIMILARITY_CACHE_SCHEMA = getSchemaInstance().getTable('version_similarity_cache') || '';
+export const VERSION_SIMILARITY_CACHE_INDEX = getSchemaInstance().getIndex('idx_vsc_handle') || '';
+// Graph schemas
+export const GRAPH_ENTITY_SCHEMA = getSchemaInstance().getTable('graph_entities') || '';
+export const GRAPH_ENTITY_INDEX_NAME = getSchemaInstance().getIndex('idx_entity_name') || '';
+export const GRAPH_ENTITY_INDEX_TYPE = getSchemaInstance().getIndex('idx_entity_type') || '';
+export const GRAPH_ENTITY_INDEX_SOURCE = getSchemaInstance().getIndex('idx_entity_source') || '';
+export const GRAPH_RELATIONSHIP_SCHEMA = getSchemaInstance().getTable('graph_relationships') || '';
+export const GRAPH_RELATIONSHIP_INDEX_SOURCE = getSchemaInstance().getIndex('idx_rel_source') || '';
+export const GRAPH_RELATIONSHIP_INDEX_TARGET = getSchemaInstance().getIndex('idx_rel_target') || '';
+export const GRAPH_COMMUNITY_SCHEMA = getSchemaInstance().getTable('graph_communities') || '';
+export const GRAPH_COMMUNITY_INDEX_LEVEL = getSchemaInstance().getIndex('idx_community_level') || '';
+export const GRAPH_EXTRACTION_SCHEMA = getSchemaInstance().getTable('graph_extractions') || '';
+// Schema collections
+export const CORE_SCHEMAS = {
+    card: CARD_TABLE_SCHEMA,
+    handleRegistry: HANDLE_REGISTRY_SCHEMA,
+    handleHistory: HANDLE_HISTORY_SCHEMA,
+    handleIndex: HANDLE_INDEX_SCHEMA,
+};
+export const VECTOR_SCHEMAS = {
+    metadata: VECTOR_METADATA_SCHEMA,
+    metadataIndex: VECTOR_METADATA_INDEX,
+    embeddings: VECTOR_EMBEDDINGS_SCHEMA,
+    fts: VECTOR_FTS_SCHEMA,
+};
+export const SEMANTIC_SCHEMAS = {
+    handleVersionVectors: HANDLE_VERSION_VECTORS_SCHEMA,
+    handleVersionVectorsIndexes: HANDLE_VERSION_VECTORS_INDEXES,
+    similarityCache: VERSION_SIMILARITY_CACHE_SCHEMA,
+    similarityCacheIndex: VERSION_SIMILARITY_CACHE_INDEX,
+};
+export const GRAPH_SCHEMAS = {
+    entities: GRAPH_ENTITY_SCHEMA,
+    entityIndexName: GRAPH_ENTITY_INDEX_NAME,
+    entityIndexType: GRAPH_ENTITY_INDEX_TYPE,
+    entityIndexSource: GRAPH_ENTITY_INDEX_SOURCE,
+    relationships: GRAPH_RELATIONSHIP_SCHEMA,
+    relIndexSource: GRAPH_RELATIONSHIP_INDEX_SOURCE,
+    relIndexTarget: GRAPH_RELATIONSHIP_INDEX_TARGET,
+    communities: GRAPH_COMMUNITY_SCHEMA,
+    communityIndexLevel: GRAPH_COMMUNITY_INDEX_LEVEL,
+    extractions: GRAPH_EXTRACTION_SCHEMA,
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Initialization Functions (use singleton internally)
+// ─────────────────────────────────────────────────────────────────────────────
+export function initCoreSchemas(db) {
+    const schema = MCardSchema.getInstance();
+    // Initialize both core (card) and handle tables (handle_registry, handle_history)
+    // because they are fundamental to MCard operation
+    schema.initCoreTables(db);
+    schema.initHandleTables(db);
+}
+export function initVectorSchemas(db, enableFts = true) {
+    MCardSchema.getInstance().initVectorTables(db, enableFts);
+}
+export function initSemanticSchemas(db) {
+    MCardSchema.getInstance().initSemanticTables(db);
+}
+export function initGraphSchemas(db) {
+    MCardSchema.getInstance().initGraphTables(db);
+}
+export function initAllSchemas(db, options = {}) {
+    MCardSchema.getInstance().initAllTables(db, options);
+}
+// Dynamic schema generator (dimensions can't come from SQL file)
+export function getVec0Schema(dimensions) {
+    return `
+CREATE VIRTUAL TABLE IF NOT EXISTS mcard_vec USING vec0(
+    metadata_id INTEGER PRIMARY KEY,
+    embedding float[${dimensions}]
+)
+`;
+}
+//# sourceMappingURL=schema.js.map

package/dist/storage/schema.js.map

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

package/dist/util/FileIO.d.ts

@@ -0,0 +1,44 @@
+export interface NormalizedReadResult {
+    text: string;
+    originalSize: number;
+    originalSha256Prefix: string;
+}
+/**
+ * Stream-read bytes up to byte_cap, decode, and soft wrap.
+ */
+export declare function streamReadNormalizedText(filePath: string, options: {
+    byteCap: number;
+    wrapWidth: number;
+}): Promise<NormalizedReadResult>;
+export interface FileProcessingResult {
+    content: Uint8Array | string;
+    filename: string;
+    mimeType: string;
+    extension: string;
+    isBinary: boolean;
+    size: number;
+}
+/**
+ * Check if a file is likely to cause processing issues.
+ */
+export declare function isProblematicFile(filePath: string): Promise<boolean>;
+/**
+ * Safely read a file with limits and timeouts.
+ */
+export declare function readFileSafely(filePath: string, options?: {
+    allowPathological?: boolean;
+    maxBytes?: number;
+}): Promise<Uint8Array>;
+/**
+ * List files in directory, filtering out problematic ones.
+ */
+export declare function listFiles(dirPath: string, recursive?: boolean): Promise<string[]>;
+/**
+ * Process a file and return metadata and content.
+ */
+export declare function processFileContent(filePath: string, options?: {
+    forceBinary?: boolean;
+    allowPathological?: boolean;
+    maxBytes?: number;
+}): Promise<FileProcessingResult>;
+//# sourceMappingURL=FileIO.d.ts.map

package/dist/util/FileIO.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileIO.d.ts","sourceRoot":"","sources":["../../src/util/FileIO.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC1C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChD,OAAO,CAAC,oBAAoB,CAAC,CAqE/B;AAOD,MAAM,WAAW,oBAAoB;IACjC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgC1E;AAED;;GAEG;AACH,wBAAsB,cAAc,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,OAAO,CAAC,UAAU,CAAC,CAsBrB;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,OAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAyB9F;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACxF,OAAO,CAAC,oBAAoB,CAAC,CA4B/B"}