@danypops/jittor 0.16.2 → 0.17.0

package/src/observability/context-delta.ts

@@ -0,0 +1,309 @@
+import { createHmac } from "node:crypto";
+import { normalizeModelIdentity } from "./model-identity.ts";
+
+export const CONTEXT_SEGMENT_SOURCES = [
+	"base-prompt",
+	"tool-definitions",
+	"rules",
+	"skills",
+	"project-context",
+	"conversation-message",
+	"thinking",
+	"tool-call",
+	"tool-result",
+] as const;
+export type ContextSegmentSource = (typeof CONTEXT_SEGMENT_SOURCES)[number];
+
+export const CONTEXT_SEGMENT_STATES = ["active", "compacted", "inactive"] as const;
+export type ContextSegmentState = (typeof CONTEXT_SEGMENT_STATES)[number];
+
+export const CONTEXT_SNAPSHOT_MAX_SEGMENTS = 512;
+const OPAQUE_FINGERPRINT = /^[A-Za-z0-9_-]{32,64}$/;
+
+export interface ContextSnapshotSegment {
+	/** Keyed opaque logical identity. It must not contain an entry id, path, label, or content. */
+	id: string;
+	/** Keyed opaque fingerprint of the ephemeral segment value. */
+	fingerprint: string;
+	source: ContextSegmentSource;
+	tokens: number;
+	state: ContextSegmentState;
+	/** Position in the final provider request's stable-prefix sequence, or null for historical-only segments. */
+	requestPosition: number | null;
+}
+
+export interface ContextSnapshot {
+	version: 1;
+	snapshotId: string;
+	sessionId: string;
+	provider: string;
+	model: string;
+	capturedAt: number;
+	truncated: boolean;
+	segments: ContextSnapshotSegment[];
+}
+
+export type ContextSegmentLifecycle = "added" | "retained" | "changed" | "evicted" | "compacted" | "inactive";
+
+export interface ContextSegmentChange {
+	id: string;
+	source: ContextSegmentSource;
+	lifecycle: ContextSegmentLifecycle;
+	previousTokens: number;
+	currentTokens: number;
+	deltaTokens: number;
+	requestPosition: number | null;
+}
+
+export interface ContextSourceGrowth {
+	source: ContextSegmentSource;
+	deltaTokens: number;
+}
+
+export type ContextPrefixResetReason = "initial" | "session-changed" | "provider-changed" | "model-changed" | null;
+
+export interface ContextDelta {
+	previousSnapshotId: string | null;
+	currentSnapshotId: string;
+	capturedAt: number;
+	truncated: boolean;
+	stablePrefixTokens: number;
+	firstChangedSegment: Pick<ContextSnapshotSegment, "id" | "source" | "requestPosition"> | null;
+	resetReason: ContextPrefixResetReason;
+	changes: ContextSegmentChange[];
+	growthBySource: ContextSourceGrowth[];
+}
+
+const SNAPSHOT_FIELDS = new Set<keyof ContextSnapshot>([
+	"version",
+	"snapshotId",
+	"sessionId",
+	"provider",
+	"model",
+	"capturedAt",
+	"truncated",
+	"segments",
+]);
+const SEGMENT_FIELDS = new Set<keyof ContextSnapshotSegment>(["id", "fingerprint", "source", "tokens", "state", "requestPosition"]);
+
+function opaqueFingerprint(value: unknown, name: string): string {
+	if (typeof value !== "string" || !OPAQUE_FINGERPRINT.test(value)) throw new Error(`${name} fingerprint is invalid`);
+	return value;
+}
+
+function nonNegativeInteger(value: unknown, name: string): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`${name} is invalid`);
+	return value;
+}
+
+function validateSegment(value: unknown): ContextSnapshotSegment {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("context snapshot segment must be an object");
+	const input = value as Record<string, unknown>;
+	for (const key of Object.keys(input)) {
+		if (!SEGMENT_FIELDS.has(key as keyof ContextSnapshotSegment))
+			throw new Error(`context snapshot segment contains unsupported field: ${key}`);
+	}
+	if (!CONTEXT_SEGMENT_SOURCES.includes(input.source as ContextSegmentSource))
+		throw new Error("context snapshot segment source is invalid");
+	if (!CONTEXT_SEGMENT_STATES.includes(input.state as ContextSegmentState)) throw new Error("context snapshot segment state is invalid");
+	const requestPosition = input.requestPosition;
+	if (requestPosition !== null && (typeof requestPosition !== "number" || !Number.isSafeInteger(requestPosition) || requestPosition < 0))
+		throw new Error("context snapshot segment request position is invalid");
+	return {
+		id: opaqueFingerprint(input.id, "segment id"),
+		fingerprint: opaqueFingerprint(input.fingerprint, "segment"),
+		source: input.source as ContextSegmentSource,
+		tokens: nonNegativeInteger(input.tokens, "context snapshot segment tokens"),
+		state: input.state as ContextSegmentState,
+		requestPosition: requestPosition as number | null,
+	};
+}
+
+/** Strict, content-free ingress validation before a snapshot can be compared or persisted. */
+export function validateContextSnapshot(value: unknown): ContextSnapshot {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("context snapshot must be an object");
+	const input = value as Record<string, unknown>;
+	for (const key of Object.keys(input)) {
+		if (!SNAPSHOT_FIELDS.has(key as keyof ContextSnapshot)) throw new Error(`context snapshot contains unsupported field: ${key}`);
+	}
+	if (input.version !== 1) throw new Error("context snapshot version is unsupported");
+	if (!Array.isArray(input.segments)) throw new Error("context snapshot segments must be an array");
+	if (input.segments.length > CONTEXT_SNAPSHOT_MAX_SEGMENTS) throw new Error("context snapshot exceeds the segment limit");
+	const segments = input.segments.map(validateSegment);
+	const ids = new Set<string>();
+	const requestPositions = new Set<number>();
+	for (const segment of segments) {
+		if (ids.has(segment.id)) throw new Error("context snapshot contains a duplicate segment id");
+		ids.add(segment.id);
+		if (segment.requestPosition !== null) {
+			if (requestPositions.has(segment.requestPosition)) throw new Error("context snapshot contains a duplicate request position");
+			requestPositions.add(segment.requestPosition);
+			if (segment.state !== "active") throw new Error("historical context segment cannot have a request position");
+		}
+	}
+	if (typeof input.provider !== "string" || typeof input.model !== "string") throw new Error("context snapshot model identity is invalid");
+	const identity = normalizeModelIdentity(input.provider, input.model);
+	return {
+		version: 1,
+		snapshotId: opaqueFingerprint(input.snapshotId, "snapshot id"),
+		sessionId: opaqueFingerprint(input.sessionId, "session id"),
+		provider: identity.provider,
+		model: identity.model,
+		capturedAt: nonNegativeInteger(input.capturedAt, "context snapshot capture time"),
+		truncated:
+			input.truncated === false
+				? false
+				: input.truncated === true
+					? true
+					: (() => {
+							throw new Error("context snapshot truncated flag is invalid");
+						})(),
+		segments,
+	};
+}
+
+function resetReason(previous: ContextSnapshot | null, current: ContextSnapshot): ContextPrefixResetReason {
+	if (!previous) return "initial";
+	if (previous.sessionId !== current.sessionId) return "session-changed";
+	if (previous.provider !== current.provider) return "provider-changed";
+	if (previous.model !== current.model) return "model-changed";
+	return null;
+}
+
+function requestSegments(snapshot: ContextSnapshot): ContextSnapshotSegment[] {
+	return snapshot.segments
+		.filter((segment): segment is ContextSnapshotSegment & { requestPosition: number } => segment.requestPosition !== null)
+		.sort((left, right) => left.requestPosition - right.requestPosition);
+}
+
+function sameRequestSegment(left: ContextSnapshotSegment, right: ContextSnapshotSegment): boolean {
+	return (
+		left.id === right.id &&
+		left.fingerprint === right.fingerprint &&
+		left.source === right.source &&
+		left.tokens === right.tokens &&
+		left.state === right.state &&
+		left.requestPosition === right.requestPosition
+	);
+}
+
+function prefixEvidence(
+	previous: ContextSnapshot | null,
+	current: ContextSnapshot,
+	reset: ContextPrefixResetReason,
+): Pick<ContextDelta, "stablePrefixTokens" | "firstChangedSegment"> {
+	const previousRequest = previous ? requestSegments(previous) : [];
+	const currentRequest = requestSegments(current);
+	if (reset !== null) {
+		const first = currentRequest[0] ?? previousRequest[0];
+		return {
+			stablePrefixTokens: 0,
+			firstChangedSegment: first ? { id: first.id, source: first.source, requestPosition: first.requestPosition } : null,
+		};
+	}
+	let stablePrefixTokens = 0;
+	const limit = Math.max(previousRequest.length, currentRequest.length);
+	for (let index = 0; index < limit; index++) {
+		const before = previousRequest[index];
+		const after = currentRequest[index];
+		if (before && after && sameRequestSegment(before, after)) {
+			stablePrefixTokens += after.tokens;
+			continue;
+		}
+		const first = after ?? before;
+		return {
+			stablePrefixTokens,
+			firstChangedSegment: first ? { id: first.id, source: first.source, requestPosition: first.requestPosition } : null,
+		};
+	}
+	return { stablePrefixTokens, firstChangedSegment: null };
+}
+
+function lifecycle(previous: ContextSnapshotSegment | undefined, current: ContextSnapshotSegment): ContextSegmentLifecycle {
+	if (current.state === "compacted") return "compacted";
+	if (current.state === "inactive") return "inactive";
+	if (!previous) return "added";
+	return sameRequestSegment(previous, current) ||
+		(previous.id === current.id &&
+			previous.fingerprint === current.fingerprint &&
+			previous.source === current.source &&
+			previous.tokens === current.tokens &&
+			previous.state === current.state)
+		? "retained"
+		: "changed";
+}
+
+function sourceGrowth(previous: ContextSnapshot | null, current: ContextSnapshot): ContextSourceGrowth[] {
+	const before = new Map<ContextSegmentSource, number>();
+	const after = new Map<ContextSegmentSource, number>();
+	for (const segment of previous?.segments ?? []) before.set(segment.source, (before.get(segment.source) ?? 0) + segment.tokens);
+	for (const segment of current.segments) after.set(segment.source, (after.get(segment.source) ?? 0) + segment.tokens);
+	return CONTEXT_SEGMENT_SOURCES.filter((source) => before.has(source) || after.has(source)).map((source) => ({
+		source,
+		deltaTokens: (after.get(source) ?? 0) - (before.get(source) ?? 0),
+	}));
+}
+
+/**
+ * Correlates bounded keyed identities. Stable-prefix correlation is evidence of structural churn,
+ * not proof of a provider cache hit or miss.
+ */
+export function compareContextSnapshots(previousValue: ContextSnapshot | null, currentValue: ContextSnapshot): ContextDelta {
+	const previous = previousValue === null ? null : validateContextSnapshot(previousValue);
+	const current = validateContextSnapshot(currentValue);
+	const priorById = new Map((previous?.segments ?? []).map((segment) => [segment.id, segment]));
+	const changes: ContextSegmentChange[] = current.segments.map((segment) => {
+		const prior = priorById.get(segment.id);
+		priorById.delete(segment.id);
+		return {
+			id: segment.id,
+			source: segment.source,
+			lifecycle: lifecycle(prior, segment),
+			previousTokens: prior?.tokens ?? 0,
+			currentTokens: segment.tokens,
+			deltaTokens: segment.tokens - (prior?.tokens ?? 0),
+			requestPosition: segment.requestPosition,
+		};
+	});
+	for (const segment of previous?.segments ?? []) {
+		if (!priorById.has(segment.id)) continue;
+		changes.push({
+			id: segment.id,
+			source: segment.source,
+			lifecycle: "evicted",
+			previousTokens: segment.tokens,
+			currentTokens: 0,
+			deltaTokens: -segment.tokens,
+			requestPosition: null,
+		});
+	}
+	const reset = resetReason(previous, current);
+	return {
+		previousSnapshotId: previous?.snapshotId ?? null,
+		currentSnapshotId: current.snapshotId,
+		capturedAt: current.capturedAt,
+		truncated: current.truncated,
+		...prefixEvidence(previous, current, reset),
+		resetReason: reset,
+		changes,
+		growthBySource: sourceGrowth(previous, current),
+	};
+}
+
+export interface ContextFingerprinter {
+	fingerprint(value: string | Uint8Array): string;
+}
+
+/** HMAC keeps low-entropy/context labels resistant to offline reversal if snapshot rows are copied. */
+export class HmacContextFingerprinter implements ContextFingerprinter {
+	private readonly key: Uint8Array;
+
+	constructor(key: Uint8Array) {
+		if (key.byteLength < 32) throw new Error("context fingerprint key must contain at least 32 bytes");
+		this.key = key.slice();
+	}
+
+	fingerprint(value: string | Uint8Array): string {
+		return createHmac("sha256", this.key).update(value).digest().subarray(0, 24).toString("base64url");
+	}
+}

