@matthewfl/pi-contemplator 0.0.1

package/src/agents/contemplator/prompts.ts

@@ -0,0 +1,212 @@
+/** Build the contemplator prompt as one readable template with review-only blocks. */
+export function buildContemplatorSystemPrompt(
+  reviewerEnabled: boolean,
+): string {
+  return `You are the background contemplator supporting a primary agent. You are the System 2 thinker: slower, more deliberative, and focused on the larger shape of the problem while the primary agent handles the immediate work.
+
+Neither you nor the primary agent should be assumed to know the correct solution. You are jointly exploring a problem space from different perspectives. The primary agent interacts with the actual environment and carries out the work. You maintain a longer-term view of the reasoning, evidence, assumptions, alternatives, unresolved questions${reviewerEnabled ? ", and recurring structural patterns" : ""} that emerge over time.
+
+You receive incremental observations and reflections produced by other agent loops. Some memories summarize user messages. Pay extra attention to memories about the user’s intent, priorities, constraints, corrections, and desired outcome.
+
+You see only the memory ledger, not the primary agent’s live activity. Your understanding may be incomplete or slightly stale. Do not infer inactivity, failure, or lack of progress from missing recent results. A result may simply not have reached memory yet.
+
+${reviewerEnabled ? `Each memory has an identifier. Cite relevant memory identifiers in every probe or review request so the primary agent or reviewer can recover the supporting context.` : `Each memory has an identifier. Cite relevant memory identifiers in every probe so the primary agent can recover the context behind your question.`}
+
+Maintain an evolving understanding of:
+
+- what the user is ultimately trying to accomplish;
+- what has actually been observed so far;
+- the primary agent’s apparent direction;
+- assumptions on which the current direction depends;
+- important details that remain unknown or unconfirmed;
+- relevant alternatives that remain open;
+- connections, contradictions, and recurring patterns across memories;
+- ways the problem could be framed or decomposed differently${reviewerEnabled ?
+`;\n- whether repeated local work may indicate a structural problem in the workflow or software.` : `.`}
+
+Your central responsibility is to identify gaps in the current thinking.
+
+A reasoning gap may include:
+
+- depending on a detail that has not been established;
+- treating one possible explanation as though alternatives have been ruled out;
+- moving from an observation to a conclusion without a clear connection;
+- relying on an assumption whose failure would undermine the current direction;
+- overlooking an important part of the user’s request;
+- exploring one region of the solution space while neglecting a meaningfully different possibility;
+- accepting an idea without obtaining evidence that distinguishes it from competing ideas when that distinction matters;
+- failing to connect relevant information from separate memories;
+- continuing while depending on an uncertainty that later decisions require to be resolved.
+
+Do not treat the absence of a recent test result, tool result, or implementation update as a reasoning gap. A gap exists when the recorded reasoning depends on missing knowledge, not merely when the ledger lacks the latest execution details.
+
+Do not encourage speculation merely because several possibilities can be imagined. When the user’s direction is clear and action is cheap, safe, and reversible, direct progress may be more informative than further hypothesis formation. Distinguish uncertainty that must be resolved before proceeding from uncertainty that can be resolved naturally by doing the work.
+
+Your other high-value responsibility is reality-checking. Compare recent claims, interpretations, and assumptions with earlier recorded evidence. When a recent claim conflicts with an earlier observation, reflection, user-intent memory, or previously supported conclusion, make the contradiction visible and cite the memories on both sides.
+
+Also look for opportunities to help the primary agent:
+
+- remain aligned with the user’s actual direction;
+- distinguish observations from interpretations;
+- expose an assumption that should not yet be treated as settled;
+- consider a relevant alternative that has not received meaningful attention;
+- identify what evidence would distinguish between competing explanations when the distinction affects the work;
+- break the problem into smaller questions that can be explored independently;
+- find a more revealing or efficient way to explore the problem;
+- recognize a clear, unproductive loop;
+- reconsider a direction weakened by specific evidence${reviewerEnabled ?
+`;\n- recognize when repeated local work indicates a deeper workflow or software-design issue.` : `.`}
+
+Prefer asking one probing question over prescribing a solution. Do not assume that you know the answer and are guiding the primary agent toward it. Ask questions that help both agents discover what is missing, what remains possible, and what evidence or reframing would meaningfully improve the work.
+
+A useful probe may ask:
+
+- What assumption is this direction depending on?
+- Which relevant possibility has not yet been ruled out?
+- What observation would distinguish the current explanation from an alternative?
+- Is a conclusion stronger than the evidence recorded for it?
+- Is there a smaller question that would clarify the larger problem?
+- Are several attempts failing because they share the same hidden premise?
+- Has an important user constraint disappeared from the current framing?
+- Is continued reasoning producing new information, or could a direct interaction resolve the uncertainty more reliably?
+
+Questions should be grounded in the actual memories rather than generic problem-solving advice.
+
+You have access to search_memories for finding older ${reviewerEnabled ? `observations, reflections, and durable review results` : `observations and reflections`} on the current branch. Use it when the updates provided do not contain enough context, searching with distinctive terms rather than broad questions. Results include memory identifiers that you can cite in a probe${reviewerEnabled ? ` or review request` : ``}.
+
+You also have recall for recovering exact source context behind a specific memory identifier. Use it when a result is important but compressed.
+
+${reviewerEnabled ?
+`Specific recorded evidence that contradicts or materially weakens the current approach should produce a probe unless the issue is better handled by a deeper structural review. A concrete reasoning gap that the primary agent appears to depend upon should also produce a probe unless it reveals a recurring structural problem deserving review.` :
+`Specific recorded evidence that contradicts or materially weakens the current approach should produce a probe. A concrete reasoning gap that the primary agent appears to depend upon should also produce a probe.`}
+
+Pay particular attention to unproductive loops. A loop may be present when multiple memories show the primary agent:
+
+- returning to the same obstacle through different superficial approaches;
+- avoiding a difficult uncertainty by introducing increasingly fragile shortcuts;
+- abandoning an idea because evaluating it appears difficult, then spending more effort on alternatives that fail for related reasons;
+- changing approaches without gaining information that distinguishes between likely explanations;
+- repeatedly addressing consequences without reconsidering the assumption or framing that produces them${reviewerEnabled ?
+`;\n- repeatedly reconstructing the same information or operation without preserving a reusable result.` : `.`}
+
+Do not infer a loop from a single failure, silence, elapsed time, token count, or missing recent results. A loop must be supported by a clear pattern across multiple memories. Activity measurements may support the diagnosis, but they are not proof by themselves.
+
+You may probe a previously raised theme again when new memories show that the primary agent remains caught in an unproductive pattern. Do not merely repeat the earlier question. Use the accumulated evidence to ask about the larger assumption, uncertainty, decomposition, feedback process, or missing reusable structure keeping the loop in place.
+
+${
+  reviewerEnabled
+    ? `You have two forms of intervention.
+
+Use send_probe when one concise, memory-grounded question could materially improve the primary agent’s next reasoning round by exposing:
+
+- a contradiction;
+- a consequential reasoning gap;
+- drift from user intent;
+- an overlooked possibility;
+- an unproductive loop;
+- or a reason to stop speculating and obtain a direct result.
+
+Use request_review when multiple memories suggest a recurring structural problem that deserves independent investigation and, if supported, a durable conceptual proposal.
+
+Choose scope "workflow" when the suspected structural problem concerns how the primary agent performs the work. Examples include:
+
+- repeated reconstruction of the same information;
+- excessive reasoning about something that could be determined directly;
+- repeated manual searches, traces, transformations, or correlations;
+- an unnecessarily slow or low-information feedback loop;
+- repeated one-off scripts that should become a reusable capability;
+- failure to preserve a useful result or representation;
+- a process that is unreliable, token-intensive, difficult to reproduce, or difficult to review.
+
+Choose scope "software" when the suspected structural problem concerns the software being produced. Examples include:
+
+- repeated special cases;
+- duplicated concepts or behavior;
+- several fixes involving the same missing invariant;
+- unclear responsibility boundaries;
+- unsuitable state or data representations;
+- recurring workarounds;
+- local fixes that may indicate a missing abstraction or structural redesign.
+
+A review request should identify:
+
+- the memories revealing the pattern;
+- the suspected structural concern;
+- what the reviewer should determine;
+- relevant user constraints or uncertainties.
+
+Do not design the solution in the review request. State the concern as a possibility. The reviewer must independently recall and search memories, examine supporting and contrary evidence, and decide whether a proposal is justified.
+
+Do not request a review based only on a single inconvenience, one failed attempt, silence, elapsed time, token count, or generic best practice. The request should be grounded in a recurring pattern or an especially consequential structural issue.
+
+Before requesting a review, search for an existing review result or proposal that may already address the concern. When one exists, prefer citing it in a probe. Request another review only when new memories reveal a material limitation, a substantially different problem, or a need to revise or extend the earlier design.`
+    : ``
+}
+
+Do not:
+
+- behave as though you already know the correct solution;
+- ask leading questions that smuggle in an unsupported conclusion;
+- judge the primary agent’s pacing from silence or delayed memory;
+- declare the work complete, correct, mature, or successful;
+- remind the primary agent to perform routine tasks;
+- manage implementation step by step;
+- focus on tests, commands, files, syntax, programming language, or other low-level details unless they reveal a broader reasoning gap, strategic pattern, or bottleneck;
+- repeat memories as a status summary;
+- offer encouragement, praise, or generic advice;
+- invent details absent from the memories;
+- send several questions or competing suggestions at once;
+- send a question that could have been written without seeing the relevant memories${reviewerEnabled ?
+`;\n- request a structural review merely because a design improvement is theoretically possible that is irrelevant to the task at hand.` : `.`}
+
+When one high-signal question could materially improve the exploration of the problem, call send_probe with one concise, natural-language question.
+
+A good probe should:
+
+- cite the relevant memory identifiers;
+- identify the concrete gap, contradiction, pattern, or overlooked possibility;
+- ask one focused question;
+- help clarify what is known, what is assumed, or what should be explored;
+- remain useful even if the primary agent has progressed since the memories were recorded.
+
+${
+  reviewerEnabled
+    ? `When a recurring structural pattern deserves deeper independent analysis, call request_review instead.
+
+A good review request should:
+
+- select exactly one scope;
+- cite the memories showing the pattern;
+- describe the suspected issue without assuming the diagnosis is correct;
+- explain what the reviewer should investigate;
+- preserve relevant user intent and constraints;
+- leave the conceptual design to the reviewer.`
+    : ``
+}
+
+${reviewerEnabled ?
+`Your interventions are asynchronous. Use no more than one intervention per update: either send_probe, request_review, or neither.` :
+`Your probes are delivered asynchronously. Send no more than one probe per update.`}
+
+Prioritize:
+
+1. Gaps between what the current reasoning depends upon and what has actually been established.
+2. Contradictions between recent claims and earlier evidence.
+3. Misalignment with recorded user intent.
+4. Relevant alternatives or parts of the problem receiving insufficient consideration.
+5. Clear unproductive loops supported by multiple memories.
+6. Connections that reveal a better framing, decomposition, or way to reduce uncertainty.
+${
+  reviewerEnabled
+    ? `7. Recurring workflow problems that may deserve a durable workflow review.
+8. Recurring software-design symptoms that may deserve a durable software review.`
+    : ``
+}
+
+If no specific, grounded, materially useful intervention exists, do not call an intervention tool.`
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+/** Full prompt retained for callers and tests that enable structural reviews. */
+export const CONTEMPLATOR_SYSTEM = buildContemplatorSystemPrompt(true);

package/src/agents/dropper/agent.ts

@@ -0,0 +1,291 @@
+import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@earendil-works/pi-agent-core";
+import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { Type } from "@earendil-works/pi-ai";
+import { streamSimple } from "@earendil-works/pi-ai/compat";
+import type { Static } from "typebox";
+import { debugLog } from "../../debug-log.js";
+import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
+import { logAgentStreamError } from "../stream-errors.js";
+import { reflectionToSummaryLine, type Observation, type Reflection } from "../../session-ledger/index.js";
+import { DROPPER_SYSTEM } from "./prompts.js";
+import {
+	REFLECTION_COVERAGE_DROP_RANK,
+	coverageTierForObservation,
+	reflectionCoverageMap,
+	summarizeCoverageByRelevance,
+	summarizeCoverageByRelevanceForIds,
+	observationToDropperLine,
+} from "./coverage.js";
+import { observationPoolMetrics } from "./pool.js";
+import type { LlmUsageInput } from "../../runtime.js";
+export {
+	maxDropCountForPool,
+	observationPoolFullness,
+	observationPoolMetrics,
+} from "./pool.js";
+export type { ObservationPoolMetrics } from "./pool.js";
+export {
+	REFLECTION_COVERAGE_TIERS,
+	coverageTierForObservation,
+	emptyCoverageSummaryByRelevance,
+	observationToDropperLine,
+	reflectionCoverageMap,
+	reflectionCoverageTierForCount,
+	reflectionSupportCounts,
+	summarizeCoverageByRelevance,
+	summarizeCoverageByRelevanceForIds,
+	summarizeCoverageTransitionsByRelevance,
+} from "./coverage.js";
+export type { CoverageSummaryByRelevance, CoverageTransitionSummaryByRelevance, ReflectionCoverageTier } from "./coverage.js";
+
+interface RunDropperArgs {
+	model: Model<any>;
+	apiKey: string;
+	headers?: Record<string, string>;
+	reflections: Reflection[];
+	observations: Observation[];
+	targetTokens: number;
+	signal?: AbortSignal;
+	agentLoop?: typeof agentLoop;
+	maxTurns?: number;
+	thinkingLevel?: ModelThinkingLevel;
+	recordUsage?: (usage: LlmUsageInput) => void;
+}
+
+const RELEVANCE_DROP_RANK: Record<Observation["relevance"], number> = {
+	low: 0,
+	medium: 1,
+	high: 2,
+	critical: 3,
+};
+
+const DropObservationsSchema = Type.Object({
+	ids: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+	reason: Type.Optional(Type.String()),
+});
+
+type DropObservationsArgs = Static<typeof DropObservationsSchema>;
+
+function joinOrEmpty(items: string[]): string {
+	return items.length ? items.join("\n") : "(none yet)";
+}
+
+function relevanceCounts(observations: readonly Observation[]): Record<Observation["relevance"], number> {
+	return observations.reduce<Record<Observation["relevance"], number>>((counts, observation) => {
+		counts[observation.relevance]++;
+		return counts;
+	}, { low: 0, medium: 0, high: 0, critical: 0 });
+}
+
+export function normalizeDropObservationIds(
+	ids: readonly string[] | undefined,
+	observations: readonly Observation[],
+): string[] | undefined {
+	if (!ids || ids.length === 0) return undefined;
+	const allowed = new Map(observations.map((observation) => [observation.id, observation]));
+	const result: string[] = [];
+	const seen = new Set<string>();
+	for (const id of ids) {
+		const observation = allowed.get(id);
+		if (!observation) continue;
+		if (seen.has(id)) continue;
+		seen.add(id);
+		result.push(id);
+	}
+	return result.length > 0 ? result : undefined;
+}
+
+function timestampRank(timestamp: string): number {
+	const parsed = Date.parse(timestamp);
+	return Number.isFinite(parsed) ? parsed : Number.POSITIVE_INFINITY;
+}
+
+export function selectDropCandidates(
+	ids: readonly string[],
+	observations: readonly Observation[],
+	maxDrops: number,
+	reflections: readonly Reflection[] = [],
+): string[] {
+	if (maxDrops <= 0 || ids.length === 0) return [];
+
+	const byId = new Map(observations.map((observation) => [observation.id, observation]));
+	const coverageById = reflectionCoverageMap(observations, reflections);
+	const firstProposalIndex = new Map<string, number>();
+	for (let i = 0; i < ids.length; i++) {
+		const id = ids[i];
+		if (!firstProposalIndex.has(id)) firstProposalIndex.set(id, i);
+	}
+
+	return Array.from(firstProposalIndex.entries())
+		.map(([id, index]) => ({ id, index, observation: byId.get(id) }))
+		.filter((candidate): candidate is { id: string; index: number; observation: Observation } =>
+			candidate.observation !== undefined
+		)
+		.sort((a, b) => {
+			const coverageDelta = REFLECTION_COVERAGE_DROP_RANK[coverageTierForObservation(a.observation, coverageById)]
+				- REFLECTION_COVERAGE_DROP_RANK[coverageTierForObservation(b.observation, coverageById)];
+			const relevanceDelta = RELEVANCE_DROP_RANK[a.observation.relevance] - RELEVANCE_DROP_RANK[b.observation.relevance];
+			const ageDelta = timestampRank(a.observation.timestamp) - timestampRank(b.observation.timestamp);
+			return coverageDelta || relevanceDelta || ageDelta || a.index - b.index;
+		})
+		.slice(0, maxDrops)
+		.map((candidate) => candidate.id);
+}
+
+export async function runDropper(args: RunDropperArgs): Promise<string[] | undefined> {
+	const { model, apiKey, headers, reflections, observations, targetTokens, signal } = args;
+	if (observations.length === 0) return undefined;
+
+	const metrics = observationPoolMetrics(observations, targetTokens);
+	const { observationTokens, fullness, tokensOverTarget, maxDropsAllowed } = metrics;
+	const coverageById = reflectionCoverageMap(observations, reflections);
+	const coverageSummaryByRelevance = summarizeCoverageByRelevance(observations, coverageById);
+	debugLog("dropper.agent_start", {
+		activeObservationCount: observations.length,
+		reflectionCount: reflections.length,
+		observationTokens,
+		targetTokens,
+		tokensOverTarget,
+		fullness,
+		maxDropsAllowed,
+		relevanceCounts: relevanceCounts(observations),
+		coverageSummaryByRelevance,
+	});
+	if (maxDropsAllowed <= 0) {
+		debugLog("dropper.result", {
+			reason: "not_over_target",
+			toolCallCount: 0,
+			rawRequestedIdsCount: 0,
+			acceptedCandidateCount: 0,
+			selectedDropsCount: 0,
+			selectedDropTokens: 0,
+			selectedCoverageSummaryByRelevance: summarizeCoverageByRelevanceForIds([], observations, coverageById),
+			maxDropsAllowed,
+		});
+		return undefined;
+	}
+
+	const proposedDropIds: string[] = [];
+	const proposed = new Set<string>();
+	const allowed = new Map(observations.map((observation) => [observation.id, observation]));
+	let toolCallCount = 0;
+	let rawRequestedIdsCount = 0;
+	let missingIdsCount = 0;
+	let criticalCandidateIdsCount = 0;
+	let duplicateInRequestCount = 0;
+	let duplicateInRunCount = 0;
+
+	const dropObservations: AgentTool<typeof DropObservationsSchema> = {
+		name: "drop_observations",
+		label: "Drop observations",
+		description: "Propose active observation ids that are safe to remove from compacted memory.",
+		parameters: DropObservationsSchema,
+		execute: async (_id, params: DropObservationsArgs) => {
+			toolCallCount++;
+			rawRequestedIdsCount += params.ids.length;
+			const seenInRequest = new Set<string>();
+			let added = 0;
+			let requestMissingIds = 0;
+			let requestCriticalCandidateIds = 0;
+			let requestDuplicateIds = 0;
+			let requestDuplicateInRunIds = 0;
+			for (const id of params.ids) {
+				const observation = allowed.get(id);
+				if (!observation) {
+					missingIdsCount++;
+					requestMissingIds++;
+					continue;
+				}
+				if (seenInRequest.has(id)) {
+					duplicateInRequestCount++;
+					requestDuplicateIds++;
+					continue;
+				}
+				seenInRequest.add(id);
+				if (proposed.has(id)) {
+					duplicateInRunCount++;
+					requestDuplicateInRunIds++;
+					continue;
+				}
+				proposed.add(id);
+				proposedDropIds.push(id);
+				if (observation.relevance === "critical") {
+					criticalCandidateIdsCount++;
+					requestCriticalCandidateIds++;
+				}
+				added++;
+			}
+			debugLog("dropper.tool_call", {
+				toolCallCount,
+				rawRequestedIdsCount: params.ids.length,
+				acceptedIdsCount: added,
+				missingIdsCount: requestMissingIds,
+				criticalCandidateIdsCount: requestCriticalCandidateIds,
+				duplicateInRequestCount: requestDuplicateIds,
+				duplicateInRunCount: requestDuplicateInRunIds,
+				totalCandidates: proposedDropIds.length,
+				maxDropsAllowed,
+			});
+			return {
+				content: [{ type: "text", text: `Queued ${added} drop candidate${added === 1 ? "" : "s"}. Candidates this run: ${proposedDropIds.length}. Maximum drops allowed: ${maxDropsAllowed}.` }],
+				details: { added, totalCandidates: proposedDropIds.length, maxDropsAllowed },
+			};
+		},
+	};
+
+	const fullnessPercent = Math.round(fullness * 100);
+	const userText = `CURRENT REFLECTIONS:\n${joinOrEmpty(reflections.map(reflectionToSummaryLine))}\n\nCURRENT OBSERVATIONS:\n${joinOrEmpty(observations.map((observation) => observationToDropperLine(observation, coverageTierForObservation(observation, coverageById))))}\n\nActive observation pool: ~${observationTokens.toLocaleString()} tokens; target: ~${targetTokens.toLocaleString()} tokens; fullness against target: ~${fullnessPercent.toLocaleString()}%; over target by ~${tokensOverTarget.toLocaleString()} tokens.\nMaximum drops allowed this run: ${maxDropsAllowed.toLocaleString()} observation${maxDropsAllowed === 1 ? "" : "s"}. This maximum is sized to move the active pool toward the target if every proposed drop is clearly safe.\nThis maximum is a hard upper bound, not a target. Drop fewer or none if fewer observations are clearly safe.`;
+	const prompts: Message[] = [{ role: "user", content: [{ type: "text", text: userText }], timestamp: Date.now() }];
+	const context: AgentContext = { systemPrompt: DROPPER_SYSTEM, messages: [], tools: [dropObservations as AgentTool<any>] };
+	const reasoning = (model as { reasoning?: unknown }).reasoning;
+	const thinkingLevel = args.thinkingLevel ?? "low";
+	const effectiveMaxTurns = args.maxTurns && args.maxTurns > 0 ? args.maxTurns : undefined;
+	let turnCount = 0;
+	const config: AgentLoopConfig = {
+		model,
+		apiKey,
+		headers,
+		maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
+		convertToLlm: (msgs) => msgs as Message[],
+		toolExecution: "sequential",
+		...(reasoning && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
+		...(effectiveMaxTurns !== undefined ? { shouldStopAfterTurn: () => ++turnCount >= effectiveMaxTurns } : {}),
+	};
+
+	const loop = args.agentLoop ?? agentLoop;
+	const stream = loop(prompts, context, config, signal, streamSimple);
+	for await (const event of stream) {
+		// Tool execution collects candidate ids.
+		logAgentStreamError("dropper", event);
+	}
+	const result = await stream.result();
+	if (args.recordUsage) {
+		for (const message of result) {
+			if (message.role === "assistant" && message.usage) args.recordUsage(message.usage);
+		}
+	}
+	const droppedIds = selectDropCandidates(proposedDropIds, observations, maxDropsAllowed, reflections);
+	const reason = droppedIds.length > 0
+		? "selected_nonempty"
+		: toolCallCount === 0
+			? "no_tool_call"
+			: proposedDropIds.length === 0
+				? "all_filtered"
+				: "selected_empty";
+	const selectedDropTokens = droppedIds.reduce((sum, id) => sum + (allowed.get(id)?.tokenCount ?? 0), 0);
+	debugLog("dropper.result", {
+		reason,
+		toolCallCount,
+		rawRequestedIdsCount,
+		missingIdsCount,
+		criticalCandidateIdsCount,
+		duplicateInRequestCount,
+		duplicateInRunCount,
+		acceptedCandidateCount: proposedDropIds.length,
+		selectedDropsCount: droppedIds.length,
+		selectedDropTokens,
+		selectedCoverageSummaryByRelevance: summarizeCoverageByRelevanceForIds(droppedIds, observations, coverageById),
+		maxDropsAllowed,
+	});
+	return droppedIds.length > 0 ? droppedIds : undefined;
+}

package/src/agents/dropper/coverage.ts

@@ -0,0 +1,128 @@
+import type { Observation, Reflection } from "../../session-ledger/index.js";
+
+export const REFLECTION_COVERAGE_TIERS = ["none", "partial", "strong"] as const;
+export type ReflectionCoverageTier = typeof REFLECTION_COVERAGE_TIERS[number];
+
+type Relevance = Observation["relevance"];
+
+type CoverageBucket = Record<ReflectionCoverageTier, { count: number; tokens: number }>;
+export type CoverageSummaryByRelevance = Record<Relevance, CoverageBucket>;
+export type CoverageTransitionSummaryByRelevance = Record<Relevance, Record<string, { count: number; tokens: number }>>;
+
+export const REFLECTION_COVERAGE_DROP_RANK: Record<ReflectionCoverageTier, number> = {
+	strong: 0,
+	partial: 1,
+	none: 2,
+};
+
+export function reflectionSupportCounts(reflections: readonly Reflection[]): Map<string, number> {
+	const counts = new Map<string, number>();
+	for (const reflection of reflections) {
+		const uniqueIds = new Set(reflection.supportingObservationIds);
+		for (const id of uniqueIds) counts.set(id, (counts.get(id) ?? 0) + 1);
+	}
+	return counts;
+}
+
+export function reflectionCoverageTierForCount(count: number): ReflectionCoverageTier {
+	if (count <= 0) return "none";
+	if (count === 1) return "partial";
+	return "strong";
+}
+
+export function reflectionCoverageMap(
+	observations: readonly Observation[],
+	reflections: readonly Reflection[],
+): Map<string, ReflectionCoverageTier> {
+	const counts = reflectionSupportCounts(reflections);
+	return new Map(observations.map((observation) => [
+		observation.id,
+		reflectionCoverageTierForCount(counts.get(observation.id) ?? 0),
+	]));
+}
+
+function emptyCoverageBucket(): CoverageBucket {
+	return {
+		none: { count: 0, tokens: 0 },
+		partial: { count: 0, tokens: 0 },
+		strong: { count: 0, tokens: 0 },
+	};
+}
+
+export function emptyCoverageSummaryByRelevance(): CoverageSummaryByRelevance {
+	return {
+		low: emptyCoverageBucket(),
+		medium: emptyCoverageBucket(),
+		high: emptyCoverageBucket(),
+		critical: emptyCoverageBucket(),
+	};
+}
+
+export function summarizeCoverageByRelevance(
+	observations: readonly Observation[],
+	coverageById: ReadonlyMap<string, ReflectionCoverageTier>,
+): CoverageSummaryByRelevance {
+	const summary = emptyCoverageSummaryByRelevance();
+	for (const observation of observations) {
+		const tier = coverageById.get(observation.id) ?? "none";
+		const bucket = summary[observation.relevance][tier];
+		bucket.count++;
+		bucket.tokens += observation.tokenCount;
+	}
+	return summary;
+}
+
+export function summarizeCoverageByRelevanceForIds(
+	ids: readonly string[],
+	observations: readonly Observation[],
+	coverageById: ReadonlyMap<string, ReflectionCoverageTier>,
+): CoverageSummaryByRelevance {
+	const byId = new Map(observations.map((observation) => [observation.id, observation]));
+	const selected = ids.flatMap((id) => {
+		const observation = byId.get(id);
+		return observation ? [observation] : [];
+	});
+	return summarizeCoverageByRelevance(selected, coverageById);
+}
+
+export function emptyCoverageTransitionSummaryByRelevance(): CoverageTransitionSummaryByRelevance {
+	return {
+		low: {},
+		medium: {},
+		high: {},
+		critical: {},
+	};
+}
+
+export function summarizeCoverageTransitionsByRelevance(
+	observations: readonly Observation[],
+	beforeCoverageById: ReadonlyMap<string, ReflectionCoverageTier>,
+	afterCoverageById: ReadonlyMap<string, ReflectionCoverageTier>,
+): CoverageTransitionSummaryByRelevance {
+	const summary = emptyCoverageTransitionSummaryByRelevance();
+	for (const observation of observations) {
+		const before = beforeCoverageById.get(observation.id) ?? "none";
+		const after = afterCoverageById.get(observation.id) ?? "none";
+		if (before === after) continue;
+		const key = `${before}->${after}`;
+		const bucket = summary[observation.relevance][key] ?? { count: 0, tokens: 0 };
+		bucket.count++;
+		bucket.tokens += observation.tokenCount;
+		summary[observation.relevance][key] = bucket;
+	}
+	return summary;
+}
+
+export function observationToDropperLine(
+	observation: Observation,
+	coverage: ReflectionCoverageTier,
+): string {
+	return `[${observation.id}] ${observation.timestamp} [${observation.relevance}] [coverage: ${coverage}] ${observation.content}`;
+}
+
+export function coverageTierForObservation(
+	observation: Observation,
+	coverageById: ReadonlyMap<string, ReflectionCoverageTier>,
+): ReflectionCoverageTier {
+	return coverageById.get(observation.id) ?? "none";
+}