@rol1n/memory-log 0.0.0-stage → 0.1.0

package/extensions/memory-log/index.ts

@@ -0,0 +1,149 @@
+/**
+ * memory-log — Observational Memory Log (Orchestrator).
+ *
+ * Tiered asynchronous subprocess observational memory system:
+ * - Observers: Background concurrent distillation of conversation chunks into timestamped atomic facts;
+ * - Ledger: Persists with branches to the current session;
+ * - Compaction: Model-free deterministic context reconstruction (Journey, Memory Map, short-term buffer);
+ * - Consolidator: Auto-archives older observations to durable topic files under .memory/<sessionId>/ and JOURNEY.md.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { handleCompactCommand, registerCompactCommand } from "./commands/compact.ts";
+import { handleConsolidateCommand, registerConsolidateCommand } from "./commands/consolidate.ts";
+import { handleStatusCommand, registerStatusCommand } from "./commands/status.ts";
+import { registerCompactionHook } from "./hooks/compaction-hook.ts";
+import { registerCompactionTrigger } from "./hooks/compaction-trigger.ts";
+import { registerConsolidatorTrigger } from "./hooks/consolidator-trigger.ts";
+import { registerObserverTrigger } from "./hooks/observer-trigger.ts";
+import { OM_ENABLED, type Entry } from "./ledger/index.ts";
+import { ensureSessionMemory } from "./memory/session.ts";
+import { Runtime } from "./runtime.ts";
+
+function readGateFromLedger(branch: Entry[], defaultEnabled: boolean): boolean {
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i];
+    if (entry.type === "custom" && entry.customType === OM_ENABLED) {
+      return (entry.data as { enabled?: boolean } | undefined)?.enabled ?? defaultEnabled;
+    }
+  }
+  return defaultEnabled;
+}
+
+export default function observationalMemory(pi: ExtensionAPI): void {
+  const runtime = new Runtime();
+
+  function attachIfEnabled(ctx: any): void {
+    if (runtime.enabled && ctx.mode === "tui" && ctx.hasUI && ctx.ui) {
+      runtime.status.attach(ctx.ui);
+    } else {
+      runtime.status.detach();
+    }
+  }
+
+  pi.on("session_start", (_event: unknown, ctx: any) => {
+    runtime.ensureConfig(ctx.cwd);
+    runtime.dispatchedCoversUpToId = undefined;
+    const branch = ctx.sessionManager.getBranch() as Entry[];
+    runtime.enabled = readGateFromLedger(branch, runtime.config.defaultEnabled);
+    if (runtime.enabled) runtime.memoryRoot = ensureSessionMemory(ctx);
+    attachIfEnabled(ctx);
+    runtime.refreshFooterGauges(branch, ctx.getContextUsage?.()?.tokens ?? null);
+    runtime.refreshCost(ctx.sessionManager.getEntries() as Entry[]);
+  });
+
+  pi.on("session_shutdown", () => {
+    runtime.status.detach();
+    runtime.abortAllWorkers();
+  });
+
+  const setGate = (next: boolean, ctx: ExtensionContext) => {
+    if (next === runtime.enabled) {
+      if (ctx.hasUI) ctx.ui.notify(`memory-log is already ${next ? "enabled" : "disabled"}`, "info");
+      return;
+    }
+    runtime.enabled = next;
+    pi.appendEntry(OM_ENABLED, { enabled: next });
+    if (next) {
+      runtime.memoryRoot = ensureSessionMemory(ctx as any);
+      attachIfEnabled(ctx);
+      runtime.refreshFooterGauges(
+        (ctx as any).sessionManager.getBranch() as Entry[],
+        (ctx as any).getContextUsage?.()?.tokens ?? null,
+      );
+      runtime.refreshCost((ctx as any).sessionManager.getEntries() as Entry[]);
+    } else {
+      runtime.abortAllWorkers();
+      runtime.status.detach();
+    }
+    if (ctx.hasUI) ctx.ui.notify(`memory-log is now ${next ? "enabled" : "disabled"}`, "info");
+  };
+
+  const getCompletions = (prefix: string): AutocompleteItem[] | null => {
+    const candidates: AutocompleteItem[] = [
+      { value: "status", label: "status", description: "View memory log system status and timeline" },
+      { value: "on", label: "on", description: "Enable memory log for current session" },
+      { value: "off", label: "off", description: "Disable memory log for current session" },
+      { value: "compact", label: "compact", description: "Run memory compaction immediately (ignore context threshold)" },
+      { value: "consolidate", label: "consolidate", description: "Archive short-term observations to durable topic files immediately" },
+    ];
+    const trimmed = prefix.trimStart();
+    const filtered = candidates.filter((item) => item.value.startsWith(trimmed));
+    return filtered.length > 0 ? filtered : null;
+  };
+
+  const commandHandler = async (args: string, ctx: ExtensionContext) => {
+    const action = (args.trim().split(/\s+/)[0] || "").toLowerCase();
+
+    if (action === "on") {
+      setGate(true, ctx);
+      return;
+    }
+
+    if (action === "off") {
+      setGate(false, ctx);
+      return;
+    }
+
+    if (action === "compact") {
+      await handleCompactCommand(args, ctx, runtime);
+      return;
+    }
+
+    if (action === "consolidate") {
+      await handleConsolidateCommand(args, ctx, runtime);
+      return;
+    }
+
+    if (action === "status" || action === "timeline" || !action) {
+      if (!action && !runtime.enabled) {
+        setGate(true, ctx);
+        return;
+      }
+      await handleStatusCommand(args, ctx, runtime);
+      return;
+    }
+
+    // Toggle gate if unknown action
+    setGate(!runtime.enabled, ctx);
+  };
+
+  // Primary command: /mem-log [status|on|off|compact|consolidate]
+  pi.registerCommand("mem-log", {
+    description: "Manage observational memory log system (/mem-log [status|on|off|compact|consolidate])",
+    getArgumentCompletions: getCompletions,
+    handler: commandHandler,
+  });
+
+  // Triggers + hooks
+  registerObserverTrigger(pi, runtime);
+  registerConsolidatorTrigger(pi, runtime);
+  registerCompactionTrigger(pi, runtime);
+  registerCompactionHook(pi, runtime);
+
+  // Subcommands (:status, :compact, :consolidate)
+  registerStatusCommand(pi, runtime);
+  registerCompactCommand(pi, runtime);
+  registerConsolidateCommand(pi, runtime);
+}

package/extensions/memory-log/ledger/fold.ts

@@ -0,0 +1,77 @@
+import {
+  isObservationsDroppedData,
+  isObservationsRecordedData,
+  OM_OBSERVATIONS_DROPPED,
+  OM_OBSERVATIONS_RECORDED,
+  type Entry,
+  type Observation,
+} from "./types.ts";
+
+export type FoldLedgerOptions = {
+  /** Fold entries from branch root through this entry id, inclusive. Omit to fold through branch tip. */
+  upToEntryId?: string;
+};
+
+export type FoldedLedger = {
+  /** Every first-valid observation record through the fold boundary, including dropped ones. */
+  observations: Observation[];
+  /** Observations not tombstoned by a folded drop entry — the live injected buffer. */
+  activeObservations: Observation[];
+  /** Tombstoned observation timestamps, including ids with no corresponding folded observation. */
+  droppedObservationTimestamps: Set<string>;
+  /** First-valid observation records by timestamp (id), including dropped ones. */
+  observationsByTimestamp: Map<string, Observation>;
+};
+
+function foldEndIndex(entries: Entry[], upToEntryId: string | undefined): number {
+  if (!upToEntryId) return entries.length - 1;
+  const idx = entries.findIndex((entry) => entry.id === upToEntryId);
+  return idx === -1 ? entries.length - 1 : idx;
+}
+
+function isCustomEntry(entry: Entry, customType: string): boolean {
+  return entry.type === "custom" && entry.customType === customType;
+}
+
+/**
+ * Fold valid memory ledger entries from the branch root through the target entry.
+ */
+export function foldLedger(entries: Entry[], options: FoldLedgerOptions = {}): FoldedLedger {
+  const observationsByTimestamp = new Map<string, Observation>();
+  const droppedObservationTimestamps = new Set<string>();
+  const endIdx = foldEndIndex(entries, options.upToEntryId);
+
+  for (let i = 0; i <= endIdx; i++) {
+    const entry = entries[i];
+    if (!entry) continue;
+
+    if (isCustomEntry(entry, OM_OBSERVATIONS_RECORDED)) {
+      if (!isObservationsRecordedData(entry.data)) continue;
+      for (const observation of entry.data.observations) {
+        if (!observationsByTimestamp.has(observation.timestamp)) {
+          observationsByTimestamp.set(observation.timestamp, observation);
+        }
+      }
+      continue;
+    }
+
+    if (isCustomEntry(entry, OM_OBSERVATIONS_DROPPED)) {
+      if (!isObservationsDroppedData(entry.data)) continue;
+      for (const timestamp of entry.data.observationTimestamps) {
+        droppedObservationTimestamps.add(timestamp);
+      }
+    }
+  }
+
+  const observations = Array.from(observationsByTimestamp.values());
+  const activeObservations = observations.filter(
+    (observation) => !droppedObservationTimestamps.has(observation.timestamp),
+  );
+
+  return {
+    observations,
+    activeObservations,
+    droppedObservationTimestamps,
+    observationsByTimestamp,
+  };
+}