package/src/{domain → observability}/context-hub.ts

@@ -24,12 +24,22 @@ import {
 	CONTEXT_HUB_SEGMENT_LABEL_MAX_CHARACTERS,
 } from "../constants.ts";
 import type { MetricObservation } from "./metric.ts";
+import {
+	type RequestTokenReconciliation,
+	type TokenMeasurement,
+	validateRequestTokenReconciliation,
+	validateTokenMeasurement,
+} from "./token-measurement.ts";
 
 export type ContextConfidenceTier = (typeof CONTEXT_HUB_CONFIDENCE_TIERS)[number];
 
 export interface ContextSegmentItem {
 	label: string;
 	estimatedTokens: number;
+	/** Explicit provenance for this item's own token count. Omitted only by legacy/cooperative producers that have not migrated yet. */
+	measurement?: TokenMeasurement;
+	/** Provider aggregate for the request associated with this entry, kept separate from this item's own cost. */
+	requestTokenReconciliation?: RequestTokenReconciliation;
 	children?: ContextSegmentItem[];
 }
 
@@ -78,12 +88,19 @@ function validateSegmentItem(value: unknown, depth: number): ContextSegmentItem
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("context segment item must be an object");
 	const input = value as Record<string, unknown>;
 	for (const key of Object.keys(input)) {
-		if (key !== "label" && key !== "estimatedTokens" && key !== "children")
+		if (key !== "label" && key !== "estimatedTokens" && key !== "measurement" && key !== "requestTokenReconciliation" && key !== "children")
 			throw new Error(`context segment item contains unexpected field: ${key}`);
 	}
