@feltdb/core 0.2.0 → 0.3.0

package/dist/index-analytics.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Index Analytics and Performance Monitoring
+ *
+ * Tracks index usage, query performance, and generates optimization recommendations.
+ * Uses Rust implementation via WASM for performance-critical operations,
+ * with TypeScript fallback when WASM unavailable.
+ */
+export interface IndexMetrics {
+    name: string;
+    reads: number;
+    writes: number;
+    hitRate: number;
+    avgQueryTimeMs: number;
+    avgWriteTimeMs: number;
+    entries: number;
+    lastUsedAt: number;
+    createdAt: number;
+}
+export interface QueryTrace {
+    timestamp: number;
+    fields: string[];
+    operator: string;
+    indexUsed?: string;
+    executionTimeMs: number;
+    rowsScanned: number;
+    resultCount: number;
+}
+export interface PerformanceReport {
+    collectionName: string;
+    period: 'hourly' | 'daily' | 'weekly';
+    totalQueries: number;
+    indexedQueries: number;
+    fullScans: number;
+    avgQueryTimeMs: number;
+    slowestQuery?: QueryTrace;
+    indexMetrics: IndexMetrics[];
+    recommendations: TuningRecommendation[];
+    timestamp: number;
+}
+export interface TuningRecommendation {
+    type: 'create_index' | 'drop_index' | 'optimize_index';
+    priority: 'high' | 'medium' | 'low';
+    indexName?: string;
+    reason: string;
+    expectedSpeedup?: number;
+    estimatedROI?: number;
+}
+/**
+ * Tracks index usage and query performance.
+ */
+export declare class IndexAnalytics {
+    private metrics;
+    private queryTraces;
+    private fieldQueryCount;
+    private maxTraces;
+    /**
+     * Record an index usage event.
+     */
+    recordIndexUsage(indexName: string, operation: 'read' | 'write', timeMs: number): void;
+    /**
+     * Record a query execution.
+     */
+    recordQuery(fields: string[], operator: string, executionTimeMs: number, rowsScanned: number, resultCount: number, indexUsed?: string): void;
+    /**
+     * Get metrics for an index.
+     */
+    getIndexMetrics(indexName: string): IndexMetrics | null;
+    /**
+     * Get all index metrics.
+     */
+    getAllMetrics(): IndexMetrics[];
+    /**
+     * Get query traces (for performance analysis).
+     */
+    getQueryTraces(limit?: number): QueryTrace[];
+    /**
+     * Get slowest queries.
+     */
+    getSlowestQueries(limit?: number): QueryTrace[];
+    /**
+     * Get most frequently queried fields.
+     */
+    getFrequentFields(limit?: number): Array<[string, number]>;
+    /**
+     * Calculate hit rate for an index.
+     */
+    calculateHitRate(indexName: string): number;
+    /**
+     * Generate performance report.
+     */
+    generateReport(collectionName: string, period?: 'hourly' | 'daily' | 'weekly'): PerformanceReport;
+    /**
+     * Generate tuning recommendations based on usage patterns.
+     */
+    private generateRecommendations;
+    /**
+     * Reset analytics (for testing or period rollover).
+     */
+    reset(): void;
+}
+/**
+ * Automatic tuning engine - applies recommendations automatically.
+ */
+export declare class AutoTuner {
+    private analytics;
+    private appliedRecommendations;
+    constructor(analytics: IndexAnalytics);
+    /**
+     * Check if a recommendation should be auto-applied.
+     */
+    shouldAutoApply(recommendation: TuningRecommendation): boolean;
+    /**
+     * Apply a recommendation.
+     */
+    applyRecommendation(recommendation: TuningRecommendation): boolean;
+    /**
+     * Get recommendations that are ready for auto-apply.
+     */
+    getAutoApplyableRecommendations(report: PerformanceReport): TuningRecommendation[];
+}
+//# sourceMappingURL=index-analytics.d.ts.map

package/dist/index-analytics.d.ts.map

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

package/dist/index-analytics.js

