@poolzin/pool-bot 2026.1.26 → 2026.1.30

package/dist/gateway/hooks/progressive-disclosure-timeline.js

@@ -0,0 +1,231 @@
+/**
+ * Progressive Disclosure - Timeline Layer (Phase 3)
+ *
+ * Load contextual timeline information for search results
+ * Safe: Read-only, lazy loading, batched I/O
+ *
+ * Purpose:
+ * - After user sees index results, load timeline context
+ * - Provides: Date summaries, result counts, temporal context
+ * - Called only when user drills down (not automatic)
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+// ============================================================================
+// Constants
+// ============================================================================
+const MEMORY_DIR = "/root/pool";
+const MAX_SUMMARY_LENGTH = 300;
+// ============================================================================
+// Timeline Layer Implementation
+// ============================================================================
+/**
+ * Load timeline context for given result IDs
+ * Safe: Read-only, handles errors gracefully
+ *
+ * @param ids - Result IDs (format: "memory/YYYY-MM-DD.md#L123")
+ * @returns Map of date strings to TimelineEntry
+ */
+export async function loadTimelineContext(ids) {
+    // Validate inputs
+    if (!ids || ids.length === 0) {
+        return {};
+    }
+    try {
+        // Extract unique dates from IDs
+        const dates = extractUniqueDates(ids);
+        // Load timeline for each date
+        const timeline = {};
+        for (const date of dates) {
+            const entry = await loadTimelineForDate(date);
+            if (entry) {
+                timeline[date] = entry;
+            }
+        }
+        return timeline;
+    }
+    catch (err) {
+        console.error("[pd-timeline] Failed to load timeline:", err);
+        return {};
+    }
+}
+/**
+ * Extract unique dates from result IDs
+ * Safe: Handles invalid ID formats gracefully
+ */
+function extractUniqueDates(ids) {
+    const dates = new Set();
+    for (const id of ids) {
+        try {
+            // Extract date from ID: "memory/2026-02-04.md#L123" -> "2026-02-04"
+            const match = id.match(/(\d{4}-\d{2}-\d{2})\.md/);
+            if (match) {
+                dates.add(match[1]);
+            }
+        }
+        catch (err) {
+            // Skip invalid IDs
+            if (PROGRESSIVE_DISCLOSURE_FLAGS.DEBUG_MODE) {
+                console.warn(`[pd-timeline] Invalid ID format: ${id}`);
+            }
+        }
+    }
+    return Array.from(dates).sort(); // Sort chronologically
+}
+/**
+ * Load timeline entry for a specific date
+ * Safe: Returns null if file doesn't exist or can't be read
+ */
+async function loadTimelineForDate(date) {
+    try {
+        // Try daily memory file first
+        const dailyPath = join(MEMORY_DIR, "memory", `${date}.md`);
+        const content = await readFile(dailyPath, "utf-8");
+        return parseTimelineEntry(date, content);
+    }
+    catch (err) {
+        // Daily file doesn't exist, try MEMORY.md
+        if (err.code === "ENOENT") {
+            try {
+                const memoryPath = join(MEMORY_DIR, "MEMORY.md");
+                const content = await readFile(memoryPath, "utf-8");
+                // For MEMORY.md, use today's date
+                return parseTimelineEntry(date, content);
+            }
+            catch (memoryErr) {
+                // MEMORY.md also doesn't exist or can't be read
+                return null;
+            }
+        }
+        // Other error (permission, etc)
+        return null;
+    }
+}
+/**
+ * Parse timeline entry from content
+ * Safe: Handles malformed content gracefully
+ */
+function parseTimelineEntry(date, content) {
+    // Extract title (first heading)
+    const title = extractTitle(content) || `Memory: ${date}`;
+    // Extract summary (first paragraph or heading)
+    const summary = extractSummary(content);
+    // Count results (rough estimate: count headings)
+    const resultCount = countHeadings(content);
+    return {
+        date,
+        title,
+        summary,
+        resultCount,
+    };
+}
+/**
+ * Extract title from content (first # heading)
+ */
+function extractTitle(content) {
+    const match = content.match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : undefined;
+}
+/**
+ * Extract summary from content
+ * Safe: Returns first meaningful text
+ */
+function extractSummary(content) {
+    // Try to find first paragraph
+    const lines = content.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip empty lines, headings, code blocks
+        if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("```")) {
+            continue;
+        }
+        // Found first paragraph
+        if (trimmed.length > MAX_SUMMARY_LENGTH) {
+            return trimmed.slice(0, MAX_SUMMARY_LENGTH) + "...";
+        }
+        return trimmed;
+    }
+    // No summary found, return generic
+    return "No summary available";
+}
+/**
+ * Count headings in content (rough result count estimate)
+ */
+function countHeadings(content) {
+    const matches = content.match(/^#{2,}\s+.+$/gm);
+    return matches ? matches.length : 0;
+}
+// ============================================================================
+// Batch Loading (Performance Optimization)
+// ============================================================================
+/**
+ * Load timeline for multiple date ranges in parallel
+ * Safe: Limits concurrency, handles errors
+ *
+ * @param dateRanges - Array of date ranges to load
+ * @returns Map of dates to TimelineEntry
+ */
+export async function loadTimelineBatch(dateRanges) {
+    const timeline = {};
+    // Process ranges in parallel (with limit)
+    const promises = dateRanges.map((range) => loadDateRange(range));
+    const results = await Promise.allSettled(promises);
+    // Merge results
+    for (const result of results) {
+        if (result.status === "fulfilled") {
+            Object.assign(timeline, result.value);
+        }
+    }
+    return timeline;
+}
+/**
+ * Load timeline for a date range
+ */
+async function loadDateRange(range) {
+    const timeline = {};
+    const startDate = new Date(range.start);
+    const endDate = new Date(range.end);
+    const currentDate = new Date(startDate);
+    while (currentDate <= endDate) {
+        const dateStr = currentDate.toISOString().split("T")[0];
+        const entry = await loadTimelineForDate(dateStr);
+        if (entry) {
+            timeline[dateStr] = entry;
+        }
+        // Next day
+        currentDate.setDate(currentDate.getDate() + 1);
+    }
+    return timeline;
+}
+// ============================================================================
+// Utilities (for testing)
+// ============================================================================
+/**
+ * Parse date from result ID
+ * Safe: Returns null if invalid format
+ */
+export function parseDateFromId(id) {
+    const match = id.match(/(\d{4}-\d{2}-\d{2})\.md/);
+    return match ? match[1] : null;
+}
+/**
+ * Format date for display
+ * Safe: Returns original if invalid format
+ */
+export function formatTimelineDate(date) {
+    try {
+        const d = new Date(date);
+        return d.toLocaleDateString("en-US", {
+            year: "numeric",
+            month: "short",
+            day: "numeric",
+        });
+    }
+    catch {
+        return date;
+    }
+}
+// ============================================================================
+// Feature Flags (imported from types)
+// ============================================================================
+import { PROGRESSIVE_DISCLOSURE_FLAGS } from "./progressive-disclosure-types.js";

package/dist/gateway/hooks/progressive-disclosure-types.js

@@ -0,0 +1,65 @@
+/**
+ * Progressive Disclosure - Type Definitions
+ *
+ * Phase 1: Type definitions for memory search v2
+ * Safe: All new types, backward compatible, no breaking changes
+ *
+ * Concept:
+ * - Layer 1 (index): IDs + snippets (~90% token savings)
+ * - Layer 2 (timeline): Contextual information by date
+ * - Layer 3 (details): Full content on-demand
+ */
+// ============================================================================
+// Feature Flags
+// ============================================================================
+/**
+ * Progressive disclosure feature flags
+ */
+export const PROGRESSIVE_DISCLOSURE_FLAGS = {
+    /**
+     * Master switch for progressive disclosure
+     * Default: false (opt-in for safety)
+     */
+    ENABLED: false,
+    /**
+     * Enable index caching (performance optimization)
+     * Default: true (safe to enable)
+     */
+    CACHE_ENABLED: true,
+    /**
+     * Maximum cache size (number of entries)
+     * Default: 100
+     */
+    CACHE_MAX_SIZE: 100,
+    /**
+     * Cache TTL in milliseconds (5 minutes)
+     * Default: 300000
+     */
+    CACHE_TTL_MS: 300000,
+    /**
+     * Enable debug logging
+     * Default: false
+     */
+    DEBUG_MODE: false,
+};
+// ============================================================================
+// Type Guards (safe runtime checking)
+// ============================================================================
+/**
+ * Check if search result is success
+ */
+export function isSearchSuccess(result) {
+    return result.success === true;
+}
+/**
+ * Check if search result is error
+ */
+export function isSearchError(result) {
+    return result.success === false;
+}
+/**
+ * Check if layer is valid
+ */
+export function isValidLayer(layer) {
+    return layer === "index" || layer === "timeline" || layer === "details";
+}

package/dist/gateway/hooks/progressive-disclosure.js

@@ -0,0 +1,242 @@
+/**
+ * Progressive Disclosure - Integration Layer (Phase 5)
+ *
+ * Main entry point: memory_search_v2
+ * Safe: Feature-flagged, backward compatible, never throws
+ *
+ * This is the ONLY file that exports the public API.
+ * All other files are internal implementation details.
+ */
+import { PROGRESSIVE_DISCLOSURE_FLAGS } from "./progressive-disclosure-types.js";
+import { searchIndexOnly, clearIndexCache } from "./progressive-disclosure-index.js";
+import { loadTimelineContext } from "./progressive-disclosure-timeline.js";
+import { loadFullDetails, resetRateLimiter } from "./progressive-disclosure-details.js";
+// ============================================================================
+// Feature Flag (MASTER SWITCH)
+// ============================================================================
+/**
+ * Main feature flag for progressive disclosure
+ * Default: OFF (opt-in for safety)
+ *
+ * To enable: Set PROGRESSIVE_DISCLOSURE_FLAGS.ENABLED = true
+ * To disable: Set PROGRESSIVE_DISCLOSURE_FLAGS.ENABLED = false
+ *
+ * When disabled: memory_search_v2 throws error "Progressive disclosure not enabled"
+ * When enabled: memory_search_v2 works normally
+ */
+export const PROGRESSIVE_DISCLOSURE_ENABLED = PROGRESSIVE_DISCLOSURE_FLAGS.ENABLED;
+// ============================================================================
+// Main API: memory_search_v2
+// ============================================================================
+/**
+ * Progressive disclosure memory search v2
+ *
+ * 3-layer search for token efficiency:
+ * - Layer 1 (index): IDs + snippets (~90% token savings)
+ * - Layer 2 (timeline): Contextual information by date
+ * - Layer 3 (details): Full content on-demand
+ *
+ * Safe:
+ * - Feature-flagged (throws when disabled)
+ * - Never throws (returns error object on failure)
+ * - Backward compatible (memory_search v1 still works)
+ *
+ * @param query - Search query string
+ * @param options - Search options (layer, maxResults, filters)
+ * @returns Search result or error object (never throws)
+ *
+ * @example
+ * ```ts
+ * // Index only (default, fastest)
+ * const result = await memory_search_v2('decision');
+ * // → { index: [...], timeline: {}, details: {} }
+ *
+ * // Index + timeline
+ * const result = await memory_search_v2('decision', { layer: 'timeline' });
+ * // → { index: [...], timeline: {...}, details: {} }
+ *
+ * // Full details (slowest, most tokens)
+ * const result = await memory_search_v2('decision', { layer: 'details' });
+ * // → { index: [...], timeline: {...}, details: {...} }
+ * ```
+ */
+export async function memory_search_v2(query, options = {}) {
+    // Feature flag check (safe exit)
+    if (!PROGRESSIVE_DISCLOSURE_FLAGS.ENABLED) {
+        return {
+            success: false,
+            error: {
+                code: "FEATURE_DISABLED",
+                message: "Progressive disclosure is not enabled. Set PROGRESSIVE_DISCLOSURE_FLAGS.ENABLED = true to use memory_search_v2.",
+                query,
+                recoverable: false,
+            },
+        };
+    }
+    const startTime = Date.now();
+    try {
+        // Validate inputs
+        const safeQuery = query?.trim() || "";
+        if (!safeQuery) {
+            return {
+                success: false,
+                error: {
+                    code: "INVALID_QUERY",
+                    message: "Query cannot be empty",
+                    query,
+                    recoverable: false,
+                },
+            };
+        }
+        const layer = options.layer || "index";
+        const maxResults = options.maxResults || 10;
+        // Execute search (layer by layer)
+        const result = await executeSearch(safeQuery, layer, maxResults, options);
+        return {
+            success: true,
+            data: result,
+        };
+    }
+    catch (err) {
+        // Never throw: return error object
+        return {
+            success: false,
+            error: {
+                code: "SEARCH_FAILED",
+                message: err instanceof Error ? err.message : "Unknown error",
+                query,
+                layer: options.layer,
+                recoverable: true,
+            },
+        };
+    }
+    finally {
+        if (PROGRESSIVE_DISCLOSURE_FLAGS.DEBUG_MODE) {
+            const duration = Date.now() - startTime;
+            console.log(`[pd-v2] Search completed in ${duration}ms`);
+        }
+    }
+}
+/**
+ * Execute search layer by layer
+ * Safe: Handles all errors, returns complete result
+ */
+async function executeSearch(query, layer, maxResults, options) {
+    const startTime = Date.now();
+    // Layer 1: Index (always executed)
+    const index = await searchIndexOnly(query, {
+        maxResults,
+        threshold: options.threshold,
+        tags: options.tags,
+        dateRange: options.dateRange,
+    });
+    // Layer 2: Timeline (optional)
+    let timeline = {};
+    if (layer === "timeline" || layer === "details") {
+        const ids = index.map((r) => r.id);
+        timeline = await loadTimelineContext(ids);
+    }
+    // Layer 3: Details (optional)
+    let details = {};
+    if (layer === "details") {
+        const ids = index.map((r) => r.id);
+        details = await loadFullDetails(ids);
+    }
+    const executionTimeMs = Date.now() - startTime;
+    // Estimate token usage (rough approximation)
+    const tokensEstimated = {
+        index: index.length * 50, // ~50 tokens per index result
+        timeline: Object.keys(timeline).length * 100, // ~100 tokens per timeline entry
+        details: Object.values(details).reduce((sum, d) => sum + (d?.content?.length || 0) / 4, 0), // ~4 chars per token
+        total: 0, // Calculated below
+    };
+    tokensEstimated.total =
+        tokensEstimated.index + tokensEstimated.timeline + tokensEstimated.details;
+    return {
+        query,
+        layer,
+        index,
+        timeline: timeline,
+        details: details,
+        metadata: {
+            totalResults: index.length,
+            executionTimeMs,
+            layerExecuted: layer,
+            tokensEstimated: tokensEstimated,
+            timestamp: Date.now(),
+        },
+    };
+}
+// ============================================================================
+// Convenience Functions (for ease of use)
+// ============================================================================
+/**
+ * Search index only (fastest, least tokens)
+ * Convenience wrapper for memory_search_v2(query, { layer: 'index' })
+ */
+export async function searchIndex(query, maxResults) {
+    return memory_search_v2(query, { layer: "index", maxResults });
+}
+/**
+ * Search with timeline (medium speed, medium tokens)
+ * Convenience wrapper for memory_search_v2(query, { layer: 'timeline' })
+ */
+export async function searchTimeline(query, maxResults) {
+    return memory_search_v2(query, { layer: "timeline", maxResults });
+}
+/**
+ * Search with full details (slowest, most tokens)
+ * Convenience wrapper for memory_search_v2(query, { layer: 'details' })
+ */
+export async function searchDetails(query, maxResults) {
+    return memory_search_v2(query, { layer: "details", maxResults });
+}
+// ============================================================================
+// Cache Management (for testing and optimization)
+// ============================================================================
+/**
+ * Clear all progressive disclosure caches
+ * Safe: No-op when feature flag is disabled
+ */
+export function clearProgressiveDisclosureCache() {
+    if (!PROGRESSIVE_DISCLOSURE_FLAGS.ENABLED) {
+        return;
+    }
+    clearIndexCache();
+}
+/**
+ * Reset progressive disclosure state (for testing)
+ * Safe: No-op when feature flag is disabled
+ */
+export function resetProgressiveDisclosure() {
+    if (!PROGRESSIVE_DISCLOSURE_FLAGS.ENABLED) {
+        return;
+    }
+    clearIndexCache();
+    resetRateLimiter();
+}
+// ============================================================================
+// Statistics (for monitoring and debugging)
+// ============================================================================
+/**
+ * Get progressive disclosure statistics
+ * Safe: Returns empty stats when feature flag is disabled
+ */
+export function getProgressiveDisclosureStats() {
+    if (!PROGRESSIVE_DISCLOSURE_FLAGS.ENABLED) {
+        return {
+            enabled: false,
+            cache: { size: 0 },
+            rateLimiter: { lastLoadTime: 0 },
+        };
+    }
+    // Import dynamically to avoid circular dependencies
+    const { getIndexCacheStats } = require("./progressive-disclosure-index.js");
+    const { getRateLimiterStats } = require("./progressive-disclosure-details.js");
+    return {
+        enabled: true,
+        featureFlags: PROGRESSIVE_DISCLOSURE_FLAGS,
+        cache: getIndexCacheStats(),
+        rateLimiter: getRateLimiterStats(),
+    };
+}