@dotdo/postgres 0.1.0

package/dist/routing/cost-metrics.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Cost Metrics Collector
+ *
+ * Task: postgres-d6g.9
+ *
+ * Collects and analyzes routing cost metrics to optimize decisions.
+ *
+ * Cost Model:
+ * - Worker: $0.02 per million CPU ms
+ * - DO: $12.50 per million requests + wall time
+ * - WebSocket hibernation: 95% cheaper for idle DO connections
+ */
+export type RuntimeType = 'worker' | 'durable-object';
+export interface QueryExecution {
+    queryId: string;
+    sql: string;
+    runtime: RuntimeType;
+    cpuTimeMs: number;
+    wallTimeMs: number;
+    timestamp: number;
+    sqlHash?: string;
+    metadata?: {
+        queryType?: string;
+        tablesAccessed?: string[];
+        rowsReturned?: number;
+        [key: string]: unknown;
+    };
+}
+export interface WebSocketSession {
+    connectionId: string;
+    activeTimeMs: number;
+    hibernatedTimeMs: number;
+    messagesCount: number;
+}
+export interface TimeWindow {
+    since?: number;
+    until?: number;
+}
+export interface RuntimeCosts {
+    cpuCost: number;
+    requestCost: number;
+    durationCost: number;
+    hibernationSavings: number;
+}
+export interface CostSummary {
+    worker: {
+        executionCount: number;
+        totalCpuTimeMs: number;
+        avgCpuTimeMs: number;
+        p50CpuTimeMs: number;
+        p95CpuTimeMs: number;
+        p99CpuTimeMs: number;
+        totalCost: number;
+    };
+    durableObject: {
+        executionCount: number;
+        totalCpuTimeMs: number;
+        avgCpuTimeMs: number;
+        p50CpuTimeMs: number;
+        p95CpuTimeMs: number;
+        p99CpuTimeMs: number;
+        totalCost: number;
+    };
+    totalCpuTimeMs: number;
+    totalCost: number;
+}
+export interface CostBreakdown {
+    byQueryType: Record<string, {
+        cost: number;
+        count: number;
+        avgCpuTimeMs: number;
+    }>;
+    byTable: Record<string, {
+        cost: number;
+        count: number;
+        avgCpuTimeMs: number;
+    }>;
+}
+export interface RuntimeComparison {
+    workerCost: number;
+    doCost: number;
+    recommendation: RuntimeType;
+    savingsPercent: number;
+}
+export interface Anomaly {
+    queryId: string;
+    sql: string;
+    cpuTimeMs: number;
+    reason: string;
+}
+export interface AnomalyReport {
+    slowQueries: Anomaly[];
+    routingInefficiencies: Anomaly[];
+}
+export interface CollectorConfig {
+    /** Worker CPU cost per million ms (default: $0.02) */
+    workerCpuCostPerMillion?: number;
+    /** DO request cost per million requests (default: $12.50) */
+    doRequestCostPerMillion?: number;
+    /** DO duration cost per GB-second (default: $12.50) */
+    doDurationCostPerGbSecond?: number;
+    /** DO memory in MB for duration calculation (default: 128) */
+    doMemoryMb?: number;
+    /** Maximum number of executions to retain */
+    maxExecutions?: number;
+    /** Slow query threshold in ms */
+    slowQueryThresholdMs?: number;
+    /** CPU time threshold for routing decision (default: 50ms) */
+    cpuTimeThresholdMs?: number;
+}
+export declare class CostMetricsCollector {
+    private executions;
+    private webSocketSessions;
+    private config;
+    constructor(config?: CollectorConfig);
+    recordExecution(execution: QueryExecution): void;
+    recordWebSocketSession(session: WebSocketSession): void;
+    getExecutions(window?: TimeWindow): QueryExecution[];
+    calculateCosts(window?: TimeWindow): CostSummary & {
+        worker: RuntimeCosts;
+        durableObject: RuntimeCosts;
+    };
+    private calculatePercentiles;
+    compareRuntimes(sqlHash: string): RuntimeComparison;
+    getSummary(window?: TimeWindow): CostSummary;
+    getCostBreakdown(window?: TimeWindow): CostBreakdown;
+    private calculateExecutionCost;
+    detectAnomalies(): AnomalyReport;
+    exportJSON(): string;
+    importJSON(json: string): void;
+    clear(): void;
+}
+//# sourceMappingURL=cost-metrics.d.ts.map