@@ -0,0 +1,279 @@
+/**
+ * Index Analytics and Performance Monitoring
+ *
+ * Tracks index usage, query performance, and generates optimization recommendations.
+ * Uses Rust implementation via WASM for performance-critical operations,
+ * with TypeScript fallback when WASM unavailable.
+ */
+/**
+ * Tracks index usage and query performance.
+ */
+export class IndexAnalytics {
+    constructor() {
+        this.metrics = new Map();
+        this.queryTraces = [];
+        this.fieldQueryCount = new Map();
+        this.maxTraces = 10000; // Keep last 10K queries
+    }
+    /**
+     * Record an index usage event.
+     */
+    recordIndexUsage(indexName, operation, timeMs) {
+        if (!this.metrics.has(indexName)) {
+            this.metrics.set(indexName, {
+                name: indexName,
+                reads: 0,
+                writes: 0,
+                hitRate: 0,
+                avgQueryTimeMs: 0,
+                avgWriteTimeMs: 0,
+                entries: 0,
+                lastUsedAt: Date.now(),
+                createdAt: Date.now(),
+            });
+        }
+        const metric = this.metrics.get(indexName);
+        if (operation === 'read') {
+            metric.reads++;
+            metric.avgQueryTimeMs = (metric.avgQueryTimeMs * (metric.reads - 1) + timeMs) / metric.reads;
+        }
+        else {
+            metric.writes++;
+            metric.avgWriteTimeMs = (metric.avgWriteTimeMs * (metric.writes - 1) + timeMs) / metric.writes;
+        }
+        metric.lastUsedAt = Date.now();
+    }
+    /**
+     * Record a query execution.
+     */
+    recordQuery(fields, operator, executionTimeMs, rowsScanned, resultCount, indexUsed) {
+        const trace = {
+            timestamp: Date.now(),
+            fields,
+            operator,
+            indexUsed,
+            executionTimeMs,
+            rowsScanned,
+            resultCount,
+        };
+        this.queryTraces.push(trace);
+        if (this.queryTraces.length > this.maxTraces) {
+            this.queryTraces.shift();
+        }
+        // Track field access patterns
+        for (const field of fields) {
+            this.fieldQueryCount.set(field, (this.fieldQueryCount.get(field) || 0) + 1);
+        }
+        // Update hit rate
+        if (indexUsed && this.metrics.has(indexUsed)) {
+            const metric = this.metrics.get(indexUsed);
+            metric.reads++;
+        }
+    }
+    /**
+     * Get metrics for an index.
+     */
+    getIndexMetrics(indexName) {
+        return this.metrics.get(indexName) || null;
+    }
+    /**
+     * Get all index metrics.
+     */
+    getAllMetrics() {
+        return Array.from(this.metrics.values());
+    }
+    /**
+     * Get query traces (for performance analysis).
+     */
+    getQueryTraces(limit = 100) {
+        return this.queryTraces.slice(-limit);
+    }
+    /**
+     * Get slowest queries.
+     */
+    getSlowestQueries(limit = 10) {
+        return [...this.queryTraces]
+            .sort((a, b) => b.executionTimeMs - a.executionTimeMs)
+            .slice(0, limit);
+    }
+    /**
+     * Get most frequently queried fields.
+     */
+    getFrequentFields(limit = 20) {
+        return [...this.fieldQueryCount.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, limit);
+    }
+    /**
+     * Calculate hit rate for an index.
+     */
+    calculateHitRate(indexName) {
+        const metric = this.metrics.get(indexName);
+        if (!metric || metric.reads === 0)
+            return 0;
+        const queriesUsingIndex = this.queryTraces.filter(q => q.indexUsed === indexName).length;
+        const totalQueries = this.queryTraces.length;
+        return totalQueries > 0 ? queriesUsingIndex / totalQueries : 0;
+    }
+    /**
+     * Generate performance report.
+     */
+    generateReport(collectionName, period = 'daily') {
+        const now = Date.now();
+        const cutoff = period === 'hourly'
+            ? now - 3600000
+            : period === 'daily'
+                ? now - 86400000
+                : now - 604800000;
+        const recentTraces = this.queryTraces.filter(t => t.timestamp > cutoff);
+        const indexedQueries = recentTraces.filter(t => t.indexUsed).length;
+        const fullScans = recentTraces.length - indexedQueries;
+        const avgQueryTime = recentTraces.length > 0
+            ? recentTraces.reduce((sum, t) => sum + t.executionTimeMs, 0) / recentTraces.length
+            : 0;
+        const slowestQuery = recentTraces.length > 0
+            ? [...recentTraces].sort((a, b) => b.executionTimeMs - a.executionTimeMs)[0]
+            : undefined;
+        const metrics = this.getAllMetrics().map(m => ({
+            ...m,
+            hitRate: this.calculateHitRate(m.name),
+        }));
+        const recommendations = this.generateRecommendations(recentTraces, metrics);
+        return {
+            collectionName,
+            period,
+            totalQueries: recentTraces.length,
+            indexedQueries,
+            fullScans,
+            avgQueryTimeMs: avgQueryTime,
+            slowestQuery,
+            indexMetrics: metrics,
+            recommendations,
+            timestamp: now,
+        };
+    }
+    /**
+     * Generate tuning recommendations based on usage patterns.
+     */
+    generateRecommendations(traces, metrics) {
+        const recommendations = [];
+        if (traces.length === 0)
+            return recommendations;
+        // Recommend indexes for frequently scanned fields
+        const fieldScans = new Map();
+        for (const trace of traces) {
+            if (!trace.indexUsed && trace.rowsScanned > 1000) {
+                // Full scan with many rows
+                for (const field of trace.fields) {
+                    fieldScans.set(field, (fieldScans.get(field) || 0) + trace.rowsScanned);
+                }
+            }
+        }
+        // Recommend creating indexes for high-cost full scans
+        for (const [field, totalRowsScanned] of fieldScans) {
+            const avgScannedPerQuery = totalRowsScanned / traces.length;
+            if (avgScannedPerQuery > 1000) {
+                recommendations.push({
+                    type: 'create_index',
+                    priority: 'high',
+                    reason: `Field '${field}' scanned ${avgScannedPerQuery.toFixed(0)} rows per query`,
+                    expectedSpeedup: avgScannedPerQuery / 10, // Estimate 10x speedup with index
+                });
+            }
+        }
+        // Recommend dropping unused indexes
+        const unusedThreshold = 0.01; // Hit rate < 1%
+        for (const metric of metrics) {
+            if (metric.hitRate < unusedThreshold && metric.lastUsedAt < Date.now() - 86400000) {
+                // Not used in last 24 hours
+                recommendations.push({
+                    type: 'drop_index',
+                    priority: 'low',
+                    indexName: metric.name,
+                    reason: `Index has ${(metric.hitRate * 100).toFixed(1)}% hit rate and unused for 24h`,
+                    estimatedROI: -0.01, // Minor cleanup benefit
+                });
+            }
+        }
+        // Recommend compound indexes
+        const fieldPairs = new Map();
+        for (const trace of traces) {
+            if (trace.fields.length === 2) {
+                const key = [...trace.fields].sort().join('|');
+                fieldPairs.set(key, (fieldPairs.get(key) || 0) + 1);
+            }
+        }
+        for (const [fields, count] of fieldPairs) {
+            if (count > traces.length * 0.1) {
+                // Used in > 10% of queries
+                const fieldArray = fields.split('|');
+                recommendations.push({
+                    type: 'create_index',
+                    priority: 'medium',
+                    reason: `Fields '${fieldArray.join(', ')}' queried together in ${count} queries`,
+                    expectedSpeedup: 5, // Estimate 5x speedup with compound index
+                });
+            }
+        }
+        // Sort by priority and expected impact
+        recommendations.sort((a, b) => {
+            const priorityOrder = { high: 0, medium: 1, low: 2 };
+            const priorityDiff = priorityOrder[a.priority] - priorityOrder[b.priority];
+            if (priorityDiff !== 0)
+                return priorityDiff;
+            return (b.expectedSpeedup || 0) - (a.expectedSpeedup || 0);
+        });
+        return recommendations.slice(0, 5); // Top 5 recommendations
+    }
+    /**
+     * Reset analytics (for testing or period rollover).
+     */
+    reset() {
+        this.metrics.clear();
+        this.queryTraces = [];
+        this.fieldQueryCount.clear();
+    }
+}
+/**
+ * Automatic tuning engine - applies recommendations automatically.
+ */
+export class AutoTuner {
+    constructor(analytics) {
+        this.appliedRecommendations = new Set();
+        this.analytics = analytics;
+    }
+    /**
+     * Check if a recommendation should be auto-applied.
+     */
+    shouldAutoApply(recommendation) {
+        // Only auto-apply high-priority recommendations
+        if (recommendation.priority !== 'high')
+            return false;
+        // Don't apply the same recommendation twice
+        const key = `${recommendation.type}:${recommendation.indexName || recommendation.reason}`;
+        if (this.appliedRecommendations.has(key))
+            return false;
+        // Expected speedup should be significant (5x or more)
+        if ((recommendation.expectedSpeedup || 0) < 5)
+            return false;
+        return true;
+    }
+    /**
+     * Apply a recommendation.
+     */
+    applyRecommendation(recommendation) {
+        if (!this.shouldAutoApply(recommendation))
+            return false;
+        const key = `${recommendation.type}:${recommendation.indexName || recommendation.reason}`;
+        this.appliedRecommendations.add(key);
+        // Implementation would call collection.createIndex() or drop index
+        // For now, just track that we would apply it
+        return true;
+    }
+    /**
+     * Get recommendations that are ready for auto-apply.
+     */
+    getAutoApplyableRecommendations(report) {
+        return report.recommendations.filter(r => this.shouldAutoApply(r));
+    }
+}