package/extensions/memory-log/ledger/index.ts

@@ -0,0 +1,7 @@
+export * from "./types.ts";
+export * from "./fold.ts";
+export * from "./progress.ts";
+export * from "./projection.ts";
+export * from "./pool.ts";
+export * from "./render.ts";
+export * from "./serialize.ts";

package/extensions/memory-log/ledger/pool.ts

@@ -0,0 +1,38 @@
+import { sortObservations } from "./render.ts";
+import type { Observation } from "./types.ts";
+
+export function poolTokens(observations: Observation[]): number {
+  let total = 0;
+  for (const observation of observations) total += observation.tokenCount;
+  return total;
+}
+
+export type PromotionOverflow = {
+  /** Oldest observations to hand to the consolidator (chronological order). */
+  promote: Observation[];
+  /** Token total of the observations kept in the buffer. */
+  keptTokens: number;
+  /** Token total of the whole active pool. */
+  totalTokens: number;
+};
+
+/**
+ * Select the promotion overflow: keep the newest observations whose cumulative tokens stay
+ * within `poolTargetTokens`, promote everything older. Always keeps at least the single
+ * newest observation, even if it alone exceeds the target.
+ */
+export function selectPromotionOverflow(active: Observation[], poolTargetTokens: number): PromotionOverflow {
+  const sorted = sortObservations(active);
+  const totalTokens = poolTokens(sorted);
+
+  let keptTokens = 0;
+  let firstKeptIdx = sorted.length;
+  for (let i = sorted.length - 1; i >= 0; i--) {
+    const t = sorted[i].tokenCount;
+    if (firstKeptIdx !== sorted.length && keptTokens + t > poolTargetTokens) break;
+    keptTokens += t;
+    firstKeptIdx = i;
+  }
+
+  return { promote: sorted.slice(0, firstKeptIdx), keptTokens, totalTokens };
+}

package/extensions/memory-log/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/extensions/memory-log/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/extensions/memory-log/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");
+}