@rol1n/memory-log 0.0.0-stage → 0.1.1

package/ledger/progress.ts

@@ -0,0 +1,181 @@
+import { estimateEntryTokens } from "../tokens.ts";
+import {
+  OM_OBSERVATIONS_DROPPED,
+  OM_OBSERVATIONS_RECORDED,
+  type Entry,
+  type MemoryCustomType,
+} from "./types.ts";
+
+const SOURCE_ENTRY_TYPES = new Set(["message", "custom_message", "branch_summary"]);
+
+export function isSourceEntry(entry: Entry): boolean {
+  return SOURCE_ENTRY_TYPES.has(entry.type);
+}
+
+/**
+ * A source entry is a valid chunk/compaction boundary only if it can legitimately START a
+ * chunk — i.e. it is not a tool-result message. Anchoring boundaries to non-tool-result entries
+ * keeps every tool call together with its result in the same chunk (and the same verbatim tail
+ * at compaction).
+ */
+export function isValidCutPoint(entry: Entry): boolean {
+  if (entry.type === "custom_message" || entry.type === "branch_summary") return true;
+  if (entry.type === "message") {
+    const role = (entry.message as { role?: string } | undefined)?.role;
+    return role === "user" || role === "assistant";
+  }
+  return false;
+}
+
+/** Id of the last source entry on the branch (the tip). Tombstone `coversUpToId` anchor. */
+export function lastSourceEntryId(entries: Entry[]): string | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (isSourceEntry(entries[i])) return entries[i].id;
+  }
+  return undefined;
+}
+
+export function entryIndexById(entries: Entry[]): Map<string, number> {
+  const idToIndex = new Map<string, number>();
+  for (let i = 0; i < entries.length; i++) idToIndex.set(entries[i].id, i);
+  return idToIndex;
+}
+
+export function entryIndexForId(entries: Entry[], entryId: string | undefined): number {
+  if (!entryId) return -1;
+  const idx = entryIndexById(entries).get(entryId);
+  return idx ?? -1;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isNonEmptyArray(value: unknown): value is unknown[] {
+  return Array.isArray(value) && value.length > 0;
+}
+
+function isValidCoverageEntry(entry: Entry, customType: MemoryCustomType): entry is Entry & { data: { coversUpToId: string } } {
+  if (entry.type !== "custom" || entry.customType !== customType) return false;
+  if (!isObject(entry.data) || typeof entry.data.coversUpToId !== "string") return false;
+
+  if (customType === OM_OBSERVATIONS_RECORDED) return isNonEmptyArray(entry.data.observations);
+  return isNonEmptyArray(entry.data.observationTimestamps);
+}
+
+export function latestCoverageIndex(entries: Entry[], customType: MemoryCustomType): number {
+  const idToIndex = entryIndexById(entries);
+  let latest = -1;
+
+  for (const entry of entries) {
+    if (!isValidCoverageEntry(entry, customType)) continue;
+    const coveredIndex = idToIndex.get(entry.data.coversUpToId);
+    if (coveredIndex === undefined) continue;
+    if (coveredIndex > latest) latest = coveredIndex;
+  }
+
+  return latest;
+}
+
+export function latestCoverageMarkerId(entries: Entry[], customType: MemoryCustomType): string | undefined {
+  const idToIndex = entryIndexById(entries);
+  let latestIndex = -1;
+  let latestMarkerId: string | undefined;
+
+  for (const entry of entries) {
+    if (!isValidCoverageEntry(entry, customType)) continue;
+    const coveredIndex = idToIndex.get(entry.data.coversUpToId);
+    if (coveredIndex === undefined) continue;
+    if (coveredIndex > latestIndex) {
+      latestIndex = coveredIndex;
+      latestMarkerId = entry.data.coversUpToId;
+    }
+  }
+
+  return latestMarkerId;
+}
+
+export function earlierCoverageMarkerId(
+  entries: Entry[],
+  firstId: string | undefined,
+  secondId: string | undefined,
+): string | undefined {
+  if (!firstId) return secondId;
+  if (!secondId) return firstId;
+
+  const idToIndex = entryIndexById(entries);
+  const firstIndex = idToIndex.get(firstId);
+  const secondIndex = idToIndex.get(secondId);
+  if (firstIndex === undefined) return secondIndex === undefined ? undefined : secondId;
+  if (secondIndex === undefined) return firstId;
+  return firstIndex <= secondIndex ? firstId : secondId;
+}
+
+export function rawTokensAfterIndex(entries: Entry[], index: number): number {
+  let total = 0;
+  for (let i = Math.max(0, index + 1); i < entries.length; i++) {
+    if (isSourceEntry(entries[i])) total += estimateEntryTokens(entries[i]);
+  }
+  return total;
+}
+
+export function rawTokensSinceCoverage(entries: Entry[], customType: MemoryCustomType): number {
+  return rawTokensAfterIndex(entries, latestCoverageIndex(entries, customType));
+}
+
+export function rawTokensSinceObservationCoverage(entries: Entry[]): number {
+  return rawTokensSinceCoverage(entries, OM_OBSERVATIONS_RECORDED);
+}
+
+export function rawTokensSinceDropCoverage(entries: Entry[]): number {
+  return rawTokensSinceCoverage(entries, OM_OBSERVATIONS_DROPPED);
+}
+
+export function findLastCompactionIndex(entries: Entry[]): number {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (entries[i].type === "compaction") return i;
+  }
+  return -1;
+}
+
+export function rawTokensSinceLastCompaction(entries: Entry[]): number {
+  const compactionIndex = findLastCompactionIndex(entries);
+  if (compactionIndex === -1) return rawTokensAfterIndex(entries, -1);
+
+  const firstKeptEntryId = entries[compactionIndex].firstKeptEntryId;
+  const firstKeptIndex = entryIndexForId(entries, firstKeptEntryId);
+
+  if (firstKeptIndex === -1) return rawTokensAfterIndex(entries, compactionIndex);
+  return rawTokensAfterIndex(entries, firstKeptIndex - 1);
+}
+
+export type SourceSlice = {
+  entries: Entry[];
+  /** Id of the last source entry in the slice → the chunk's `coversUpToId` watermark. */
+  coversUpToId: string | undefined;
+  tokens: number;
+};
+
+/**
+ * Select the next observation chunk: the source entries strictly after `afterEntryId`
+ * (the latest covered watermark), accumulated until adding the next entry would exceed
+ * `chunkTokens`.
+ */
+export function selectSourceSlice(entries: Entry[], afterEntryId: string | undefined, chunkTokens: number): SourceSlice {
+  const startIndex = afterEntryId ? entryIndexForId(entries, afterEntryId) : -1;
+  const slice: Entry[] = [];
+  let tokens = 0;
+  let coversUpToId: string | undefined;
+
+  for (let i = Math.max(0, startIndex + 1); i < entries.length; i++) {
+    const entry = entries[i];
+    if (!isSourceEntry(entry)) continue;
+    const entryTokens = estimateEntryTokens(entry);
+    if (slice.length > 0 && tokens + entryTokens > chunkTokens && isValidCutPoint(entry)) break;
+    slice.push(entry);
+    tokens += entryTokens;
+    coversUpToId = entry.id;
+  }
+
+  return { entries: slice, coversUpToId, tokens };
+}