package/dist/index-backend.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Index Backend - Dynamically selects between WASM and TypeScript implementations
+ *
+ * Uses Rust/WASM for production performance, falls back to TS for testing/development
+ */
+import type { IndexConfig, IndexQuery } from './index-types.js';
+export interface IIndexBackend {
+    createIndex(config: IndexConfig): void;
+    updateRecord(recordId: string, oldValue: Record<string, any> | null, newValue: Record<string, any>): void;
+    queryIndex(name: string, query: IndexQuery): string[];
+    queryCompoundIndex(name: string, values: Record<string, any>): string[];
+    listIndexes(): IndexConfig[];
+}
+export declare class IndexBackend implements IIndexBackend {
+    private tsBackend;
+    private wasmBackend;
+    private useWasm;
+    constructor();
+    initializeWasm(): Promise<void>;
+    createIndex(config: IndexConfig): void;
+    updateRecord(recordId: string, oldValue: Record<string, any> | null, newValue: Record<string, any>): void;
+    queryIndex(name: string, query: IndexQuery): string[];
+    queryCompoundIndex(name: string, values: Record<string, any>): string[];
+    listIndexes(): IndexConfig[];
+}
+//# sourceMappingURL=index-backend.d.ts.map

package/dist/index-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-backend.d.ts","sourceRoot":"","sources":["../src/index-backend.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEhE,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1G,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,CAAC;IACtD,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CAAC;IACxE,WAAW,IAAI,WAAW,EAAE,CAAC;CAC9B;AAyBD,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,OAAO,CAAkB;;IAM3B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAcrC,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAYtC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAezG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE;IAYrD,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAgBvE,WAAW,IAAI,WAAW,EAAE;CAW7B"}

