import { z } from 'zod';
import type { CodebaseIndex } from '../types.js';
import type { OccEntityFreshness, OccEntityRef } from './api-types.js';
import type { EntityIndex } from './store.js';
import type { LiveEntityIndex } from './resolve.js';
import type { EntityDiagnostic } from './types.js';
import type { EntityEvidenceGapSummary } from './evidence.js';
export declare const EntityHotspotOptionsSchema: z.ZodObject<{
    limit: z.ZodOptional<z.ZodNumber>;
    relativePath: z.ZodOptional<z.ZodString>;
    since: z.ZodOptional<z.ZodString>;
    pageRank: z.ZodOptional<z.ZodBoolean>;
}, z.core.$strip>;
export type EntityHotspotOptions = z.infer<typeof EntityHotspotOptionsSchema>;
/** Programmatic-only controls kept off the CLI/MCP schemas. */
export interface EntityHotspotRuntimeOptions extends EntityHotspotOptions {
    /** Deterministic clock injection for callers that need reproducible ageDays. */
    now?: Date;
}
export interface EntityHotspotWeight {
    value: number;
    basis: 'token-count' | 'line-span';
}
export interface EntityHotspotRow {
    entity: OccEntityRef;
    logicChangeCount: number;
    cosmeticChangeCount: number;
    neutralChangeCount: number;
    unknownChangeCount: number;
    lastLogicChange: string;
    ageDays: number;
    weight: EntityHotspotWeight;
    /** Normalized 0–100 graph score, present only when pageRank was requested. */
    pageRank?: number;
    /** logicChangeCount × weight × (1 + pageRank / 100 when enabled). */
    score: number;
    /** True when the oldest event is a bounded-window seed rather than a proven birth. */
    birthAtWindowBoundary: boolean;
}
export interface EntityHotspotHonesty {
    freshness: {
        fresh: boolean;
        reasons: OccEntityFreshness['reasons'];
        workingTreeMeasured: boolean;
    };
    truncation: {
        truncated: boolean;
        reasons: EntityDiagnostic[];
        omitted: number;
    };
    coverage: {
        commitsIndexed: number;
        commitsConsidered: number;
        eventsConsidered: number;
        entitiesConsidered: number;
        entitiesRanked: number;
        boundaryBirths: number;
        unknownChangeEvents: number;
        since?: string;
    };
    ambiguityCount: number;
    evidenceGaps: EntityEvidenceGapSummary;
}
export type EntityHotspotResult = {
    status: 'resolved';
    rows: EntityHotspotRow[];
    scoring: 'logic-change-count × size-weight' | 'logic-change-count × size-weight × pagerank-factor';
    honesty: EntityHotspotHonesty;
} | {
    status: 'error';
    code: 'invalid-options' | 'invalid-since';
    message: string;
};
export interface EntityHotspotContext {
    index: CodebaseIndex;
    entityIndex: EntityIndex;
    live: LiveEntityIndex;
    freshness: OccEntityFreshness;
}
/**
 * Rank current entities from persisted lineage events.
 *
 * The aggregation never reparses history and never upgrades an unknown change
 * to a logic change. A bounded-window seed is also excluded from the logic
 * count: it proves only that an entity existed at the boundary, not that it was
 * created there.
 */
export declare function rankEntityHotspots(options: EntityHotspotRuntimeOptions, context: EntityHotspotContext): EntityHotspotResult;
