@sovorn/pi-session-memory 0.1.0

package/src/projection.ts

@@ -0,0 +1,349 @@
+import type { ContextEvent, ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { supersessionStatuses } from "./supersession.ts";
+
+const OBSERVATION_TYPE = "pi-session-memory.observation";
+const REFLECTION_TYPE = "pi-session-memory.reflection";
+const MAX_CANDIDATES = 8;
+export const CANDIDATES = 6;
+const MAX_PROJECTION_CHARS = 6_000;
+export const PROJECTION_CHARS = 4_000;
+
+export interface ProjectionLimits {
+  candidates: number;
+  chars: number;
+}
+const MAX_NEED_CHARS = 800;
+const MAX_CANDIDATE_TEXT_CHARS = 500;
+const MAX_GATE_STATE_BYTES = 8_000;
+const MAX_ENTRY_ID_CHARS = 256;
+const MAX_MEMORY_TEXT_CHARS = 1_000;
+const MAX_RAW_SOURCES = 12;
+const MAX_REFLECTION_SOURCES = 6;
+const MEMORY_LABEL = "Relevant prior session memory (validated active-branch provenance; context only):";
+const STOP_WORDS = new Set(["this", "that", "with", "from", "what", "when", "where", "which", "about", "please", "current", "need", "does", "have", "been", "were", "your", "they", "them", "then", "than"]);
+
+export type ProjectionGate = "resident" | "projection";
+export interface ProjectionGateRequest {
+  gate: ProjectionGate;
+  state: string;
+}
+export interface ProjectionSufficiencyDecision {
+  accepted: boolean;
+  p_true: number;
+  confidence: number;
+}
+export interface ProjectionSelectionDecision {
+  selected_entry_id: string | null;
+}
+export type ProjectionDecision = ProjectionSufficiencyDecision | ProjectionSelectionDecision;
+type EvaluateProjection = (sessionId: string, request: ProjectionGateRequest, ctx: ExtensionContext) => Promise<ProjectionDecision>;
+type ContextMessages = ContextEvent["messages"];
+
+interface ObservationData {
+  schemaVersion: 1;
+  text: string;
+  sourceEntryIds: string[];
+}
+interface ReflectionData {
+  schemaVersion: 1;
+  text: string;
+  supportingObservationIds: string[];
+}
+interface IndexedObservation {
+  data: ObservationData;
+  index: number;
+}
+interface Candidate {
+  entryId: string;
+  kind: "observation" | "reflection";
+  text: string;
+  observationIds: string[];
+  sourceEntryIds: string[];
+  sourceText: string;
+  branchIndex: number;
+}
+type Resident = Pick<Candidate, "entryId" | "kind" | "text">;
+export function registerProjection(pi: ExtensionAPI, evaluate: EvaluateProjection, limits: ProjectionLimits = { candidates: CANDIDATES, chars: PROJECTION_CHARS }): () => void {
+  const residents = new Map<string, Resident>();
+  pi.on("context", async (event, ctx) => {
+    try {
+      const sessionId = ctx.sessionManager.getSessionId();
+      let branch = ctx.sessionManager.getBranch();
+      const originalMessages = event.messages;
+      const latestUserText = lastUserText(originalMessages);
+      if (!latestUserText) return { messages: originalMessages };
+      const limit = boundedLimit(limits.candidates, CANDIDATES, MAX_CANDIDATES);
+      const outputLimit = boundedLimit(limits.chars, PROJECTION_CHARS, MAX_PROJECTION_CHARS);
+
+      let candidates = currentCandidates(branch);
+      const currentTerms = words(latestUserText);
+      const memoryNeed = needsMemory(latestUserText, currentTerms, candidates);
+      if (!memoryNeed) return { messages: withoutMemoryProjections(originalMessages) };
+
+      const residentId = residents.get(sessionId)?.entryId;
+      if (residentId) {
+        const resident = candidateById(branch, residentId);
+        if (resident) {
+          const state = encodeState({ need: truncate(latestUserText, MAX_NEED_CHARS), candidate: { entryId: resident.entryId, kind: resident.kind, text: resident.text } });
+          if (!state) return { messages: withoutMemoryProjections(originalMessages) };
+          const decision = await evaluate(sessionId, { gate: "resident", state }, ctx);
+          const currentBranch = ctx.sessionManager.getBranch();
+          if (ctx.sessionManager.getSessionId() !== sessionId) return { messages: withoutMemoryProjections(originalMessages) };
+          const currentResident = candidateById(currentBranch, resident.entryId);
+          if (!currentResident || currentResident.text !== resident.text || currentResident.kind !== resident.kind) {
+            residents.delete(sessionId);
+            return { messages: withoutMemoryProjections(originalMessages) };
+          }
+          if (!isSufficiencyDecision(decision)) return { messages: withoutMemoryProjections(originalMessages) };
+          if (decision.accepted) {
+            const text = renderCandidate(currentResident);
+            if (text.length > outputLimit) return { messages: withoutMemoryProjections(originalMessages) };
+            residents.set(sessionId, asResident(currentResident));
+            return { messages: withProjection(originalMessages, text) };
+          }
+          branch = currentBranch;
+          candidates = currentCandidates(branch);
+        }
+        residents.delete(sessionId);
+      }
+
+      const ranked = candidates
+        .map((candidate) => ({ candidate, score: candidateScore(candidate, currentTerms, words(activeContextText(originalMessages, latestUserText)), branch.length) }))
+        .sort((left, right) => right.score - left.score || right.candidate.branchIndex - left.candidate.branchIndex)
+        .slice(0, limit)
+        .map(({ candidate }) => candidate);
+      if (ranked.length === 0) return { messages: withoutMemoryProjections(originalMessages) };
+
+      const state = encodeState({
+        need: truncate(latestUserText, MAX_NEED_CHARS),
+        candidates: ranked.map(({ entryId, kind, text }) => ({ entryId, kind, text: truncate(text, MAX_CANDIDATE_TEXT_CHARS) })),
+      });
+      if (!state) return { messages: withoutMemoryProjections(originalMessages) };
+      const selection = await evaluate(sessionId, { gate: "projection", state }, ctx);
+      if (!isSelectionDecision(selection) || selection.selected_entry_id === null) return { messages: withoutMemoryProjections(originalMessages) };
+      const selected = ranked.find(({ entryId }) => entryId === selection.selected_entry_id);
+      if (!selected) return { messages: withoutMemoryProjections(originalMessages) };
+
+      const currentBranch = ctx.sessionManager.getBranch();
+      if (ctx.sessionManager.getSessionId() !== sessionId) return { messages: withoutMemoryProjections(originalMessages) };
+      const revalidated = candidateById(currentBranch, selected.entryId);
+      if (!revalidated || revalidated.text !== selected.text || revalidated.kind !== selected.kind) return { messages: withoutMemoryProjections(originalMessages) };
+      const text = renderCandidate(revalidated);
+      if (text.length > outputLimit) return { messages: withoutMemoryProjections(originalMessages) };
+      residents.set(sessionId, asResident(revalidated));
+      return { messages: withProjection(originalMessages, text) };
+    } catch {
+      return { messages: withoutMemoryProjections(event.messages) };
+    }
+  });
+
+  return () => residents.clear();
+}
+
+export function currentCandidates(branch: SessionEntry[]): Candidate[] {
+  const statuses = supersessionStatuses(branch);
+  return activeCandidates(branch).filter(({ entryId }) => statuses.get(entryId)?.status === "current");
+}
+
+function activeCandidates(branch: SessionEntry[]): Candidate[] {
+  const entries = new Map<string, SessionEntry>();
+  const indexes = new Map<string, number>();
+  branch.forEach((entry, index) => {
+    if (entries.has(entry.id)) throw new Error("Active branch contains duplicate entry IDs");
+    entries.set(entry.id, entry);
+    indexes.set(entry.id, index);
+  });
+  const rawEntries = new Map<string, Extract<SessionEntry, { type: "message" }>>();
+  for (const [id, entry] of entries) if (isMessageEntry(entry)) rawEntries.set(id, entry);
+  const observations = new Map<string, IndexedObservation>();
+  for (const [id, entry] of entries) {
+    if (!isCustomEntry(entry, OBSERVATION_TYPE) || !isObservationData(entry.data) ||
+        !entry.data.sourceEntryIds.every((sourceId) => rawEntries.has(sourceId))) continue;
+    observations.set(id, { data: entry.data, index: indexes.get(id) ?? 0 });
+  }
+
+  const candidates: Candidate[] = [];
+  for (const [id, value] of observations) {
+    const sources = value.data.sourceEntryIds.flatMap((sourceId) => {
+      const source = rawEntries.get(sourceId);
+      return source ? [messageText(source.message)] : [];
+    });
+    candidates.push({
+      entryId: id,
+      kind: "observation",
+      text: value.data.text,
+      observationIds: [id],
+      sourceEntryIds: value.data.sourceEntryIds,
+      sourceText: sources.join(" "),
+      branchIndex: value.index,
+    });
+  }
+
+  for (const [id, entry] of entries) {
+    if (!isCustomEntry(entry, REFLECTION_TYPE) || !isReflectionData(entry.data)) continue;
+    const linked = entry.data.supportingObservationIds.map((observationId) => observations.get(observationId));
+    if (linked.some((observation) => observation === undefined)) continue;
+    const linkedObservations = linked.filter((observation): observation is IndexedObservation => observation !== undefined);
+    const sourceEntryIds = [...new Set(linkedObservations.flatMap(({ data }) => data.sourceEntryIds))];
+    const sourceText = sourceEntryIds.flatMap((sourceId) => {
+      const source = rawEntries.get(sourceId);
+      return source ? [messageText(source.message)] : [];
+    }).join(" ");
+    candidates.push({
+      entryId: id,
+      kind: "reflection",
+      text: entry.data.text,
+      observationIds: entry.data.supportingObservationIds,
+      sourceEntryIds,
+      sourceText: `${linkedObservations.map(({ data }) => data.text).join(" ")} ${sourceText}`,
+      branchIndex: indexes.get(id) ?? 0,
+    });
+  }
+  return candidates;
+}
+
+function candidateById(branch: SessionEntry[], entryId: string): Candidate | undefined {
+  return currentCandidates(branch).find((candidate) => candidate.entryId === entryId);
+}
+
+function needsMemory(need: string, terms: Set<string>, candidates: Candidate[]): boolean {
+  if (/\b(remember|earlier|previous|prior|before|last time|as we|what did we|continue|we decided|already|again|resume)\b/i.test(need)) return true;
+  return candidates.some((candidate) => overlap(terms, words(`${candidate.text} ${candidate.sourceText}`)) > 0);
+}
+
+function candidateScore(candidate: Candidate, currentTerms: Set<string>, contextTerms: Set<string>, branchLength: number): number {
+  const candidateTerms = words(`${candidate.text} ${candidate.sourceText}`);
+  const sourceRecency = candidate.branchIndex >= Math.max(0, branchLength - 12) ? 2 : 0;
+  const memoryRecency = candidate.branchIndex >= Math.max(0, branchLength - 30) ? 1 : 0;
+  return overlap(currentTerms, candidateTerms) * 8 + overlap(contextTerms, candidateTerms) * 2 + sourceRecency + memoryRecency;
+}
+
+function activeContextText(messages: ContextMessages, latestUserText: string): string {
+  const recent = messages.slice(-7).filter((message) => message.role !== "user" || messageText(message) !== latestUserText);
+  return recent.map((message) => messageText(message)).join(" ");
+}
+
+function lastUserText(messages: ContextMessages): string | undefined {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message.role === "user") {
+      const text = messageText(message).trim();
+      return text.length > 0 ? text : undefined;
+    }
+  }
+  return undefined;
+}
+
+function asResident(candidate: Candidate): Resident {
+  return { entryId: candidate.entryId, kind: candidate.kind, text: candidate.text };
+}
+
+function renderCandidate(candidate: Candidate): string {
+  const links = [
+    candidate.observationIds.length > 0 ? `supporting observation IDs: ${candidate.observationIds.join(", ")}` : "",
+    candidate.sourceEntryIds.length > 0 ? `source entry IDs: ${candidate.sourceEntryIds.join(", ")}` : "",
+  ].filter(Boolean).join("; ");
+  return `${MEMORY_LABEL}\n[${candidate.kind} ${candidate.entryId}] ${candidate.text}${links ? `\n${links}` : ""}`;
+}
+
+function isMemoryProjectionMessage(message: ContextMessages[number]): boolean {
+  return message.role === "user" && messageText(message).startsWith(MEMORY_LABEL);
+}
+
+function withoutMemoryProjections(messages: ContextMessages): ContextMessages {
+  return messages.filter((message) => !isMemoryProjectionMessage(message));
+}
+
+function withProjection(messages: ContextMessages, text: string): ContextMessages {
+  const base = withoutMemoryProjections(messages);
+  let requestStart = -1;
+  for (let index = base.length - 1; index >= 0; index -= 1) {
+    if (base[index].role === "user") {
+      requestStart = index;
+      break;
+    }
+  }
+  if (requestStart < 0) return base;
+  const projection = {
+    role: "user" as const,
+    content: [{ type: "text" as const, text }],
+    timestamp: Date.now(),
+  };
+  return [...base.slice(0, requestStart), projection, ...base.slice(requestStart)];
+}
+
+function encodeState(value: unknown): string | undefined {
+  const state = JSON.stringify(value);
+  return Buffer.byteLength(state, "utf8") <= MAX_GATE_STATE_BYTES ? state : undefined;
+}
+
+function boundedLimit(value: number, fallback: number, maximum: number): number {
+  return Number.isSafeInteger(value) && value >= 1 && value <= maximum ? value : fallback;
+}
+
+function words(text: string): Set<string> {
+  const tokens = text.toLocaleLowerCase().match(/[\p{L}\p{N}]{4,}/gu) ?? [];
+  return new Set(tokens.map((token) => token.replace(/(ing|ed|es|s)$/u, "").replace(/e$/u, "")).filter((token) => !STOP_WORDS.has(token)));
+}
+
+function overlap(left: Set<string>, right: Set<string>): number {
+  let matches = 0;
+  for (const token of left) if (right.has(token)) matches += 1;
+  return matches;
+}
+
+function truncate(value: string, maximum: number): string {
+  return value.slice(0, maximum);
+}
+
+function messageText(message: unknown): string {
+  const content = isRecord(message) && "content" in message ? message.content : message;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.flatMap((part): string[] => isRecord(part) && part.type === "text" && typeof part.text === "string" ? [part.text] : []).join("\n");
+}
+
+function isCustomEntry(entry: unknown, customType: string): entry is Extract<SessionEntry, { type: "custom" }> {
+  return isRecord(entry) && entry.type === "custom" && entry.customType === customType && typeof entry.id === "string";
+}
+
+function isMessageEntry(entry: unknown): entry is Extract<SessionEntry, { type: "message" }> {
+  return isRecord(entry) && entry.type === "message" && typeof entry.id === "string" && isRecord(entry.message) &&
+    ["user", "assistant", "toolResult"].includes(String(entry.message.role));
+}
+
+function isObservationData(value: unknown): value is ObservationData {
+  return isRecord(value) && value.schemaVersion === 1 && isMemoryText(value.text) && Array.isArray(value.sourceEntryIds) &&
+    value.sourceEntryIds.length > 0 && value.sourceEntryIds.length <= MAX_RAW_SOURCES && value.sourceEntryIds.every(isEntryId) &&
+    new Set(value.sourceEntryIds).size === value.sourceEntryIds.length;
+}
+
+function isReflectionData(value: unknown): value is ReflectionData {
+  return isRecord(value) && value.schemaVersion === 1 && isMemoryText(value.text) && Array.isArray(value.supportingObservationIds) &&
+    value.supportingObservationIds.length > 0 && value.supportingObservationIds.length <= MAX_REFLECTION_SOURCES &&
+    value.supportingObservationIds.every(isEntryId) && new Set(value.supportingObservationIds).size === value.supportingObservationIds.length;
+}
+
+function isMemoryText(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= MAX_MEMORY_TEXT_CHARS;
+}
+
+function isEntryId(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= MAX_ENTRY_ID_CHARS;
+}
+
+function isSelectionDecision(value: ProjectionDecision): value is ProjectionSelectionDecision {
+  return "selected_entry_id" in value && (value.selected_entry_id === null || typeof value.selected_entry_id === "string");
+}
+
+function isSufficiencyDecision(value: ProjectionDecision): value is ProjectionSufficiencyDecision {
+  return "accepted" in value && typeof value.accepted === "boolean" && isProbability(value.p_true) && isProbability(value.confidence);
+}
+
+function isProbability(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/supersession.ts

@@ -0,0 +1,223 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+const OBSERVATION_TYPE = "pi-session-memory.observation";
+const REFLECTION_TYPE = "pi-session-memory.reflection";
+const SUPERSESSION_TYPE = "pi-session-memory.supersession";
+const MAX_MEMORY_TEXT_CHARS = 1_000;
+const MAX_RAW_SOURCES = 12;
+const MAX_REFLECTION_SOURCES = 6;
+const MAX_ENTRY_ID_CHARS = 256;
+const MIN_SUPERSESSION_PROBABILITY = 0.75;
+const MAX_REJECTION_PROBABILITY = 0.25;
+const MIN_SUPERSESSION_CONFIDENCE = 0.75;
+
+export type MemoryStatus =
+  | { status: "current" }
+  | { status: "superseded"; recordEntryId: string; replacementEntryId: string }
+  | { status: "stale" }
+  | { status: "unresolved" };
+
+export type SupersessionDecisionOutcome =
+  | { status: "superseded"; decision: { accepted: true; p_true: number; confidence: number } }
+  | { status: "rejected" | "unresolved" };
+
+export type SupersessionData =
+  | {
+      schemaVersion: 1;
+      status: "superseded";
+      supersededEntryId: string;
+      replacementEntryId: string;
+      decision: { accepted: true; p_true: number; confidence: number };
+    }
+  | {
+      schemaVersion: 1;
+      status: "unresolved";
+      supersededEntryId: string;
+      replacementEntryId: string;
+    };
+
+interface ObservationData {
+  schemaVersion: 1;
+  text: string;
+  sourceEntryIds: string[];
+}
+interface ReflectionData {
+  schemaVersion: 1;
+  text: string;
+  supportingObservationIds: string[];
+}
+export function supersessionStatuses(branch: SessionEntry[]): Map<string, MemoryStatus> {
+  const entries = new Map<string, SessionEntry>();
+  const indexes = new Map<string, number>();
+  const rawIds = new Set<string>();
+  for (const [index, entry] of branch.entries()) {
+    if (entries.has(entry.id)) return unresolvedStatuses(branch);
+    entries.set(entry.id, entry);
+    indexes.set(entry.id, index);
+    if (isMessageEntry(entry)) rawIds.add(entry.id);
+  }
+
+  const observations = new Map<string, { data: ObservationData; index: number }>();
+  const memories = new Map<string, number>();
+  const statuses = new Map<string, MemoryStatus>();
+  for (const [id, entry] of entries) {
+    if (!isCustomEntry(entry, OBSERVATION_TYPE)) continue;
+    if (!isEntryId(id) || !isObservationData(entry.data) || !entry.data.sourceEntryIds.every((sourceId) => rawIds.has(sourceId))) {
+      statuses.set(id, { status: "unresolved" });
+      continue;
+    }
+    const index = indexes.get(id) ?? 0;
+    observations.set(id, { data: entry.data, index });
+    memories.set(id, index);
+    statuses.set(id, { status: "current" });
+  }
+
+  const reflections = new Map<string, ReflectionData>();
+  for (const [id, entry] of entries) {
+    if (!isCustomEntry(entry, REFLECTION_TYPE)) continue;
+    if (!isEntryId(id) || !isReflectionData(entry.data) || !entry.data.supportingObservationIds.every((observationId) => observations.has(observationId))) {
+      statuses.set(id, { status: "unresolved" });
+      continue;
+    }
+    const index = indexes.get(id) ?? 0;
+    reflections.set(id, entry.data);
+    memories.set(id, index);
+    statuses.set(id, { status: "current" });
+  }
+
+  const recordStatuses = new Map<string, MemoryStatus>();
+  const statusAt = (entryId: string): MemoryStatus => {
+    const direct: MemoryStatus = recordStatuses.get(entryId) ?? statuses.get(entryId) ?? { status: "unresolved" };
+    if (direct.status !== "current") return direct;
+    const reflection = reflections.get(entryId);
+    if (!reflection) return direct;
+    for (const observationId of reflection.supportingObservationIds) {
+      const support: MemoryStatus = recordStatuses.get(observationId) ?? statuses.get(observationId) ?? { status: "unresolved" };
+      if (support.status === "unresolved") return { status: "unresolved" };
+      if (support.status !== "current") return { status: "stale" };
+    }
+    return direct;
+  };
+
+  for (const [index, entry] of branch.entries()) {
+    if (!isCustomEntry(entry, SUPERSESSION_TYPE)) continue;
+    const recordId = isEntryId(entry.id) ? entry.id : undefined;
+    const targetId = isRecord(entry.data) && isEntryId(entry.data.supersededEntryId) ? entry.data.supersededEntryId : undefined;
+    const replacementId = isRecord(entry.data) && isEntryId(entry.data.replacementEntryId) ? entry.data.replacementEntryId : undefined;
+    const data = parseSupersessionData(entry.data);
+    if (!data || !recordId) {
+      if (targetId && statuses.has(targetId)) recordStatuses.set(targetId, { status: "unresolved" });
+      if (replacementId && statuses.has(replacementId)) recordStatuses.set(replacementId, { status: "unresolved" });
+      continue;
+    }
+
+    const oldIndex = memories.get(data.supersededEntryId);
+    const replacement = observations.get(data.replacementEntryId);
+    const oldStatus = statusAt(data.supersededEntryId);
+    const replacementStatus = statusAt(data.replacementEntryId);
+    const validLinks = oldIndex !== undefined && replacement !== undefined &&
+      oldIndex < replacement.index && replacement.index < index &&
+      oldStatus.status === "current" && replacementStatus.status === "current";
+    if (!validLinks || data.status === "unresolved") {
+      recordStatuses.set(data.supersededEntryId, { status: "unresolved" });
+      recordStatuses.set(data.replacementEntryId, { status: "unresolved" });
+      continue;
+    }
+    recordStatuses.set(data.supersededEntryId, {
+      status: "superseded",
+      recordEntryId: recordId,
+      replacementEntryId: data.replacementEntryId,
+    });
+  }
+
+  for (const id of statuses.keys()) statuses.set(id, statusAt(id));
+  for (const id of recordStatuses.keys()) statuses.set(id, statusAt(id));
+  return statuses;
+}
+
+export function classifySupersessionDecision(value: unknown): SupersessionDecisionOutcome {
+  if (!isRecord(value) || typeof value.accepted !== "boolean" || !isProbability(value.p_true) || !isProbability(value.confidence)) {
+    return { status: "unresolved" };
+  }
+  if (value.accepted && value.p_true >= MIN_SUPERSESSION_PROBABILITY && value.confidence >= MIN_SUPERSESSION_CONFIDENCE) {
+    return { status: "superseded", decision: { accepted: true, p_true: value.p_true, confidence: value.confidence } };
+  }
+  if (!value.accepted && value.p_true <= MAX_REJECTION_PROBABILITY && value.confidence >= MIN_SUPERSESSION_CONFIDENCE) {
+    return { status: "rejected" };
+  }
+  return { status: "unresolved" };
+}
+
+function parseSupersessionData(value: unknown): SupersessionData | undefined {
+  if (!isRecord(value) || value.schemaVersion !== 1 || !isEntryId(value.supersededEntryId) || !isEntryId(value.replacementEntryId)) return undefined;
+  if (value.status === "unresolved" && hasExactKeys(value, ["schemaVersion", "status", "supersededEntryId", "replacementEntryId"])) {
+    return {
+      schemaVersion: 1,
+      status: "unresolved",
+      supersededEntryId: value.supersededEntryId,
+      replacementEntryId: value.replacementEntryId,
+    };
+  }
+  if (value.status !== "superseded" || !hasExactKeys(value, ["schemaVersion", "status", "supersededEntryId", "replacementEntryId", "decision"]) ||
+      !isRecord(value.decision) || !hasExactKeys(value.decision, ["accepted", "p_true", "confidence"]) ||
+      value.decision.accepted !== true || !isProbability(value.decision.p_true) || value.decision.p_true < MIN_SUPERSESSION_PROBABILITY ||
+      !isProbability(value.decision.confidence) || value.decision.confidence < MIN_SUPERSESSION_CONFIDENCE) return undefined;
+  return {
+    schemaVersion: 1,
+    status: "superseded",
+    supersededEntryId: value.supersededEntryId,
+    replacementEntryId: value.replacementEntryId,
+    decision: { accepted: true, p_true: value.decision.p_true, confidence: value.decision.confidence },
+  };
+}
+
+function unresolvedStatuses(branch: SessionEntry[]): Map<string, MemoryStatus> {
+  const statuses = new Map<string, MemoryStatus>();
+  for (const entry of branch) {
+    if (isCustomEntry(entry, OBSERVATION_TYPE) || isCustomEntry(entry, REFLECTION_TYPE)) {
+      statuses.set(entry.id, { status: "unresolved" });
+    }
+  }
+  return statuses;
+}
+
+function isCustomEntry(entry: unknown, customType: string): entry is Extract<SessionEntry, { type: "custom" }> {
+  return isRecord(entry) && entry.type === "custom" && entry.customType === customType && typeof entry.id === "string";
+}
+
+function isMessageEntry(entry: unknown): entry is Extract<SessionEntry, { type: "message" }> {
+  return isRecord(entry) && entry.type === "message" && typeof entry.id === "string" && isRecord(entry.message) &&
+    ["user", "assistant", "toolResult"].includes(String(entry.message.role));
+}
+
+function isObservationData(value: unknown): value is ObservationData {
+  return isRecord(value) && value.schemaVersion === 1 && isMemoryText(value.text) && Array.isArray(value.sourceEntryIds) &&
+    value.sourceEntryIds.length > 0 && value.sourceEntryIds.length <= MAX_RAW_SOURCES && value.sourceEntryIds.every(isEntryId) &&
+    new Set(value.sourceEntryIds).size === value.sourceEntryIds.length;
+}
+
+function isReflectionData(value: unknown): value is ReflectionData {
+  return isRecord(value) && value.schemaVersion === 1 && isMemoryText(value.text) && Array.isArray(value.supportingObservationIds) &&
+    value.supportingObservationIds.length > 0 && value.supportingObservationIds.length <= MAX_REFLECTION_SOURCES &&
+    value.supportingObservationIds.every(isEntryId) && new Set(value.supportingObservationIds).size === value.supportingObservationIds.length;
+}
+
+function isMemoryText(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= MAX_MEMORY_TEXT_CHARS;
+}
+
+function isEntryId(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= MAX_ENTRY_ID_CHARS;
+}
+
+function isProbability(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: string[]): boolean {
+  return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/worker/__init__.py

@@ -0,0 +1 @@
+"""Pinned, local Laya gate worker."""

package/worker/__main__.py

@@ -0,0 +1,31 @@
+"""Run one persistent JSONL worker process."""
+
+import sys
+
+
+PYTHON_VERSION_ERROR = "Laya worker requires Python 3.11; set PI_SESSION_MEMORY_PYTHON to a Python 3.11 interpreter."
+
+
+def main() -> int:
+    if sys.version_info[:2] != (3, 11):
+        print(PYTHON_VERSION_ERROR, file=sys.stderr, flush=True)
+        return 1
+
+    from contextlib import redirect_stdout
+
+    from worker.laya_runtime import LayaEvaluator
+    from worker.protocol import serve
+
+    try:
+        with redirect_stdout(sys.stderr):
+            evaluator = LayaEvaluator()
+    except Exception as error:
+        print(f"Laya worker startup failed ({type(error).__name__}).", file=sys.stderr, flush=True)
+        return 1
+
+    serve(sys.stdin.buffer, sys.stdout.buffer, sys.stderr, evaluator.evaluate)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())