pi-blackhole 0.4.2 → 0.4.3

package/src/om/ledger/recall.ts

@@ -5,12 +5,12 @@
  * Unmodified.
  */
 import {
-	isObservationsDroppedEntry,
-	isObservationsRecordedEntry,
-	isReflectionsRecordedEntry,
-	type Entry,
-	type Observation,
-	type Reflection,
+  isObservationsDroppedEntry,
+  isObservationsRecordedEntry,
+  isReflectionsRecordedEntry,
+  type Entry,
+  type Observation,
+  type Reflection,
 } from "./types.js";
 
 const SOURCE_TYPES = new Set(["message", "custom_message", "branch_summary"]);
@@ -18,226 +18,277 @@ const SOURCE_TYPES = new Set(["message", "custom_message", "branch_summary"]);
 export type { Entry, Observation, Reflection };
 
 type ObservationLedgerLocation = {
-	entryId: string;
-	entryIndex: number;
-	recordIndex: number;
+  entryId: string;
+  entryIndex: number;
+  recordIndex: number;
 };
 
 type ReflectionLedgerLocation = {
-	entryId: string;
-	entryIndex: number;
-	recordIndex: number;
+  entryId: string;
+  entryIndex: number;
+  recordIndex: number;
 };
 
 export type RecalledObservation = {
-	observation: Observation;
-	observationEntryId: string;
-	observationRecordIndex: number;
-	status: "active" | "dropped";
-	sourceEntryIds: string[];
-	sourceEntries: Entry[];
-	missingSourceEntryIds: string[];
-	nonSourceEntryIds: string[];
+  observation: Observation;
+  observationEntryId: string;
+  observationRecordIndex: number;
+  status: "active" | "dropped";
+  sourceEntryIds: string[];
+  sourceEntries: Entry[];
+  missingSourceEntryIds: string[];
+  nonSourceEntryIds: string[];
 };
 
 export type RecalledReflection = {
-	reflection: Reflection;
-	reflectionEntryId: string;
-	reflectionRecordIndex: number;
+  reflection: Reflection;
+  reflectionEntryId: string;
+  reflectionRecordIndex: number;
 };
 
 export type RecallResult =
