import type { MemoryResult } from "./types.js";
export type ProvenanceReportLevel = "off" | "metadata" | "full";
export declare const PROVENANCE_REPORT_LEVELS: readonly ProvenanceReportLevel[];
/** Gateway-scoped stream this plugin emits on (contract §2). */
export declare const PROVENANCE_STREAM = "hindsight-openclaw.provenance";
/** Mirrors the consumer's per-item excerpt bound (contract §3). */
export declare const PROVENANCE_EXCERPT_MAX_CHARS = 2000;
/** Mirrors the consumer's per-report item cap (contract §3). */
export declare const PROVENANCE_MAX_ITEMS = 24;
export interface ProvenanceItemV1 {
    id?: string;
    type?: string;
    date?: string;
    score?: number;
    text?: string;
}
export interface ProvenanceReportV1 {
    v: 1;
    source: "hindsight";
    kind: "memory";
    injected?: {
        chars?: number;
        position?: string;
    };
    retrieval?: {
        route?: string;
        bank?: string;
    };
    items: ProvenanceItemV1[];
}
/** Structural emitAgentEvent surface (installed SDK types may predate it). */
export type EmitAgentEventFn = (event: {
    runId: string;
    sessionKey?: string;
    stream: string;
    data: unknown;
}) => unknown;
/** Minimal logger surface (matches the plugin's scoped logger). */
export interface ProvenanceLogger {
    warn: (message: string) => void;
}
/** Normalize the operator's config value; anything off-list means "off". */
export declare function resolveProvenanceLevel(raw: unknown): ProvenanceReportLevel;
/**
 * Feature-detect emitAgentEvent on the FIRST registration's plugin api.
 *
 * GATEWAY QUIRK (bench-verified 2026-06-12): the agent runtime RE-REGISTERS
 * plugins per run, and emitting through a re-registration's api is rejected
 * `"plugin is not loaded"` — callers MUST pass the first registration's api
 * (module-level singleton in index.ts).
 */
export declare function resolveEmitAgentEvent(api: unknown): EmitAgentEventFn | undefined;
/** Map the recallInjectionPosition config onto the contract vocabulary. */
export declare function injectionPositionLabel(position: "prepend" | "append" | "user" | undefined): string;
/**
 * Report for the injected recall set. `results` is the FINAL list (post
 * threshold filter, post topK — exactly the facts the LLM sees). `scoreById`
 * carries the cross_encoder scores from the recall trace when the server
 * provided them (null otherwise). Returns null when level is "off" or there
 * is nothing citable.
 */
export declare function buildMemoryProvenance(results: MemoryResult[], scoreById: Map<string, number> | null, bank: string, position: string, injectedChars: number, level: ProvenanceReportLevel): ProvenanceReportV1 | null;
/**
 * Stable categories logged when emission fails. Operators triage by code; the
 * underlying gateway `reason` / Error message is intentionally NEVER passed to
 * the logger because in `full` mode it may echo back the payload (excerpts of
 * the injected facts) it was rejecting — and the tracing invariant of this
 * module is that report content never reaches logs. Mirrors the
 * openclaw-knowledge plugin's classifier so both plugins behave identically.
 */
export type ProvenanceEmitFailureCode = "plugin_not_loaded" | "missing_run_context" | "invalid_stream" | "validation_error" | "rate_limited" | "rejected" | "throw";
/**
 * Map a gateway-supplied `reason` to a stable category code. Substring-based on
 * the lower-cased reason — coarse on purpose so a future gateway wording change
 * does not break the classifier silently. Unknown reasons collapse to
 * `"rejected"` so the field always has a non-empty, content-free value.
 */
export declare function classifyRejectionReason(reason: string | undefined): ProvenanceEmitFailureCode;
/**
 * Emit a turn's report. Every guard degrades to SILENCE (missing SDK
 * function, missing runId, gateway rejection) — provenance must never break
 * or delay a turn. Failures are logged as a STABLE CATEGORY CODE (never the
 * raw gateway reason or Error message): a silent `{emitted:false}` is
 * undiagnosable in the field, but echoing the raw reason could leak fragments
 * of the injected payload back into the log stream (the tracing invariant).
 */
export declare function emitProvenanceReport(emit: EmitAgentEventFn | undefined, logger: ProvenanceLogger, runId: string | undefined, sessionKey: string | undefined, report: ProvenanceReportV1 | null): void;