Skip to content
71 changes: 64 additions & 7 deletions src/cache-ledger.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import { METADATA_CANONICAL_SYS_FP, METADATA_FOLD_COVERAGE, METADATA_LAST_RESPON
import { clearPostRebuildAnchor, markDirty, type Session } from "./session.js";
import { isForeignMembership } from "./request-membership.js";
import { billInputUsage } from "./billing.js";
import { normalizeUpstreamOrigin } from "./util.js";
import { CALIBRATION_PROVENANCE_TEXT_ONLY, normalizeUpstreamOrigin } from "./util.js";
import { toolFail, toolOk, type ProxyToolResult } from "./proxy-tool-result.js";

// Render window for handleAcpCache's detail:"full" text view (#1489). The
Expand Down Expand Up @@ -529,6 +529,11 @@ type Capture = {
sentBody?: SeamSlot;
inBody?: InboundSlot;
imageFacts?: ForwardedImageFacts;
// #5952: the calibration pair for THIS send — final wire text estimate
// (no image reserve) + the image reserve of the same body, noted at the
// relay main-lane send chokepoint. The settle that bills this body
// consumes exactly this entry instead of the shared prepare slot.
calibration?: { estimate: number; imageTokens: number; origin?: string; model?: string };
};
const captures = new AsyncLocalStorage<Capture>();
let captureOrder = 0;
Expand All @@ -546,6 +551,7 @@ export async function withCacheCapture<T>(session: Session | undefined, fn: () =
delete capture.sentBody;
delete capture.inBody;
delete capture.imageFacts;
delete capture.calibration;
}
}
});
Expand Down Expand Up @@ -861,6 +867,22 @@ export function noteForwardedImageFacts(session: Session, facts: ForwardedImageF
imageFactsLastSent.set(session, facts);
}

/** #5952: the per-request calibration pair for THIS send — the final wire
* text estimate (textOverhead, no image reserve) + the image reserve of
* the same body, noted at the relay main-lane send chokepoint next to
* noteOutboundContextEstimates. The next settleUsageReport /
* settleOverflowCalibration consumes exactly this entry (same pairing
* guarantee as the seam forensics): a concurrent request's prepare can no
* longer overwrite the estimate a settle reads, and an image-bearing
* sample can no longer train the text multiplier. Outside a capture there
* is no per-request owner for the pair, so it is dropped, never parked on
* the session where a later settle could misread it as this request's —
* lanes outside the capture (loop/plugin) keep the legacy shared slot. */
export function noteCalibrationPair(session: Session, pair: { estimate: number; imageTokens: number; origin?: string; model?: string }): void {
const capture = captures.getStore();
if (capture?.session === session) { capture.calibration = pair; return; }
}

