dsh-context-compression-improved 0.1.1 → 0.2.1

package/packages/selector/src/runtime/adaptive-cost.ts

@@ -0,0 +1,194 @@
+/** Conservative cost interval used by the Adaptive History gate. */
+
+import type {
+  MeasuredTokenSurfaceNode,
+  TokenCount,
+} from './measurement.ts'
+import { decimalRateNanoUnits } from './deepseek-official-pricing.ts'
+
+/** Inputs that conservatively bound one already-planned Adaptive History batch. */
+export interface AdaptiveTokenBoundsInput {
+  /** Exact sum of the planned canonical replacements' net token reduction. */
+  readonly exactReclaimedTokens: number
+  /** Durable sequence number of the earliest message changed by the plan. */
+  readonly earliestChangedSeq: number
+  /** Official request-level prompt_tokens from the immediately preceding request. */
+  readonly previousPromptTokens: number
+  /** Tokenizer artifact revision carried by that request's exact provider key. */
+  readonly expectedTokenizerRevision: string
+  /** Tokenizer-first measurement of that exact preceding assembled request. */
+  readonly previousRequestMeasurement: TokenCount
+  /** Same-revision provider-tokenizer counts for the durable surface. */
+  readonly measuredNodes: readonly MeasuredTokenSurfaceNode[]
+}
+
+/** Available lower-benefit and upper-risk bounds for one History batch. */
+export interface AvailableAdaptiveTokenBounds {
+  readonly kind: 'available'
+  readonly measurementKind: 'exact-tokenizer' | 'tokenizer-estimate'
+  /** D: conservative lower bound of input tokens removed by the plan. */
+  readonly reclaimedLowerBoundTokens: number
+  /** A: conservative upper bound of retained suffix tokens that may lose a hit. */
+  readonly affectedRetainedSuffixUpperBoundTokens: number
+  /** Known exact canonical prefix before the first changed durable sequence. */
+  readonly exactPrefixLowerBoundTokens: number
+}
+
+/** Available conservative bounds or an explicit reason they cannot be derived. */
+export type AdaptiveTokenBounds = AvailableAdaptiveTokenBounds | {
+  readonly kind: 'unknown'
+  readonly reason: string
+}
+
+/**
+ * Bound Adaptive's benefit and cache-loss exposure without attributing the
+ * request-level cache split to individual messages. Removed tokens are not
+ * charged again as part of the retained suffix.
+ * @param input - exact planned reclaim, adjacent request measurement, and same-revision nodes.
+ * @returns Conservative removal/cache-risk bounds or an explicit unknown reason.
+ */
+export function deriveAdaptiveTokenBounds(input: AdaptiveTokenBoundsInput): AdaptiveTokenBounds {
+  if (!isCount(input.exactReclaimedTokens) || input.exactReclaimedTokens === 0) {
+    return unknown('invalid-reclaimed-token-count')
+  }
+  if (!isCount(input.earliestChangedSeq)) return unknown('invalid-earliest-changed-seq')
+  if (!isCount(input.previousPromptTokens)) return unknown('invalid-previous-prompt-tokens')
+  if (input.expectedTokenizerRevision.length === 0) {
+    return unknown('expected-tokenizer-revision-unavailable')
+  }
+
+  const request = input.previousRequestMeasurement
+  let margin = 0
+  let measurementKind: AvailableAdaptiveTokenBounds['measurementKind']
+  if (request.kind === 'unavailable') return unknown('request-measurement-unavailable')
+  if (request.kind === 'exact-tokenizer') {
+    if (!isCount(request.tokens) || request.tokens !== input.previousPromptTokens) {
+      return unknown('exact-request-usage-mismatch')
+    }
+    if (request.tokenizerRevision !== input.expectedTokenizerRevision) {
+      return unknown('request-tokenizer-revision-mismatch')
+    }
+    measurementKind = request.kind
+  } else {
+    const calibration = request.calibration
+    if (calibration === undefined) return unknown('estimate-calibration-unavailable')
+    if (!isCount(request.tokens)
+      || !isCount(request.upperBoundTokens)
+      || request.upperBoundTokens < request.tokens
+      || input.previousPromptTokens > request.upperBoundTokens
+      || !isCount(calibration.sampleCount)
+      || !isCount(calibration.conservativeMarginTokens)) {
+      return unknown('invalid-estimate-calibration')
+    }
+    margin = calibration.conservativeMarginTokens
+    measurementKind = request.kind
+  }
+
+  const reclaimedLowerBoundTokens = Math.max(0, input.exactReclaimedTokens - margin)
+  if (reclaimedLowerBoundTokens === 0) return unknown('reclaim-not-positive-after-margin')
+
+  let identity: { readonly tokenizerId: string; readonly tokenizerRevision: string } | undefined
+  let exactPrefixLowerBoundTokens = 0
+  const seen = new Set<number>()
+  for (const node of input.measuredNodes) {
+    if (!isCount(node.seq) || seen.has(node.seq)) return unknown('invalid-measured-node-sequence')
+    seen.add(node.seq)
+    if (node.seq >= input.earliestChangedSeq || node.count.kind !== 'exact-tokenizer') continue
+    if (!isCount(node.count.tokens)) return unknown('invalid-exact-prefix-count')
+    if (node.count.tokenizerRevision !== input.expectedTokenizerRevision) {
+      return unknown('exact-prefix-tokenizer-revision-mismatch')
+    }
+    if (identity !== undefined
+      && (identity.tokenizerId !== node.count.tokenizerId
+        || identity.tokenizerRevision !== node.count.tokenizerRevision)) {
+      return unknown('exact-prefix-tokenizer-identity-mismatch')
+    }
+    identity ??= node.count
+    exactPrefixLowerBoundTokens += node.count.tokens
+    if (!isCount(exactPrefixLowerBoundTokens)) return unknown('exact-prefix-overflow')
+  }
+
+  const accounted = exactPrefixLowerBoundTokens + reclaimedLowerBoundTokens
+  if (!isCount(accounted) || accounted > input.previousPromptTokens) {
+    return unknown('adaptive-bounds-exceed-previous-prompt')
+  }
+  return {
+    kind: 'available',
+    measurementKind,
+    reclaimedLowerBoundTokens,
+    affectedRetainedSuffixUpperBoundTokens: input.previousPromptTokens - accounted,
+    exactPrefixLowerBoundTokens,
+  }
+}
+
+/** Conservative bounds, capacity authority, and applicable official input prices. */
+export interface ConservativeAdaptiveDecisionInput {
+  readonly capacityPressure: boolean
+  readonly bounds: AdaptiveTokenBounds
+  /** Official price per one million cache-hit input tokens. */
+  readonly inputCacheHitRate?: string
+  /** Official price per one million cache-miss input tokens. */
+  readonly inputCacheMissRate?: string
+  /** Request-level hit total; caps, but never attributes, the affected hit exposure. */
+  readonly observedCacheReadTokens?: number
+}
+
+/** Authorization decision plus fixed-point comparison telemetry when evaluated. */
+export type ConservativeAdaptiveDecision =
+  | { readonly allowHistory: true; readonly reason: 'capacity-override' }
+  | {
+    readonly allowHistory: boolean
+    readonly reason: string
+    readonly minimumRemovalValue?: string
+    readonly maximumCacheLossPenalty?: string
+  }
+
+/**
+ * Allow routine History only when D*P_hit is strictly greater than A*(P_miss-P_hit).
+ * @param input - capacity state, token bounds, request hit cap, and official input rates.
+ * @returns Capacity override or a strict fixed-point conservative-cost decision.
+ */
+export function decideConservativeAdaptive(
+  input: ConservativeAdaptiveDecisionInput,
+): ConservativeAdaptiveDecision {
+  if (input.capacityPressure) return { allowHistory: true, reason: 'capacity-override' }
+  if (input.bounds.kind === 'unknown') {
+    return { allowHistory: false, reason: input.bounds.reason }
+  }
+  if (input.inputCacheHitRate === undefined || input.inputCacheMissRate === undefined) {
+    return { allowHistory: false, reason: 'adaptive-unknown-price' }
+  }
+  const hit = decimalRateNanoUnits(input.inputCacheHitRate)
+  const miss = decimalRateNanoUnits(input.inputCacheMissRate)
+  if (hit === undefined || miss === undefined || miss < hit) {
+    return { allowHistory: false, reason: 'adaptive-unknown-price' }
+  }
+  if (input.observedCacheReadTokens !== undefined && !isCount(input.observedCacheReadTokens)) {
+    return { allowHistory: false, reason: 'adaptive-invalid-cache-telemetry' }
+  }
+  const affectedHitUpperBound = input.observedCacheReadTokens === undefined
+    ? input.bounds.affectedRetainedSuffixUpperBoundTokens
+    : Math.min(
+      input.bounds.affectedRetainedSuffixUpperBoundTokens,
+      input.observedCacheReadTokens,
+    )
+  const minimumRemovalValue = BigInt(input.bounds.reclaimedLowerBoundTokens) * hit
+  const maximumCacheLossPenalty = BigInt(affectedHitUpperBound)
+    * (miss - hit)
+  return {
+    allowHistory: minimumRemovalValue > maximumCacheLossPenalty,
+    reason: minimumRemovalValue > maximumCacheLossPenalty
+      ? 'cost-interval-clearly-favourable'
+      : 'cache-risk-not-clearly-paid-back',
+    minimumRemovalValue: minimumRemovalValue.toString(),
+    maximumCacheLossPenalty: maximumCacheLossPenalty.toString(),
+  }
+}
+
+function unknown(reason: string): AdaptiveTokenBounds {
+  return { kind: 'unknown', reason }
+}
+
+function isCount(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0
+}