-	| {
-			status: "not_found";
-			memoryId: string;
-			kind: undefined;
-			reflections: [];
-			observations: [];
-			sourceEntries: [];
-			missingSourceEntryIds: [];
-			nonSourceEntryIds: [];
-			missingSupportingObservationIds: [];
-			collision: false;
-			partial: false;
-	  }
-	| {
-			status: "found";
-			memoryId: string;
-			kind: "observation" | "reflection" | "mixed";
-			reflections: RecalledReflection[];
-			observations: RecalledObservation[];
-			sourceEntries: Entry[];
-			missingSourceEntryIds: string[];
-			nonSourceEntryIds: string[];
-			missingSupportingObservationIds: string[];
-			collision: boolean;
-			partial: boolean;
-	  };
-
-type IndexedObservation = ObservationLedgerLocation & { observation: Observation };
+  | {
+      status: "not_found";
+      memoryId: string;
+      kind: undefined;
+      reflections: [];
+      observations: [];
+      sourceEntries: [];
+      missingSourceEntryIds: [];
+      nonSourceEntryIds: [];
+      missingSupportingObservationIds: [];
+      collision: false;
+      partial: false;
+    }
+  | {
+      status: "found";
+      memoryId: string;
+      kind: "observation" | "reflection" | "mixed";
+      reflections: RecalledReflection[];
+      observations: RecalledObservation[];
+      sourceEntries: Entry[];
+      missingSourceEntryIds: string[];
+      nonSourceEntryIds: string[];
+      missingSupportingObservationIds: string[];
+      collision: boolean;
+      partial: boolean;
+    };
+
+type IndexedObservation = ObservationLedgerLocation & {
+  observation: Observation;
+};
 type IndexedReflection = ReflectionLedgerLocation & { reflection: Reflection };
 
 function isSourceEntry(entry: Entry): boolean {
-	return SOURCE_TYPES.has(entry.type);
+  return SOURCE_TYPES.has(entry.type);
 }
 
 function uniqueById(entries: Entry[]): Entry[] {
-	const seen = new Set<string>();
-	const result: Entry[] = [];
-	for (const entry of entries) {
-		if (seen.has(entry.id)) continue;
-		seen.add(entry.id);
-		result.push(entry);
-	}
-	return result;
+  const seen = new Set<string>();
+  const result: Entry[] = [];
+  for (const entry of entries) {
+    if (seen.has(entry.id)) continue;
+    seen.add(entry.id);
+    result.push(entry);
+  }
+  return result;
 }
 
 function uniqueStrings(values: string[]): string[] {
-	return Array.from(new Set(values));
+  return Array.from(new Set(values));
 }
 
 export function indexLedger(entries: Entry[]): {
-	observations: IndexedObservation[];
-	reflections: IndexedReflection[];
-	droppedIds: Set<string>;
+  observations: IndexedObservation[];
+  reflections: IndexedReflection[];
+  droppedIds: Set<string>;
 } {
-	const observations: IndexedObservation[] = [];
-	const reflections: IndexedReflection[] = [];
-	const droppedIds = new Set<string>();
-
-	for (let entryIndex = 0; entryIndex < entries.length; entryIndex++) {
-		const entry = entries[entryIndex];
-		if (isObservationsRecordedEntry(entry)) {
-			entry.data.observations.forEach((observation, recordIndex) => {
-				observations.push({ observation, entryId: entry.id, entryIndex, recordIndex });
-			});
-			continue;
-		}
-		if (isReflectionsRecordedEntry(entry)) {
-			entry.data.reflections.forEach((reflection, recordIndex) => {
-				reflections.push({ reflection, entryId: entry.id, entryIndex, recordIndex });
-			});
-			continue;
-		}
-		if (isObservationsDroppedEntry(entry)) {
-			entry.data.observationIds.forEach((id) => droppedIds.add(id));
-		}
-	}
-
-	return { observations, reflections, droppedIds };
+  const observations: IndexedObservation[] = [];
+  const reflections: IndexedReflection[] = [];
+  const droppedIds = new Set<string>();
+
+  for (let entryIndex = 0; entryIndex < entries.length; entryIndex++) {
+    const entry = entries[entryIndex];
+    if (isObservationsRecordedEntry(entry)) {
+      entry.data.observations.forEach((observation, recordIndex) => {
+        observations.push({
+          observation,
+          entryId: entry.id,
+          entryIndex,
+          recordIndex,
+        });
+      });
+      continue;
+    }
+    if (isReflectionsRecordedEntry(entry)) {
+      entry.data.reflections.forEach((reflection, recordIndex) => {
+        reflections.push({
+          reflection,
+          entryId: entry.id,
+          entryIndex,
+          recordIndex,
+        });
+      });
+      continue;
+    }
+    if (isObservationsDroppedEntry(entry)) {
+      entry.data.observationIds.forEach((id) => droppedIds.add(id));
+    }
+  }
+
+  return { observations, reflections, droppedIds };
 }
 
