@specverse/engines 4.1.0

package/dist/realize/utils/ai-spec-loader.js

@@ -0,0 +1,142 @@
+/**
+ * AI-Optimized Spec Loader Utility
+ *
+ * Loads SpecVerse YAML files and generates AIOptimizedSpec using:
+ * 1. UnifiedSpecVerseParser - Handles YAML parsing, imports, conventions
+ * 2. AIViewGenerator - Generates optimized spec with inference
+ *
+ * This utility eliminates duplicate parsing logic across all generators.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import { UnifiedSpecVerseParser } from '../../parser/index.js';
+import { AIViewGenerator } from '../../generators/index.js';
+// ES module equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+// Load JSON schema from engine-entities (single source of truth)
+const getSchemaPath = () => {
+    // Try engine-entities package first (single source of truth)
+    try {
+        const entitiesPkg = dirname(require.resolve('@specverse/entities/package.json'));
+        const entitiesSchema = resolve(entitiesPkg, 'schema', 'SPECVERSE-SCHEMA.json');
+        if (existsSync(entitiesSchema))
+            return entitiesSchema;
+    }
+    catch { /* engine-entities not available */ }
+    // Fallback paths
+    const possiblePaths = [
+        resolve(process.cwd(), 'schema/SPECVERSE-SCHEMA.json'),
+        resolve(__dirname, '../../../schema/SPECVERSE-SCHEMA.json'),
+        resolve(__dirname, '../../schema/SPECVERSE-SCHEMA.json'),
+    ];
+    for (const path of possiblePaths) {
+        if (existsSync(path))
+            return path;
+    }
+    return possiblePaths[0];
+};
+const schemaPath = getSchemaPath();
+const schemaJson = JSON.parse(readFileSync(schemaPath, 'utf8'));
+/**
+ * Load and generate AIOptimizedSpec from a SpecVerse YAML file
+ */
+export function loadAIOptimizedSpec(yamlFile, options = {}) {
+    try {
+        // 1. Read YAML file
+        const yamlContent = readFileSync(yamlFile, 'utf8');
+        // 2. Parse with UnifiedSpecVerseParser (handles imports, conventions, validation)
+        const parser = new UnifiedSpecVerseParser(schemaJson);
+        const result = parser.parse(yamlContent, 'specly');
+        // Check for parse errors
+        if (result.errors && result.errors.length > 0) {
+            const errorMessages = result.errors
+                .map((err) => `  - ${err.message} (line ${err.line || '?'}, col ${err.column || '?'})`)
+                .join('\n');
+            throw new Error(`Parse errors in ${yamlFile}:\n${errorMessages}`);
+        }
+        // Check for warnings (non-fatal)
+        if (result.warnings && result.warnings.length > 0) {
+            console.warn(`⚠️  Warnings in ${yamlFile}:`);
+            result.warnings.forEach((warn) => {
+                console.warn(`  - ${warn.message}`);
+            });
+        }
+        // 3. Generate AIOptimizedSpec (runs inference, expands CURED, etc.)
+        const generator = new AIViewGenerator();
+        const optimized = generator.generate(result.ast, options);
+        return optimized;
+    }
+    catch (error) {
+        // Provide helpful error messages
+        if (error.code === 'ENOENT') {
+            throw new Error(`File not found: ${yamlFile}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Load AIOptimizedSpec with deployment filtering
+ */
+export function loadForDeployment(yamlFile, deploymentName, instanceName) {
+    return loadAIOptimizedSpec(yamlFile, {
+        deployment: deploymentName,
+        instance: instanceName
+    });
+}
+/**
+ * Load AIOptimizedSpec with manifest configuration
+ */
+export function loadWithManifest(yamlFile, manifestConfig) {
+    return loadAIOptimizedSpec(yamlFile, {
+        manifest: manifestConfig
+    });
+}
+/**
+ * Get component metadata from AIOptimizedSpec
+ */
+export function getComponentMetadata(spec) {
+    return {
+        name: spec.metadata.component,
+        version: spec.metadata.version,
+        description: spec.metadata.description,
+        tags: spec.metadata.tags,
+        deployment: spec.metadata.deployment,
+        instance: spec.metadata.instance,
+        manifest: spec.metadata.manifest
+    };
+}
+/**
+ * Get all models from AIOptimizedSpec
+ */
+export function getModels(spec) {
+    return spec.models || [];
+}
+/**
+ * Get all controllers from AIOptimizedSpec
+ */
+export function getControllers(spec) {
+    return spec.controllers || [];
+}
+/**
+ * Get all services from AIOptimizedSpec
+ */
+export function getServices(spec) {
+    return spec.services || [];
+}
+/**
+ * Get all events from AIOptimizedSpec
+ */
+export function getEvents(spec) {
+    return spec.events || [];
+}
+/**
+ * Get infrastructure requirements from AIOptimizedSpec
+ */
+export function getInfrastructure(spec) {
+    return spec.infrastructure || {};
+}
+//# sourceMappingURL=ai-spec-loader.js.map

package/dist/realize/utils/ai-spec-loader.js.map

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

package/dist/realize/utils/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Realize Utilities
+ *
+ * Shared utilities for code realization (code generation)
+ */
+export * from './ai-spec-loader.js';
+export * from './manifest-loader.js';
+export * from './mapping-migration.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/realize/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/realize/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC"}

package/dist/realize/utils/index.js

@@ -0,0 +1,9 @@
+/**
+ * Realize Utilities
+ *
+ * Shared utilities for code realization (code generation)
+ */
+export * from './ai-spec-loader.js';
+export * from './manifest-loader.js';
+export * from './mapping-migration.js';
+//# sourceMappingURL=index.js.map

package/dist/realize/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/realize/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC"}

package/dist/realize/utils/manifest-loader.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Manifest Loader Utility
+ *
+ * Loads and validates SpecVerse manifest files.
+ * Provides default manifests for testing and development.
+ */
+import type { CapabilityMapping, InstanceMapping, DefaultMappings, DeploymentReference } from '../types/index.js';
+import type { DefaultMappingsV2, OverrideMapping } from '../types/unified-mappings.js';
+/**
+ * Instance Factory Declaration
+ *
+ * Declares an instance factory with its source metadata.
+ * Source structure matches registry FactorySource exactly.
+ */
+export interface InstanceFactoryDeclaration {
+    /** Factory name (must match registry) */
+    name: string;
+    /** Source metadata */
+    source: {
+        /** Source type */
+        type: 'npm' | 'git' | 'url';
+        /** NPM package name (for npm type) */
+        package?: string;
+        /** Version constraint (for npm type) */
+        version?: string;
+        /** Git repository URL (for git type) */
+        url?: string;
+        /** Entry point file path */
+        entrypoint?: string;
+    };
+}
+export interface ManifestConfig {
+    specVersion: string;
+    name: string;
+    description?: string;
+    version: string;
+    /** v3.3 Deployment Reference (REQUIRED) */
+    deployment: DeploymentReference;
+    /**
+     * Instance Factories (NEW - v3.6+)
+     *
+     * Explicit declarations of instance factories with source metadata.
+     * This allows validation without registry lookup.
+     */
+    instanceFactories?: InstanceFactoryDeclaration[];
+    /**
+     * Two-Level Mapping System (v3.6+) - RECOMMENDED
+     *
+     * Simplified mapping system with two clear levels:
+     * - defaults: Sugar syntax for common cases
+     * - overrides: Explicit control with optional configuration
+     */
+    defaults?: DefaultMappingsV2;
+    overrides?: OverrideMapping[];
+    /**
+     * Three-Level Mapping System (v3.3) - LEGACY
+     *
+     * Maintained for backward compatibility.
+     * Will be deprecated in future versions.
+     * Use two-level system (defaults + overrides) instead.
+     */
+    defaultMappings?: DefaultMappings;
+    capabilityMappings?: CapabilityMapping[];
+    instanceMappings?: InstanceMapping[];
+    /** Global configuration */
+    configuration?: Record<string, any>;
+    /** Manifest templates for common tech stacks */
+    manifestTemplates?: Array<{
+        template: string;
+        version?: string;
+    }>;
+    /** Internal metadata */
+    _manifestName?: string;
+    _manifestPath?: string;
+    _isDefault?: boolean;
+}
+export interface ManifestValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Load manifest from file
+ */
+export declare function loadManifest(manifestPath: string): ManifestConfig;
+/**
+ * Get manifest configuration value by path
+ */
+export declare function getManifestValue(manifest: ManifestConfig | null | undefined, path: string, defaultValue?: any): any;
+/**
+ * Validate manifest structure (v3.3 only - no backward compatibility)
+ */
+export declare function validateManifest(manifest: ManifestConfig | null | undefined): ManifestValidationResult;
+/**
+ * Merge manifests (v3.3 composition)
+ */
+export declare function mergeManifests(baseManifest: ManifestConfig | null | undefined, overrideManifest: ManifestConfig | null | undefined): ManifestConfig | null;
+/**
+ * Get manifest summary for debugging
+ */
+export declare function getManifestSummary(manifest: ManifestConfig): {
+    name: string;
+    version: string;
+    deployment: string;
+    mappingStrategies: string[];
+    instanceCount?: number;
+};
+//# sourceMappingURL=manifest-loader.d.ts.map

package/dist/realize/utils/manifest-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../../../src/realize/utils/manifest-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EAChB,MAAM,8BAA8B,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IAEb,sBAAsB;IACtB,MAAM,EAAE;QACN,kBAAkB;QAClB,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;QAE5B,sCAAsC;QACtC,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB,wCAAwC;QACxC,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB,wCAAwC;QACxC,GAAG,CAAC,EAAE,MAAM,CAAC;QAEb,4BAA4B;QAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAEhB,2CAA2C;IAC3C,UAAU,EAAE,mBAAmB,CAAC;IAEhC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,0BAA0B,EAAE,CAAC;IAEjD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAE9B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACzC,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IAErC,2BAA2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEpC,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,KAAK,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IAEH,wBAAwB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,CA8CjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EAC3C,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,GAAG,GACjB,GAAG,CAiBL;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,wBAAwB,CAgDtG;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EAC/C,gBAAgB,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAClD,cAAc,GAAG,IAAI,CAyBvB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,GAAG;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAsBA"}

package/dist/realize/utils/manifest-loader.js

@@ -0,0 +1,168 @@
+/**
+ * Manifest Loader Utility
+ *
+ * Loads and validates SpecVerse manifest files.
+ * Provides default manifests for testing and development.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { parse as parseYaml } from 'yaml';
+import { resolve } from 'path';
+/**
+ * Load manifest from file
+ */
+export function loadManifest(manifestPath) {
+    if (!manifestPath) {
+        throw new Error('Manifest path is required');
+    }
+    const fullPath = resolve(manifestPath);
+    if (!existsSync(fullPath)) {
+        throw new Error(`Manifest file not found: ${fullPath}`);
+    }
+    try {
+        const yamlContent = readFileSync(fullPath, 'utf8');
+        const parsed = parseYaml(yamlContent);
+        // Handle unified container format (manifests: { ManifestName: { ... } })
+        if (parsed.manifests && typeof parsed.manifests === 'object') {
+            const manifestKeys = Object.keys(parsed.manifests);
+            if (manifestKeys.length === 0) {
+                throw new Error('Manifests container is empty');
+            }
+            // Use first manifest
+            const manifestName = manifestKeys[0];
+            const manifest = parsed.manifests[manifestName];
+            // Add metadata
+            manifest._manifestName = manifestName;
+            manifest._manifestPath = fullPath;
+            return manifest;
+        }
+        // Handle direct manifest format (legacy or simplified)
+        if (parsed.specVersion) {
+            return parsed;
+        }
+        throw new Error('Invalid manifest format: missing "manifests" container or "specVersion"');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Manifest file not found: ${fullPath}`);
+        }
+        throw new Error(`Failed to load manifest: ${error.message}`);
+    }
+}
+/**
+ * Get manifest configuration value by path
+ */
+export function getManifestValue(manifest, path, defaultValue) {
+    if (!manifest || !path) {
+        return defaultValue;
+    }
+    const parts = path.split('.');
+    let current = manifest;
+    for (const part of parts) {
+        if (current && typeof current === 'object' && part in current) {
+            current = current[part];
+        }
+        else {
+            return defaultValue;
+        }
+    }
+    return current;
+}
+/**
+ * Validate manifest structure (v3.3 only - no backward compatibility)
+ */
+export function validateManifest(manifest) {
+    const errors = [];
+    if (!manifest) {
+        errors.push('Manifest is null or undefined');
+        return { valid: false, errors };
+    }
+    // Required fields
+    if (!manifest.specVersion) {
+        errors.push('Missing required field: specVersion');
+    }
+    else if (!manifest.specVersion.match(/^\d+\.\d+/)) {
+        errors.push(`Invalid specVersion format: ${manifest.specVersion}. Expected semver (e.g., 3.5.0).`);
+    }
+    if (!manifest.name) {
+        errors.push('Missing required field: name');
+    }
+    if (!manifest.version) {
+        errors.push('Missing required field: version');
+    }
+    // v3.3 required: deployment reference
+    if (!manifest.deployment) {
+        errors.push('Missing required field: deployment (must reference a deployment specification)');
+    }
+    else {
+        if (!manifest.deployment.deploymentSource) {
+            errors.push('deployment.deploymentSource is required');
+        }
+        if (!manifest.deployment.deploymentName) {
+            errors.push('deployment.deploymentName is required');
+        }
+    }
+    // v3.3 required: at least one mapping strategy
+    const hasMappings = manifest.defaultMappings ||
+        (manifest.capabilityMappings && manifest.capabilityMappings.length > 0) ||
+        (manifest.instanceMappings && manifest.instanceMappings.length > 0);
+    if (!hasMappings) {
+        errors.push('At least one mapping strategy is required: defaultMappings, capabilityMappings, or instanceMappings');
+    }
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+/**
+ * Merge manifests (v3.3 composition)
+ */
+export function mergeManifests(baseManifest, overrideManifest) {
+    if (!baseManifest)
+        return overrideManifest || null;
+    if (!overrideManifest)
+        return baseManifest;
+    // v3.3 merge: arrays override completely, objects merge
+    return {
+        ...baseManifest,
+        ...overrideManifest,
+        // Deployment reference: override completely
+        deployment: overrideManifest.deployment || baseManifest.deployment,
+        // Default mappings: merge objects
+        defaultMappings: {
+            ...(baseManifest.defaultMappings || {}),
+            ...(overrideManifest.defaultMappings || {})
+        },
+        // Capability mappings: override array completely
+        capabilityMappings: overrideManifest.capabilityMappings || baseManifest.capabilityMappings,
+        // Instance mappings: override array completely
+        instanceMappings: overrideManifest.instanceMappings || baseManifest.instanceMappings,
+        // Configuration: merge objects
+        configuration: {
+            ...(baseManifest.configuration || {}),
+            ...(overrideManifest.configuration || {})
+        }
+    };
+}
+/**
+ * Get manifest summary for debugging
+ */
+export function getManifestSummary(manifest) {
+    const strategies = [];
+    if (manifest.defaultMappings) {
+        const count = Object.keys(manifest.defaultMappings).length;
+        strategies.push(`defaultMappings (${count} categories)`);
+    }
+    if (manifest.capabilityMappings && manifest.capabilityMappings.length > 0) {
+        strategies.push(`capabilityMappings (${manifest.capabilityMappings.length} patterns)`);
+    }
+    if (manifest.instanceMappings && manifest.instanceMappings.length > 0) {
+        strategies.push(`instanceMappings (${manifest.instanceMappings.length} instances)`);
+    }
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        deployment: `${manifest.deployment?.deploymentName || 'unknown'} from ${manifest.deployment?.deploymentSource || 'unknown'}`,
+        mappingStrategies: strategies
+    };
+}
+//# sourceMappingURL=manifest-loader.js.map

