/**
 * Context Governor (Long-Horizon Context Virtualization, 2.5.0; production
 * hardening 2.6.0).
 *
 * First-class preflight enforcement of the safe input budget. Before a provider
 * is invoked, the candidate assembly (system prompt + tools + dynamic prompt +
 * messages) is conservatively counted and reduced until it fits — or a
 * structured unrecoverable condition is returned with region diagnostics.
 *
 * Reduction is deterministic and LLM-free (it runs BEFORE the model call, so it
 * cannot depend on another model call):
 *   1. Re-apply the durable virtualization ledger (already-archived tool
 *      results are restored to their virtualized representation, never the raw
 *      payload).
 *   2. Virtualize oversized/older tool results into the cold evidence archive
 *      (retaining a synopsis + durable evidence reference).
 *   3. Roll the context over: retire the historical transcript and replace the
 *      prefix with a bounded mission-context-checkpoint preamble + recent tail.
 *   4. Trim the recent tail deterministically (bounded iterations, pinned state
 *      never evicted).
 *
 * The governor never invents mission state: the checkpoint is an operational
 * projection, and completion authority stays with the Reliability Kernel.
 */
import { type ContextCapability } from "./context-capability.js";
import { type ContextAssembly, type TokenAccountingMode } from "./context-token.js";
import type { EvidenceArchive } from "./evidence-archive.js";
import { type EvidenceReference, type MissionContextCheckpoint } from "./mission-checkpoint.js";
export type GovernorAction = "pass" | "virtualized" | "rollover" | "compacted" | "unrecoverable";
export interface ContextGovernorDiagnostics {
    action: GovernorAction;
    capability: ContextCapability;
    iterations: number;
    inputTokensBefore: number;
    inputTokensAfter: number;
    pressureRatioBefore: number;
    pressureRatioAfter: number;
    toolResultsArchived: number;
    /** Tool results restored to a virtualized form from the durable ledger. */
    toolResultsRevirtualized: number;
    messagesEvicted: number;
    tokensEvicted: number;
    rolloverOccurred: boolean;
    checkpointRevision?: number;
    evidenceIdsArchived: string[];
    reducedRegions: string[];
    unrecoverableReason?: string;
    /** Fixed prefix (system + tools + dynamic prompt) token cost. */
    fixedPrefixTokens: number;
    /** Current token accounting mode. */
    tokenAccountingMode: TokenAccountingMode;
    recoveryIteration: number;
}
export interface ContextGovernorResult {
    assembly: ContextAssembly;
    diagnostics: ContextGovernorDiagnostics;
}
export interface ContextGovernorOptions {
    capability: ContextCapability;
    archive: EvidenceArchive;
    /** Supplies the current durable mission checkpoint for rollover rehydration. */
    checkpointProvider?: () => MissionContextCheckpoint | undefined;
    /** When present, resolves the capability per call (model may change at runtime). */
    capabilityProvider?: () => ContextCapability;
    maxIterations?: number;
    /** Recent-token tail kept hot across a rollover. */
    keepRecentTokens?: number;
    /** Tool results at/above this cost are candidates for virtualization. */
    toolResultVirtualizeThreshold?: number;
    /** Minimum number of messages always retained (never evicted below this). */
    minRetainedMessages?: number;
    now?: () => number;
    /** Durable virtualization ledger source (e.g., the current session). */
    virtualizationProvider?: () => ToolVirtualizationRecord[];
    /** Durable virtualization ledger sink (persists the full snapshot). */
    virtualizationSink?: (records: ToolVirtualizationRecord[]) => void;
    /** Initial virtualization records to seed the ledger (session resume). */
    initialVirtualizations?: ToolVirtualizationRecord[];
    /** Initial evidence references to seed the archive map (session resume). */
    initialEvidenceRefs?: EvidenceReference[];
}
/** Durable virtualization provenance: which tool result maps to which cold evidence. */
export interface ToolVirtualizationRecord {
    toolCallId: string;
    evidenceId: string;
    contentHash: string;
    source: string;
    synopsis: string;
    contentBytes: number;
    virtualizedAtMs: number;
}
/** Structured context captured when a provider rejects a request for size. */
export interface ProviderOverflowContext {
    configuredContextWindow: number;
    estimatedInputTokens: number;
    reservedOutputTokens: number;
    safetyReserveTokens: number;
    accountingMode: TokenAccountingMode;
    providerError?: string;
    /** Provider-reported input token count when available. */
    observedInputTokens?: number;
    /** Provider-reported maximum context when available. */
    observedContextWindow?: number;
}
/** Opt-in telemetry surface (metadata only; never prompt content). */
export interface ContextGovernorTelemetry {
    tokenAccountingMode: TokenAccountingMode;
    estimatedInputTokens: number;
    providerObservedInputTokens?: number;
    estimationError?: number;
    estimationErrorRatio?: number;
    configuredContextWindow: number;
    baseSafeInputBudget: number;
    effectiveSafeInputBudget: number;
    reservedOutputTokens: number;
    safetyReserveTokens: number;
    overflowCount: number;
    providerOverflowCount: number;
    forcedReductionCount: number;
    rolloverCount: number;
    archivedEvidenceCount: number;
    reusedEvidenceCount: number;
    duplicateArchiveAvoidedCount: number;
    fixedPrefixTokens: number;
    messageTokens: number;
    toolSchemaTokens: number;
    recoveryIteration: number;
    adaptiveSafetyReserveTokens: number;
    calibratedMultiplier: number;
    calibrationSamples: number;
}
export declare class ContextGovernor {
    private readonly _options;
    /** Durable virtualization ledger: toolCallId -> cold evidence record. */
    private readonly _virtualizations;
    /** Cumulative evidence refs (id -> short summary) archived during this governor's lifetime. */
    private readonly _archivedEvidenceRefs;
    /** Optional sink notified when cumulative evidence refs change (durable persistence). */
    private _evidenceRefsSink?;
    /** Total provider overflow disagreements recorded. */
    private _overflowCount;
    /** Provider overflow disagreements specifically (subset of _overflowCount). */
    private _providerOverflowCount;
    /** Number of forced reductions (adaptive safety applied). */
    private _forcedReductionCount;
    /** Number of rollovers performed across this governor's lifetime. */
    private _rolloverCount;
    /** Number of times an existing cold evidence id was reused (no duplicate write). */
    private _reusedEvidenceCount;
    /** Number of duplicate archive writes avoided. */
    private _duplicateArchiveAvoidedCount;
    /** Cumulative adaptive safety reserve tokens (bounded). */
    private _adaptiveSafetyReserveTokens;
    /** Calibrated conservative multiplier from provider usage (>= 1). */
    private _calibratedMultiplier;
    /** Number of provider usage observations used for calibration. */
    private _calibrationSamples;
    /** Last observed provider usage (estimated vs observed). */
    private _lastUsageObservation;
    /** Most recent governance diagnostics (telemetry surface). */
    private _lastDiagnostics;
    /** Most recent structured overflow context. */
    private _lastOverflowContext;
    /** Most recent region cost breakdown (telemetry). */
    private _lastRegionCosts;
    /** Most recent governance diagnostics (telemetry surface). */
    get lastDiagnostics(): ContextGovernorDiagnostics | undefined;
    /** Number of provider overflow disagreements recorded. */
    get overflowCount(): number;
    /** Number of provider-reported context overflow events. */
    get providerOverflowCount(): number;
    /** Most recent structured provider overflow context, if any. */
    get lastOverflowContext(): ProviderOverflowContext | undefined;
    getTokenAccountingMode(): TokenAccountingMode;
    /**
     * Cumulative evidence references archived during this governor's lifetime.
     * Used to persist references into the durable mission checkpoint so they
     * survive a rollover without embedding the raw artifact.
     */
    getArchivedEvidenceRefs(): {
        evidenceId: string;
        summary: string;
    }[];
    /** Current durable virtualization ledger snapshot. */
    getVirtualizations(): ToolVirtualizationRecord[];
    constructor(options: ContextGovernorOptions);
    /** Update the checkpoint provider (set after the session builds it). */
    setCheckpointProvider(provider: ContextGovernorOptions["checkpointProvider"]): void;
    /**
     * Attach a durable sink for archived evidence references. Invoked whenever
     * new cold evidence is archived so references can survive process death and
     * be restored on explicit child resume.
     */
    setEvidenceRefsSink(sink: (refs: EvidenceReference[]) => void): void;
    private _emitEvidenceRefs;
    /** Update the capability provider (for runtime model switches). */
    setCapabilityProvider(provider: ContextGovernorOptions["capabilityProvider"]): void;
    /**
     * Refresh the durable virtualization ledger from the persistence source
     * (e.g., after a session resume where a new session snapshot was loaded).
     */
    private _refreshVirtualizations;
    private _persistVirtualizations;
    /**
     * Record a provider context-overflow disagreement. Subsequent `govern` calls
     * apply a progressively stricter budget (bounded) so a tokenizer mismatch
     * forces stronger deterministic reduction instead of looping.
     */
    recordOverflow(context?: ProviderOverflowContext): void;
    /**
     * Feed an authoritative provider usage observation into deterministic
     * calibration. Only ever biases the estimator MORE conservative (never less).
     */
    observeProviderUsage(estimatedInputTokens: number, observedInputTokens: number): void;
    private _applyCalibrationRatio;
    private _deriveAdaptiveCapability;
    private _accounting;
    /**
     * Preflight-reduce an assembly to satisfy the safe input budget.
     *
     * @returns the reduced assembly plus diagnostics. When `action` is
     * "unrecoverable", the caller must NOT send the request.
     */
    govern(assembly: ContextAssembly): Promise<ContextGovernorResult>;
    private _countEvicted;
    /**
     * Restore the virtualized representation for any tool result present in the
     * durable ledger. Returns a new assembly (message objects are NOT mutated so
     * the caller's durable state is preserved) and the count of restored results.
     */
    private _applyPersistedVirtualizations;
    private _unrecoverableReason;
    private _virtualizeToolResults;
    private _recordVirtualization;
    /** Roll the context over: preamble + recent tail. Returns undefined if no change. */
    private _rollover;
    /** Drop the oldest non-pinned messages while retaining at least the recent tail + minimum. */
    private _trimTail;
    /** Opt-in telemetry snapshot (metadata only; never prompt content). */
    getTelemetry(): ContextGovernorTelemetry;
}
/**
 * Rehydrate an archived evidence artifact back into hot context text. Used when
 * a model needs an old tool output again; the governor does not auto-page-in
 * (avoiding loops).
 */
export declare function rehydrateEvidence(archive: EvidenceArchive, evidenceId: string, maxChars?: number): Promise<string | undefined>;
//# sourceMappingURL=context-governor.d.ts.map