package/dist/index-backend.js

@@ -0,0 +1,115 @@
+/**
+ * Index Backend - Dynamically selects between WASM and TypeScript implementations
+ *
+ * Uses Rust/WASM for production performance, falls back to TS for testing/development
+ */
+let wasmIndexModule = null;
+let wasmAvailable = false;
+async function loadWasm() {
+    if (wasmIndexModule !== null)
+        return wasmIndexModule;
+    try {
+        // Try to import WASM module
+        // @ts-ignore - WASM module is optional and built separately
+        const wasmModule = await import('@feltdb/wasm');
+        wasmIndexModule = wasmModule;
+        wasmAvailable = true;
+        return wasmModule;
+    }
+    catch {
+        // Fall back to TypeScript implementation
+        wasmAvailable = false;
+        return null;
+    }
+}
+// Import TS implementation for fallback
+import { IndexManager as TsIndexManager } from './index-manager.js';
+export class IndexBackend {
+    constructor() {
+        this.tsBackend = null;
+        this.wasmBackend = null;
+        this.useWasm = false;
+        this.tsBackend = new TsIndexManager();
+    }
+    async initializeWasm() {
+        if (this.wasmBackend !== null)
+            return;
+        const wasm = await loadWasm();
+        if (wasm && wasm.WasmIndexManager) {
+            try {
+                this.wasmBackend = new wasm.WasmIndexManager();
+                this.useWasm = true;
+            }
+            catch {
+                this.useWasm = false;
+            }
+        }
+    }
+    createIndex(config) {
+        if (this.useWasm && this.wasmBackend) {
+            try {
+                this.wasmBackend.create_index(JSON.stringify(config));
+                return;
+            }
+            catch {
+                // Fall back to TS
+            }
+        }
+        this.tsBackend?.createIndex(config);
+    }
+    updateRecord(recordId, oldValue, newValue) {
+        if (this.useWasm && this.wasmBackend) {
+            try {
+                // Convert record to index-friendly string format
+                const oldStr = oldValue ? JSON.stringify(oldValue) : null;
+                const newStr = JSON.stringify(newValue);
+                this.wasmBackend.update_record(recordId, oldStr, newStr);
+                return;
+            }
+            catch {
+                // Fall back to TS
+            }
+        }
+        this.tsBackend?.updateRecord(recordId, oldValue, newValue);
+    }
+    queryIndex(name, query) {
+        if (this.useWasm && this.wasmBackend) {
+            try {
+                const results = this.wasmBackend.query_index(name, query.operator, String(query.value || ''));
+                return JSON.parse(results);
+            }
+            catch {
+                // Fall back to TS
+            }
+        }
+        return this.tsBackend?.queryIndex(name, query) || [];
+    }
+    queryCompoundIndex(name, values) {
+        if (this.useWasm && this.wasmBackend) {
+            try {
+                const valueString = Object.values(values)
+                    .map(v => String(v))
+                    .join('\0');
+                const results = this.wasmBackend.query_index(name, 'eq', valueString);
+                return JSON.parse(results);
+            }
+            catch {
+                // Fall back to TS
+            }
+        }
+        // For TS backend, this would need a similar compound query interface
+        return [];
+    }
+    listIndexes() {
+        if (this.useWasm && this.wasmBackend) {
+            try {
+                const indexes = this.wasmBackend.list_indexes();
+                return JSON.parse(indexes);
+            }
+            catch {
+                // Fall back to TS
+            }
+        }
+        return this.tsBackend?.listIndexes() || [];
+    }
+}