function settleImageLearning(session: Session, billedTotal: number): void {
const capture = captures.getStore();
const facts = capture?.session === session ? capture.imageFacts : imageFactsLastSent.get(session);
Expand Down Expand Up @@ -1831,10 +1853,25 @@ function ingestCalibrationPair(session: Session, billed: number, upstream: strin
const settleOrigin = normalizeUpstreamOrigin(upstream);
const pendingCalibOrigin = session.stats.lastCalibrationPolicyOrigin !== undefined ? normalizeUpstreamOrigin(session.stats.lastCalibrationPolicyOrigin) : undefined;
const calibPolicy = pendingCalibOrigin === settleOrigin ? session.stats.lastCalibrationPolicy : undefined;
const pendingEst = session.stats.lastLocalTextEstimate;
const pendingOrigin = normalizeUpstreamOrigin(session.stats.lastLocalTextEstimateOrigin);
// #5952: the per-request capture pair wins over the shared prepare slot —
// it is the final wire estimate of the request THIS report bills, noted
// at the send chokepoint. Consumed once: the settle that reads it owns
// it, so a concurrent settle can never re-read it as its own.
const capture = captures.getStore();
const capturePair = capture?.session === session ? capture.calibration : undefined;
if (capture?.session === session) delete capture.calibration;
// An image-bearing sample carries no text-only signal: it must not train
// the text multiplier at all — not even through the legacy slot, which a
// concurrent prepare may have left holding another request's estimate.
if (capturePair !== undefined && capturePair.imageTokens > 0) return;
const pendingEst = capturePair !== undefined ? capturePair.estimate : session.stats.lastLocalTextEstimate;
const pendingOrigin = capturePair !== undefined ? normalizeUpstreamOrigin(capturePair.origin) : normalizeUpstreamOrigin(session.stats.lastLocalTextEstimateOrigin);
if (pendingEst !== undefined && pendingEst >= CALIBRATION_MIN_ESTIMATE && settleOrigin !== undefined && pendingOrigin === settleOrigin) {
const rawSample = billed / pendingEst;
// #5952: provenance of THIS sample — text-only only when it arrived
// on a capture pair. A legacy shared-slot sample carries none, so a
// ring holding one stays mixed until the window flushes it out.
const sampleProvenance = capturePair !== undefined ? CALIBRATION_PROVENANCE_TEXT_ONLY : undefined;
// #2117 B: the ring is keyed by route AND model — tokenizers bill
// differently across models, so a mid-session model switch starts a
// FRESH ring instead of blending two models' billing scales into one
Expand All @@ -1844,8 +1881,10 @@ function ingestCalibrationPair(session: Session, billed: number, upstream: strin
// whose load whitelist drops the model fields (#2141) — continues
// and ADOPTS the first known model. Discarding it would clear a
// provenance-matched published k̂ on the first post-restart settle
// (the #2129 regression class).
const settleModel = typeof session.metadata?.lastModel === "string" && session.metadata.lastModel !== "" ? session.metadata.lastModel : undefined;
// (the #2129 regression class). The capture pair's model, when
// known, is this request's own — it outranks the session's
// last-known model (#5952).
const settleModel = capturePair?.model !== undefined ? capturePair.model : (typeof session.metadata?.lastModel === "string" && session.metadata.lastModel !== "" ? session.metadata.lastModel : undefined);
let ring = session.stats.calibrationRing;
if (!ring || ring.origin !== settleOrigin || (ring.model !== undefined && settleModel !== undefined && ring.model !== settleModel)) {
ring = { origin: settleOrigin, model: settleModel, values: [] };
Expand All @@ -1854,7 +1893,16 @@ function ingestCalibrationPair(session: Session, billed: number, upstream: strin
}
if (rawSample >= CALIBRATION_SAMPLE_MIN && rawSample <= CALIBRATION_SAMPLE_MAX) {
ring.values.push(rawSample);
if (ring.values.length > CALIBRATION_SAMPLE_WINDOW) ring.values.shift();
// #5952: provenances ride in lockstep with values — a legacy
// ring restored without the array pads with undefined, so the
// publish verdict below stays aligned with the window.
if (ring.provenances === undefined) ring.provenances = [];
while (ring.provenances.length < ring.values.length - 1) ring.provenances.push(undefined);
ring.provenances.push(sampleProvenance);
if (ring.values.length > CALIBRATION_SAMPLE_WINDOW) {
ring.values.shift();
ring.provenances.shift();
}
const spread = Math.max(...ring.values) / Math.min(...ring.values);
if (ring.values.length >= 2 && spread <= CALIBRATION_CONSISTENCY_RATIO) {
const mean = ring.values.reduce((a, b) => a + b, 0) / ring.values.length;
Expand All @@ -1864,21 +1912,30 @@ function ingestCalibrationPair(session: Session, billed: number, upstream: strin
delete session.stats.calibratedEstimate;
delete session.stats.calibratedEstimateOrigin;
delete session.stats.calibratedEstimateModel;
delete session.stats.calibratedEstimateProvenance;
} else {
const clamped = Math.min(CALIBRATION_CLAMP_MAX, Math.max(CALIBRATION_CLAMP_MIN, mean));
session.stats.calibratedEstimate = calibPolicy?.max !== undefined ? Math.min(clamped, calibPolicy.max) : clamped;
session.stats.calibratedEstimateOrigin = settleOrigin;
// Provenance is the ring's model key, not this sample's stamp —
// an unknown-model settle continues a model-keyed ring without
// blanking the established provenance. Stays inside the publish
// branch: the disabled path above clears all three fields and
// branch: the disabled path above clears all four fields and
// must not re-stamp one of them (#3211 review).
session.stats.calibratedEstimateModel = ring.model;
// #5952: the published factor's provenance is the ring's —
// "text-only-v1" only when every value in the window
// carries it. A single legacy sample in the window keeps
// the factor inert until the window flushes it out.
const ringProvenance = ring.provenances !== undefined && ring.provenances.length === ring.values.length && ring.provenances.every((p) => p === CALIBRATION_PROVENANCE_TEXT_ONLY) ? CALIBRATION_PROVENANCE_TEXT_ONLY : undefined;
if (ringProvenance !== undefined) session.stats.calibratedEstimateProvenance = ringProvenance;
else delete session.stats.calibratedEstimateProvenance;
}
} else {
delete session.stats.calibratedEstimate;
delete session.stats.calibratedEstimateOrigin;
delete session.stats.calibratedEstimateModel;
delete session.stats.calibratedEstimateProvenance;
}
}
session.stats.calibrationRing = ring;
Expand Down
29 changes: 22 additions & 7 deletions src/persist.ts
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ import { resolveBackendName } from "./storage/backend.js";
import { toLegacyLike, type LegacySessionLike } from "./storage/ingest.js";
import { sha256Hex, type CheckpointRow, type MessageRefContentRow, type MessageIdContentRow } from "./storage/store.js";
import { contentStoreOf } from "./store.js";
import type { WireProtocol } from "./util.js";
import { CALIBRATION_PROVENANCE_TEXT_ONLY, type WireProtocol } from "./util.js";
import { currentContextObservation, canonicalJson, CALIBRATION_CLAMP_MAX, CALIBRATION_CLAMP_MIN, CALIBRATION_SAMPLE_MAX, CALIBRATION_SAMPLE_MIN, CALIBRATION_SAMPLE_WINDOW } from "./cache-ledger.js";

/**
Expand Down Expand Up @@ -225,7 +225,8 @@ interface PersistedSession {
calibratedEstimate?: number;
calibratedEstimateOrigin?: string;
calibratedEstimateModel?: string;
calibrationRing?: { origin: string; model?: string; values: number[] };
calibratedEstimateProvenance?: string;
calibrationRing?: { origin: string; model?: string; values: number[]; provenances?: (string | undefined)[] };
pendingFoldUsage?: boolean;
lastLocalTextEstimate?: number;
lastLocalTextEstimateOrigin?: string;
Expand Down Expand Up @@ -4201,15 +4202,25 @@ function restoreCalibratedEstimate(v: unknown): number | undefined {
// itself would admit (finite, within the plausibility band) and only the newest
// window-size entries; anything else drops the ring wholesale so a malformed
// file can neither teach a factor nor mask a fresh learning run on restart.
function restoreCalibrationRing(v: unknown): { origin: string; model?: string; values: number[] } | undefined {
// #5952: (value, provenance) pairs stay aligned through the filter + window
// slice, so a restored ring's provenance verdict matches its values; a stored
// provenance entry counts only on an exact "text-only-v1" match, and the key
// is omitted entirely when no entry survives (legacy files keep their exact
// restored shape).
function restoreCalibrationRing(v: unknown): { origin: string; model?: string; values: number[]; provenances?: (string | undefined)[] } | undefined {
if (!v || typeof v !== "object") return undefined;
const ring = v as { origin?: unknown; model?: unknown; values?: unknown };
const ring = v as { origin?: unknown; model?: unknown; values?: unknown; provenances?: unknown };
if (typeof ring.origin !== "string" || ring.origin.length === 0) return undefined;
if (!Array.isArray(ring.values)) return undefined;
const values = ring.values.filter((x): x is number => typeof x === "number" && Number.isFinite(x) && x >= CALIBRATION_SAMPLE_MIN && x <= CALIBRATION_SAMPLE_MAX);
const recent = values.slice(-CALIBRATION_SAMPLE_WINDOW);
const storedProvenances = Array.isArray(ring.provenances) ? ring.provenances : undefined;
const kept = ring.values
.map((x, i) => ({ value: x, provenance: storedProvenances?.[i] }))
.filter((e): e is { value: number; provenance: unknown } => typeof e.value === "number" && Number.isFinite(e.value) && e.value >= CALIBRATION_SAMPLE_MIN && e.value <= CALIBRATION_SAMPLE_MAX);
const recent = kept.slice(-CALIBRATION_SAMPLE_WINDOW);
if (recent.length === 0) return undefined;
const provenances = recent.map((e) => (e.provenance === CALIBRATION_PROVENANCE_TEXT_ONLY ? CALIBRATION_PROVENANCE_TEXT_ONLY : undefined));
const model = typeof ring.model === "string" && ring.model.trim().length > 0 ? ring.model : undefined;
return recent.length > 0 ? { origin: ring.origin, ...(model === undefined ? {} : { model }), values: recent } : undefined;
return { origin: ring.origin, ...(model === undefined ? {} : { model }), values: recent.map((e) => e.value), ...(provenances.some((p) => p !== undefined) ? { provenances } : {}) };
}

function restoreBlockContents(entries: Iterable<readonly [string, unknown]>): Map<string, BlockContent> {
Expand Down Expand Up @@ -4300,6 +4311,10 @@ function buildSession(parsed: PersistedSession): Session {
calibratedEstimate: restoreCalibratedEstimate(stats.calibratedEstimate),
calibratedEstimateOrigin: typeof stats.calibratedEstimateOrigin === "string" && stats.calibratedEstimateOrigin.trim().length > 0 ? stats.calibratedEstimateOrigin : undefined,
calibratedEstimateModel: typeof stats.calibratedEstimateModel === "string" && stats.calibratedEstimateModel.trim().length > 0 ? stats.calibratedEstimateModel : undefined,
// #5952: restored on an exact "text-only-v1" match only, like the
// ring's provenance entries — a stale mixed-modal multiplier must
// not survive a restart wearing a provenance it never earned.
calibratedEstimateProvenance: stats.calibratedEstimateProvenance === CALIBRATION_PROVENANCE_TEXT_ONLY ? CALIBRATION_PROVENANCE_TEXT_ONLY : undefined,
calibrationRing: restoreCalibrationRing(stats.calibrationRing),
// Intentionally NOT restored (#2129 triage): pendingFoldUsage is set at
// compress execution and consumed only as a log-suffix attribution by the
Expand Down
13 changes: 12 additions & 1 deletion src/server/relay.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import { type BiliMessage } from "acp-kernel/wire";
import { absorbToolName, applyAbsorbView } from "../absorb.js";
import { APIG_RESIGN_SCHEME, resignApig } from "../apig-resign.js";
import { noteSuccessfulForward } from "../cache-keepalive.js";
import { credentialFingerprint, generationParamFp, lastForwardedBody, noteClientAbort, noteForwardedBody, noteForwardedImageFacts, noteInboundMessages, noteOutboundContextEstimates, settleOverflowCalibration, settleUsageReport, withCacheCapture } from "../cache-ledger.js";
import { credentialFingerprint, generationParamFp, lastForwardedBody, noteCalibrationPair, noteClientAbort, noteForwardedBody, noteForwardedImageFacts, noteInboundMessages, noteOutboundContextEstimates, settleOverflowCalibration, settleUsageReport, withCacheCapture } from "../cache-ledger.js";
import { warnCacheCollapse } from "../cache-warn.js";
import { stampOutbound } from "../chain-checkpoint.js";
import { rewrapCommandcodeBody } from "../commandcode-wire.js";
Expand Down Expand Up @@ -1185,6 +1185,17 @@ const reply = prepared && !prepared.sidePassthrough ? createHandoffReply(prepare
imageTokens: est.imageTokens,
calibrated: scaledText !== est.textOverhead,
});
// #5952: the calibration pair for THIS send — the final wire text
// estimate (no image reserve) + the image reserve of the same body,
// so the settle that bills this body trains the text multiplier only
// from text-only evidence, even when a concurrent request overwrote
// the shared prepare slot in between.
noteCalibrationPair(prepared.session, {
estimate: est.textOverhead,
imageTokens: est.imageTokens,
origin: normalizeUpstreamOrigin(upstreamUrl),
model: typeof sentParsed?.model === "string" && sentParsed.model !== "" ? sentParsed.model : (prepared.model ?? prepared.google?.model),
});
// #2131: exact message count for seam forensics (sentParsed is the one
// shared parse above — Responses carries "input", Google native "contents").
const sentArr = sentParsed !== null ? (sentParsed.messages ?? sentParsed.input ?? sentParsed.contents) : null;
Expand Down
22 changes: 20 additions & 2 deletions src/session.ts
Original file line number Diff line number Diff line change
Expand Up @@ -588,11 +588,27 @@ export type Session = {
* Absent on factors published before this field existed → reads
* treat it as compatible and retire it through normal rollover. */
calibratedEstimateModel?: string;
/** #5952: provenance of the published calibratedEstimate —
* "text-only-v1" when every sample in calibrationRing came from a
* text-only final wire estimate (per-request capture pair); absent
* for factors trained on the legacy shared prepare slot, whose
* evidence may include image-billed usage. The read gate
* (currentCalibrationFactor) only applies a factor carrying this
* stamp. Persisted so a restart doesn't silently re-arm a stale
* mixed-modal multiplier; reset at native-compaction boundaries
* with the rest of the baseline stats. */
calibratedEstimateProvenance?: string;
/** #1933 F1 / #2117 B: evidence ring behind calibratedEstimate —
* the recent admitted raw samples for ONE origin+model (max 3).
* Persisted so a restart doesn't re-arm the warmup delay; reset at
* native-compaction boundaries with the rest of the baseline stats. */
calibrationRing?: { origin: string; model?: string; values: number[] };
* native-compaction boundaries with the rest of the baseline stats.
* #5952: provenances[i] is the provenance of values[i] —
* "text-only-v1" for a sample from a text-only final wire
* estimate, undefined for a legacy shared-slot sample. The
* published factor's provenance is "text-only-v1" only when every
* value in the window carries it; one legacy sample in the window
* keeps the factor inert until the window flushes it out. */
calibrationRing?: { origin: string; model?: string; values: number[]; provenances?: (string | undefined)[] };
/** #1933 F1: pending pairing input — local estimate of the LAST
* prepared outbound in BILLED caliber (estimateCoreMessages +
* system/tools overhead + image reserve, defaultCountTokens rate;
Expand Down Expand Up @@ -1811,6 +1827,8 @@ export function resetSessionCompression(session: Session): void {
delete session.stats.calibratedEstimateOrigin;
// #2117 B: same boundary — the factor's model provenance dies with it.
delete session.stats.calibratedEstimateModel;
// #5952: same boundary — the factor's text-only provenance dies with it.
delete session.stats.calibratedEstimateProvenance;
delete session.stats.calibrationRing;
delete session.stats.lastLocalTextEstimate;
delete session.stats.lastLocalTextEstimateOrigin;
Expand Down
Loading
Loading