+	const estimatedTokens = boundedInteger(input.estimatedTokens, "item.estimatedTokens");
+	const measurement = input.measurement === undefined ? undefined : validateTokenMeasurement(input.measurement);
+	if (measurement && measurement.tokens !== estimatedTokens) throw new Error("item measurement tokens must match item.estimatedTokens");
+	const requestTokenReconciliation =
+		input.requestTokenReconciliation === undefined ? undefined : validateRequestTokenReconciliation(input.requestTokenReconciliation);
 	const item: ContextSegmentItem = {
 		label: nonEmptyString(input.label, "item.label", CONTEXT_HUB_ITEM_LABEL_MAX_CHARACTERS),
-		estimatedTokens: boundedInteger(input.estimatedTokens, "item.estimatedTokens"),
+		estimatedTokens,
+		...(measurement ? { measurement } : {}),
+		...(requestTokenReconciliation ? { requestTokenReconciliation } : {}),
 	};
 	if (input.children !== undefined) {
 		if (!Array.isArray(input.children)) throw new Error("item.children must be an array");

package/src/observability/context-snapshot-history.ts

@@ -0,0 +1,281 @@
+import {
+	CONTEXT_SEGMENT_SOURCES,
+	CONTEXT_SNAPSHOT_MAX_SEGMENTS,
+	type ContextDelta,
+	type ContextPrefixResetReason,
+	type ContextSegmentChange,
+	type ContextSnapshot,
+	type ContextSnapshotSegment,
+	type ContextSourceGrowth,
+	compareContextSnapshots,
+	validateContextSnapshot,
+} from "./context-delta.ts";
+import type { MetricObservation, StoredMetricObservation } from "./metric.ts";
+import type { MetricStore } from "./store.ts";
+
+const CONTEXT_SNAPSHOT_METRIC_SOURCE = "pi-context-snapshot";
+const CONTEXT_SNAPSHOT_HEADER_METRIC = "snapshot";
+const CONTEXT_SNAPSHOT_SEGMENT_METRIC = "segment";
+const CONTEXT_SNAPSHOT_CHANGE_METRIC = "change";
+const CONTEXT_SNAPSHOT_MAX_CHANGES = CONTEXT_SNAPSHOT_MAX_SEGMENTS * 2;
+
+interface SnapshotHeaderAttributes {
+	snapshotId: string;
+	previousSnapshotId: string | null;
+	provider: string;
+	model: string;
+	segmentCount: number;
+	changeCount: number;
+	truncated: boolean;
+	resetReason: ContextPrefixResetReason;
+	firstChangedSegment: ContextDelta["firstChangedSegment"];
+	growthBySource: ContextSourceGrowth[];
+}
+
+export interface ContextSnapshotHistory {
+	record(snapshot: ContextSnapshot): ContextDelta;
+	latestSnapshot(sessionId: string): ContextSnapshot | null;
+	latestDelta(sessionId: string): ContextDelta | null;
+}
+
+function recordValue(value: unknown, name: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${name} is invalid`);
+	return value as Record<string, unknown>;
+}
+
+function integer(value: unknown, name: string, maximum = Number.MAX_SAFE_INTEGER): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > maximum) throw new Error(`${name} is invalid`);
+	return value;
+}
+
+function nullableFingerprint(value: unknown, name: string): string | null {
+	if (value === null) return null;
+	if (typeof value !== "string" || !/^[A-Za-z0-9_-]{32,64}$/.test(value)) throw new Error(`${name} is invalid`);
+	return value;
+}
+
+function headerAttributes(row: StoredMetricObservation): SnapshotHeaderAttributes {
+	const input = row.attributes;
+	if (typeof input.provider !== "string" || typeof input.model !== "string") throw new Error("stored context snapshot identity is invalid");
+	const resetReason = input.resetReason;
+	if (resetReason !== null && !["initial", "session-changed", "provider-changed", "model-changed"].includes(resetReason as string))
+		throw new Error("stored context snapshot reset reason is invalid");
+	const growth = input.growthBySource;
+	if (!Array.isArray(growth) || growth.length > CONTEXT_SEGMENT_SOURCES.length) throw new Error("stored context source growth is invalid");
+	const growthBySource = growth.map((value) => {
+		const item = recordValue(value, "stored context source growth");
+		if (
+			!CONTEXT_SEGMENT_SOURCES.includes(item.source as ContextSourceGrowth["source"]) ||
+			typeof item.deltaTokens !== "number" ||
+			!Number.isSafeInteger(item.deltaTokens)
+		)
+			throw new Error("stored context source growth is invalid");
+		return { source: item.source as ContextSourceGrowth["source"], deltaTokens: item.deltaTokens };
+	});
+	let firstChangedSegment: ContextDelta["firstChangedSegment"] = null;
+	if (input.firstChangedSegment !== null) {
+		const first = recordValue(input.firstChangedSegment, "stored first changed context segment");
+		if (
+			typeof first.id !== "string" ||
+			!CONTEXT_SEGMENT_SOURCES.includes(first.source as ContextSnapshotSegment["source"]) ||
+			(first.requestPosition !== null && (typeof first.requestPosition !== "number" || !Number.isSafeInteger(first.requestPosition)))
+		)
+			throw new Error("stored first changed context segment is invalid");
+		firstChangedSegment = {
+			id: first.id,
+			source: first.source as ContextSnapshotSegment["source"],
+			requestPosition: first.requestPosition as number | null,
+		};
+	}
+	return {
+		snapshotId: nullableFingerprint(input.snapshotId, "stored snapshot id")!,
+		previousSnapshotId: nullableFingerprint(input.previousSnapshotId, "stored previous snapshot id"),
+		provider: input.provider,
+		model: input.model,
+		segmentCount: integer(input.segmentCount, "stored context segment count", CONTEXT_SNAPSHOT_MAX_SEGMENTS),
+		changeCount: integer(input.changeCount, "stored context change count", CONTEXT_SNAPSHOT_MAX_CHANGES),
+		truncated: input.truncated === true,
+		resetReason: resetReason as ContextPrefixResetReason,
+		firstChangedSegment,
+		growthBySource,
+	};
+}
+
+function segmentObservation(snapshot: ContextSnapshot, segment: ContextSnapshotSegment, index: number): MetricObservation {
+	return {
+		source: CONTEXT_SNAPSHOT_METRIC_SOURCE,
+		scope: snapshot.sessionId,
+		metric: CONTEXT_SNAPSHOT_SEGMENT_METRIC,
+		value: segment.tokens,
+		unit: "tokens",
+		observedAt: snapshot.capturedAt,
+		attributes: {
+			snapshotId: snapshot.snapshotId,
+			index,
+			id: segment.id,
+			fingerprint: segment.fingerprint,
+			source: segment.source,
+			state: segment.state,
+			requestPosition: segment.requestPosition,
+		},
+	};
+}
+
+function changeObservation(snapshot: ContextSnapshot, change: ContextSegmentChange, index: number): MetricObservation {
+	return {
+		source: CONTEXT_SNAPSHOT_METRIC_SOURCE,
+		scope: snapshot.sessionId,
+		metric: CONTEXT_SNAPSHOT_CHANGE_METRIC,
+		value: change.deltaTokens,
+		unit: "tokens",
+		observedAt: snapshot.capturedAt,
+		attributes: { snapshotId: snapshot.snapshotId, index, ...change },
+	};
+}
+
+function headerObservation(snapshot: ContextSnapshot, delta: ContextDelta): MetricObservation {
+	return {
+		source: CONTEXT_SNAPSHOT_METRIC_SOURCE,
+		scope: snapshot.sessionId,
+		metric: CONTEXT_SNAPSHOT_HEADER_METRIC,
+		value: delta.stablePrefixTokens,
+		unit: "tokens",
+		observedAt: snapshot.capturedAt,
+		attributes: {
+			snapshotId: snapshot.snapshotId,
+			previousSnapshotId: delta.previousSnapshotId,
+			provider: snapshot.provider,
+			model: snapshot.model,
+			segmentCount: snapshot.segments.length,
+			changeCount: delta.changes.length,
+			truncated: snapshot.truncated,
+			resetReason: delta.resetReason,
+			firstChangedSegment: delta.firstChangedSegment,
+			growthBySource: delta.growthBySource,
+		},
+	};
+}
+
+function segmentFromRow(row: StoredMetricObservation): { index: number; segment: ContextSnapshotSegment } {
+	const input = row.attributes;
+	const requestPosition = input.requestPosition;
+	if (row.value === null) throw new Error("stored context segment token count is invalid");
+	return {
+		index: integer(input.index, "stored context segment index", CONTEXT_SNAPSHOT_MAX_SEGMENTS - 1),
+		segment: {
+			id: String(input.id),
+			fingerprint: String(input.fingerprint),
+			source: input.source as ContextSnapshotSegment["source"],
+			tokens: integer(row.value, "stored context segment token count"),
+			state: input.state as ContextSnapshotSegment["state"],
+			requestPosition: requestPosition === null ? null : integer(requestPosition, "stored context request position"),
+		},
+	};
+}
+
+function changeFromRow(row: StoredMetricObservation): { index: number; change: ContextSegmentChange } {
+	const input = row.attributes;
+	if (!CONTEXT_SEGMENT_SOURCES.includes(input.source as ContextSegmentChange["source"]))
+		throw new Error("stored context change source is invalid");
+	if (!["added", "retained", "changed", "evicted", "compacted", "inactive"].includes(input.lifecycle as string))
+		throw new Error("stored context change lifecycle is invalid");
+	const deltaTokens = input.deltaTokens;
+	if (typeof deltaTokens !== "number" || !Number.isSafeInteger(deltaTokens)) throw new Error("stored context change delta is invalid");
+	return {
+		index: integer(input.index, "stored context change index", CONTEXT_SNAPSHOT_MAX_CHANGES - 1),
+		change: {
+			id: String(input.id),
+			source: input.source as ContextSegmentChange["source"],
+			lifecycle: input.lifecycle as ContextSegmentChange["lifecycle"],
+			previousTokens: integer(input.previousTokens, "stored previous context tokens"),
+			currentTokens: integer(input.currentTokens, "stored current context tokens"),
+			deltaTokens,
+			requestPosition: input.requestPosition === null ? null : integer(input.requestPosition, "stored context change position"),
+		},
+	};
+}
+
+/** Persists snapshots using MetricStore's real atomic batch and reloads them without retaining source content. */
+export class MetricContextSnapshotHistory implements ContextSnapshotHistory {
+	constructor(private readonly metrics: MetricStore) {}
+
+	record(value: ContextSnapshot): ContextDelta {
+		const snapshot = validateContextSnapshot(value);
+		const latest = this.latestSnapshot(snapshot.sessionId);
+		if (latest?.snapshotId === snapshot.snapshotId) {
+			const existing = this.latestDelta(snapshot.sessionId);
+			if (!existing) throw new Error("context snapshot exists without its delta");
+			return existing;
+		}
+		const delta = compareContextSnapshots(latest, snapshot);
+		this.metrics.recordBatch([
+			headerObservation(snapshot, delta),
+			...snapshot.segments.map((segment, index) => segmentObservation(snapshot, segment, index)),
+			...delta.changes.map((change, index) => changeObservation(snapshot, change, index)),
+		]);
+		return delta;
+	}
+
+	latestSnapshot(sessionId: string): ContextSnapshot | null {
+		const header = this.latestHeader(sessionId);
+		if (!header) return null;
+		const attributes = headerAttributes(header);
+		const segments = this.rowsForSnapshot(sessionId, CONTEXT_SNAPSHOT_SEGMENT_METRIC, attributes.snapshotId, attributes.segmentCount)
+			.map(segmentFromRow)
+			.sort((left, right) => left.index - right.index)
+			.map(({ segment }) => segment);
+		if (segments.length !== attributes.segmentCount) throw new Error("stored context snapshot is incomplete");
+		return validateContextSnapshot({
+			version: 1,
+			snapshotId: attributes.snapshotId,
+			sessionId,
+			provider: attributes.provider,
+			model: attributes.model,
+			capturedAt: header.observedAt,
+			truncated: attributes.truncated,
+			segments,
+		});
+	}
+
+	latestDelta(sessionId: string): ContextDelta | null {
+		const header = this.latestHeader(sessionId);
+		if (!header) return null;
+		const attributes = headerAttributes(header);
+		const changes = this.rowsForSnapshot(sessionId, CONTEXT_SNAPSHOT_CHANGE_METRIC, attributes.snapshotId, attributes.changeCount)
+			.map(changeFromRow)
+			.sort((left, right) => left.index - right.index)
+			.map(({ change }) => change);
+		if (changes.length !== attributes.changeCount) throw new Error("stored context delta is incomplete");
+		if (header.value === null) throw new Error("stored stable prefix is invalid");
+		return {
+			previousSnapshotId: attributes.previousSnapshotId,
+			currentSnapshotId: attributes.snapshotId,
+			capturedAt: header.observedAt,
+			truncated: attributes.truncated,
+			stablePrefixTokens: integer(header.value, "stored stable prefix"),
+			firstChangedSegment: attributes.firstChangedSegment,
+			resetReason: attributes.resetReason,
+			changes,
+			growthBySource: attributes.growthBySource,
+		};
+	}
+
+	private latestHeader(sessionId: string): StoredMetricObservation | null {
+		return (
+			this.metrics.query({
+				source: CONTEXT_SNAPSHOT_METRIC_SOURCE,
+				scope: sessionId,
+				metric: CONTEXT_SNAPSHOT_HEADER_METRIC,
+				order: "desc",
+				limit: 1,
+			})[0] ?? null
+		);
+	}
+
+	private rowsForSnapshot(sessionId: string, metric: string, snapshotId: string, expected: number): StoredMetricObservation[] {
+		if (expected === 0) return [];
+		return this.metrics
+			.query({ source: CONTEXT_SNAPSHOT_METRIC_SOURCE, scope: sessionId, metric, order: "desc", limit: expected })
+			.filter((row) => row.attributes.snapshotId === snapshotId);
+	}
+}