@iowarp/clio-coder 0.3.2 → 0.3.4

package/src/domains/context/working-set/replay/reference-graph.ts

@@ -0,0 +1,79 @@
+import type { SessionEntry } from "../../../session/entries.js";
+import type { PathIndex, PathObservation } from "../path-index.js";
+import type { Trace } from "./trace.js";
+
+export interface ReferenceEdge {
+	/** Ref key of the earlier tool_result. */
+	from: string;
+	toTurnIndex: number;
+	kind: "file_reread" | "file_discovery" | "file_rewrite";
+}
+
+export interface ReferenceGraph {
+	edges: ReadonlyArray<ReferenceEdge>;
+	/** Critical future references only: file_reread and file_discovery. */
+	futureTurnsOf: ReadonlyMap<string, ReadonlyArray<number>>;
+}
+
+const READ_CLASS_OPS = new Set<PathObservation["op"]>(["read", "grep", "find", "ls", "code_nav"]);
+const MUTATION_OPS = new Set<PathObservation["op"]>(["write", "edit"]);
+
+function isToolResult(entry: SessionEntry | undefined): boolean {
+	return entry?.kind === "message" && entry.role === "tool_result";
+}
+
+function isReadableObservation(observation: PathObservation): boolean {
+	return !observation.isError && observation.path.length > 0 && READ_CLASS_OPS.has(observation.op);
+}
+
+function edgeKey(edge: ReferenceEdge): string {
+	return `${edge.from}\u0000${edge.toTurnIndex}\u0000${edge.kind}`;
+}
+
+/**
+ * Label future path use without inspecting result prose. Rewrites are emitted
+ * for diagnosis but deliberately stay out of `futureTurnsOf`: a mutation makes
+ * the earlier read stale rather than critical to retain.
+ */
+export function buildReferenceGraph(trace: Trace, index: PathIndex): ReferenceGraph {
+	const entryById = new Map(trace.entries.map((entry) => [entry.turnId, entry]));
+	const edges: ReferenceEdge[] = [];
+	const seenEdges = new Set<string>();
+	const future = new Map<string, Set<number>>();
+
+	const add = (edge: ReferenceEdge): void => {
+		const key = edgeKey(edge);
+		if (seenEdges.has(key)) return;
+		seenEdges.add(key);
+		edges.push(edge);
+		if (edge.kind === "file_rewrite") return;
+		const turns = future.get(edge.from);
+		if (turns === undefined) future.set(edge.from, new Set([edge.toTurnIndex]));
+		else turns.add(edge.toTurnIndex);
+	};
+
+	for (const earlier of index.observations) {
+		if (!isToolResult(entryById.get(earlier.ref.entry)) || !isReadableObservation(earlier)) continue;
+		const surfaced = new Set(earlier.surfaced);
+		for (const later of index.observations) {
+			if (later.entryIndex <= earlier.entryIndex) continue;
+			if (isReadableObservation(later) && later.path === earlier.path) {
+				add({ from: earlier.ref.entry, toTurnIndex: later.turnIndex, kind: "file_reread" });
+			}
+			if (isReadableObservation(later) && surfaced.has(later.path)) {
+				add({ from: earlier.ref.entry, toTurnIndex: later.turnIndex, kind: "file_discovery" });
+			}
+			if (later.path === earlier.path && MUTATION_OPS.has(later.op)) {
+				add({ from: earlier.ref.entry, toTurnIndex: later.turnIndex, kind: "file_rewrite" });
+			}
+		}
+	}
+
+	const futureTurnsOf = new Map<string, ReadonlyArray<number>>();
+	for (const [ref, turns] of future)
+		futureTurnsOf.set(
+			ref,
+			[...turns].sort((a, b) => a - b),
+		);
+	return { edges, futureTurnsOf };
+}

package/src/domains/context/working-set/replay/report.ts

