@jagilber-org/index-server 1.19.1

package/dist/services/handlers.trace.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../server/registry");
+const tracing_1 = require("./tracing");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+// trace_dump: writes current in-memory ring buffer (if enabled) to a file and returns summary.
+// Params: { file?: string }
+(0, registry_1.registerHandler)('trace_dump', (p) => {
+    const tracingCfg = (0, runtimeConfig_1.getRuntimeConfig)().tracing;
+    const fallback = path_1.default.join(process.cwd(), 'snapshots', 'trace-buffer.json');
+    const file = p?.file || tracingCfg.buffer.file || fallback;
+    (0, tracing_1.dumpTraceBufferNow)(file);
+    let size = 0;
+    let bytes = 0;
+    try {
+        if (fs_1.default.existsSync(file)) {
+            const stat = fs_1.default.statSync(file);
+            bytes = stat.size;
+            const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+            if (raw && Array.isArray(raw.records))
+                size = raw.records.length;
+        }
+    }
+    catch { /* ignore */ }
+    return { dumped: true, file, records: size, bytes, env: (0, tracing_1.summarizeTraceEnv)(), bufferEnabled: (0, tracing_1.getTraceBuffer)().length > 0 };
+});

package/dist/services/handlers.usage.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/handlers.usage.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../server/registry");
+const indexContext_1 = require("./indexContext");
+(0, registry_1.registerHandler)('usage_track', (p) => { if (!p.id)
+    return { error: 'missing id' }; const opts = { action: p.action, signal: p.signal, comment: p.comment }; const r = (0, indexContext_1.incrementUsage)(p.id, opts); if (!r)
+    return { notFound: true }; return r; });
+(0, registry_1.registerHandler)('usage_hotset', (p) => { const st = (0, indexContext_1.ensureLoaded)(); const snap = (0, indexContext_1.loadUsageSnapshot)(); const limit = Math.max(1, Math.min(p.limit ?? 10, 100)); const items = [...st.list].filter(e => (e.usageCount ?? 0) > 0).sort((a, b) => { const ua = a.usageCount ?? 0, ub = b.usageCount ?? 0; if (ub !== ua)
+    return ub - ua; return (b.lastUsedAt || '').localeCompare(a.lastUsedAt || ''); }).slice(0, limit).map(e => { const rec = snap[e.id] || {}; const item = { id: e.id, usageCount: e.usageCount, lastUsedAt: e.lastUsedAt }; if (rec.lastSignal)
+    item.lastSignal = rec.lastSignal; if (rec.lastComment)
+    item.lastComment = rec.lastComment; return item; }); return { hash: st.hash, count: items.length, items, limit }; });

