import { type GenerationAttemptMode, type GenerationAttemptOutcome, type GenerationAttemptReason, type ProviderId } from "../types.js";
import type { OperationUsageSnapshot } from "./operation-usage.js";
import type { ContextUsageSnapshot } from "./token-usage.js";
/** Versioned runtime representation for one observed context measurement. */
export declare const CONTEXT_SNAPSHOT_VERSION: 1;
export type ContextSnapshotScope = "provider-request" | "assembled-request" | "message-history" | "unknown";
export type ContextSnapshotPrecision = "provider-exact" | "estimate" | "unknown";
export type ContextLimitSource = "session-override" | "model-catalog" | "configured-trigger" | "provider-reported" | "unknown";
export interface ContextSnapshotLimit {
    readonly source: ContextLimitSource;
    readonly tokens?: number | undefined;
}
export type ContextSnapshotHeadroom = {
    readonly kind: "known";
    /** Remaining tokens in the same scope as contextTokens. */
    readonly remainingTokens: number;
    /** Optional future request-budget metadata; T110 leaves it unknown. */
    readonly effectiveTriggerTokens?: number | undefined;
    readonly outputReserveTokens?: number | undefined;
    readonly safetyMarginTokens?: number | undefined;
} | {
    readonly kind: "unknown";
};
/** Provider-reported cache outcomes; absence is explicitly unknown, never zero. */
export type ContextSnapshotCache = {
    readonly kind: "unknown";
} | {
    readonly kind: "reported";
    readonly readTokens?: number | undefined;
    readonly creationTokens?: number | undefined;
    /** Input tokens explicitly not served from the provider cache. */
    readonly uncachedTokens?: number | undefined;
};
/** Provider-reported reasoning usage; absence is explicitly unknown, never zero. */
export type ContextSnapshotReasoning = {
    readonly kind: "unknown";
} | {
    readonly kind: "reported";
    readonly outputTokens?: number | undefined;
    readonly inputArtifactTokens?: number | undefined;
};
/**
 * A T100 record sequence is scoped to one logical provider operation. It is
 * exposed only when that operation snapshot actually reached the caller.
 */
export type ContextAttemptReference = {
    readonly kind: "unavailable";
} | {
    readonly kind: "generation";
    readonly sequence: number;
    readonly provider: ProviderId;
    readonly model: string;
    readonly mode: GenerationAttemptMode;
    readonly reason: GenerationAttemptReason;
    readonly outcome: GenerationAttemptOutcome;
};
export interface ContextSnapshotV1 {
    readonly version: typeof CONTEXT_SNAPSHOT_VERSION;
    /** The observed context fill in the declared scope. */
    readonly contextTokens: number;
    readonly lastCompletionTokens: number;
    readonly sessionPromptTokens: number;
    readonly sessionCompletionTokens: number;
    readonly scope: ContextSnapshotScope;
    readonly precision: ContextSnapshotPrecision;
    readonly limit: ContextSnapshotLimit;
    readonly headroom: ContextSnapshotHeadroom;
    readonly cache: ContextSnapshotCache;
    readonly reasoning: ContextSnapshotReasoning;
    readonly attempt: ContextAttemptReference;
    /** Epoch milliseconds captured at measurement time, never at projection time. */
    readonly observedAt: number;
}
export interface CreateContextSnapshotInput {
    readonly contextTokens: number;
    readonly lastCompletionTokens?: number | undefined;
    readonly sessionPromptTokens?: number | undefined;
    readonly sessionCompletionTokens?: number | undefined;
    readonly scope: ContextSnapshotScope;
    readonly precision: ContextSnapshotPrecision;
    readonly limit?: ContextSnapshotLimit | undefined;
    readonly headroom?: ContextSnapshotHeadroom | undefined;
    readonly cache?: ContextSnapshotCache | undefined;
    readonly reasoning?: ContextSnapshotReasoning | undefined;
    readonly attempt?: ContextAttemptReference | undefined;
    readonly observedAt?: number | undefined;
}
/** Build one immutable, versioned observation without synthesizing telemetry. */
export declare function createContextSnapshot(input: CreateContextSnapshotInput): ContextSnapshotV1;
/** The only legacy projection consumed by existing renderers and old history. */
export declare function toLegacyContextUsage(snapshot: ContextSnapshotV1): ContextUsageSnapshot;
export declare function contextLimitFromSessionOverride(tokens: number | undefined): ContextSnapshotLimit;
/** Rebind only live limit metadata; measurements retain their original time. */
export declare function withContextSnapshotLimit(snapshot: ContextSnapshotV1, limit: ContextSnapshotLimit): ContextSnapshotV1;
/** Convert an unversioned six-field persisted/rendering snapshot once. */
export declare function contextSnapshotFromLegacy(snapshot: ContextUsageSnapshot, limit: ContextSnapshotLimit, observedAt?: number | undefined): ContextSnapshotV1;
/** Narrow persisted JSON before treating it as the current schema. */
export declare function isContextSnapshotV1(value: unknown): value is ContextSnapshotV1;
/** Return the final physical T100 attempt only when it really exists. */
export declare function contextAttemptFromOperationUsage(operationUsage: OperationUsageSnapshot | undefined): ContextAttemptReference;