package/ledger/projection.ts

@@ -0,0 +1,115 @@
+import {
+  OM_FOLDED,
+  isMemoryDetails,
+  isObservationsDroppedEntry,
+  isObservationsRecordedEntry,
+  type Entry,
+  type MemoryDetails,
+  type Observation,
+} from "./types.ts";
+
+export type Projection = {
+  observations: Observation[];
+};
+
+export type CompactionProjection = Projection & {
+  details: MemoryDetails;
+};
+
+type ProjectionBoundary =
+  | { kind: "entry"; entryId: string }
+  | { kind: "beforeEntry"; entryId: string }
+  | { kind: "tip" }
+  | { kind: "none" };
+
+function entryIndexById(entries: Entry[]): Map<string, number> {
+  const indexes = new Map<string, number>();
+  for (let i = 0; i < entries.length; i++) indexes.set(entries[i].id, i);
+  return indexes;
+}
+
+function boundaryIndex(entries: Entry[], indexes: Map<string, number>, boundary: ProjectionBoundary): number {
+  if (boundary.kind === "tip") return entries.length - 1;
+  if (boundary.kind === "none") return -1;
+  const idx = indexes.get(boundary.entryId);
+  if (idx === undefined) return -1;
+  return boundary.kind === "beforeEntry" ? idx - 1 : idx;
+}
+
+function coverageIndex(entry: Entry & { data: { coversUpToId: string } }, indexes: Map<string, number>): number {
+  return indexes.get(entry.data.coversUpToId) ?? -1;
+}
+
+function isCoveredAtOrBefore(
+  entry: Entry & { data: { coversUpToId: string } },
+  indexes: Map<string, number>,
+  boundary: number,
+): boolean {
+  const index = coverageIndex(entry, indexes);
+  return index >= 0 && boundary >= 0 && index <= boundary;
+}
+
+/**
+ * Fold active observations whose source coverage lies at-or-before `boundary`, in
+ * first-valid-record-wins order, with folded drops applied.
+ */
+function foldProjection(entries: Entry[], boundary: ProjectionBoundary): Projection {
+  const indexes = entryIndexById(entries);
+  const boundaryIdx = boundaryIndex(entries, indexes, boundary);
+  const observations: Observation[] = [];
+  const seen = new Set<string>();
+  const dropped = new Set<string>();
+
+  for (const entry of entries) {
+    if (isObservationsRecordedEntry(entry) && isCoveredAtOrBefore(entry, indexes, boundaryIdx)) {
+      for (const observation of entry.data.observations) {
+        if (seen.has(observation.timestamp)) continue;
+        seen.add(observation.timestamp);
+        observations.push(observation);
+      }
+      continue;
+    }
+    if (isObservationsDroppedEntry(entry) && isCoveredAtOrBefore(entry, indexes, boundaryIdx)) {
+      for (const timestamp of entry.data.observationTimestamps) dropped.add(timestamp);
+    }
+  }
+
+  return { observations: observations.filter((observation) => !dropped.has(observation.timestamp)) };
+}
+
+export function fullProjection(entries: Entry[], upToEntryId?: string): Projection {
+  return foldProjection(entries, upToEntryId ? { kind: "entry", entryId: upToEntryId } : { kind: "tip" });
+}
+
+function latestCompactionDetails(entries: Entry[]): MemoryDetails | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type !== "compaction") continue;
+    if (isMemoryDetails(entry.details)) return entry.details;
+  }
+  return undefined;
+}
+
+/** What a fresh session sees: the observations folded into the last compaction. */
+export function visibleProjection(entries: Entry[], upToEntryId?: string): Projection {
+  if (!upToEntryId) {
+    const details = latestCompactionDetails(entries);
+    return details ? { observations: [...details.observations] } : { observations: [] };
+  }
+  return fullProjection(entries, upToEntryId);
+}
+
+/**
+ * Build the deterministic compaction projection: active observations covered up to
+ * `firstKeptEntryId`, plus the `details` blob stamped into the compaction entry so a
+ * future visible projection can replay it.
+ */
+export function buildCompactionProjection(entries: Entry[], firstKeptEntryId: string): CompactionProjection {
+  const projection = foldProjection(entries, { kind: "beforeEntry", entryId: firstKeptEntryId });
+  const details: MemoryDetails = {
+    type: OM_FOLDED,
+    version: 1,
+    observations: projection.observations,
+  };
+  return { observations: projection.observations, details };
+}