package/dist/services/hotScore.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Phase 3: Hotness/Ranking System - Core Hot Score Algorithm
+ *
+ * Implements instruction ranking based on temporal usage patterns,
+ * recency weighting, and usage frequency with configurable decay parameters.
+ *
+ * Hot Score Formula:
+ * hotScore = (recentUsage * recencyWeight) + (historicalUsage * historyWeight) + bonuses
+ *
+ * @module HotScore
+ * @version 1.0.0
+ * @since Phase 3 Implementation
+ */
+/**
+ * Configuration parameters for hot score calculation
+ */
+export interface HotScoreConfig {
+    /** Weight for recent usage (last 24 hours). Default: 0.7 */
+    recencyWeight: number;
+    /** Weight for historical usage (beyond 24 hours). Default: 0.3 */
+    historyWeight: number;
+    /** Decay factor per hour for temporal weighting. Default: 0.95 */
+    temporalDecay: number;
+    /** Minimum score threshold for ranking inclusion. Default: 0.01 */
+    minScoreThreshold: number;
+    /** Maximum lookback hours for historical analysis. Default: 168 (7 days) */
+    maxLookbackHours: number;
+    /** Bonus points for first-time usage. Default: 0.1 */
+    firstUseBonus: number;
+    /** Bonus points for diverse usage patterns. Default: 0.05 */
+    diversityBonus: number;
+}
+/**
+ * Usage data point for hot score calculation
+ */
+export interface UsagePoint {
+    /** Timestamp of usage event (Unix epoch ms) */
+    timestamp: number;
+    /** Usage count at this point */
+    count: number;
+    /** Optional context metadata */
+    context?: Record<string, string | number | boolean>;
+}
+/**
+ * Computed hot score result with breakdown
+ */
+export interface HotScoreResult {
+    /** Final computed hot score */
+    score: number;
+    /** Breakdown of score components */
+    breakdown: {
+        recentUsage: number;
+        historicalUsage: number;
+        recencyContribution: number;
+        historyContribution: number;
+        bonuses: number;
+    };
+    /** Ranking metadata */
+    metadata: {
+        totalUsageEvents: number;
+        uniqueHours: number;
+        firstUsage?: number;
+        lastUsage?: number;
+        usageTrend: 'increasing' | 'decreasing' | 'stable';
+    };
+}
+/**
+ * Default hot score configuration optimized for enterprise usage patterns
+ */
+export declare const DEFAULT_HOT_SCORE_CONFIG: HotScoreConfig;
+/**
+ * Hot score calculation service
+ *
+ * Provides sophisticated instruction ranking based on temporal usage patterns
+ * with configurable weighting, decay factors, and bonus systems.
+ */
+export declare class HotScoreService {
+    private config;
+    /**
+     * Initialize hot score service with configuration
+     *
+     * @param config - Hot score calculation parameters
+     */
+    constructor(config?: HotScoreConfig);
+    /**
+     * Calculate hot score for instruction based on usage history
+     *
+     * @param instructionId - Unique identifier for instruction
+     * @param usageHistory - Temporal usage data points
+     * @param currentTime - Current timestamp for recency calculation (defaults to now)
+     * @returns Hot score result with detailed breakdown
+     */
+    calculateHotScore(instructionId: string, usageHistory: UsagePoint[], _currentTime?: number): HotScoreResult;
+    /**
+     * Calculate usage score for a specific time window with temporal decay
+     */
+    private calculateTimeWindowUsage;
+    /**
+     * Calculate bonus points for special usage patterns
+     */
+    private calculateBonuses;
+    /**
+     * Generate ranking metadata for analysis and debugging
+     */
+    private generateMetadata;
+    /**
+     * Create empty result for instructions with no usage history
+     */
+    private createEmptyResult;
+    /**
+     * Update configuration parameters
+     *
+     * @param newConfig - Updated configuration parameters
+     */
+    updateConfig(newConfig: Partial<HotScoreConfig>): void;
+    /**
+     * Get current configuration
+     *
+     * @returns Current hot score configuration
+     */
+    getConfig(): HotScoreConfig;
+    /**
+     * Batch calculate hot scores for multiple instructions
+     *
+     * @param instructionUsage - Map of instruction ID to usage history
+     * @param currentTime - Current timestamp for calculations
+     * @returns Map of instruction ID to hot score results
+     */
+    calculateBatchHotScores(instructionUsage: Map<string, UsagePoint[]>, _currentTime?: number): Map<string, HotScoreResult>;
+}
+/**
+ * Utility function to create hot score service with default configuration
+ *
+ * @param overrides - Configuration overrides
+ * @returns Configured hot score service instance
+ */
+export declare function createHotScoreService(overrides?: Partial<HotScoreConfig>): HotScoreService;