package/packages/selector/src/runtime/audit.ts

@@ -0,0 +1,215 @@
+/** Structured, content-free runtime audit records for context compression. */
+
+import type {
+  CompressionPolicy,
+  CompressionProfile,
+  ContextCompressionSettings,
+  HistoryMode,
+  ResolvedConfig,
+} from './types.ts'
+
+/** Stable prefix used to locate one JSON audit record in Harness runtime logs. */
+export const COMPRESSION_AUDIT_PREFIX = 'context-compression audit '
+
+/** Compression primitive that committed one model-free surface rewrite. */
+export type CompressionAuditComponent =
+  | 'fresh'
+  | 'aggregate'
+  | 'history'
+  | 'tail-trim'
+  | 'native-tool-result'
+  | 'dedupe'
+  | 'summary-locator'
+
+/** Non-mutating outcome of evaluating one component at one runtime boundary. */
+export type CompressionAuditEvaluationStatus = 'disabled' | 'skipped'
+
+interface CompressionAuditBase {
+  readonly schemaVersion: 1
+  readonly sessionId: string
+}
+
+/** Complete settings and deployment config frozen on first runtime observation. */
+export interface CompressionPolicyFrozenAuditRecord extends CompressionAuditBase {
+  readonly kind: 'policy-frozen'
+  readonly settingsSource: 'host-settings' | 'plugin-config-fallback'
+  /** Where the frozen Auto Compact threshold came from. */
+  readonly autoCompactThresholdSource?: 'generation-config' | 'host-settings' | 'schema-default'
+  /** Present when the stored document was invalid and the session froze losslessly. */
+  readonly settingsInvalidFallback?: 'lossless-off'
+  readonly settings: ContextCompressionSettings
+  readonly deploymentConfig: ResolvedConfig
+}
+
+/** Routed request facts captured alongside one policy resolution. */
+export interface CompressionRouteAuditFact {
+  readonly provider: string
+  readonly model: string
+  readonly modality?: string
+}
+
+/** Bundled tokenizer identity backing exact counts for one route. */
+export interface CompressionTokenizerAuditFact {
+  readonly repository: string
+  readonly revision: string
+}
+
+/** How the resolved History watermarks were derived for one Session. */
+export interface CompressionCoordinationAuditFact {
+  /** Frozen Auto Compact threshold percent from the settings snapshot. */
+  readonly thresholdPercent: number
+  /** `A = floor(C × a)`; undefined when linkage did not resolve. */
+  readonly autoCompactTokens?: number
+  /** `D = floor(A × 0.875)`; undefined when linkage did not resolve. */
+  readonly microDeadlineTokens?: number
+  /**
+   * Whether History follows the Auto Compact watermark, explicit deployment
+   * overrides, a mix of both, Custom manual tokens, or the fixed preset.
+   */
+  readonly paramSource: 'auto-compact-linked' | 'deployment-override' | 'mixed' | 'custom-manual' | 'fixed-preset'
+}
+
+/** One effective policy resolution, including context-percent capacity when used. */
+export interface CompressionPolicyResolvedAuditRecord extends CompressionAuditBase {
+  readonly kind: 'policy-resolved'
+  readonly policy: CompressionPolicy
+  readonly contextWindowTokens?: number
+  readonly coordination?: CompressionCoordinationAuditFact
+  readonly route?: CompressionRouteAuditFact
+  readonly tokenizer?: CompressionTokenizerAuditFact
+}
+
+/** One committed model-free surface rewrite and its exact token accounting. */
+export interface CompressionRewriteAuditRecord extends CompressionAuditBase {
+  readonly kind: 'rewrite'
+  readonly profile: CompressionProfile
+  readonly component: CompressionAuditComponent
+  readonly stage: 'fresh' | 'pressure'
+  readonly reducer: string
+  readonly historyMode?: HistoryMode
+  readonly manifestEventType: 'compaction/prune'
+  readonly manifestSeq: number
+  readonly replacementSeq: number
+  readonly sourceSeqs: readonly number[]
+  readonly tokensBefore: number
+  readonly tokensAfter: number
+  readonly tokensRemoved: number
+  readonly tokenizerId: string
+  readonly tokenizerRevision: string
+}
+
+/** Why an enabled component did not rewrite, or why it was disabled. */
+export interface CompressionComponentEvaluationAuditRecord extends CompressionAuditBase {
+  readonly kind: 'component-evaluation'
+  readonly profile: CompressionProfile
+  readonly component: CompressionAuditComponent
+  readonly stage: 'fresh' | 'pressure'
+  readonly status: CompressionAuditEvaluationStatus
+  readonly reason: string
+  readonly historyMode?: HistoryMode
+  readonly measurementKind?: 'exact-tokenizer' | 'tokenizer-estimate' | 'unavailable'
+  readonly currentTokens?: number
+  readonly triggerTokens?: number
+  readonly targetTokens?: number
+  /** Reclaim the planned batch reached (insufficient-reclaim family only). */
+  readonly reclaimTokens?: number
+  /** Reclaim the batch required (insufficient-reclaim family only). */
+  readonly requiredTokens?: number
+}
+
+/** One fail-open runtime error, without prompt or tool-result content. */
+export interface CompressionFailureAuditRecord extends CompressionAuditBase {
+  readonly kind: 'failure'
+  readonly stage: 'fresh' | 'pressure'
+  readonly operation:
+    | 'request-boundary'
+    | 'terminal-pass'
+    | 'policy-resolution'
+    | 'summary-locator'
+    | 'publication'
+  readonly component?: CompressionAuditComponent
+  readonly manifestSeq?: number
+  readonly errorName: string
+  readonly errorMessage: string
+}
+
+/** One observed core Native auto-compaction summary event. */
+export interface NativeAutoCompactAuditRecord extends CompressionAuditBase {
+  readonly kind: 'native-auto-compact'
+  readonly manifestEventType: 'compaction/summary'
+  readonly manifestSeq: number
+  readonly reducer: 'llm-summary'
+  readonly provider: string
+  readonly model: string
+  readonly tokensBefore: number | null
+  readonly tokensAfter: null
+}
+
+/** One Exact Sources locator block appended to a landed Auto Compact summary. */
+export interface SummaryLocatorAuditRecord extends CompressionAuditBase {
+  readonly kind: 'summary-locator'
+  readonly profile: CompressionProfile
+  readonly checkpointSeq: number
+  readonly summarySeq: number
+  readonly locatorChars: number
+  readonly spillFiles: number
+  readonly touchedFiles: number
+}
+
+/** One background estimator pass. Only numeric metadata — never prompts or keys. */
+export interface EstimatorOutcomeAuditRecord extends CompressionAuditBase {
+  readonly kind: 'estimator-outcome'
+  readonly profile: CompressionProfile
+  readonly channel: 'host' | 'direct'
+  readonly sampled: number
+  readonly expired: number
+  readonly latencyMs: number
+  readonly ok: boolean
+}
+
+/** Closed version-one context-compression audit vocabulary. */
+export type CompressionAuditRecord =
+  | CompressionPolicyFrozenAuditRecord
+  | CompressionPolicyResolvedAuditRecord
+  | CompressionRewriteAuditRecord
+  | CompressionComponentEvaluationAuditRecord
+  | CompressionFailureAuditRecord
+  | NativeAutoCompactAuditRecord
+  | SummaryLocatorAuditRecord
+  | EstimatorOutcomeAuditRecord
+
+/** Minimal logger method consumed by the audit publisher. */
+export interface CompressionAuditLogger {
+  /**
+   * Publish one informational message.
+   * @param message - complete single-line audit message.
+   * @returns logger-specific chaining value, if any.
+   */
+  info(message: string): unknown
+}
+
+/**
+ * Encode one stable single-line audit message.
+ * @param record - content-free structured audit record.
+ * @returns the fixed prefix followed by one JSON object.
+ */
+export function formatCompressionAudit(record: CompressionAuditRecord): string {
+  return `${COMPRESSION_AUDIT_PREFIX}${JSON.stringify(record)}`
+}
+
+/**
+ * Publish one audit message through the Harness logger.
+ * @param logger - current plugin logger.
+ * @param record - structured record committed by the caller.
+ */
+export function emitCompressionAudit(
+  logger: CompressionAuditLogger,
+  record: CompressionAuditRecord,
+): void {
+  try {
+    logger.info(formatCompressionAudit(record))
+  }
+  catch {
+    // Swallow logger failures: audit publication must not roll back a committed rewrite.
+  }
+}