package/dist/index-dashboard.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Index Performance Dashboard
+ *
+ * Real-time visualization and monitoring of index performance metrics.
+ */
+import type { IndexMetrics, PerformanceReport, TuningRecommendation } from './index-analytics.js';
+export interface DashboardMetrics {
+    timestamp: number;
+    indexes: IndexDashboard[];
+    queryPerformance: QueryPerformanceSummary;
+    recommendations: TuningRecommendation[];
+}
+export interface IndexDashboard {
+    name: string;
+    type: string;
+    reads: number;
+    writes: number;
+    hitRate: number;
+    avgQueryMs: number;
+    avgWriteMs: number;
+    entries: number;
+    lastUsedRelative: string;
+    health: 'healthy' | 'warning' | 'critical';
+    healthReason?: string;
+}
+export interface QueryPerformanceSummary {
+    totalQueries: number;
+    indexedQueries: number;
+    fullScans: number;
+    indexUsageRate: number;
+    avgQueryMs: number;
+    p50QueryMs: number;
+    p95QueryMs: number;
+    p99QueryMs: number;
+    slowQueries: number;
+}
+/**
+ * Dashboard formatter - converts raw metrics to display format.
+ */
+export declare class DashboardFormatter {
+    /**
+     * Format index metrics for display.
+     */
+    static formatIndexMetrics(metrics: IndexMetrics): IndexDashboard;
+    /**
+     * Format performance report for display.
+     */
+    static formatReport(report: PerformanceReport): DashboardMetrics;
+    /**
+     * Format duration for display.
+     */
+    private static formatDuration;
+    /**
+     * Generate ASCII dashboard.
+     */
+    static renderASCII(dashboard: DashboardMetrics): string;
+    /**
+     * Generate JSON dashboard data.
+     */
+    static renderJSON(dashboard: DashboardMetrics): string;
+}
+/**
+ * Real-time dashboard updates via events.
+ */
+export declare class LiveDashboard {
+    private metrics;
+    private listeners;
+    private updateInterval;
+    private intervalHandle?;
+    /**
+     * Start streaming dashboard updates.
+     */
+    start(updateFn: () => DashboardMetrics, interval?: number): void;
+    /**
+     * Stop streaming updates.
+     */
+    stop(): void;
+    /**
+     * Subscribe to dashboard updates.
+     */
+    subscribe(listener: (metrics: DashboardMetrics) => void): () => void;
+    /**
+     * Get current dashboard state.
+     */
+    getCurrent(): DashboardMetrics | null;
+    private notifyListeners;
+}
+/**
+ * Alert system for performance anomalies.
+ */
+export interface PerformanceAlert {
+    severity: 'info' | 'warning' | 'critical';
+    type: 'slow_query' | 'high_full_scans' | 'unused_index' | 'index_overhead';
+    message: string;
+    timestamp: number;
+    metrics?: Record<string, number | string>;
+}
+export declare class PerformanceAlerter {
+    private alerts;
+    private thresholds;
+    /**
+     * Check dashboard against thresholds and generate alerts.
+     */
+    checkThresholds(dashboard: DashboardMetrics): PerformanceAlert[];
+    /**
+     * Get recent alerts.
+     */
+    getRecentAlerts(limit?: number): PerformanceAlert[];
+    /**
+     * Clear old alerts.
+     */
+    clearOldAlerts(olderThanMs?: number): void;
+}
+//# sourceMappingURL=index-dashboard.d.ts.map

package/dist/index-dashboard.d.ts.map

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