export type ContextValue = null | boolean | number | string | ContextValue[] | { [key: string]: ContextValue; }; export interface ContextTokenEstimate { tokens: number; serializedBytes: number; } /** Estimators are deliberately replaceable: provider tokenization is not a timeless fact. */ export interface ContextTokenEstimator { id: string; version: string; estimate(value: ContextValue): ContextTokenEstimate; } export interface ContextProviderProfile { id: string; version: string; estimator: { id: string; version: string; }; limits: { aggregateTokens: number; stateAndLongestQuestionTokens: number; }; /** Reserve this portion of each documented limit; 2_000 means twenty percent. */ safetyMarginBps: number; requestEnvelopeTokens: number; } export interface ContextQuestion { id: string; subject: string; entry: ContextValue; /** A question with dependencies is placed in a later execution wave. */ dependsOn?: string[]; /** Questions may share a request only when this key is identical. */ compatibilityKey?: string; } export interface ContextPlanInput { subject: string; authorizedState: ContextValue; authorizationDigest: `sha256:${string}`; incompleteContext: boolean; questions: ContextQuestion[]; } export interface ContextPartition { id: string; wave: number; compatibilityKey: string; subject: string; stateDigest: `sha256:${string}`; questionIds: string[]; questionDigests: Record; questionDependencies: Record; estimate: { stateTokens: number; questionTokens: Record; longestQuestionTokens: number; aggregateTokens: number; stateAndLongestQuestionTokens: number; }; reason: 'fits-original-group' | 'aggregate-limit-partition' | 'dependency-wave'; } export interface ContextPlan { schemaVersion: 'decision-context-plan/v1'; planDigest: `sha256:${string}`; assumptionsDigest: `sha256:${string}`; inputDigest: `sha256:${string}`; subject: string; authorizationDigest: `sha256:${string}`; incompleteContext: boolean; automaticActionAllowed: boolean; estimator: { id: string; version: string; }; providerProfile: { id: string; version: string; digest: `sha256:${string}`; }; limits: { documentedAggregateTokens: number; documentedStateAndLongestQuestionTokens: number; safetyMarginBps: number; effectiveAggregateTokens: number; effectiveStateAndLongestQuestionTokens: number; }; rawEstimate: { stateTokens: number; allQuestionTokens: number; longestQuestionTokens: number; aggregateTokens: number; stateAndLongestQuestionTokens: number; }; partitions: ContextPartition[]; } export interface ContextActualUsageEvidence { schemaVersion: 'decision-context-usage/v1'; planDigest: `sha256:${string}`; partitionId: string; /** Exact questions carried by this provider request. */ questionIds: string[]; estimator: { id: string; version: string; }; providerProfile: { id: string; version: string; }; estimatedInputTokens: number; actualInputTokens: number; estimationErrorTokens: number; estimationErrorBps: number | null; } export type ContextPlanFailureReason = 'invalid-input' | 'invalid-profile' | 'estimator-profile-mismatch' | 'oversized-state' | 'oversized-question' | 'dependency-error' | 'stale-plan' /** Partitioned native batching was requested without a qualified rollout (D06 fail-closed default). */ | 'rollout-unqualified'; export declare class ContextPlanError extends Error { readonly reason: ContextPlanFailureReason; readonly details: Readonly>; constructor(reason: ContextPlanFailureReason, message: string, details?: Readonly>); } /** Conservative, deterministic fallback; it does not claim vendor-tokenizer equivalence. */ export declare class CanonicalJsonByteEstimator implements ContextTokenEstimator { readonly version: string; private readonly bytesPerToken; readonly id: string; constructor(version?: string, bytesPerToken?: number); estimate(value: ContextValue): ContextTokenEstimate; } export declare function planDecisionContext(input: ContextPlanInput, profile: ContextProviderProfile, estimator: ContextTokenEstimator): ContextPlan; /** Replanning is intentional: a changed profile, estimator or authorized input invalidates the old plan. */ export declare function assertContextPlanCurrent(plan: ContextPlan, input: ContextPlanInput, profile: ContextProviderProfile, estimator: ContextTokenEstimator): void; /** Provider usage augments evidence and never mutates or recomputes the original plan. */ export declare function recordContextActualUsage(plan: ContextPlan, partitionId: string, actualInputTokens: number, questionId?: string | readonly string[]): ContextActualUsageEvidence; //# sourceMappingURL=context-plan.d.ts.map