package/dist/services/hotScore.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * Phase 3: Hotness/Ranking System - Core Hot Score Algorithm
+ *
+ * Implements instruction ranking based on temporal usage patterns,
+ * recency weighting, and usage frequency with configurable decay parameters.
+ *
+ * Hot Score Formula:
+ * hotScore = (recentUsage * recencyWeight) + (historicalUsage * historyWeight) + bonuses
+ *
+ * @module HotScore
+ * @version 1.0.0
+ * @since Phase 3 Implementation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HotScoreService = exports.DEFAULT_HOT_SCORE_CONFIG = void 0;
+exports.createHotScoreService = createHotScoreService;
+const logger_js_1 = require("./logger.js");
+/**
+ * Default hot score configuration optimized for enterprise usage patterns
+ */
+exports.DEFAULT_HOT_SCORE_CONFIG = {
+    recencyWeight: 0.7, // Favor recent activity
+    historyWeight: 0.3, // But consider historical patterns
+    temporalDecay: 0.95, // 5% decay per hour
+    minScoreThreshold: 0.01, // Filter very low scores
+    maxLookbackHours: 168, // 7 days historical window
+    firstUseBonus: 0.1, // Encourage exploration
+    diversityBonus: 0.05 // Reward varied usage
+};
+/**
+ * Hot score calculation service
+ *
+ * Provides sophisticated instruction ranking based on temporal usage patterns
+ * with configurable weighting, decay factors, and bonus systems.
+ */
+class HotScoreService {
+    config;
+    /**
+     * Initialize hot score service with configuration
+     *
+     * @param config - Hot score calculation parameters
+     */
+    constructor(config = exports.DEFAULT_HOT_SCORE_CONFIG) {
+        this.config = { ...config };
+        (0, logger_js_1.logInfo)('[hotScore] HotScoreService initialized', {
+            recencyWeight: this.config.recencyWeight,
+            historyWeight: this.config.historyWeight,
+            temporalDecay: this.config.temporalDecay,
+            maxLookbackHours: this.config.maxLookbackHours
+        });
+    }
+    /**
+     * Calculate hot score for instruction based on usage history
+     *
+     * @param instructionId - Unique identifier for instruction
+     * @param usageHistory - Temporal usage data points
+     * @param currentTime - Current timestamp for recency calculation (defaults to now)
+     * @returns Hot score result with detailed breakdown
+     */
+    calculateHotScore(instructionId, usageHistory, _currentTime = Date.now()) {
+        if (!usageHistory.length) {
+            return this.createEmptyResult();
+        }
+        const currentTime = _currentTime; // internal alias; parameter intentionally prefixed underscore to satisfy lint
+        const sortedHistory = usageHistory
+            .filter(point => point.timestamp <= currentTime)
+            .sort((a, b) => b.timestamp - a.timestamp); // Most recent first
+        const cutoffTime = currentTime - (this.config.maxLookbackHours * 60 * 60 * 1000);
+        const relevantHistory = sortedHistory.filter(point => point.timestamp >= cutoffTime);
+        if (!relevantHistory.length) {
+            return this.createEmptyResult();
+        }
+        // Calculate temporal weights and usage components
+        const recentBoundary = currentTime - (24 * 60 * 60 * 1000); // 24 hours ago
+        const recentUsage = this.calculateTimeWindowUsage(relevantHistory, recentBoundary, currentTime);
+        const historicalUsage = this.calculateTimeWindowUsage(relevantHistory, cutoffTime, recentBoundary);
+        // Apply configuration weights
+        const recencyContribution = recentUsage * this.config.recencyWeight;
+        const historyContribution = historicalUsage * this.config.historyWeight;
+        // Calculate bonuses
+        const bonuses = this.calculateBonuses(instructionId, relevantHistory, currentTime);
+        // Compute final score
+        const score = recencyContribution + historyContribution + bonuses;
+        // Generate metadata
+        const metadata = this.generateMetadata(relevantHistory, currentTime);
+        const result = {
+            score: Math.max(0, score),
+            breakdown: {
+                recentUsage,
+                historicalUsage,
+                recencyContribution,
+                historyContribution,
+                bonuses
+            },
+            metadata
+        };
+        (0, logger_js_1.logDebug)('[hotScore] Hot score calculated', {
+            instructionId,
+            score: result.score,
+            usagePoints: relevantHistory.length,
+            ...result.breakdown
+        });
+        return result;
+    }
+    /**
+     * Calculate usage score for a specific time window with temporal decay
+     */
+    calculateTimeWindowUsage(history, windowStart, windowEnd) {
+        const windowHistory = history.filter(point => point.timestamp >= windowStart && point.timestamp < windowEnd);
+        if (!windowHistory.length)
+            return 0;
+        let totalScore = 0;
+        for (const point of windowHistory) {
+            const hoursFromEnd = (windowEnd - point.timestamp) / (60 * 60 * 1000);
+            const decayFactor = Math.pow(this.config.temporalDecay, hoursFromEnd);
+            totalScore += point.count * decayFactor;
+        }
+        return totalScore;
+    }
+    /**
+     * Calculate bonus points for special usage patterns
+     */
+    calculateBonuses(instructionId, history, _currentTime) {
+        let bonuses = 0;
+        // First use bonus (encourages exploration)
+        const totalUsage = history.reduce((sum, point) => sum + point.count, 0);
+        if (totalUsage === 1) {
+            bonuses += this.config.firstUseBonus;
+        }
+        // Diversity bonus (rewards varied usage patterns)
+        const uniqueHours = new Set(history.map(point => Math.floor(point.timestamp / (60 * 60 * 1000)))).size;
+        if (uniqueHours >= 3) {
+            bonuses += this.config.diversityBonus;
+        }
+        return bonuses;
+    }
+    /**
+     * Generate ranking metadata for analysis and debugging
+     */
+    generateMetadata(history, _currentTime) {
+        const timestamps = history.map(p => p.timestamp);
+        const totalUsageEvents = history.reduce((sum, point) => sum + point.count, 0);
+        const uniqueHours = new Set(history.map(point => Math.floor(point.timestamp / (60 * 60 * 1000)))).size;
+        const firstUsage = Math.min(...timestamps);
+        const lastUsage = Math.max(...timestamps);
+        // Simple trend analysis (last quarter vs previous quarter)
+        const quarterDuration = (_currentTime - firstUsage) / 4;
+        const lastQuarterStart = _currentTime - quarterDuration;
+        const lastQuarterUsage = history
+            .filter(p => p.timestamp >= lastQuarterStart)
+            .reduce((sum, point) => sum + point.count, 0);
+        const previousQuarterEnd = lastQuarterStart;
+        const previousQuarterStart = previousQuarterEnd - quarterDuration;
+        const previousQuarterUsage = history
+            .filter(p => p.timestamp >= previousQuarterStart && p.timestamp < previousQuarterEnd)
+            .reduce((sum, point) => sum + point.count, 0);
+        let usageTrend = 'stable';
+        if (lastQuarterUsage > previousQuarterUsage * 1.1) {
+            usageTrend = 'increasing';
+        }
+        else if (lastQuarterUsage < previousQuarterUsage * 0.9) {
+            usageTrend = 'decreasing';
+        }
+        return {
+            totalUsageEvents,
+            uniqueHours,
+            firstUsage,
+            lastUsage,
+            usageTrend
+        };
+    }
+    /**
+     * Create empty result for instructions with no usage history
+     */
+    createEmptyResult() {
+        return {
+            score: 0,
+            breakdown: {
+                recentUsage: 0,
+                historicalUsage: 0,
+                recencyContribution: 0,
+                historyContribution: 0,
+                bonuses: 0
+            },
+            metadata: {
+                totalUsageEvents: 0,
+                uniqueHours: 0,
+                usageTrend: 'stable'
+            }
+        };
+    }
+    /**
+     * Update configuration parameters
+     *
+     * @param newConfig - Updated configuration parameters
+     */
+    updateConfig(newConfig) {
+        this.config = { ...this.config, ...newConfig };
+        (0, logger_js_1.logInfo)('[hotScore] Hot score configuration updated', newConfig);
+    }
+    /**
+     * Get current configuration
+     *
+     * @returns Current hot score configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Batch calculate hot scores for multiple instructions
+     *
+     * @param instructionUsage - Map of instruction ID to usage history
+     * @param currentTime - Current timestamp for calculations
+     * @returns Map of instruction ID to hot score results
+     */
+    calculateBatchHotScores(instructionUsage, _currentTime = Date.now()) {
+        const results = new Map();
+        for (const [instructionId, usageHistory] of instructionUsage) {
+            const result = this.calculateHotScore(instructionId, usageHistory, _currentTime);
+            // Apply minimum threshold filter
+            if (result.score >= this.config.minScoreThreshold) {
+                results.set(instructionId, result);
+            }
+        }
+        (0, logger_js_1.logInfo)('[hotScore] Batch hot scores calculated', {
+            totalInstructions: instructionUsage.size,
+            qualifyingInstructions: results.size,
+            minThreshold: this.config.minScoreThreshold
+        });
+        return results;
+    }
+}
+exports.HotScoreService = HotScoreService;
+/**
+ * Utility function to create hot score service with default configuration
+ *
+ * @param overrides - Configuration overrides
+ * @returns Configured hot score service instance
+ */
+function createHotScoreService(overrides) {
+    const config = overrides ? { ...exports.DEFAULT_HOT_SCORE_CONFIG, ...overrides } : exports.DEFAULT_HOT_SCORE_CONFIG;
+    return new HotScoreService(config);
+}