-function resolveObservationSources(entries: Entry[], observation: Observation, location: ObservationLedgerLocation): RecalledObservation {
-	const sourceEntryIds = uniqueStrings(observation.sourceEntryIds);
-	const byId = new Map(entries.map((entry) => [entry.id, entry]));
-	const sourceEntries: Entry[] = [];
-	const missingSourceEntryIds: string[] = [];
-	const nonSourceEntryIds: string[] = [];
-
-	for (const sourceEntryId of sourceEntryIds) {
-		const sourceEntry = byId.get(sourceEntryId);
-		if (!sourceEntry) {
-			missingSourceEntryIds.push(sourceEntryId);
-			continue;
-		}
-		if (!isSourceEntry(sourceEntry)) {
-			nonSourceEntryIds.push(sourceEntryId);
-			continue;
-		}
-		sourceEntries.push(sourceEntry);
-	}
-
-	return {
-		observation,
-		observationEntryId: location.entryId,
-		observationRecordIndex: location.recordIndex,
-		status: "active",
-		sourceEntryIds,
-		sourceEntries,
-		missingSourceEntryIds,
-		nonSourceEntryIds,
-	};
+function resolveObservationSources(
+  entries: Entry[],
+  observation: Observation,
+  location: ObservationLedgerLocation,
+): RecalledObservation {
+  const sourceEntryIds = uniqueStrings(observation.sourceEntryIds);
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  const sourceEntries: Entry[] = [];
+  const missingSourceEntryIds: string[] = [];
+  const nonSourceEntryIds: string[] = [];
+
+  for (const sourceEntryId of sourceEntryIds) {
+    const sourceEntry = byId.get(sourceEntryId);
+    if (!sourceEntry) {
+      missingSourceEntryIds.push(sourceEntryId);
+      continue;
+    }
+    if (!isSourceEntry(sourceEntry)) {
+      nonSourceEntryIds.push(sourceEntryId);
+      continue;
+    }
+    sourceEntries.push(sourceEntry);
+  }
+
+  return {
+    observation,
+    observationEntryId: location.entryId,
+    observationRecordIndex: location.recordIndex,
+    status: "active",
+    sourceEntryIds,
+    sourceEntries,
+    missingSourceEntryIds,
+    nonSourceEntryIds,
+  };
 }
 
 function notFound(memoryId: string): RecallResult {
-	return {
-		status: "not_found",
-		memoryId,
-		kind: undefined,
-		reflections: [],
-		observations: [],
-		sourceEntries: [],
-		missingSourceEntryIds: [],
-		nonSourceEntryIds: [],
-		missingSupportingObservationIds: [],
-		collision: false,
-		partial: false,
-	};
+  return {
+    status: "not_found",
+    memoryId,
+    kind: undefined,
+    reflections: [],
+    observations: [],
+    sourceEntries: [],
+    missingSourceEntryIds: [],
+    nonSourceEntryIds: [],
+    missingSupportingObservationIds: [],
+    collision: false,
+    partial: false,
+  };
 }
 
-export function recallMemorySources(entries: Entry[], memoryId: string): RecallResult {
-	const { observations: indexedObservations, reflections: indexedReflections, droppedIds } = indexLedger(entries);
-	const directObservationMatches = indexedObservations.filter(({ observation }) => observation.id === memoryId);
-	const reflectionMatches = indexedReflections.filter(({ reflection }) => reflection.id === memoryId);
-
-	if (directObservationMatches.length === 0 && reflectionMatches.length === 0) return notFound(memoryId);
-
-	const observationsById = new Map<string, IndexedObservation>();
-	for (const indexed of indexedObservations) {
-		if (!observationsById.has(indexed.observation.id)) observationsById.set(indexed.observation.id, indexed);
-	}
-
-	const recalledByKey = new Map<string, RecalledObservation>();
-	const rawMissingSupportingObservationIds: string[] = [];
-
-	function addObservation(indexed: IndexedObservation): void {
-		const key = `${indexed.entryId}:${indexed.recordIndex}`;
-		if (recalledByKey.has(key)) return;
-		const recalled = resolveObservationSources(entries, indexed.observation, indexed);
-		recalled.status = droppedIds.has(indexed.observation.id) ? "dropped" : "active";
-		recalledByKey.set(key, recalled);
-	}
-
-	for (const match of directObservationMatches) addObservation(match);
-
-	for (const { reflection } of reflectionMatches) {
-		for (const observationId of uniqueStrings(reflection.supportingObservationIds)) {
-			const indexed = observationsById.get(observationId);
-			if (!indexed) {
-				rawMissingSupportingObservationIds.push(observationId);
-				continue;
-			}
-			addObservation(indexed);
-		}
-	}
-
-	const recalledObservations = Array.from(recalledByKey.values());
-	const recalledReflections: RecalledReflection[] = reflectionMatches.map(({ reflection, entryId, recordIndex }) => ({
-		reflection,
-		reflectionEntryId: entryId,
-		reflectionRecordIndex: recordIndex,
-	}));
-	const sourceEntries = uniqueById(recalledObservations.flatMap((match) => match.sourceEntries));
-	const missingSourceEntryIds = uniqueStrings(recalledObservations.flatMap((match) => match.missingSourceEntryIds));
-	const nonSourceEntryIds = uniqueStrings(recalledObservations.flatMap((match) => match.nonSourceEntryIds));
-	const uniqueMissingSupportingObservationIds = uniqueStrings(rawMissingSupportingObservationIds);
-	const matchCount = directObservationMatches.length + reflectionMatches.length;
-
-	return {
-		status: "found",
-		memoryId,
-		kind: directObservationMatches.length > 0 && reflectionMatches.length > 0
-			? "mixed"
-			: reflectionMatches.length > 0
-				? "reflection"
-				: "observation",
-		reflections: recalledReflections,
-		observations: recalledObservations,
-		sourceEntries,
-		missingSourceEntryIds,
-		nonSourceEntryIds,
-		missingSupportingObservationIds: uniqueMissingSupportingObservationIds,
-		collision: matchCount > 1,
-		partial: missingSourceEntryIds.length > 0 || nonSourceEntryIds.length > 0 || uniqueMissingSupportingObservationIds.length > 0,
-	};
+export function recallMemorySources(
+  entries: Entry[],
+  memoryId: string,
+): RecallResult {
+  const {
+    observations: indexedObservations,
+    reflections: indexedReflections,
+    droppedIds,
+  } = indexLedger(entries);
+  const directObservationMatches = indexedObservations.filter(
+    ({ observation }) => observation.id === memoryId,
+  );
+  const reflectionMatches = indexedReflections.filter(
+    ({ reflection }) => reflection.id === memoryId,
+  );
+
+  if (directObservationMatches.length === 0 && reflectionMatches.length === 0)
+    return notFound(memoryId);
+
+  const observationsById = new Map<string, IndexedObservation>();
+  for (const indexed of indexedObservations) {
+    if (!observationsById.has(indexed.observation.id))
+      observationsById.set(indexed.observation.id, indexed);
+  }
+
+  const recalledByKey = new Map<string, RecalledObservation>();
+  const rawMissingSupportingObservationIds: string[] = [];
+
+  function addObservation(indexed: IndexedObservation): void {
+    const key = `${indexed.entryId}:${indexed.recordIndex}`;
+    if (recalledByKey.has(key)) return;
+    const recalled = resolveObservationSources(
+      entries,
+      indexed.observation,
+      indexed,
+    );
+    recalled.status = droppedIds.has(indexed.observation.id)
+      ? "dropped"
+      : "active";
+    recalledByKey.set(key, recalled);
+  }
+
+  for (const match of directObservationMatches) addObservation(match);
+
+  for (const { reflection } of reflectionMatches) {
+    for (const observationId of uniqueStrings(
+      reflection.supportingObservationIds,
+    )) {
+      const indexed = observationsById.get(observationId);
+      if (!indexed) {
+        rawMissingSupportingObservationIds.push(observationId);
+        continue;
+      }
+      addObservation(indexed);
+    }
+  }
+
+  const recalledObservations = Array.from(recalledByKey.values());
+  const recalledReflections: RecalledReflection[] = reflectionMatches.map(
+    ({ reflection, entryId, recordIndex }) => ({
+      reflection,
+      reflectionEntryId: entryId,
+      reflectionRecordIndex: recordIndex,
+    }),
+  );
+  const sourceEntries = uniqueById(
+    recalledObservations.flatMap((match) => match.sourceEntries),
+  );
+  const missingSourceEntryIds = uniqueStrings(
+    recalledObservations.flatMap((match) => match.missingSourceEntryIds),
+  );
+  const nonSourceEntryIds = uniqueStrings(
+    recalledObservations.flatMap((match) => match.nonSourceEntryIds),
+  );
+  const uniqueMissingSupportingObservationIds = uniqueStrings(
+    rawMissingSupportingObservationIds,
+  );
+  const matchCount = directObservationMatches.length + reflectionMatches.length;
+
+  return {
+    status: "found",
+    memoryId,
+    kind:
+      directObservationMatches.length > 0 && reflectionMatches.length > 0
+        ? "mixed"
+        : reflectionMatches.length > 0
+          ? "reflection"
+          : "observation",
+    reflections: recalledReflections,
+    observations: recalledObservations,
+    sourceEntries,
+    missingSourceEntryIds,
+    nonSourceEntryIds,
+    missingSupportingObservationIds: uniqueMissingSupportingObservationIds,
+    collision: matchCount > 1,
+    partial:
+      missingSourceEntryIds.length > 0 ||
+      nonSourceEntryIds.length > 0 ||
+      uniqueMissingSupportingObservationIds.length > 0,
+  };
 }

package/src/om/ledger/render-summary.ts

@@ -18,18 +18,26 @@ export const OM_FOOTER_FULL = `----\n${OM_INSTRUCTIONS_FULL}\n----`;
 export const OM_FOOTER_BASIC = `----\n${OM_INSTRUCTIONS_BASIC}\n----`;
 
 export function observationToSummaryLine(observation: Observation): string {
-	return `[${observation.id}] ${observation.timestamp} [${observation.relevance}] ${observation.content}`;
+  return `[${observation.id}] ${observation.timestamp} [${observation.relevance}] ${observation.content}`;
 }
 
 /** Score an observation for cap/trim selection.
  *  Relevance tier dominates: medium (5+) always outranks low (max 2).
  *  Recency is based on position in the flat-mapped array (0 = oldest, N-1 = newest),
  *  avoiding wall-clock dependency that punishes sessions spanning days or weeks. */
-export function scoreObservation(obs: Observation, index: number, total: number): number {
-	const base = obs.relevance === "high" || obs.relevance === "critical" ? 10
-		: obs.relevance === "medium" ? 5 : 1;
-	const recency = total > 1 ? index / (total - 1) : 1;
-	return base + recency;
+export function scoreObservation(
+  obs: Observation,
+  index: number,
+  total: number,
+): number {
+  const base =
+    obs.relevance === "high" || obs.relevance === "critical"
+      ? 10
+      : obs.relevance === "medium"
+        ? 5
+        : 1;
+  const recency = total > 1 ? index / (total - 1) : 1;
+  return base + recency;
 }
 
 /** Select observations up to a token budget, keeping all high-relevance items
@@ -39,58 +47,79 @@ export function scoreObservation(obs: Observation, index: number, total: number)
  *  Reflections are never trimmed — they are inherently rare and always stay.
  *  Observations stay in the branch either way; this only caps what is rendered
  *  in the compaction summary output. */
-export function selectPriorObservations(observations: Observation[], maxTokens: number): Observation[] {
-	// Track original indices so we can restore chronological order after scoring
-	const indexed = observations.map((obs, i) => ({ obs, originalIndex: i }));
-	const high = indexed.filter(item => item.obs.relevance === "high" || item.obs.relevance === "critical");
-	const rest = indexed.filter(item => item.obs.relevance !== "high" && item.obs.relevance !== "critical");
+export function selectPriorObservations(
+  observations: Observation[],
+  maxTokens: number,
+): Observation[] {
+  // Track original indices so we can restore chronological order after scoring
+  const indexed = observations.map((obs, i) => ({ obs, originalIndex: i }));
+  const high = indexed.filter(
+    (item) =>
+      item.obs.relevance === "high" || item.obs.relevance === "critical",
+  );
+  const rest = indexed.filter(
+    (item) =>
+      item.obs.relevance !== "high" && item.obs.relevance !== "critical",
+  );
 
-	// High always kept — consume budget first
-	let budget = maxTokens;
-	const selected = new Set<{ obs: Observation; originalIndex: number }>();
-	for (const item of high) {
-		const lineTokens = Math.ceil(observationToSummaryLine(item.obs).length / 4);
-		selected.add(item);
-		budget -= lineTokens;
-	}
+  // High always kept — consume budget first
+  let budget = maxTokens;
+  const selected = new Set<{ obs: Observation; originalIndex: number }>();
+  for (const item of high) {
+    const lineTokens = Math.ceil(observationToSummaryLine(item.obs).length / 4);
+    selected.add(item);
+    budget -= lineTokens;
+  }
 
-	// Score medium + low and select best within remaining budget
-	if (rest.length > 0 && budget > 0) {
-		const scored = rest.map((item, i) => ({ item, score: scoreObservation(item.obs, i, rest.length) }));
-		scored.sort((a, b) => b.score - a.score); // highest score first
-		for (const { item } of scored) {
-			const lineTokens = Math.ceil(observationToSummaryLine(item.obs).length / 4);
-			if (budget - lineTokens < 0) break;
-			selected.add(item);
-			budget -= lineTokens;
-		}
-	}
+  // Score medium + low and select best within remaining budget
+  if (rest.length > 0 && budget > 0) {
+    const scored = rest.map((item, i) => ({
+      item,
+      score: scoreObservation(item.obs, i, rest.length),
+    }));
+    scored.sort((a, b) => b.score - a.score); // highest score first
+    for (const { item } of scored) {
+      const lineTokens = Math.ceil(
+        observationToSummaryLine(item.obs).length / 4,
+      );
+      if (budget - lineTokens < 0) break;
+      selected.add(item);
+      budget -= lineTokens;
+    }
+  }
 
-	// Restore original chronological order before returning
-	return Array.from(selected)
-		.sort((a, b) => a.originalIndex - b.originalIndex)
-		.map(item => item.obs);
+  // Restore original chronological order before returning
+  return Array.from(selected)
+    .sort((a, b) => a.originalIndex - b.originalIndex)
+    .map((item) => item.obs);
 }
 
 export function reflectionToSummaryLine(reflection: Reflection): string {
-	return `[${reflection.id}] ${reflection.content}`;
+  return `[${reflection.id}] ${reflection.content}`;
 }
 
-export function renderSummary(reflections: Reflection[], observations: Observation[]): string {
-	const hasContent = reflections.length > 0 || observations.length > 0;
+export function renderSummary(
+  reflections: Reflection[],
+  observations: Observation[],
+): string {
+  const hasContent = reflections.length > 0 || observations.length > 0;
 
-	const parts: string[] = [];
-	if (reflections.length > 0) {
-		parts.push(`## Reflections\n${reflections.map(reflectionToSummaryLine).join("\n")}`);
-	}
-	if (observations.length > 0) {
-		parts.push(`## Observations\n${observations.map(observationToSummaryLine).join("\n")}`);
-	}
+  const parts: string[] = [];
+  if (reflections.length > 0) {
+    parts.push(
+      `## Reflections\n${reflections.map(reflectionToSummaryLine).join("\n")}`,
+    );
+  }
+  if (observations.length > 0) {
+    parts.push(
+      `## Observations\n${observations.map(observationToSummaryLine).join("\n")}`,
+    );
+  }
 
-	const footer = hasContent ? OM_FOOTER_FULL : OM_FOOTER_BASIC;
-	if (parts.length > 0) {
-		parts.push(footer);
-		return parts.join("\n\n");
-	}
-	return footer;
+  const footer = hasContent ? OM_FOOTER_FULL : OM_FOOTER_BASIC;
+  if (parts.length > 0) {
+    parts.push(footer);
+    return parts.join("\n\n");
+  }
+  return footer;
 }