monora-ai 2.0.0 → 2.1.3

package/dist/data-governance.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Data Governance Module for ISO 42001 A.7 compliance.
+ *
+ * This module provides data governance tracking supporting ISO 42001 controls:
+ * - A.7.2: Data for development and enhancement
+ * - A.7.4: Quality of data
+ * - A.7.6: Data preparation
+ *
+ * Extends existing lineage and provenance features (A.7.3, A.7.5).
+ *
+ * Cross-SDK Parity:
+ *   Both Python and Node.js SDKs provide identical data governance APIs:
+ *   - createDatasetRecord() / create_dataset_record()
+ *   - recordQualityMetrics() / record_quality_metrics()
+ *   - addPreparationStep() / add_preparation_step()
+ *   - recordBiasAssessment() / record_bias_assessment()
+ */
+import { MonoraConfig } from './config';
+export type DatasetCategory = 'training' | 'validation' | 'test' | 'production' | 'synthetic';
+export type QualityStatus = 'passed' | 'failed' | 'not_assessed';
+export type PreparationStepType = 'cleaning' | 'normalization' | 'encoding' | 'augmentation' | 'sampling' | 'transformation' | 'filtering';
+export type AcquisitionMethod = 'api' | 'manual_collection' | 'purchase' | 'synthetic_generation' | 'scraping' | 'donation';
+/**
+ * Data quality metrics (A.7.4).
+ */
+export interface DataQualityMetrics {
+    completeness: number;
+    accuracy: number;
+    consistency: number;
+    timeliness: number;
+    uniqueness: number;
+    representativeness: number;
+}
+export declare function qualityMetricsToDict(metrics: DataQualityMetrics): Record<string, any>;
+export declare function checkQualityThresholds(metrics: DataQualityMetrics, thresholds: Record<string, number>): string[];
+/**
+ * A data preparation step (A.7.6).
+ */
+export interface PreparationStep {
+    stepId: string;
+    stepType: PreparationStepType;
+    description: string;
+    inputDataset: string;
+    outputDataset: string;
+    parameters: Record<string, any>;
+    executedAt: string;
+    executedBy: string;
+}
+export declare function preparationStepToDict(step: PreparationStep): Record<string, any>;
+/**
+ * Bias assessment for a dataset.
+ */
+export interface DatasetBiasAssessment {
+    assessmentId: string;
+    dimension: string;
+    metric: string;
+    value: number;
+    threshold: number;
+    passed: boolean;
+    assessedAt: string;
+}
+export declare function biasAssessmentToDict(assessment: DatasetBiasAssessment): Record<string, any>;
+/**
+ * Complete dataset record for ISO 42001 A.7.
+ */
+export interface DatasetRecord {
+    datasetId: string;
+    name: string;
+    description: string;
+    category: DatasetCategory;
+    source: string;
+    acquisitionMethod: AcquisitionMethod;
+    acquisitionDate: string;
+    dataRights: string;
+    qualityMetrics?: DataQualityMetrics;
+    qualityThresholds: Record<string, number>;
+    qualityStatus: QualityStatus;
+    lineage: string[];
+    transformations: string[];
+    preparationSteps: PreparationStep[];
+    biasAssessments: DatasetBiasAssessment[];
+    recordCount?: number;
+    schemaRef?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function datasetRecordToDict(dataset: DatasetRecord): Record<string, any>;
+/**
+ * Create a new dataset record.
+ */
+export interface CreateDatasetRecordOptions {
+    name: string;
+    description: string;
+    category: DatasetCategory;
+    source: string;
+    acquisitionMethod: AcquisitionMethod;
+    acquisitionDate?: string;
+    dataRights?: string;
+    lineage?: string[];
+    recordCount?: number;
+    schemaRef?: string;
+    config?: MonoraConfig;
+}
+export declare function createDatasetRecord(options: CreateDatasetRecordOptions): DatasetRecord;
+/**
+ * Register an existing dataset record.
+ */
+export declare function registerDataset(record: DatasetRecord): void;
+/**
+ * Get a dataset record by ID.
+ */
+export declare function getDatasetRecord(datasetId: string): DatasetRecord | undefined;
+/**
+ * Get all registered dataset records.
+ */
+export declare function getAllDatasets(): DatasetRecord[];
+/**
+ * Clear all dataset records from the registry.
+ */
+export declare function clearDatasets(): void;
+/**
+ * Record quality metrics for a dataset (A.7.4).
+ */
+export interface RecordQualityMetricsOptions {
+    datasetId: string;
+    completeness?: number;
+    accuracy?: number;
+    consistency?: number;
+    timeliness?: number;
+    uniqueness?: number;
+    representativeness?: number;
+    config?: MonoraConfig;
+}
+export declare function recordQualityMetrics(options: RecordQualityMetricsOptions): DataQualityMetrics;
+/**
+ * Add a data preparation step (A.7.6).
+ */
+export interface AddPreparationStepOptions {
+    datasetId: string;
+    stepType: PreparationStepType;
+    description: string;
+    outputDatasetId?: string;
+    parameters?: Record<string, any>;
+    executedBy?: string;
+}
+export declare function addPreparationStep(options: AddPreparationStepOptions): PreparationStep;
+/**
+ * Record a bias assessment for a dataset.
+ */
+export interface RecordBiasAssessmentOptions {
+    datasetId: string;
+    dimension: string;
+    metric: string;
+    value: number;
+    threshold: number;
+}
+export declare function recordBiasAssessment(options: RecordBiasAssessmentOptions): DatasetBiasAssessment;
+/**
+ * Update the lineage of a dataset.
+ */
+export declare function updateDatasetLineage(datasetId: string, parentIds: string[]): void;
+/**
+ * Get the full lineage graph for a dataset.
+ */
+export declare function getDatasetLineage(datasetId: string): Record<string, any>;
+/**
+ * Validate that a dataset meets quality requirements for intended use.
+ */
+export interface ValidateDatasetOptions {
+    datasetId: string;
+    intendedUse: DatasetCategory;
+    config?: MonoraConfig;
+}
+export declare function validateDatasetForUse(options: ValidateDatasetOptions): Record<string, any>;
+/**
+ * Get a summary of a dataset for reporting.
+ */
+export declare function getDatasetSummary(datasetId: string): Record<string, any>;
+/**
+ * Get aggregate report of all datasets.
+ */
+export declare function getDataGovernanceReport(config?: MonoraConfig): Record<string, any>;
+/**
+ * Emit the current state of a dataset record as an event.
+ */
+export declare function emitDatasetRecord(datasetId: string, config?: MonoraConfig): void;
+//# sourceMappingURL=data-governance.d.ts.map

package/dist/data-governance.d.ts.map

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

package/dist/data-governance.js

@@ -0,0 +1,424 @@
+"use strict";
+/**
+ * Data Governance Module for ISO 42001 A.7 compliance.
+ *
+ * This module provides data governance tracking supporting ISO 42001 controls:
+ * - A.7.2: Data for development and enhancement
+ * - A.7.4: Quality of data
+ * - A.7.6: Data preparation
+ *
+ * Extends existing lineage and provenance features (A.7.3, A.7.5).
+ *
+ * Cross-SDK Parity:
+ *   Both Python and Node.js SDKs provide identical data governance APIs:
+ *   - createDatasetRecord() / create_dataset_record()
+ *   - recordQualityMetrics() / record_quality_metrics()
+ *   - addPreparationStep() / add_preparation_step()
+ *   - recordBiasAssessment() / record_bias_assessment()
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.qualityMetricsToDict = qualityMetricsToDict;
+exports.checkQualityThresholds = checkQualityThresholds;
+exports.preparationStepToDict = preparationStepToDict;
+exports.biasAssessmentToDict = biasAssessmentToDict;
+exports.datasetRecordToDict = datasetRecordToDict;
+exports.createDatasetRecord = createDatasetRecord;
+exports.registerDataset = registerDataset;
+exports.getDatasetRecord = getDatasetRecord;
+exports.getAllDatasets = getAllDatasets;
+exports.clearDatasets = clearDatasets;
+exports.recordQualityMetrics = recordQualityMetrics;
+exports.addPreparationStep = addPreparationStep;
+exports.recordBiasAssessment = recordBiasAssessment;
+exports.updateDatasetLineage = updateDatasetLineage;
+exports.getDatasetLineage = getDatasetLineage;
+exports.validateDatasetForUse = validateDatasetForUse;
+exports.getDatasetSummary = getDatasetSummary;
+exports.getDataGovernanceReport = getDataGovernanceReport;
+exports.emitDatasetRecord = emitDatasetRecord;
+const crypto_1 = require("crypto");
+const logger_1 = require("./logger");
+/**
+ * Generate a deterministic ID from parts.
+ */
+function generateId(prefix, ...parts) {
+    const combined = parts.join(':');
+    const hash = (0, crypto_1.createHash)('sha256').update(combined).digest('hex').slice(0, 12);
+    return `${prefix}_${hash}`;
+}
+/**
+ * Get current UTC timestamp in ISO format.
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+function qualityMetricsToDict(metrics) {
+    return {
+        completeness: metrics.completeness,
+        accuracy: metrics.accuracy,
+        consistency: metrics.consistency,
+        timeliness: metrics.timeliness,
+        uniqueness: metrics.uniqueness,
+        representativeness: metrics.representativeness,
+    };
+}
+function checkQualityThresholds(metrics, thresholds) {
+    const failures = [];
+    for (const [metric, threshold] of Object.entries(thresholds)) {
+        const value = metrics[metric];
+        if (value !== undefined && value < threshold) {
+            failures.push(`${metric} (${value.toFixed(3)} < ${threshold})`);
+        }
+    }
+    return failures;
+}
+function preparationStepToDict(step) {
+    return {
+        step_id: step.stepId,
+        step_type: step.stepType,
+        description: step.description,
+        input_dataset: step.inputDataset,
+        output_dataset: step.outputDataset,
+        parameters: step.parameters,
+        executed_at: step.executedAt,
+        executed_by: step.executedBy,
+    };
+}
+function biasAssessmentToDict(assessment) {
+    return {
+        assessment_id: assessment.assessmentId,
+        dimension: assessment.dimension,
+        metric: assessment.metric,
+        value: assessment.value,
+        threshold: assessment.threshold,
+        passed: assessment.passed,
+        assessed_at: assessment.assessedAt,
+    };
+}
+function datasetRecordToDict(dataset) {
+    const result = {
+        dataset_id: dataset.datasetId,
+        name: dataset.name,
+        description: dataset.description,
+        category: dataset.category,
+        source: dataset.source,
+        acquisition_method: dataset.acquisitionMethod,
+        acquisition_date: dataset.acquisitionDate,
+        data_rights: dataset.dataRights,
+        quality_thresholds: dataset.qualityThresholds,
+        quality_status: dataset.qualityStatus,
+        lineage: dataset.lineage,
+        transformations: dataset.transformations,
+        preparation_steps: dataset.preparationSteps.map(preparationStepToDict),
+        bias_assessments: dataset.biasAssessments.map(biasAssessmentToDict),
+        created_at: dataset.createdAt,
+        updated_at: dataset.updatedAt,
+    };
+    if (dataset.qualityMetrics) {
+        result.quality_metrics = qualityMetricsToDict(dataset.qualityMetrics);
+    }
+    if (dataset.recordCount !== undefined) {
+        result.record_count = dataset.recordCount;
+    }
+    if (dataset.schemaRef) {
+        result.schema_ref = dataset.schemaRef;
+    }
+    return result;
+}
+// Runtime dataset registry
+const datasets = new Map();
+function createDatasetRecord(options) {
+    const governanceConfig = options.config?.data_governance;
+    const defaultThresholds = governanceConfig?.default_quality_thresholds || {};
+    const acquisitionDate = options.acquisitionDate || new Date().toISOString().split('T')[0];
+    const datasetId = generateId('ds', options.name, options.source, acquisitionDate);
+    const record = {
+        datasetId,
+        name: options.name,
+        description: options.description,
+        category: options.category,
+        source: options.source,
+        acquisitionMethod: options.acquisitionMethod,
+        acquisitionDate,
+        dataRights: options.dataRights || '',
+        qualityThresholds: { ...defaultThresholds },
+        qualityStatus: 'not_assessed',
+        lineage: options.lineage || [],
+        transformations: [],
+        preparationSteps: [],
+        biasAssessments: [],
+        recordCount: options.recordCount,
+        schemaRef: options.schemaRef,
+        createdAt: nowIso(),
+        updatedAt: nowIso(),
+    };
+    datasets.set(datasetId, record);
+    return record;
+}
+/**
+ * Register an existing dataset record.
+ */
+function registerDataset(record) {
+    datasets.set(record.datasetId, record);
+}
+/**
+ * Get a dataset record by ID.
+ */
+function getDatasetRecord(datasetId) {
+    return datasets.get(datasetId);
+}
+/**
+ * Get all registered dataset records.
+ */
+function getAllDatasets() {
+    return Array.from(datasets.values());
+}
+/**
+ * Clear all dataset records from the registry.
+ */
+function clearDatasets() {
+    datasets.clear();
+}
+function recordQualityMetrics(options) {
+    const dataset = datasets.get(options.datasetId);
+    if (!dataset) {
+        throw new Error(`Dataset ${options.datasetId} not found`);
+    }
+    const metrics = {
+        completeness: options.completeness ?? 0,
+        accuracy: options.accuracy ?? 0,
+        consistency: options.consistency ?? 0,
+        timeliness: options.timeliness ?? 0,
+        uniqueness: options.uniqueness ?? 0,
+        representativeness: options.representativeness ?? 0,
+    };
+    dataset.qualityMetrics = metrics;
+    // Check against thresholds
+    const failures = checkQualityThresholds(metrics, dataset.qualityThresholds);
+    dataset.qualityStatus = failures.length > 0 ? 'failed' : 'passed';
+    dataset.updatedAt = nowIso();
+    // Emit quality event
+    emitDataGovernanceEvent(dataset, 'data_quality_check', options.config);
+    return metrics;
+}
+function addPreparationStep(options) {
+    const dataset = datasets.get(options.datasetId);
+    if (!dataset) {
+        throw new Error(`Dataset ${options.datasetId} not found`);
+    }
+    const stepId = generateId('prep', options.datasetId, options.stepType, options.description.slice(0, 20));
+    const step = {
+        stepId,
+        stepType: options.stepType,
+        description: options.description,
+        inputDataset: options.datasetId,
+        outputDataset: options.outputDatasetId || options.datasetId,
+        parameters: options.parameters || {},
+        executedAt: nowIso(),
+        executedBy: options.executedBy || '',
+    };
+    dataset.preparationSteps.push(step);
+    dataset.transformations.push(`${options.stepType}: ${options.description}`);
+    dataset.updatedAt = nowIso();
+    return step;
+}
+function recordBiasAssessment(options) {
+    const dataset = datasets.get(options.datasetId);
+    if (!dataset) {
+        throw new Error(`Dataset ${options.datasetId} not found`);
+    }
+    const assessmentId = generateId('bias', options.datasetId, options.dimension, options.metric);
+    const passed = options.value >= options.threshold;
+    const assessment = {
+        assessmentId,
+        dimension: options.dimension,
+        metric: options.metric,
+        value: options.value,
+        threshold: options.threshold,
+        passed,
+        assessedAt: nowIso(),
+    };
+    dataset.biasAssessments.push(assessment);
+    dataset.updatedAt = nowIso();
+    return assessment;
+}
+/**
+ * Update the lineage of a dataset.
+ */
+function updateDatasetLineage(datasetId, parentIds) {
+    const dataset = datasets.get(datasetId);
+    if (!dataset) {
+        throw new Error(`Dataset ${datasetId} not found`);
+    }
+    dataset.lineage = parentIds;
+    dataset.updatedAt = nowIso();
+}
+/**
+ * Get the full lineage graph for a dataset.
+ */
+function getDatasetLineage(datasetId) {
+    const dataset = datasets.get(datasetId);
+    if (!dataset) {
+        return {};
+    }
+    function getAncestors(dsId, visited) {
+        if (visited.has(dsId)) {
+            return [];
+        }
+        visited.add(dsId);
+        const ds = datasets.get(dsId);
+        if (!ds) {
+            return [{ dataset_id: dsId, status: 'not_found' }];
+        }
+        const ancestors = [];
+        for (const parentId of ds.lineage) {
+            ancestors.push(...getAncestors(parentId, visited));
+        }
+        return [
+            {
+                dataset_id: ds.datasetId,
+                name: ds.name,
+                category: ds.category,
+                parents: ds.lineage,
+                transformations: ds.transformations,
+            },
+            ...ancestors,
+        ];
+    }
+    const visited = new Set();
+    const lineageTree = getAncestors(datasetId, visited);
+    return {
+        dataset_id: datasetId,
+        name: dataset.name,
+        lineage_depth: visited.size - 1,
+        lineage_tree: lineageTree,
+    };
+}
+function validateDatasetForUse(options) {
+    const dataset = datasets.get(options.datasetId);
+    if (!dataset) {
+        return {
+            valid: false,
+            dataset_id: options.datasetId,
+            issues: ['Dataset not found'],
+        };
+    }
+    const issues = [];
+    const governanceConfig = options.config?.data_governance;
+    // Check quality assessment
+    if (governanceConfig?.require_quality_assessment !== false) {
+        if (dataset.qualityStatus === 'not_assessed') {
+            issues.push('Quality assessment not performed');
+        }
+        else if (dataset.qualityStatus === 'failed') {
+            issues.push('Quality metrics below thresholds');
+        }
+    }
+    // Check bias assessment for training/validation
+    const requireBiasFor = governanceConfig?.require_bias_assessment_for || ['training', 'validation'];
+    if (requireBiasFor.includes(options.intendedUse)) {
+        if (dataset.biasAssessments.length === 0) {
+            issues.push(`Bias assessment required for ${options.intendedUse} datasets`);
+        }
+        else {
+            const failedBias = dataset.biasAssessments.filter(b => !b.passed);
+            if (failedBias.length > 0) {
+                issues.push(`Bias thresholds not met: ${failedBias.map(b => b.dimension).join(', ')}`);
+            }
+        }
+    }
+    return {
+        valid: issues.length === 0,
+        dataset_id: options.datasetId,
+        name: dataset.name,
+        intended_use: options.intendedUse,
+        quality_status: dataset.qualityStatus,
+        bias_assessments_count: dataset.biasAssessments.length,
+        issues,
+    };
+}
+/**
+ * Get a summary of a dataset for reporting.
+ */
+function getDatasetSummary(datasetId) {
+    const dataset = datasets.get(datasetId);
+    if (!dataset) {
+        return {};
+    }
+    return {
+        dataset_id: dataset.datasetId,
+        name: dataset.name,
+        category: dataset.category,
+        source: dataset.source,
+        acquisition_method: dataset.acquisitionMethod,
+        acquisition_date: dataset.acquisitionDate,
+        quality_status: dataset.qualityStatus,
+        quality_metrics: dataset.qualityMetrics ? qualityMetricsToDict(dataset.qualityMetrics) : null,
+        preparation_steps_count: dataset.preparationSteps.length,
+        bias_assessments_count: dataset.biasAssessments.length,
+        bias_assessments_passed: dataset.biasAssessments.filter(b => b.passed).length,
+        lineage_depth: dataset.lineage.length,
+        record_count: dataset.recordCount,
+    };
+}
+/**
+ * Get aggregate report of all datasets.
+ */
+function getDataGovernanceReport(config) {
+    if (datasets.size === 0) {
+        return {
+            total_datasets: 0,
+            by_category: {},
+            by_quality_status: {},
+            datasets: [],
+        };
+    }
+    const byCategory = {};
+    const byQuality = {};
+    const datasetsSummary = [];
+    datasets.forEach(dataset => {
+        byCategory[dataset.category] = (byCategory[dataset.category] || 0) + 1;
+        byQuality[dataset.qualityStatus] = (byQuality[dataset.qualityStatus] || 0) + 1;
+        datasetsSummary.push({
+            dataset_id: dataset.datasetId,
+            name: dataset.name,
+            category: dataset.category,
+            quality_status: dataset.qualityStatus,
+        });
+    });
+    return {
+        total_datasets: datasets.size,
+        by_category: byCategory,
+        by_quality_status: byQuality,
+        datasets: datasetsSummary,
+    };
+}
+/**
+ * Emit a data governance event.
+ */
+function emitDataGovernanceEvent(dataset, eventType, config) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { getState } = require('./runtime');
+        const state = getState();
+        if (state && typeof state.emitInternal === 'function') {
+            state.emitInternal({
+                event_type: eventType,
+                timestamp: nowIso(),
+                body: datasetRecordToDict(dataset),
+            });
+        }
+    }
+    catch (err) {
+        logger_1.logger.warning('Failed to emit data governance event:', err);
+    }
+}
+/**
+ * Emit the current state of a dataset record as an event.
+ */
+function emitDatasetRecord(datasetId, config) {
+    const dataset = getDatasetRecord(datasetId);
+    if (dataset) {
+        emitDataGovernanceEvent(dataset, 'dataset_record', config);
+    }
+}