package/dist/routing/cost-metrics.d.ts.map

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

package/dist/routing/cost-metrics.js

@@ -0,0 +1,259 @@
+/**
+ * Cost Metrics Collector
+ *
+ * Task: postgres-d6g.9
+ *
+ * Collects and analyzes routing cost metrics to optimize decisions.
+ *
+ * Cost Model:
+ * - Worker: $0.02 per million CPU ms
+ * - DO: $12.50 per million requests + wall time
+ * - WebSocket hibernation: 95% cheaper for idle DO connections
+ */
+export class CostMetricsCollector {
+    executions = [];
+    webSocketSessions = [];
+    config;
+    constructor(config = {}) {
+        this.config = {
+            workerCpuCostPerMillion: config.workerCpuCostPerMillion ?? 0.02,
+            doRequestCostPerMillion: config.doRequestCostPerMillion ?? 12.50,
+            doDurationCostPerGbSecond: config.doDurationCostPerGbSecond ?? 12.50,
+            doMemoryMb: config.doMemoryMb ?? 128,
+            maxExecutions: config.maxExecutions ?? 10000,
+            slowQueryThresholdMs: config.slowQueryThresholdMs ?? 100,
+            cpuTimeThresholdMs: config.cpuTimeThresholdMs ?? 50,
+        };
+    }
+    recordExecution(execution) {
+        this.executions.push(execution);
+        // Evict oldest if over limit
+        if (this.executions.length > this.config.maxExecutions) {
+            this.executions.sort((a, b) => a.timestamp - b.timestamp);
+            this.executions = this.executions.slice(-this.config.maxExecutions);
+        }
+    }
+    recordWebSocketSession(session) {
+        this.webSocketSessions.push(session);
+    }
+    getExecutions(window) {
+        let filtered = this.executions;
+        if (window?.since) {
+            filtered = filtered.filter(e => e.timestamp >= window.since);
+        }
+        if (window?.until) {
+            filtered = filtered.filter(e => e.timestamp <= window.until);
+        }
+        return filtered;
+    }
+    calculateCosts(window) {
+        const executions = this.getExecutions(window);
+        const workerExecs = executions.filter(e => e.runtime === 'worker');
+        const doExecs = executions.filter(e => e.runtime === 'durable-object');
+        // Worker costs
+        const workerCpuTimeMs = workerExecs.reduce((sum, e) => sum + e.cpuTimeMs, 0);
+        const workerCpuCost = (workerCpuTimeMs / 1_000_000) * this.config.workerCpuCostPerMillion;
+        // DO costs
+        const doRequestCost = (doExecs.length / 1_000_000) * this.config.doRequestCostPerMillion;
+        const doWallTimeSeconds = doExecs.reduce((sum, e) => sum + e.wallTimeMs, 0) / 1000;
+        const doMemoryGb = this.config.doMemoryMb / 1024;
+        const doDurationCost = doWallTimeSeconds * doMemoryGb * this.config.doDurationCostPerGbSecond;
+        // Calculate hibernation savings
+        let hibernationSavings = 0;
+        for (const session of this.webSocketSessions) {
+            const totalTime = session.activeTimeMs + session.hibernatedTimeMs;
+            if (totalTime > 0) {
+                // Hibernation saves ~95% of duration cost for hibernated time
+                const potentialCost = (session.hibernatedTimeMs / 1000) * doMemoryGb * this.config.doDurationCostPerGbSecond;
+                hibernationSavings += potentialCost * 0.95;
+            }
+        }
+        const doCpuTimeMs = doExecs.reduce((sum, e) => sum + e.cpuTimeMs, 0);
+        return {
+            worker: {
+                cpuCost: workerCpuCost,
+                requestCost: 0,
+                durationCost: 0,
+                hibernationSavings: 0,
+                executionCount: workerExecs.length,
+                totalCpuTimeMs: workerCpuTimeMs,
+                avgCpuTimeMs: workerExecs.length > 0 ? workerCpuTimeMs / workerExecs.length : 0,
+                ...this.calculatePercentiles(workerExecs.map(e => e.cpuTimeMs)),
+                totalCost: workerCpuCost,
+            },
+            durableObject: {
+                cpuCost: 0,
+                requestCost: doRequestCost,
+                durationCost: doDurationCost,
+                hibernationSavings,
+                executionCount: doExecs.length,
+                totalCpuTimeMs: doCpuTimeMs,
+                avgCpuTimeMs: doExecs.length > 0 ? doCpuTimeMs / doExecs.length : 0,
+                ...this.calculatePercentiles(doExecs.map(e => e.cpuTimeMs)),
+                totalCost: doRequestCost + doDurationCost - hibernationSavings,
+            },
+            totalCpuTimeMs: workerCpuTimeMs + doCpuTimeMs,
+            totalCost: workerCpuCost + doRequestCost + doDurationCost - hibernationSavings,
+        };
+    }
+    calculatePercentiles(values) {
+        if (values.length === 0) {
+            return { p50CpuTimeMs: 0, p95CpuTimeMs: 0, p99CpuTimeMs: 0 };
+        }
+        const sorted = [...values].sort((a, b) => a - b);
+        const percentile = (p) => {
+            const index = Math.ceil((p / 100) * sorted.length) - 1;
+            return sorted[Math.max(0, index)] ?? 0;
+        };
+        return {
+            p50CpuTimeMs: percentile(50),
+            p95CpuTimeMs: percentile(95),
+            p99CpuTimeMs: percentile(99),
+        };
+    }
+    compareRuntimes(sqlHash) {
+        const executions = this.executions.filter(e => e.sqlHash === sqlHash);
+        const workerExecs = executions.filter(e => e.runtime === 'worker');
+        const doExecs = executions.filter(e => e.runtime === 'durable-object');
+        // Calculate average costs
+        const avgWorkerCpuTimeMs = workerExecs.length > 0
+            ? workerExecs.reduce((sum, e) => sum + e.cpuTimeMs, 0) / workerExecs.length
+            : 0;
+        const workerCost = (avgWorkerCpuTimeMs / 1_000_000) * this.config.workerCpuCostPerMillion;
+        // For DO, include request cost per query
+        const doRequestCostPerQuery = this.config.doRequestCostPerMillion / 1_000_000;
+        const avgDoWallTimeMs = doExecs.length > 0
+            ? doExecs.reduce((sum, e) => sum + e.wallTimeMs, 0) / doExecs.length
+            : 0;
+        const doMemoryGb = this.config.doMemoryMb / 1024;
+        const doDurationCostPerQuery = (avgDoWallTimeMs / 1000) * doMemoryGb * this.config.doDurationCostPerGbSecond;
+        const doCost = doRequestCostPerQuery + doDurationCostPerQuery;
+        // Default to worker for simple queries if no data
+        if (workerExecs.length === 0 && doExecs.length === 0) {
+            return {
+                workerCost: 0,
+                doCost: 0,
+                recommendation: 'worker',
+                savingsPercent: 0,
+            };
+        }
+        const recommendation = workerCost <= doCost ? 'worker' : 'durable-object';
+        const maxCost = Math.max(workerCost, doCost);
+        const minCost = Math.min(workerCost, doCost);
+        const savingsPercent = maxCost > 0 ? ((maxCost - minCost) / maxCost) * 100 : 0;
+        return {
+            workerCost,
+            doCost,
+            recommendation,
+            savingsPercent,
+        };
+    }
+    getSummary(window) {
+        const costs = this.calculateCosts(window);
+        return {
+            worker: {
+                executionCount: costs.worker.executionCount,
+                totalCpuTimeMs: costs.worker.totalCpuTimeMs,
+                avgCpuTimeMs: costs.worker.avgCpuTimeMs,
+                p50CpuTimeMs: costs.worker.p50CpuTimeMs,
+                p95CpuTimeMs: costs.worker.p95CpuTimeMs,
+                p99CpuTimeMs: costs.worker.p99CpuTimeMs,
+                totalCost: costs.worker.totalCost,
+            },
+            durableObject: {
+                executionCount: costs.durableObject.executionCount,
+                totalCpuTimeMs: costs.durableObject.totalCpuTimeMs,
+                avgCpuTimeMs: costs.durableObject.avgCpuTimeMs,
+                p50CpuTimeMs: costs.durableObject.p50CpuTimeMs,
+                p95CpuTimeMs: costs.durableObject.p95CpuTimeMs,
+                p99CpuTimeMs: costs.durableObject.p99CpuTimeMs,
+                totalCost: costs.durableObject.totalCost,
+            },
+            totalCpuTimeMs: costs.totalCpuTimeMs,
+            totalCost: costs.totalCost,
+        };
+    }
+    getCostBreakdown(window) {
+        const executions = this.getExecutions(window);
+        const byQueryType = {};
+        const byTable = {};
+        for (const exec of executions) {
+            const cost = this.calculateExecutionCost(exec);
+            const queryType = exec.metadata?.queryType ?? 'UNKNOWN';
+            if (!byQueryType[queryType]) {
+                byQueryType[queryType] = { cost: 0, count: 0, avgCpuTimeMs: 0 };
+            }
+            byQueryType[queryType].cost += cost;
+            byQueryType[queryType].count++;
+            byQueryType[queryType].avgCpuTimeMs =
+                (byQueryType[queryType].avgCpuTimeMs * (byQueryType[queryType].count - 1) + exec.cpuTimeMs) /
+                    byQueryType[queryType].count;
+            const tables = exec.metadata?.tablesAccessed ?? [];
+            for (const table of tables) {
+                if (!byTable[table]) {
+                    byTable[table] = { cost: 0, count: 0, avgCpuTimeMs: 0 };
+                }
+                byTable[table].cost += cost;
+                byTable[table].count++;
+                byTable[table].avgCpuTimeMs =
+                    (byTable[table].avgCpuTimeMs * (byTable[table].count - 1) + exec.cpuTimeMs) /
+                        byTable[table].count;
+            }
+        }
+        return { byQueryType, byTable };
+    }
+    calculateExecutionCost(exec) {
+        if (exec.runtime === 'worker') {
+            return (exec.cpuTimeMs / 1_000_000) * this.config.workerCpuCostPerMillion;
+        }
+        else {
+            const requestCost = this.config.doRequestCostPerMillion / 1_000_000;
+            const doMemoryGb = this.config.doMemoryMb / 1024;
+            const durationCost = (exec.wallTimeMs / 1000) * doMemoryGb * this.config.doDurationCostPerGbSecond;
+            return requestCost + durationCost;
+        }
+    }
+    detectAnomalies() {
+        const slowQueries = [];
+        const routingInefficiencies = [];
+        for (const exec of this.executions) {
+            // Detect slow queries
+            if (exec.cpuTimeMs >= this.config.slowQueryThresholdMs) {
+                slowQueries.push({
+                    queryId: exec.queryId,
+                    sql: exec.sql,
+                    cpuTimeMs: exec.cpuTimeMs,
+                    reason: `CPU time ${exec.cpuTimeMs}ms exceeds threshold ${this.config.slowQueryThresholdMs}ms`,
+                });
+            }
+            // Detect routing inefficiencies (Worker used for complex queries)
+            if (exec.runtime === 'worker' && exec.cpuTimeMs > this.config.cpuTimeThresholdMs) {
+                routingInefficiencies.push({
+                    queryId: exec.queryId,
+                    sql: exec.sql,
+                    cpuTimeMs: exec.cpuTimeMs,
+                    reason: `Worker used for query with ${exec.cpuTimeMs}ms CPU time (threshold: ${this.config.cpuTimeThresholdMs}ms)`,
+                });
+            }
+        }
+        return { slowQueries, routingInefficiencies };
+    }
+    exportJSON() {
+        return JSON.stringify({
+            executions: this.executions,
+            webSocketSessions: this.webSocketSessions,
+            summary: this.getSummary(),
+            config: this.config,
+        });
+    }
+    importJSON(json) {
+        const data = JSON.parse(json);
+        this.executions = data.executions ?? [];
+        this.webSocketSessions = data.webSocketSessions ?? [];
+    }
+    clear() {
+        this.executions = [];
+        this.webSocketSessions = [];
+    }
+}
+//# sourceMappingURL=cost-metrics.js.map

