pi-observational-memory 2.3.0 → 2.4.1

package/src/types.ts

@@ -4,6 +4,8 @@ export type Relevance = "low" | "medium" | "high" | "critical";
 
 export const RELEVANCE_VALUES: readonly Relevance[] = ["low", "medium", "high", "critical"] as const;
 
+export const MEMORY_ID_PATTERN = /^[a-f0-9]{12}$/;
+
 export interface ObservationRecord {
 	id: string;
 	content: string;
@@ -12,15 +14,41 @@ export interface ObservationRecord {
 	sourceEntryIds?: string[];
 }
 
-export type Reflection = string;
+export type LegacyReflection = string;
+
+export interface ReflectionRecord {
+	id: string;
+	content: string;
+	supportingObservationIds: string[];
+	legacy?: boolean;
+}
+
+export type MemoryReflection = LegacyReflection | ReflectionRecord;
+
+/**
+ * Current runtime reflection alias used by pre-v4 consumers. Later producer/consumer
+ * steps should migrate surfaces that need id-bearing records to MemoryReflection.
+ */
+export type Reflection = LegacyReflection;
 
-export interface MemoryDetails {
+export interface MemoryDetailsV3 {
 	type: "observational-memory";
 	version: 3;
 	observations: ObservationRecord[];
-	reflections: Reflection[];
+	reflections: LegacyReflection[];
 }
 
+export interface MemoryDetailsV4 {
+	type: "observational-memory";
+	version: 4;
+	observations: ObservationRecord[];
+	reflections: MemoryReflection[];
+}
+
+export type SupportedMemoryDetails = MemoryDetailsV3 | MemoryDetailsV4;
+
+export type MemoryDetails = MemoryDetailsV3;
+
 export interface ObservationEntryData {
 	records: ObservationRecord[];
 	coversFromId: string;
@@ -44,14 +72,51 @@ function isObservationRecord(v: unknown): v is ObservationRecord {
 		return false;
 	}
 	if (o.sourceEntryIds === undefined) return true;
-	return (
-		Array.isArray(o.sourceEntryIds) &&
-		o.sourceEntryIds.length > 0 &&
-		o.sourceEntryIds.every((id) => typeof id === "string" && id.length > 0)
-	);
+	return isNonEmptyStringArray(o.sourceEntryIds);
 }
 
-export function isMemoryDetails(d: unknown): d is MemoryDetails {
+function isNonEmptyStringArray(v: unknown): v is string[] {
+	return Array.isArray(v) && v.length > 0 && v.every((id) => typeof id === "string" && id.length > 0);
+}
+
+function isEmptyStringArray(v: unknown): v is string[] {
+	return Array.isArray(v) && v.length === 0;
+}
+
+export function isReflectionRecord(v: unknown): v is ReflectionRecord {
+	if (!v || typeof v !== "object") return false;
+	const o = v as Record<string, unknown>;
+	if (
+		typeof o.id !== "string" ||
+		!MEMORY_ID_PATTERN.test(o.id) ||
+		typeof o.content !== "string" ||
+		o.content.trim().length === 0 ||
+		/[\r\n]/.test(o.content)
+	) {
+		return false;
+	}
+	if (o.legacy !== undefined && typeof o.legacy !== "boolean") return false;
+	if (o.legacy === true) return isEmptyStringArray(o.supportingObservationIds);
+	return isNonEmptyStringArray(o.supportingObservationIds);
+}
+
+export function isMemoryReflection(v: unknown): v is MemoryReflection {
+	return typeof v === "string" || isReflectionRecord(v);
+}
+
+export function reflectionContent(reflection: MemoryReflection): string {
+	return typeof reflection === "string" ? reflection : reflection.content;
+}
+
+export function reflectionId(reflection: MemoryReflection): string | undefined {
+	return typeof reflection === "string" ? undefined : reflection.id;
+}
+
+export function reflectionToPromptLine(reflection: MemoryReflection): string {
+	return typeof reflection === "string" ? reflection : `[${reflection.id}] ${reflection.content}`;
+}
+
+export function isMemoryDetailsV3(d: unknown): d is MemoryDetailsV3 {
 	if (!d || typeof d !== "object") return false;
 	const o = d as Record<string, unknown>;
 	if (o.type !== "observational-memory" || o.version !== 3) return false;
@@ -60,6 +125,23 @@ export function isMemoryDetails(d: unknown): d is MemoryDetails {
 	return o.reflections.every((r) => typeof r === "string");
 }
 
+export function isMemoryDetailsV4(d: unknown): d is MemoryDetailsV4 {
+	if (!d || typeof d !== "object") return false;
+	const o = d as Record<string, unknown>;
+	if (o.type !== "observational-memory" || o.version !== 4) return false;
+	if (!Array.isArray(o.observations) || !Array.isArray(o.reflections)) return false;
+	if (!o.observations.every(isObservationRecord)) return false;
+	return o.reflections.every(isMemoryReflection);
+}
+
+export function isSupportedMemoryDetails(d: unknown): d is SupportedMemoryDetails {
+	return isMemoryDetailsV3(d) || isMemoryDetailsV4(d);
+}
+
+export function isMemoryDetails(d: unknown): d is MemoryDetails {
+	return isMemoryDetailsV3(d);
+}
+
 export function isObservationEntryData(d: unknown): d is ObservationEntryData {
 	if (!d || typeof d !== "object") return false;
 	const o = d as Record<string, unknown>;