package/ledger/render.ts

@@ -0,0 +1,38 @@
+import type { Observation } from "./types.ts";
+
+const CONTEXT_USAGE_INSTRUCTIONS = `These are condensed memories from earlier in this session.
+
+- Journey: a short, purely descriptive history of how this work reached its current state — for orientation only. It is not an instruction or a plan; do not read intent or next steps into it.
+- Observations: timestamped events from the conversation history, in chronological order.
+
+Treat these as past records. When entries conflict, the most recent observation reflects the latest known state. Work that prior observations describe as completed should not be redone unless the user explicitly asks to revisit it.`;
+
+/** A single observation line: "YYYY-MM-DDTHH:MM:SS  content". The timestamp is the id. */
+export function observationToLine(observation: Observation): string {
+  return `${observation.timestamp}  ${observation.content}`;
+}
+
+/** Sort observations chronologically by their timestamp-id (lexicographic == chronological). */
+export function sortObservations(observations: Observation[]): Observation[] {
+  return [...observations].sort((a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0));
+}
+
+/**
+ * Render the deterministic injection block:
+ *   1. Journey — the running descriptive project history (`.memory/JOURNEY.md`, read verbatim).
+ *   2. Memory map — durable topic files rendered from front-matter (`.memory/`).
+ *   3. Observations — the bounded short-term buffer, chronological and verbatim.
+ */
+export function renderSummary(journey: string | undefined, map: string | undefined, observations: Observation[]): string {
+  const sorted = sortObservations(observations);
+  const journeyText = journey?.trim();
+  if (!journeyText && !map && sorted.length === 0) return "";
+
+  const parts: string[] = [CONTEXT_USAGE_INSTRUCTIONS];
+  if (journeyText) parts.push(`## Journey\n${journeyText}`);
+  if (map && map.trim().length > 0) parts.push(map);
+  if (sorted.length > 0) {
+    parts.push(`## Observations\n${sorted.map(observationToLine).join("\n")}`);
+  }
+  return parts.join("\n\n");
+}