package/dist/services/indexContext.d.ts

@@ -0,0 +1,117 @@
+import { InstructionEntry } from '../models/instruction';
+export interface IndexState {
+    loadedAt: string;
+    hash: string;
+    byId: Map<string, InstructionEntry>;
+    list: InstructionEntry[];
+    fileCount: number;
+    versionMTime: number;
+    versionToken: string;
+    loadErrors?: {
+        file: string;
+        error: string;
+    }[];
+    loadDebug?: {
+        scanned: number;
+        accepted: number;
+        skipped: number;
+        trace?: {
+            file: string;
+            accepted: boolean;
+            reason?: string;
+        }[];
+    };
+    loadSummary?: {
+        scanned: number;
+        accepted: number;
+        skipped: number;
+        reasons: Record<string, number>;
+        cacheHits?: number;
+        hashHits?: number;
+    };
+}
+export interface UsagePersistRecord {
+    usageCount?: number;
+    firstSeenTs?: string;
+    lastUsedAt?: string;
+    lastAction?: string;
+    lastSignal?: string;
+    lastComment?: string;
+}
+export interface UsageTrackOptions {
+    action?: string;
+    signal?: string;
+    comment?: string;
+}
+export declare function clearUsageRateLimit(id?: string): void;
+export declare function loadUsageSnapshot(): Record<string, UsagePersistRecord>;
+export declare function getInstructionsDir(): string;
+export declare function diagnoseInstructionsDir(): {
+    dir: string;
+    exists: boolean;
+    writable: boolean;
+    error: string | null;
+};
+export declare function touchIndexVersion(): void;
+export declare function markindexDirty(): void;
+export declare function ensureLoaded(): IndexState;
+export interface IndexPollerOptions {
+    intervalMs?: number;
+    proactive?: boolean;
+}
+export declare function startIndexVersionPoller(opts?: IndexPollerOptions): void;
+export declare function stopIndexVersionPoller(): void;
+export declare function invalidate(): void;
+export declare function getIndexState(): IndexState;
+export declare function getDebugIndexSnapshot(): {
+    dir: string;
+    fileCountOnDisk: number;
+    fileNames: string[];
+    indexLoaded: boolean;
+    indexCount: number;
+    dirtyFlag: boolean;
+    missingIds: string[];
+    extraLoaded: string[];
+    loadedAt: string | undefined;
+    versionMTime: number | undefined;
+};
+export declare function getIndexDiagnostics(opts?: {
+    includeTrace?: boolean;
+}): {
+    dir: string;
+    loadedAt: string;
+    hash: string;
+    scanned: number;
+    accepted: number;
+    skipped: number;
+    fileCountOnDisk: number;
+    indexCount: number;
+    missingOnIndexCount: number;
+    missingOnIndex: string[];
+    reasons: Record<string, number>;
+    errorSamples: {
+        file: string;
+        error: string;
+    }[];
+    traceSample: {
+        file: string;
+        accepted: boolean;
+        reason?: string;
+    }[] | undefined;
+};
+export declare function projectGovernance(e: InstructionEntry): {
+    id: string;
+    title: string;
+    version: string;
+    owner: string;
+    priorityTier: "P1" | "P2" | "P3" | "P4";
+    nextReviewDue: string;
+    semanticSummarySha256: string;
+    changeLogLength: number;
+};
+export declare function computeGovernanceHash(entries: InstructionEntry[]): string;
+export declare function writeEntry(entry: InstructionEntry): void;
+export declare function removeEntry(id: string): void;
+export declare function scheduleUsagePersist(): void;
+export declare function incrementUsage(id: string, opts?: UsageTrackOptions): Record<string, unknown> | null;
+export declare function __testResetUsageState(): void;