package/dist/dataResidency.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Data residency validation for sinks.
+ *
+ * Validates that endpoint URLs match configured data residency requirements
+ * based on domain patterns for different geographic regions.
+ */
+import { DataResidency } from './config';
+/**
+ * Result of a data residency check.
+ */
+export interface DataResidencyCheckResult {
+    /** Whether the check passed */
+    valid: boolean;
+    /** Detected region of the endpoint (if determinable) */
+    detectedRegion: 'us' | 'eu' | 'unknown';
+    /** Required region */
+    requiredRegion: DataResidency;
+    /** The endpoint URL that was checked */
+    endpoint: string;
+    /** Human-readable message */
+    message: string;
+}
+/**
+ * Detect the likely data residency region of an endpoint URL.
+ */
+export declare function detectEndpointRegion(endpoint: string): 'us' | 'eu' | 'unknown';
+/**
+ * Validate that an endpoint URL matches the required data residency.
+ *
+ * @param endpoint - The endpoint URL to validate
+ * @param requiredResidency - The required data residency ('us', 'eu', 'any', or null)
+ * @returns Validation result with details
+ */
+export declare function validateDataResidency(endpoint: string, requiredResidency: DataResidency): DataResidencyCheckResult;
+/**
+ * Enforce data residency requirements for a sink endpoint.
+ *
+ * @param endpoint - The endpoint URL to validate
+ * @param residency - The required data residency
+ * @param action - Action on failure: 'block' throws error, 'warn' logs warning
+ * @throws Error if action is 'block' and validation fails
+ */
+export declare function enforceDataResidency(endpoint: string, residency: DataResidency, action?: 'block' | 'warn'): DataResidencyCheckResult;
+//# sourceMappingURL=dataResidency.d.ts.map

package/dist/dataResidency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataResidency.d.ts","sourceRoot":"","sources":["../src/dataResidency.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA0FzC;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,+BAA+B;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,wDAAwD;IACxD,cAAc,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;IACxC,sBAAsB;IACtB,cAAc,EAAE,aAAa,CAAC;IAC9B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAgBD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAuB9E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,aAAa,GAC/B,wBAAwB,CA4C1B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,OAAO,GAAG,MAAe,GAChC,wBAAwB,CAiB1B"}