package/dist/routing/cost-metrics.js.map

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

package/dist/routing/do-connection-pool.d.ts

@@ -0,0 +1,243 @@
+/**
+ * DO Connection Pool
+ *
+ * Task: postgres-zjj
+ *
+ * Generic connection pooling layer for high-concurrency scenarios.
+ * Provides connection reuse, health checking, and fair queuing.
+ *
+ * Key features:
+ * - Maintain pool of warm DO connections
+ * - Connection reuse to reduce latency
+ * - Max pool size configuration
+ * - Idle connection timeout
+ * - Health checking of pooled connections
+ * - Fair queuing when pool exhausted
+ */
+/**
+ * Interface for a generic poolable connection.
+ * Implementations should handle their own transport (WebSocket, HTTP, etc.)
+ */
+export interface PoolableConnection {
+    /** Unique identifier for this connection */
+    readonly id: string;
+    /** Check if connection is healthy and ready for use */
+    isHealthy(): boolean;
+    /** Close the connection and release resources */
+    close(): Promise<void>;
+    /** Get the timestamp of last activity */
+    getLastActivity(): number;
+    /** Update the last activity timestamp */
+    touch(): void;
+}
+/**
+ * Factory function to create new connections
+ */
+export type ConnectionFactory<T extends PoolableConnection> = () => Promise<T>;
+/**
+ * Health check function for validating connections
+ */
+export type HealthChecker<T extends PoolableConnection> = (conn: T) => Promise<boolean>;
+/**
+ * Configuration for the DO connection pool
+ */
+export interface DOPoolConfig<T extends PoolableConnection> {
+    /** Factory function to create new connections */
+    factory: ConnectionFactory<T>;
+    /** Maximum number of connections in the pool */
+    maxSize?: number;
+    /** Minimum number of warm connections to maintain */
+    minSize?: number;
+    /** Idle timeout before closing connection (ms) */
+    idleTimeoutMs?: number;
+    /** Timeout for acquiring a connection (ms) */
+    acquireTimeoutMs?: number;
+    /** Enable health checking of pooled connections */
+    enableHealthCheck?: boolean;
+    /** Interval for periodic health checks (ms) */
+    healthCheckIntervalMs?: number;
+    /** Custom health check function */
+    healthChecker?: HealthChecker<T>;
+    /** Enable fair queuing when pool is exhausted */
+    fairQueue?: boolean;
+    /** Maximum number of pending acquire requests in queue */
+    maxQueueSize?: number;
+    /** Enable automatic scaling of pool size based on demand */
+    autoScale?: boolean;
+    /** Scale up threshold (percentage of pool in use) */
+    scaleUpThreshold?: number;
+    /** Scale down threshold (percentage of pool in use) */
+    scaleDownThreshold?: number;
+    /** Connection validation timeout (ms) */
+    validationTimeoutMs?: number;
+    /** Enable connection warming on startup */
+    warmOnStart?: boolean;
+    /** Number of connections to warm on startup */
+    warmCount?: number;
+}
+/**
+ * Statistics for a single connection
+ */
+export interface ConnectionStats {
+    id: string;
+    createdAt: number;
+    lastUsedAt: number;
+    useCount: number;
+    errorCount: number;
+    state: 'idle' | 'in_use' | 'validating' | 'closed';
+}
+/**
+ * Pool utilization metrics
+ */
+export interface DOPoolMetrics {
+    /** Total number of connections created */
+    totalCreated: number;
+    /** Total number of connections closed */
+    totalClosed: number;
+    /** Current pool size */
+    currentSize: number;
+    /** Number of connections currently in use */
+    inUse: number;
+    /** Number of idle connections available */
+    available: number;
+    /** Number of pending acquire requests in queue */
+    pendingRequests: number;
+    /** Total successful acquisitions */
+    totalAcquisitions: number;
+    /** Total releases back to pool */
+    totalReleases: number;
+    /** Total health checks performed */
+    totalHealthChecks: number;
+    /** Total connections failed health check */
+    totalHealthCheckFailures: number;
+    /** Average wait time for acquire (ms) */
+    avgWaitTimeMs: number;
+    /** Maximum wait time observed (ms) */
+    maxWaitTimeMs: number;
+    /** Total acquire timeouts */
+    totalTimeouts: number;
+    /** Current queue length */
+    queueLength: number;
+    /** Pool utilization percentage */
+    utilizationPercent: number;
+    /** Timestamp of last activity */
+    lastActivityAt: number;
+}
+/**
+ * Generic connection pool for Durable Object connections.
+ * Designed for high-concurrency scenarios with fair queuing.
+ */
+export declare class DOConnectionPool<T extends PoolableConnection> {
+    private readonly config;
+    private readonly connections;
+    private readonly idleConnections;
+    private readonly pendingQueue;
+    private readonly idleTimers;
+    private healthCheckInterval;
+    private scaleCheckInterval;
+    private closed;
+    private totalCreated;
+    private totalClosed;
+    private totalAcquisitions;
+    private totalReleases;
+    private totalHealthChecks;
+    private totalHealthCheckFailures;
+    private totalTimeouts;
+    private waitTimes;
+    private lastActivityAt;
+    constructor(config: DOPoolConfig<T>);
+    /**
+     * Initialize the pool with warm connections
+     */
+    initialize(): Promise<void>;
+    /**
+     * Acquire a connection from the pool.
+     * Will reuse an idle connection if available, or create a new one.
+     * If pool is exhausted, request will be queued (with fair ordering).
+     */
+    acquire(): Promise<T>;
+    /**
+     * Release a connection back to the pool.
+     * Connection will be validated and made available for reuse.
+     */
+    release(conn: T): Promise<void>;
+    /**
+     * Destroy a connection without returning it to the pool.
+     * Use when connection is known to be bad.
+     */
+    destroy(conn: T): Promise<void>;
+    /**
+     * Close the pool and all connections.
+     */
+    close(): Promise<void>;
+    /**
+     * Get current pool metrics.
+     */
+    getMetrics(): DOPoolMetrics;
+    /**
+     * Get statistics for individual connections.
+     */
+    getConnectionStats(): ConnectionStats[];
+    /**
+     * Get current pool size.
+     */
+    get size(): number;
+    /**
+     * Get number of available (idle) connections.
+     */
+    get availableCount(): number;
+    /**
+     * Get number of pending requests in queue.
+     */
+    get queueLength(): number;
+    /**
+     * Check if pool is closed.
+     */
+    get isClosed(): boolean;
+    private createConnection;
+    private getIdleConnection;
+    private validateConnection;
+    private markIdle;
+    private markInUse;
+    private clearIdleTimer;
+    private handleIdleTimeout;
+    private removeConnection;
+    private enqueueRequest;
+    private runHealthCheck;
+    private ensureMinSize;
+    private checkScaling;
+    private countInUse;
+    private recordWaitTime;
+    private calculateAvgWaitTime;
+}
+/**
+ * Helper class for creating DO stub connections
+ */
+export declare class DOStubConnection implements PoolableConnection {
+    private readonly stub;
+    private readonly closeHandler?;
+    readonly id: string;
+    private lastActivity;
+    private _healthy;
+    private _closed;
+    constructor(id: string, stub: DurableObjectStub, closeHandler?: (() => Promise<void>) | undefined);
+    /**
+     * Get the underlying DO stub
+     */
+    getStub(): DurableObjectStub;
+    isHealthy(): boolean;
+    close(): Promise<void>;
+    getLastActivity(): number;
+    touch(): void;
+    markUnhealthy(): void;
+}
+/**
+ * Create a pool of DO stub connections
+ */
+export declare function createDOPool(namespace: DurableObjectNamespace, options?: {
+    idGenerator?: () => DurableObjectId;
+    maxSize?: number;
+    minSize?: number;
+    idleTimeoutMs?: number;
+}): DOConnectionPool<DOStubConnection>;
+//# sourceMappingURL=do-connection-pool.d.ts.map

package/dist/routing/do-connection-pool.d.ts.map

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