package/ledger/serialize.ts

@@ -0,0 +1,161 @@
+import type { Message, TextContent, ToolResultMessage } from "@earendil-works/pi-ai";
+
+function pad(n: number): string {
+  return n.toString().padStart(2, "0");
+}
+
+function fmtLocal(d: Date): string {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+function formatTimestamp(v: number | string | undefined): string {
+  if (v === undefined) return "????-??-?? ??:??";
+  const d = new Date(v);
+  return Number.isNaN(d.getTime()) ? "????-??-?? ??:??" : fmtLocal(d);
+}
+
+export function nowTimestamp(): string {
+  return fmtLocal(new Date());
+}
+
+export const MAX_RECORD_CONTENT_CHARS = 10_000;
+
+export function truncateRecordContent(content: string): string {
+  if (content.length <= MAX_RECORD_CONTENT_CHARS) return content;
+  const head = content.slice(0, MAX_RECORD_CONTENT_CHARS);
+  const dropped = content.length - MAX_RECORD_CONTENT_CHARS;
+  return `${head} … [truncated ${dropped} chars]`;
+}
+
+function textAndPlaceholders(content: unknown, options: { includeThinking?: boolean } = {}): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "[non-text content omitted]";
+
+  const parts: string[] = [];
+  for (const block of content as Array<Record<string, unknown>>) {
+    if (!block || typeof block !== "object") {
+      parts.push("[non-text content omitted]");
+      continue;
+    }
+    if (block.type === "text" && typeof block.text === "string") {
+      parts.push(block.text);
+      continue;
+    }
+    if (block.type === "thinking") {
+      if (options.includeThinking && typeof block.thinking === "string") {
+        parts.push(`[thinking: ${block.thinking}]`);
+        continue;
+      }
+      parts.push("[non-text content omitted]");
+      continue;
+    }
+    if (block.type === "toolCall" && typeof block.name === "string") {
+      parts.push(`[${block.name}(${JSON.stringify(block.arguments ?? {})})]`);
+      continue;
+    }
+    parts.push("[non-text content omitted]");
+  }
+  return parts.join("\n");
+}
+
+function textOnly(content: unknown): string {
+  if (content == null) return "";
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((b): b is TextContent => b?.type === "text" && typeof b.text === "string")
+    .map((b) => b.text)
+    .join("\n");
+}
+
+export function serializeConversation(messages: Message[]): string {
+  return messages
+    .map((msg): string | null => {
+      const time = formatTimestamp(msg.timestamp);
+      if (msg.role === "user") {
+        return `[User @ ${time}]: ${textOnly(msg.content)}`;
+      }
+      if (msg.role === "assistant") {
+        const body = textAndPlaceholders(msg.content, { includeThinking: true })
+          .split("\n")
+          .filter(Boolean)
+          .join("\n");
+        if (!body) return null;
+        return `[Assistant @ ${time}]: ${body}`;
+      }
+      return `[Tool result for ${(msg as ToolResultMessage).toolName} @ ${time}]: ${textOnly(msg.content)}`;
+    })
+    .filter((line): line is string => line !== null)
+    .join("\n\n");
+}
+
+export type RenderableEntry = {
+  type: string;
+  id?: string;
+  timestamp?: string;
+  message?: unknown;
+  customType?: string;
+  content?: unknown;
+  summary?: unknown;
+};
+
+function renderCustomMessage(entry: RenderableEntry): string {
+  const time = formatTimestamp(entry.timestamp);
+  const text =
+    typeof entry.content === "string"
+      ? entry.content
+      : Array.isArray(entry.content)
+        ? (entry.content as Array<{ type?: string; text?: string }>)
+            .filter((b) => b?.type === "text" && typeof b.text === "string")
+            .map((b) => b.text as string)
+            .join("\n")
+        : "";
+  const tag = entry.customType ? `Custom (${entry.customType})` : "Custom";
+  return `[${tag} @ ${time}]: ${text}`;
+}
+
+export function serializeBranchEntries(entries: RenderableEntry[]): string {
+  const blocks: string[] = [];
+  for (const entry of entries) {
+    if (entry.type === "message" && entry.message) {
+      const part = serializeConversation([entry.message as Message]);
+      if (part) blocks.push(part);
+      continue;
+    }
+    if (entry.type === "custom_message") {
+      blocks.push(renderCustomMessage(entry));
+      continue;
+    }
+    if (entry.type === "branch_summary" && typeof entry.summary === "string") {
+      const time = formatTimestamp(entry.timestamp);
+      blocks.push(`[Branch summary @ ${time}]: ${entry.summary}`);
+    }
+  }
+  return blocks.join("\n\n");
+}
+
+export type SourceAddressedSerialization = {
+  text: string;
+  sourceEntryIds: string[];
+};
+
+function isSourceRenderableEntry(entry: RenderableEntry): boolean {
+  return entry.type === "message" || entry.type === "custom_message" || entry.type === "branch_summary";
+}
+
+/**
+ * Serialize a slice of source entries into an observer prompt chunk, each block prefixed
+ * with its source entry id.
+ */
+export function serializeSourceAddressedBranchEntries(entries: RenderableEntry[]): SourceAddressedSerialization {
+  const blocks: string[] = [];
+  const sourceEntryIds: string[] = [];
+  for (const entry of entries) {
+    if (!entry.id || !isSourceRenderableEntry(entry)) continue;
+    const rendered = serializeBranchEntries([entry]);
+    if (!rendered.trim()) continue;
+    sourceEntryIds.push(entry.id);
+    blocks.push(`[Source entry id: ${entry.id}]\n${rendered}`);
+  }
+  return { text: blocks.join("\n\n"), sourceEntryIds };
+}