@@ -0,0 +1,139 @@
+import type { WorkingSetSettings } from "../../../../core/defaults.js";
+import type { ReplayLoadCascade } from "./load-clio.js";
+import type { ReplayMetricAggregate, ReplayMetrics } from "./metrics.js";
+
+export interface ReplayReportConfig {
+	policies: ReadonlyArray<string>;
+	budgets: ReadonlyArray<number>;
+	threshold: number;
+	target: number;
+	seed: number;
+	/** Synthetic corpus ids replayed, if any; ledgers from --sessions are "ledgers". */
+	corpus: ReadonlyArray<string>;
+	filter: "default" | "none";
+	settings: WorkingSetSettings;
+}
+
+export interface ReplayPolicyResult {
+	budgetTokens: number;
+	policyId: string;
+	metrics: ReplayMetricAggregate;
+}
+
+export interface ReplayReportInput {
+	config: ReplayReportConfig;
+	cascade: ReplayLoadCascade;
+	results: ReadonlyArray<ReplayPolicyResult>;
+	gitSha: string | null;
+	commandLine: ReadonlyArray<string>;
+}
+
+function metricObject(metrics: ReplayMetrics, turnsToFirstSummaryCount: number): Record<string, number | null> {
+	return {
+		traces: metrics.traces,
+		retention: metrics.retention,
+		retentionCovered: metrics.retentionCovered,
+		retentionAt10: metrics.retentionAt10,
+		evictionPrecision: metrics.evictionPrecision,
+		tokensEvicted: metrics.tokensEvicted,
+		recallTokens: metrics.recallTokens,
+		coldPrefixTokens: metrics.coldPrefixTokens,
+		evictionEvents: metrics.evictionEvents,
+		saturatedEvents: metrics.saturatedEvents,
+		turnsToFirstSummary: metrics.turnsToFirstSummary,
+		turnsToFirstSummaryCount,
+		summaries: metrics.summaries,
+	};
+}
+
+export function renderReplayJson(input: ReplayReportInput): string {
+	const filtered = Object.fromEntries(Object.entries(input.cascade.filtered).sort(([a], [b]) => a.localeCompare(b)));
+	const artifact = {
+		schema: "clio-context-replay-v2",
+		config: {
+			policies: [...input.config.policies],
+			budgets: [...input.config.budgets],
+			threshold: input.config.threshold,
+			target: input.config.target,
+			seed: input.config.seed,
+			corpus: [...input.config.corpus],
+			filter: input.config.filter,
+			settings: {
+				enabled: input.config.settings.enabled,
+				policy: input.config.settings.policy,
+				target: input.config.settings.target,
+				protectLastTurns: input.config.settings.protectLastTurns,
+				minEvictableTokens: input.config.settings.minEvictableTokens,
+			},
+		},
+		provenance: {
+			gitSha: input.gitSha,
+			commandLine: [...input.commandLine],
+		},
+		cascade: {
+			found: input.cascade.found,
+			unreadable: input.cascade.unreadable,
+			filtered,
+			kept: input.cascade.kept,
+		},
+		results: input.results.map((result) => ({
+			budgetTokens: result.budgetTokens,
+			policyId: result.policyId,
+			metrics: {
+				mean: metricObject(result.metrics.mean, result.metrics.turnsToFirstSummaryCount),
+				pooledRetention: result.metrics.pooledRetention,
+				pooledRetentionCovered: result.metrics.pooledRetentionCovered,
+				pooledRetentionAt10: result.metrics.pooledRetentionAt10,
+			},
+		})),
+	};
+	return `${JSON.stringify(artifact, null, "\t")}\n`;
+}
+
+function ratio(value: number): string {
+	return value.toFixed(3);
+}
+
+function quantity(value: number): string {
+	return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+
+function cascadeRows(cascade: ReplayLoadCascade): string[] {
+	return [
+		`| found | ${cascade.found} |`,
+		`| unreadable | ${cascade.unreadable} |`,
+		...Object.entries(cascade.filtered).map(([stage, count]) => `| ${stage} | ${count} |`),
+		`| kept | ${cascade.kept} |`,
+	];
+}
+
+export function renderReplayMarkdown(input: ReplayReportInput): string {
+	const lines = [
+		"# Clio working-set replay",
+		"",
+		"## Inclusion cascade",
+		"",
+		"| stage | traces |",
+		"| --- | ---: |",
+		...cascadeRows(input.cascade),
+	];
+	for (const budget of input.config.budgets) {
+		lines.push(
+			"",
+			`## Budget ${budget}`,
+			"",
+			"| policy | n | retention (mean) | retention (pooled) | retention covered (mean) | retention covered (pooled) | retention@10 (mean) | eviction precision (mean) | tokens evicted (mean) | recall tokens (mean) | cold prefix tokens (mean) | eviction events (mean) | saturated events | turns to first summary (mean) | summaries (mean) |",
+			"| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |",
+		);
+		for (const policy of input.config.policies) {
+			const result = input.results.find((entry) => entry.budgetTokens === budget && entry.policyId === policy);
+			if (result === undefined) continue;
+			const metrics = result.metrics.mean;
+			lines.push(
+				`| ${policy} | ${metrics.traces} | ${ratio(metrics.retention)} | ${ratio(result.metrics.pooledRetention)} | ${ratio(metrics.retentionCovered)} | ${ratio(result.metrics.pooledRetentionCovered)} | ${ratio(metrics.retentionAt10)} | ${ratio(metrics.evictionPrecision)} | ${quantity(metrics.tokensEvicted)} | ${quantity(metrics.recallTokens)} | ${quantity(metrics.coldPrefixTokens)} | ${quantity(metrics.evictionEvents)} | ${ratio(metrics.saturatedEvents)} | ${metrics.turnsToFirstSummary === null ? "—" : quantity(metrics.turnsToFirstSummary)} (n=${result.metrics.turnsToFirstSummaryCount}) | ${quantity(metrics.summaries)} |`,
+			);
+		}
+	}
+	lines.push("");
+	return lines.join("\n");
+}

package/src/domains/context/working-set/replay/runner.ts

@@ -0,0 +1,325 @@
+import type { WorkingSetSettings } from "../../../../core/defaults.js";
+import { findCutPoint } from "../../../session/compaction/cut-point.js";
+import { estimateTokens } from "../../../session/compaction/tokens.js";
+import type {
+	CompactionSummaryEntry,
+	ContextEvictionEntry,
+	EvictedItem,
+	SessionEntry,
+} from "../../../session/entries.js";
+import { EMPTY_WORKING_SET_VIEW, type PolicyInput, type WorkingSetPolicy, type WorkingSetView } from "../contract.js";
+import { buildEvictionFields, planEviction } from "../engine.js";
+import { foldWorkingSet } from "../fold.js";
+import { isTurnStart } from "../horizon.js";
+import { projectWorkingSet } from "../project.js";
+import { selectVisibleEntries } from "../visible.js";
+import type { ReplayCandidatePoolPolicy } from "./controls.js";
+import type { Trace } from "./trace.js";
+
+/**
+ * The summary stage, modeled. Live, when the projection is still over the
+ * threshold after an eviction, Clio summarizes: it cuts the history at
+ * `findCutPoint(entries, keepRecentTokens)` and replaces everything before
+ * the cut with one paraphrase. On iterative compaction, the cut search starts
+ * strictly after the previous `compactionSummary`; the retained suffix that
+ * replay still shows is canonical input to the new paraphrase, not new raw
+ * history to price a second time. A long trace replayed without that stage
+ * spends most of its length in a regime the product never enters, because
+ * operator text, call arguments, and markers accumulate past any budget and
+ * no policy can evict them. The model appends the same `compactionSummary`
+ * record the live path would, with a constant-size summary standing in for the
+ * paraphrase, and counts it, so a policy is judged by how rarely it forces the
+ * one lossy, token-spending stage.
+ */
+export interface ReplaySummaryModel {
+	/** Mirrors `compaction.keepRecentTokens`: the cut keeps at least this many recent tokens. */
+	keepRecentTokens: number;
+	/** Tokens the stand-in summary occupies. */
+	summaryTokens: number;
+}
+
+export interface ReplayConfig {
+	policyId: string;
+	budgetTokens: number;
+	threshold: number;
+	target: number;
+	settings: WorkingSetSettings;
+	seed: number;
+	/** Absent: summaries are counted as `turnsToFirstSummary` but never applied. */
+	summaries?: ReplaySummaryModel;
+}
+
+export interface ReplayEvictionEvent {
+	turnIndex: number;
+	items: ReadonlyArray<EvictedItem>;
+	tokensBefore: number;
+	tokensAfter: number;
+	/** True when this event exhausted the policy's usable candidate pool. */
+	saturated: boolean;
+	/**
+	 * Tokens of the projected working set from the earliest evicted position to
+	 * the end, after the event: what an exact-prefix cache (Anthropic, OpenAI,
+	 * vLLM) re-prefills on the next request because the bytes before it moved.
+	 */
+	coldPrefixTokens: number;
+}
+
+export interface ReplayTraceResult {
+	traceId: string;
+	policyId: string;
+	budgetTokens: number;
+	turnCount: number;
+	events: ReadonlyArray<ReplayEvictionEvent>;
+	/** Tool-result refs only; thinking-unit evictions are intentionally absent. */
+	evictedAtTurn: ReadonlyMap<string, number>;
+	turnsToFirstSummary: number | null;
+	/** Summary compactions applied under `config.summaries`. */
+	summaries: number;
+	/** Original entries plus synthetic append-only contextEviction and compactionSummary records. */
+	entries: ReadonlyArray<SessionEntry>;
+}
+
+function sumTokens(entries: ReadonlyArray<SessionEntry>): number {
+	let tokens = 0;
+	for (const entry of entries) tokens += estimateTokens(entry);
+	return tokens;
+}
+
+function hasCandidatePool(policy: WorkingSetPolicy): policy is ReplayCandidatePoolPolicy {
+	return "replayCandidateCount" in policy && typeof policy.replayCandidateCount === "function";
+}
+
+function latestCompactionIndex(entries: ReadonlyArray<SessionEntry>): number {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		if (entries[index]?.kind === "compactionSummary") return index;
+	}
+	return -1;
+}
+
+function eventSaturated(
+	policy: WorkingSetPolicy,
+	input: PolicyInput,
+	plan: { items: ReadonlyArray<EvictedItem>; tokensAfter: number },
+): boolean {
+	if (policy.id === "age-horizon") return true;
+	const targetTokens = input.pressure.target * input.pressure.contextWindow;
+	if (policy.id === "structural-v1") {
+		const thresholdTokens = input.pressure.threshold * input.pressure.contextWindow;
+		const usedAgeRung = plan.items.some((item) => item.reason === "age_horizon");
+		// Rungs 1-5 can legitimately stop between target and threshold. Saturation
+		// means rung 6 actually ran and exhausted its pool before reaching target.
+		return plan.tokensAfter > targetTokens && (plan.tokensAfter > thresholdTokens || usedAgeRung);
+	}
+	if (hasCandidatePool(policy)) return plan.items.length === policy.replayCandidateCount(input);
+	return plan.tokensAfter > targetTokens;
+}
+
+interface IncrementalProjection {
+	raw: SessionEntry[];
+	projected: SessionEntry[];
+	indexByTurnId: Map<string, number>;
+	tokens: number;
+}
+
+function rebuildProjection(
+	soFar: ReadonlyArray<SessionEntry>,
+	leaf: string | null,
+	view: WorkingSetView,
+): IncrementalProjection {
+	const raw = selectVisibleEntries(soFar, leaf ?? undefined);
+	const projected = projectWorkingSet(raw, view);
+	return {
+		raw,
+		projected,
+		indexByTurnId: new Map(raw.map((entry, index) => [entry.turnId, index])),
+		tokens: sumTokens(projected),
+	};
+}
+
+function projectAppendedEntry(entry: SessionEntry, state: IncrementalProjection, view: WorkingSetView): SessionEntry {
+	if (view.evictionEvents === 0) return entry;
+	const lastEventId = view.lastEvictionTurnId;
+	if (lastEventId !== null && state.indexByTurnId.has(lastEventId)) {
+		// The new entry follows the visible cutoff event, so it is unchanged.
+		return entry;
+	}
+	// The latest event is behind a compaction cut. projectWorkingSet deliberately
+	// treats an absent event as later than this slice, so new assistants inherit
+	// the same usage-invalidation stamp as the rest of the visible slice.
+	return projectWorkingSet([entry], view)[0] ?? entry;
+}
+
+function appendVisibleEntry(entry: SessionEntry, state: IncrementalProjection, view: WorkingSetView): void {
+	const projected = projectAppendedEntry(entry, state, view);
+	state.indexByTurnId.set(entry.turnId, state.raw.length);
+	state.raw.push(entry);
+	state.projected.push(projected);
+	state.tokens += estimateTokens(projected);
+}
+
+function applyEvictionProjection(
+	state: IncrementalProjection,
+	synthetic: ContextEvictionEntry,
+	view: WorkingSetView,
+	items: ReadonlyArray<EvictedItem>,
+): void {
+	const affected = new Set<number>();
+	for (const item of items) {
+		const index = state.indexByTurnId.get(item.ref.entry);
+		if (index !== undefined) affected.add(index);
+	}
+	// The new cutoff invalidates usage on every assistant before it. Scanning
+	// assistants once per applied event is linear in events, never in turns.
+	for (let index = 0; index < state.raw.length - 1; index += 1) {
+		const entry = state.raw[index];
+		if (entry?.kind === "message" && entry.role === "assistant") affected.add(index);
+	}
+	for (const index of affected) {
+		const source = state.raw[index];
+		const before = state.projected[index];
+		if (source === undefined || before === undefined) continue;
+		const after = projectWorkingSet([source, synthetic], view)[0] ?? source;
+		state.projected[index] = after;
+		state.tokens += estimateTokens(after) - estimateTokens(before);
+	}
+}
+
+function coldPrefixTokens(state: IncrementalProjection, items: ReadonlyArray<EvictedItem>): number {
+	let cut = state.projected.length;
+	for (const item of items) {
+		const index = state.indexByTurnId.get(item.ref.entry);
+		if (index !== undefined && index < cut) cut = index;
+	}
+	let tokens = 0;
+	for (let index = cut; index < state.projected.length; index += 1) {
+		const entry = state.projected[index];
+		if (entry !== undefined) tokens += estimateTokens(entry);
+	}
+	return tokens;
+}
+
+/** Live plan/fold/project code driven at deterministic ledger turn boundaries. */
+export function replayTrace(trace: Trace, policy: WorkingSetPolicy, config: ReplayConfig): ReplayTraceResult {
+	const soFar: SessionEntry[] = [];
+	const events: ReplayEvictionEvent[] = [];
+	const evictedAtTurn = new Map<string, number>();
+	const toolResults = new Set(
+		trace.entries
+			.filter((entry) => entry.kind === "message" && entry.role === "tool_result")
+			.map((entry) => entry.turnId),
+	);
+	let evictionSequence = 0;
+	let summaries = 0;
+	let turnIndex = 0;
+	let turnsToFirstSummary: number | null = null;
+	let lastMessageTurnId: string | null = null;
+	let view: WorkingSetView = EMPTY_WORKING_SET_VIEW;
+	let visible: IncrementalProjection = { raw: [], projected: [], indexByTurnId: new Map(), tokens: 0 };
+	const pressureLimit = config.threshold * config.budgetTokens;
+
+	for (const entry of trace.entries) {
+		if (isTurnStart(entry)) {
+			turnIndex += 1;
+			const leaf = lastMessageTurnId;
+			const tokens = visible.tokens;
+			if (tokens > pressureLimit) {
+				const input: PolicyInput = {
+					entries: visible.raw,
+					view,
+					cwd: trace.cwd,
+					settings: config.settings,
+					pressure: {
+						tokens,
+						contextWindow: config.budgetTokens,
+						threshold: config.threshold,
+						target: config.target,
+					},
+					estimateTokens,
+				};
+				const plan = planEviction(policy, input);
+				if (plan !== null) {
+					const saturated = eventSaturated(policy, input, plan);
+					evictionSequence += 1;
+					const previous = soFar[soFar.length - 1];
+					const synthetic: ContextEvictionEntry = {
+						...buildEvictionFields(plan, {
+							trigger: "pressure",
+							pressureBefore: tokens / config.budgetTokens,
+							snapshotIdBefore: null,
+						}),
+						turnId: `replay-evict-${evictionSequence}`,
+						parentTurnId: leaf,
+						timestamp: previous?.timestamp ?? entry.timestamp,
+					};
+					soFar.push(synthetic);
+					appendVisibleEntry(synthetic, visible, view);
+					view = foldWorkingSet(soFar, leaf ?? undefined);
+					applyEvictionProjection(visible, synthetic, view, plan.items);
+					events.push({
+						turnIndex,
+						items: plan.items,
+						tokensBefore: plan.tokensBefore,
+						tokensAfter: plan.tokensAfter,
+						saturated,
+						coldPrefixTokens: coldPrefixTokens(visible, plan.items),
+					});
+					for (const item of plan.items) {
+						if (toolResults.has(item.ref.entry) && !evictedAtTurn.has(item.ref.entry)) {
+							evictedAtTurn.set(item.ref.entry, turnIndex);
+						}
+					}
+				}
+				if (visible.tokens > pressureLimit) {
+					if (turnsToFirstSummary === null) turnsToFirstSummary = turnIndex;
+					const previousCompactionIndex = latestCompactionIndex(soFar);
+					const boundaryStart = previousCompactionIndex + 1;
+					const cut =
+						config.summaries === undefined
+							? boundaryStart
+							: findCutPoint(soFar, config.summaries.keepRecentTokens, { startIndex: boundaryStart }).firstKeptEntryIndex;
+					// A cut at the iterative boundary has no new history or turn prefix,
+					// which is the live "nothing to compact" case.
+					if (config.summaries !== undefined && cut > boundaryStart) {
+						summaries += 1;
+						const visibleBefore = new Set(visible.raw.map((candidate) => candidate.turnId));
+						const previous = soFar[soFar.length - 1];
+						const firstKeptTurnId = soFar[cut]?.turnId ?? "";
+						const synthetic: CompactionSummaryEntry = {
+							kind: "compactionSummary",
+							turnId: `replay-summary-${summaries}`,
+							parentTurnId: firstKeptTurnId || null,
+							timestamp: previous?.timestamp ?? entry.timestamp,
+							summary: "#".repeat(config.summaries.summaryTokens * 4),
+							tokensBefore: visible.tokens,
+							firstKeptTurnId,
+						};
+						soFar.push(synthetic);
+						visible = rebuildProjection(soFar, lastMessageTurnId, view);
+						const visibleAfter = new Set(visible.raw.map((candidate) => candidate.turnId));
+						for (const removed of visibleBefore) {
+							if (toolResults.has(removed) && !visibleAfter.has(removed) && !evictedAtTurn.has(removed)) {
+								evictedAtTurn.set(removed, turnIndex);
+							}
+						}
+					}
+				}
+			}
+		}
+		soFar.push(entry);
+		if (entry.kind === "compactionSummary") visible = rebuildProjection(soFar, lastMessageTurnId, view);
+		else appendVisibleEntry(entry, visible, view);
+		if (entry.kind === "message") lastMessageTurnId = entry.turnId;
+	}
+
+	return {
+		traceId: trace.id,
+		policyId: config.policyId,
+		budgetTokens: config.budgetTokens,
+		turnCount: trace.turnCount,
+		events,
+		evictedAtTurn,
+		turnsToFirstSummary,
+		summaries,
+		entries: soFar,
+	};
+}