import lunr from "lunr";
import { type Static, Type } from "typebox";
/**
 * One skill in the retrieval corpus. `frontmatter` is the parsed YAML head
 * of the SKILL.md file (matches `loaders/persona-skill-loader.ts` Skill shape
 * for `frontmatter` field). Only `description` plus selected frontmatter
 * fields are indexed — the body is intentionally excluded to keep the index
 * small and keyword-focused.
 */
export declare const RetrievableSkillSchema: Type.TObject<{
    skillId: Type.TString;
    name: Type.TString;
    description: Type.TString;
    frontmatter: Type.TRecord<"^.*$", Type.TUnknown>;
}>;
export type RetrievableSkill = Static<typeof RetrievableSkillSchema>;
export declare const RetrievalHitSchema: Type.TObject<{
    skillId: Type.TString;
    score: Type.TNumber;
}>;
export type RetrievalHit = Static<typeof RetrievalHitSchema>;
/**
 * Runtime attribution supplied by the caller (orchestrator).
 * These are NEVER fabricated inside the retriever (IL10).
 */
export declare const EmitRuntimeSchema: Type.TObject<{
    storeCli: Type.TString;
    cwd: Type.TString;
    sprintId: Type.TString;
    taskId: Type.TString;
    role: Type.TString;
    action: Type.TString;
    phase: Type.TOptional<Type.TString>;
    iteration: Type.TOptional<Type.TInteger>;
    startTimestamp: Type.TString;
    endTimestamp: Type.TString;
    durationMinutes: Type.TNumber;
    model: Type.TString;
    provider: Type.TString;
}>;
export type EmitRuntime = Static<typeof EmitRuntimeSchema>;
export interface EmitResult {
    emitted: number;
    failed: number;
    stderrs: string[];
}
/**
 * Opaque handle returned by `buildSkillIndex`. Internally pairs the lunr
 * index with the corpus so `retrieveTopK` can return the original skillIds.
 */
export interface SkillIndex {
    readonly _index: lunr.Index;
    readonly _byRef: Map<string, RetrievableSkill>;
}
/**
 * Build a BM25 index over the supplied corpus. Indexed fields:
 *   - `name`        (boost 4) — the skill identifier itself
 *   - `description` (boost 2) — primary intent text
 *   - `frontmatter` (boost 1) — tags / aliases
 *
 * lunr's default scoring is Okapi BM25.
 */
export declare function buildSkillIndex(corpus: readonly RetrievableSkill[]): SkillIndex;
/**
 * Return the top-k skills by BM25 score for the given query. Deterministic
 * for fixed (corpus, query) pairs. Returns `[]` when no token in the query
 * is present in any indexed field.
 */
export declare function retrieveTopK(index: SkillIndex, query: string, k: number): RetrievalHit[];
/**
 * Clamp a raw BM25 score into the [0,1] window required by the event
 * schema (`retrieval_score`). BM25 scores are unbounded above; we apply
 * `s / (1 + s)` so the relative ordering is preserved while the absolute
 * value is monotonically squashed into (0,1). Negative scores (lunr never
 * produces these in practice) clamp to 0.
 */
export declare function clampRetrievalScore(rawScore: number): number;
/**
 * Emit one `skill_usage` event per supplied hit via
 * `node <storeCli> emit <sprintId> <json>`. Returns the (emitted, failed)
 * counts. Never throws on subprocess failure — the failure is surfaced via
 * the returned counter and stderr text (IL7 — explicit, not silent).
 */
export declare function emitSkillUsageEvents(hits: readonly RetrievalHit[], runtime: EmitRuntime): EmitResult;