package/dist/realize/utils/manifest-loader.js.map

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

package/dist/realize/utils/mapping-migration.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Mapping Migration Utilities
+ *
+ * Converts legacy three-level mapping system (v3.3) to new two-level system (v3.6).
+ * Provides backward compatibility while encouraging migration to the simpler format.
+ *
+ * @module realize/utils/mapping-migration
+ * @version 3.6.0
+ */
+import type { ManifestConfig } from './manifest-loader.js';
+import type { DefaultMappingsV2, OverrideMapping } from '../types/unified-mappings.js';
+/**
+ * Convert legacy three-level mappings to new two-level system
+ *
+ * Migrates:
+ * - defaultMappings (v3.3) → defaults (v3.6)
+ * - capabilityMappings (v3.3) → overrides (v3.6)
+ * - instanceMappings (v3.3) → overrides (v3.6) with configuration
+ *
+ * @param manifest - Manifest with legacy mappings
+ * @returns Manifest with new two-level mappings
+ */
+export declare function migrateToTwoLevelSystem(manifest: ManifestConfig): ManifestConfig;
+/**
+ * Detect which mapping system is in use
+ *
+ * @param manifest - Manifest to analyze
+ * @returns Mapping system version
+ */
+export declare function detectMappingSystem(manifest: ManifestConfig): 'v3.6' | 'v3.3' | 'none';
+/**
+ * Get effective mappings using the appropriate system
+ *
+ * Automatically migrates if using legacy system.
+ *
+ * @param manifest - Manifest configuration
+ * @returns Defaults and overrides (migrated if necessary)
+ */
+export declare function getEffectiveMappings(manifest: ManifestConfig): {
+    defaults?: DefaultMappingsV2;
+    overrides?: OverrideMapping[];
+    system: 'v3.6' | 'v3.3' | 'none';
+};
+/**
+ * Validate that manifest uses consistent mapping system
+ *
+ * Warns if mixing v3.3 and v3.6 systems.
+ *
+ * @param manifest - Manifest to validate
+ * @returns Validation warnings
+ */
+export declare function validateMappingConsistency(manifest: ManifestConfig): string[];
+//# sourceMappingURL=mapping-migration.d.ts.map

package/dist/realize/utils/mapping-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping-migration.d.ts","sourceRoot":"","sources":["../../../src/realize/utils/mapping-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EAChB,MAAM,8BAA8B,CAAC;AAOtC;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,GAAG,cAAc,CAwChF;AAkED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAsBtF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG;IAC9D,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CAClC,CAyBA;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,EAAE,CAmB7E"}