package/ledger/types.ts

@@ -0,0 +1,201 @@
+/**
+ * Ledger custom-type vocabulary for observational memory.
+ */
+
+/** Observer output committed by the orchestrator; the buffer tier. */
+export const OM_OBSERVATIONS_RECORDED = "om.observations.recorded";
+/** Promotion tombstones written by the orchestrator after a consolidator run (Phase B). */
+export const OM_OBSERVATIONS_DROPPED = "om.observations.dropped";
+/** Compaction details type stamped into the compaction entry's `details`. */
+export const OM_FOLDED = "om.folded";
+/** Per-session on/off gate state. When absent, defaultEnabled applies. */
+export const OM_ENABLED = "om.enabled";
+/**
+ * Per-worker cost record (one per finished worker run). The orchestrator appends these from
+ * pi's built-in `usage.cost.total`, reported back by the worker extension via the cost file.
+ * Summed across the WHOLE session (every branch), so spend never rolls back under /tree.
+ */
+export const OM_COST = "om.cost";
+/**
+ * Synthetic continuation message used to resume the agent loop after a mid-run compaction.
+ */
+export const OM_RESUME = "om.resume";
+
+export type Entry = {
+  type: string;
+  id: string;
+  timestamp?: string;
+  message?: unknown;
+  content?: unknown;
+  customType?: string;
+  summary?: unknown;
+  fromId?: string;
+  data?: unknown;
+  details?: unknown;
+  firstKeptEntryId?: string;
+};
+
+/**
+ * Minimal observation unit.
+ * - `timestamp`: the orchestrator-assigned precise, unique id-timestamp
+ *   ("YYYY-MM-DDTHH:MM:SS" with an optional ".NN" disambiguator). Doubles as the id.
+ * - `content`: single-line plain prose.
+ * - `tokenCount`: computed in code (never by the model).
+ */
+export type Observation = {
+  timestamp: string;
+  content: string;
+  tokenCount: number;
+};
+
+export type ObservationsRecordedEntryData = {
+  observations: Observation[];
+  coversUpToId: string;
+};
+
+export type ObservationsDroppedEntryData = {
+  observationTimestamps: string[];
+  coversUpToId: string;
+};
+
+export type CostEntryData = {
+  costUsd: number;
+  role: "observer" | "consolidator";
+  runId: string;
+};
+
+/** Stamped into the compaction entry's `details` so a future visible projection can read it back. */
+export type MemoryDetails = {
+  type: typeof OM_FOLDED;
+  version: 1;
+  observations: Observation[];
+};
+
+export type MemoryCustomType = typeof OM_OBSERVATIONS_RECORDED | typeof OM_OBSERVATIONS_DROPPED;
+
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+export function isNonEmptyStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.length > 0 && value.every(isNonEmptyString);
+}
+
+function isTokenCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object";
+}
+
+export function isObservation(value: unknown): value is Observation {
+  if (!isPlainRecord(value)) return false;
+  return (
+    isNonEmptyString(value.timestamp) &&
+    isNonEmptyString(value.content) &&
+    !/\r|\n/.test(value.content) &&
+    isTokenCount(value.tokenCount)
+  );
+}
+
+export function isObservationsRecordedData(value: unknown): value is ObservationsRecordedEntryData {
+  if (!isPlainRecord(value)) return false;
+  return (
+    Array.isArray(value.observations) &&
+    value.observations.length > 0 &&
+    value.observations.every(isObservation) &&
+    isNonEmptyString(value.coversUpToId)
+  );
+}
+
+export function isObservationsDroppedData(value: unknown): value is ObservationsDroppedEntryData {
+  if (!isPlainRecord(value)) return false;
+  return isNonEmptyStringArray(value.observationTimestamps) && isNonEmptyString(value.coversUpToId);
+}
+
+export function isMemoryDetails(value: unknown): value is MemoryDetails {
+  if (!isPlainRecord(value)) return false;
+  return (
+    value.type === OM_FOLDED &&
+    value.version === 1 &&
+    Array.isArray(value.observations) &&
+    value.observations.every(isObservation)
+  );
+}
+
+export function isCostData(value: unknown): value is CostEntryData {
+  if (!isPlainRecord(value)) return false;
+  return (
+    typeof value.costUsd === "number" &&
+    Number.isFinite(value.costUsd) &&
+    value.costUsd >= 0 &&
+    (value.role === "observer" || value.role === "consolidator") &&
+    isNonEmptyString(value.runId)
+  );
+}
+
+export function isObservationsRecordedEntry(
+  entry: Entry,
+): entry is Entry & { type: "custom"; customType: typeof OM_OBSERVATIONS_RECORDED; data: ObservationsRecordedEntryData } {
+  return (
+    entry.type === "custom" &&
+    entry.customType === OM_OBSERVATIONS_RECORDED &&
+    isObservationsRecordedData(entry.data)
+  );
+}
+
+export function isObservationsDroppedEntry(
+  entry: Entry,
+): entry is Entry & { type: "custom"; customType: typeof OM_OBSERVATIONS_DROPPED; data: ObservationsDroppedEntryData } {
+  return (
+    entry.type === "custom" &&
+    entry.customType === OM_OBSERVATIONS_DROPPED &&
+    isObservationsDroppedData(entry.data)
+  );
+}
+
+export function isCostEntry(
+  entry: Entry,
+): entry is Entry & { type: "custom"; customType: typeof OM_COST; data: CostEntryData } {
+  if (entry.type !== "custom" || entry.customType !== OM_COST) return false;
+  const data = entry.data as Record<string, unknown> | undefined;
+  return (
+    !!data &&
+    typeof data.costUsd === "number" &&
+    Number.isFinite(data.costUsd as number) &&
+    (data.costUsd as number) >= 0
+  );
+}
+
+/**
+ * Sum every `om.cost` entry across the WHOLE session. Callers MUST pass all entries
+ * (`getEntries()`), NOT a single branch (`getBranch()`).
+ */
+export function sumSessionCost(allEntries: Entry[]): { costUsd: number; runs: number } {
+  let costUsd = 0;
+  let runs = 0;
+  for (const entry of allEntries) {
+    if (isCostEntry(entry)) {
+      costUsd += (entry.data as CostEntryData).costUsd;
+      runs += 1;
+    }
+  }
+  return { costUsd, runs };
+}
+
+export function buildObservationsRecordedData(
+  observations: Observation[],
+  coversUpToId: string,
+): ObservationsRecordedEntryData | undefined {
+  if (observations.length === 0 || !isNonEmptyString(coversUpToId)) return undefined;
+  return { observations, coversUpToId };
+}
+
+export function buildObservationsDroppedData(
+  observationTimestamps: string[],
+  coversUpToId: string,
+): ObservationsDroppedEntryData | undefined {
+  if (observationTimestamps.length === 0 || !isNonEmptyString(coversUpToId)) return undefined;
+  return { observationTimestamps, coversUpToId };
+}