@evo-dev/core 0.0.1-alpha.2 → 0.0.1-alpha.20

package/src/evolution/evidence/session-memory/storage.ts

@@ -0,0 +1,744 @@
+import { randomUUID } from "node:crypto";
+import {
+  appendFile,
+  chmod,
+  link,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolveEvoDevPaths } from "../../../config/paths.ts";
+import { isFileExistsError, isNotFoundError, sha256Hex } from "../../../utils/index.ts";
+import { resolveSessionMemoryPaths } from "./paths.ts";
+import { detectSessionMemorySensitivity, mergeSessionMemorySensitivity } from "./sensitivity.ts";
+import type {
+  SessionEvidenceSegmentV1,
+  SessionMemoryCursorV1,
+  SessionMemoryIndexSegment,
+  SessionMemoryPaths,
+  SessionMemoryRawEventV1,
+  SessionMemorySensitivity,
+  SessionMemorySensitivityReason,
+  SessionMemoryStateV1,
+} from "./types.ts";
+
+export class SessionMemoryEvidenceError extends Error {
+  readonly code: "not-found" | "invalid";
+
+  constructor(code: "not-found" | "invalid", message: string) {
+    super(message);
+    this.name = "SessionMemoryEvidenceError";
+    this.code = code;
+  }
+}
+
+export async function listSessionEvidenceSegments(input: {
+  homeDir: string;
+  projectKey?: string;
+}): Promise<SessionEvidenceSegmentV1[]> {
+  const rootDir = join(resolveEvoDevPaths(input.homeDir).stateDir, "session-memory");
+  const projectDirs =
+    input.projectKey === undefined ? await listDirectoryNames(rootDir) : [input.projectKey];
+  const segments: SessionEvidenceSegmentV1[] = [];
+  for (const projectKey of projectDirs) {
+    const paths = resolveSessionMemoryPaths({
+      homeDir: input.homeDir,
+      projectKey,
+      sessionKey: "list",
+    });
+    for (const sessionKey of await listDirectoryNames(paths.projectDir)) {
+      const sessionPaths = resolveSessionMemoryPaths({
+        homeDir: input.homeDir,
+        projectKey,
+        sessionKey,
+      });
+      for (const entry of await listJsonFiles(sessionPaths.segmentsDir)) {
+        try {
+          segments.push(parseSessionEvidenceSegment(JSON.parse(await readFile(entry, "utf8"))));
+        } catch {
+          // Invalid local evidence is omitted from listings and remains available for diagnostics.
+        }
+      }
+    }
+  }
+  return segments.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+
+export async function listSessionMemoryStates(input: {
+  homeDir: string;
+  projectKey?: string;
+}): Promise<SessionMemoryStateV1[]> {
+  const rootDir = join(resolveEvoDevPaths(input.homeDir).stateDir, "session-memory");
+  const projectDirs =
+    input.projectKey === undefined ? await listDirectoryNames(rootDir) : [input.projectKey];
+  const states: SessionMemoryStateV1[] = [];
+  for (const projectKey of projectDirs) {
+    const projectDir = join(rootDir, projectKey);
+    for (const sessionKey of await listDirectoryNames(projectDir)) {
+      try {
+        const state = parseSessionMemoryState(
+          JSON.parse(await readFile(join(projectDir, sessionKey, "state.json"), "utf8")) as unknown,
+        );
+        if (state.projectKey === projectKey && state.sessionKey === sessionKey) states.push(state);
+      } catch {
+        // Invalid local state is omitted from listings and remains available for diagnostics.
+      }
+    }
+  }
+  return states.sort(
+    (left, right) =>
+      right.updatedAt.localeCompare(left.updatedAt) ||
+      left.sessionKey.localeCompare(right.sessionKey),
+  );
+}
+
+export async function readSessionEvidenceSegment(input: {
+  homeDir: string;
+  projectKey: string;
+  sessionKey: string;
+  segmentId: string;
+}): Promise<SessionEvidenceSegmentV1> {
+  const paths = resolveSessionMemoryPaths(input);
+  try {
+    const segment = parseSessionEvidenceSegment(
+      JSON.parse(await readFile(paths.segmentPath(input.segmentId), "utf8")) as unknown,
+    );
+    if (
+      segment.id !== input.segmentId ||
+      segment.projectKey !== input.projectKey ||
+      segment.sessionKey !== input.sessionKey
+    ) {
+      throw new SessionMemoryEvidenceError(
+        "invalid",
+        "Session evidence identity does not match its storage path.",
+      );
+    }
+    return segment;
+  } catch (error) {
+    if (error instanceof SessionMemoryEvidenceError) throw error;
+    if (isNotFoundError(error)) {
+      throw new SessionMemoryEvidenceError("not-found", "Session evidence segment was not found.");
+    }
+    throw new SessionMemoryEvidenceError("invalid", "Session evidence segment is invalid.");
+  }
+}
+
+export async function updateSessionEvidenceSegmentLifecycle(input: {
+  homeDir: string;
+  projectKey: string;
+  sessionKey: string;
+  segmentId: string;
+  status: "distilled" | "ignored";
+  consumedByBatchId?: string;
+}): Promise<SessionEvidenceSegmentV1> {
+  const segment = await readSessionEvidenceSegment(input);
+  const consumedByBatchIds =
+    input.consumedByBatchId === undefined
+      ? segment.lifecycle.consumedByBatchIds
+      : [...new Set([...segment.lifecycle.consumedByBatchIds, input.consumedByBatchId])];
+  const updated: SessionEvidenceSegmentV1 = {
+    ...segment,
+    lifecycle: {
+      ...segment.lifecycle,
+      status: input.status,
+      consumedByBatchIds,
+    },
+  };
+  const paths = resolveSessionMemoryPaths(input);
+  await writeJson(paths.segmentPath(input.segmentId), updated);
+  return updated;
+}
+
+export async function readSessionState(path: string): Promise<SessionMemoryStateV1 | null> {
+  try {
+    return JSON.parse(await readFile(path, "utf8")) as SessionMemoryStateV1;
+  } catch (error) {
+    if (isNotFoundError(error)) return null;
+    throw error;
+  }
+}
+
+export async function readSessionCursor(
+  path: string,
+  sessionKey: string,
+  sourcePath: string,
+  now: string,
+): Promise<SessionMemoryCursorV1> {
+  try {
+    return JSON.parse(await readFile(path, "utf8")) as SessionMemoryCursorV1;
+  } catch (error) {
+    if (!isNotFoundError(error)) throw error;
+    return {
+      schemaVersion: 1,
+      kind: "session-memory-cursor",
+      sessionKey,
+      traceRefId: null,
+      sourcePath,
+      lastCapturedOffset: null,
+      lastCapturedLine: null,
+      lastCapturedEventId: null,
+      updatedAt: now,
+    };
+  }
+}
+
+export async function appendRawEvent(
+  path: string,
+  event: SessionMemoryRawEventV1,
+): Promise<{ lineNumber: number }> {
+  const existingLineCount = await countJsonlLines(path);
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, `${JSON.stringify(event)}\n`, "utf8");
+  return { lineNumber: existingLineCount + 1 };
+}
+
+export async function resetSessionRawEvents(path: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path, "", { encoding: "utf8", mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+export async function rewriteSessionRawEvents(
+  path: string,
+  lines: string[],
+  expectedCurrent: string,
+): Promise<boolean> {
+  await ensurePrivateSessionMemoryDirectory(dirname(path));
+  const temporaryPath = join(dirname(path), `.${randomUUID()}.tmp`);
+  try {
+    const handle = await open(temporaryPath, "wx", 0o600);
+    try {
+      await handle.writeFile(lines.length === 0 ? "" : `${lines.join("\n")}\n`, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    const current = await readFile(path, "utf8").catch(() => null);
+    if (current !== expectedCurrent) return false;
+    await rename(temporaryPath, path);
+    await chmod(path, 0o600);
+    return true;
+  } finally {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+  }
+}
+
+export async function readLineRange(
+  path: string,
+  fromLine: number,
+  toLine: number,
+): Promise<{
+  content: string;
+  truncated: boolean;
+  secretsDetected: boolean;
+  sensitivity: SessionMemorySensitivity;
+  sensitivityReasons: SessionMemorySensitivityReason[];
+  redactionApplied: boolean;
+}> {
+  const text = await readFile(path, "utf8");
+  const lines = text.split("\n").filter((line) => line.trim() !== "");
+  const selected = lines.slice(Math.max(0, fromLine - 1), toLine);
+  const detections = [];
+  let redactionApplied = false;
+  for (const line of selected) {
+    try {
+      const parsed = JSON.parse(line) as Partial<SessionMemoryRawEventV1>;
+      redactionApplied ||= parsed.credentialRedactionApplied === true;
+      if (parsed.sensitivity !== undefined) {
+        detections.push({
+          classification: parsed.sensitivity,
+          reasons: [...(parsed.sensitivityReasons ?? [])],
+        });
+      } else if (typeof parsed.rawPayloadJson === "string") {
+        try {
+          detections.push(
+            detectSessionMemorySensitivity(JSON.parse(parsed.rawPayloadJson) as unknown),
+          );
+        } catch {
+          detections.push(detectSessionMemorySensitivity(parsed.rawPayloadJson));
+        }
+      } else if (parsed.secretsDetected === true) {
+        detections.push({
+          classification: "credential" as const,
+          reasons: ["legacy-sensitive-flag" as const],
+        });
+      }
+    } catch {
+      detections.push(detectSessionMemorySensitivity(line));
+    }
+  }
+  const sensitivity = mergeSessionMemorySensitivity(detections);
+  return {
+    content: selected.join("\n"),
+    truncated: false,
+    secretsDetected: sensitivity.classification === "credential",
+    sensitivity: sensitivity.classification,
+    sensitivityReasons: sensitivity.reasons,
+    redactionApplied,
+  };
+}
+
+export async function writeSessionIndex(
+  paths: SessionMemoryPaths,
+  state: SessionMemoryStateV1,
+  segment: SessionEvidenceSegmentV1,
+  now: string,
+): Promise<void> {
+  const existing = await readSessionIndex(paths.indexPath);
+  const segments = [
+    ...existing.segments.filter((item) => item.id !== segment.id),
+    {
+      id: segment.id,
+      reason: segment.reason,
+      strength: segment.strength,
+      createdAt: segment.createdAt,
+      reviewState: segment.lifecycle.reviewState,
+    },
+  ];
+  await writeJson(paths.indexPath, {
+    schemaVersion: 1,
+    kind: "session-memory-index",
+    projectKey: state.projectKey,
+    sessionKey: state.sessionKey,
+    updatedAt: now,
+    lastSegmentId: segment.id,
+    segments,
+  });
+}
+
+export async function writeHistoricalSessionEvidenceSegment(input: {
+  homeDir: string;
+  paths: SessionMemoryPaths;
+  segment: SessionEvidenceSegmentV1;
+}): Promise<{ created: boolean; segment: SessionEvidenceSegmentV1 }> {
+  if (input.segment.origin?.kind !== "historical-import" || input.segment.retention === undefined) {
+    throw new Error("Historical Session Evidence requires origin and retention metadata.");
+  }
+  assertSessionMemoryPathsMatchSegment(input.homeDir, input.paths, input.segment);
+  await ensurePrivateSessionMemoryDirectory(input.paths.segmentsDir);
+  const path = input.paths.segmentPath(input.segment.id);
+  const created = await writePrivateImmutableText(
+    path,
+    `${JSON.stringify(input.segment, null, 2)}\n`,
+  );
+  if (created) {
+    return { created: true, segment: input.segment };
+  }
+  const existingInfo = await lstat(path);
+  if (!existingInfo.isFile() || existingInfo.isSymbolicLink()) {
+    throw new Error("Historical Session Evidence path is not a regular state file.");
+  }
+  const existing = await readSessionEvidenceSegment({
+    homeDir: input.homeDir,
+    projectKey: input.segment.projectKey,
+    sessionKey: input.segment.sessionKey,
+    segmentId: input.segment.id,
+  });
+  assertHistoricalSegmentCompatible(existing, input.segment);
+  await chmod(path, 0o600);
+  return { created: false, segment: existing };
+}
+
+export async function writeHistoricalSessionStateAndIndex(input: {
+  homeDir: string;
+  paths: SessionMemoryPaths;
+  projectKey: string;
+  sessionKey: string;
+  target: SessionMemoryStateV1["target"];
+  roleId: string | null;
+  policy: SessionMemoryStateV1["policy"];
+  now: string;
+}): Promise<{ state: SessionMemoryStateV1; segmentIds: string[] }> {
+  const expectedPaths = resolveSessionMemoryPaths({
+    homeDir: input.homeDir,
+    projectKey: input.projectKey,
+    sessionKey: input.sessionKey,
+  });
+  if (
+    expectedPaths.rootDir !== input.paths.rootDir ||
+    expectedPaths.projectDir !== input.paths.projectDir ||
+    expectedPaths.sessionDir !== input.paths.sessionDir ||
+    expectedPaths.segmentsDir !== input.paths.segmentsDir ||
+    expectedPaths.statePath !== input.paths.statePath ||
+    expectedPaths.indexPath !== input.paths.indexPath
+  ) {
+    throw new Error("Historical Session Memory state path does not match its identity.");
+  }
+  await ensurePrivateSessionMemoryDirectory(input.paths.rootDir);
+  await ensurePrivateSessionMemoryDirectory(input.paths.projectDir);
+  await ensurePrivateSessionMemoryDirectory(input.paths.sessionDir);
+  await ensurePrivateSessionMemoryDirectory(input.paths.segmentsDir);
+  const existing = await readSessionState(input.paths.statePath);
+  const segments = await readSessionSegmentsFromDirectory(input.paths.segmentsDir);
+  const ordered = segments.sort(
+    (left, right) =>
+      left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id),
+  );
+  const last = ordered.at(-1) ?? null;
+  const state: SessionMemoryStateV1 = {
+    schemaVersion: 1,
+    kind: "session-memory-state",
+    projectKey: input.projectKey,
+    sessionKey: input.sessionKey,
+    target: input.target,
+    runId: null,
+    roleId: input.roleId,
+    initialized: true,
+    createdAt: existing?.createdAt ?? input.now,
+    updatedAt: input.now,
+    counters: existing?.counters ?? {
+      messageTokenEstimate: 0,
+      tokensSinceLastUpdate: 0,
+      toolCallsSinceLastUpdate: 0,
+      userPromptCount: 0,
+      assistantTurnCount: 0,
+      toolCallCount: 0,
+      failureSignalCount: 0,
+      verificationSignalCount: 0,
+    },
+    activeSpan: null,
+    pendingSignals: [],
+    lastSegmentId: last?.id ?? null,
+    lastMemoryUpdateAt: input.now,
+    policy: input.policy,
+  };
+  const index = {
+    schemaVersion: 1,
+    kind: "session-memory-index",
+    projectKey: input.projectKey,
+    sessionKey: input.sessionKey,
+    updatedAt: input.now,
+    lastSegmentId: last?.id ?? null,
+    segments: ordered.map((segment) => ({
+      id: segment.id,
+      reason: segment.reason,
+      strength: segment.strength,
+      createdAt: segment.createdAt,
+      reviewState: segment.lifecycle.reviewState,
+    })),
+  };
+  await writePrivateAtomicJson(input.paths.statePath, state);
+  await writePrivateAtomicJson(input.paths.indexPath, index);
+  return { state, segmentIds: ordered.map((segment) => segment.id) };
+}
+
+export async function writeSessionEvidenceSegmentAtomic(input: {
+  homeDir: string;
+  segment: SessionEvidenceSegmentV1;
+}): Promise<void> {
+  assertSessionEvidenceRetentionState(input.segment);
+  const paths = resolveSessionMemoryPaths({
+    homeDir: input.homeDir,
+    projectKey: input.segment.projectKey,
+    sessionKey: input.segment.sessionKey,
+  });
+  await writePrivateAtomicJson(paths.segmentPath(input.segment.id), input.segment);
+}
+
+function assertSessionEvidenceRetentionState(segment: SessionEvidenceSegmentV1): void {
+  if (segment.retention === undefined) {
+    throw new Error("Atomic Session Evidence rewrite requires retention metadata.");
+  }
+  if (segment.retention.rawState === "available") {
+    if (
+      !segment.rawExcerpt.stored ||
+      segment.rawExcerpt.byteLength !== Buffer.byteLength(segment.rawExcerpt.content, "utf8") ||
+      segment.rawExcerpt.sha256 !== sha256Hex(segment.rawExcerpt.content) ||
+      segment.retention.originalRawSha256 !== segment.rawExcerpt.sha256
+    ) {
+      throw new Error("Available Session Evidence raw state is invalid.");
+    }
+    return;
+  }
+  if (
+    segment.rawExcerpt.stored ||
+    segment.rawExcerpt.content !== "" ||
+    segment.rawExcerpt.byteLength !== 0 ||
+    segment.rawExcerpt.sha256 !== sha256Hex("") ||
+    segment.retention.rawPurgedAt === null ||
+    segment.lifecycle.status !== "raw-expired"
+  ) {
+    throw new Error("Purged Session Evidence raw state is invalid.");
+  }
+}
+
+export async function writeJson(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+async function readSessionSegmentsFromDirectory(
+  segmentsDir: string,
+): Promise<SessionEvidenceSegmentV1[]> {
+  const segments: SessionEvidenceSegmentV1[] = [];
+  for (const path of await listJsonFiles(segmentsDir)) {
+    segments.push(parseSessionEvidenceSegment(JSON.parse(await readFile(path, "utf8"))));
+  }
+  return segments;
+}
+
+async function ensurePrivateSessionMemoryDirectory(path: string): Promise<void> {
+  await mkdir(path, { recursive: true, mode: 0o700 });
+  await chmod(path, 0o700);
+}
+
+async function writePrivateAtomicJson(path: string, value: unknown): Promise<void> {
+  await ensurePrivateSessionMemoryDirectory(dirname(path));
+  const temporaryPath = join(dirname(path), `.${randomUUID()}.tmp`);
+  try {
+    const handle = await open(temporaryPath, "wx", 0o600);
+    try {
+      await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporaryPath, path);
+    await chmod(path, 0o600);
+  } finally {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+  }
+}
+
+async function writePrivateImmutableText(path: string, content: string): Promise<boolean> {
+  await ensurePrivateSessionMemoryDirectory(dirname(path));
+  const temporaryPath = join(dirname(path), `.${randomUUID()}.tmp`);
+  try {
+    const handle = await open(temporaryPath, "wx", 0o600);
+    try {
+      await handle.writeFile(content, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    try {
+      await link(temporaryPath, path);
+      await chmod(path, 0o600);
+      return true;
+    } catch (error) {
+      if (!isFileExistsError(error)) throw error;
+      return false;
+    }
+  } finally {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+  }
+}
+
+function assertHistoricalSegmentCompatible(
+  existing: SessionEvidenceSegmentV1,
+  expected: SessionEvidenceSegmentV1,
+): void {
+  const existingOrigin = existing.origin;
+  const expectedOrigin = expected.origin;
+  const existingRetention = existing.retention;
+  const expectedRetention = expected.retention;
+  if (
+    existingOrigin?.kind !== "historical-import" ||
+    expectedOrigin?.kind !== "historical-import" ||
+    existingRetention === undefined ||
+    expectedRetention === undefined
+  ) {
+    throw new Error("Historical Session Evidence identity conflict.");
+  }
+  const existingProjection = {
+    schemaVersion: existing.schemaVersion,
+    kind: existing.kind,
+    id: existing.id,
+    projectKey: existing.projectKey,
+    runId: existing.runId,
+    roleId: existing.roleId,
+    sessionKey: existing.sessionKey,
+    target: existing.target,
+    createdAt: existing.createdAt,
+    reason: existing.reason,
+    strength: existing.strength,
+    origin: existingOrigin,
+    source: existing.source,
+    signals: existing.signals,
+    normalized: existing.normalized,
+    privacy: {
+      localOnly: existing.privacy.localOnly,
+      secretsDetected: existing.privacy.secretsDetected,
+      sensitivity: existing.privacy.sensitivity,
+      sensitivityReasons: existing.privacy.sensitivityReasons,
+      redactionApplied: existing.privacy.redactionApplied,
+      externalUploadAllowed: existing.privacy.externalUploadAllowed,
+    },
+    rawTruncated: existing.rawExcerpt.truncated,
+    originalRawSha256: existingRetention.originalRawSha256,
+    retentionPolicyDays: existingRetention.policyDays,
+    retentionExpiresAt: existingRetention.expiresAt,
+  };
+  const expectedProjection = {
+    schemaVersion: expected.schemaVersion,
+    kind: expected.kind,
+    id: expected.id,
+    projectKey: expected.projectKey,
+    runId: expected.runId,
+    roleId: expected.roleId,
+    sessionKey: expected.sessionKey,
+    target: expected.target,
+    createdAt: expected.createdAt,
+    reason: expected.reason,
+    strength: expected.strength,
+    origin: expectedOrigin,
+    source: expected.source,
+    signals: expected.signals,
+    normalized: expected.normalized,
+    privacy: {
+      localOnly: expected.privacy.localOnly,
+      secretsDetected: expected.privacy.secretsDetected,
+      sensitivity: expected.privacy.sensitivity,
+      sensitivityReasons: expected.privacy.sensitivityReasons,
+      redactionApplied: expected.privacy.redactionApplied,
+      externalUploadAllowed: expected.privacy.externalUploadAllowed,
+    },
+    rawTruncated: expected.rawExcerpt.truncated,
+    originalRawSha256: expectedRetention.originalRawSha256,
+    retentionPolicyDays: expectedRetention.policyDays,
+    retentionExpiresAt: expectedRetention.expiresAt,
+  };
+  if (
+    JSON.stringify(existingProjection) !== JSON.stringify(expectedProjection) ||
+    (existingRetention.rawState === "available" &&
+      (!existing.rawExcerpt.stored ||
+        existing.rawExcerpt.encoding !== "utf8" ||
+        existing.rawExcerpt.byteLength !== Buffer.byteLength(existing.rawExcerpt.content, "utf8") ||
+        existing.rawExcerpt.sha256 !== sha256Hex(existing.rawExcerpt.content) ||
+        existing.rawExcerpt.sha256 !== expected.rawExcerpt.sha256))
+  ) {
+    throw new Error("Historical Session Evidence immutable content conflict.");
+  }
+}
+
+function assertSessionMemoryPathsMatchSegment(
+  homeDir: string,
+  paths: SessionMemoryPaths,
+  segment: SessionEvidenceSegmentV1,
+): void {
+  const expected = resolveSessionMemoryPaths({
+    homeDir,
+    projectKey: segment.projectKey,
+    sessionKey: segment.sessionKey,
+  });
+  if (
+    paths.rootDir !== expected.rootDir ||
+    paths.projectDir !== expected.projectDir ||
+    paths.sessionDir !== expected.sessionDir ||
+    paths.segmentsDir !== expected.segmentsDir ||
+    paths.segmentPath(segment.id) !== expected.segmentPath(segment.id)
+  ) {
+    throw new Error("Historical Session Evidence path does not match its identity.");
+  }
+}
+
+async function countJsonlLines(path: string): Promise<number> {
+  try {
+    const text = await readFile(path, "utf8");
+    return text.split("\n").filter((line) => line.trim() !== "").length;
+  } catch (error) {
+    if (isNotFoundError(error)) return 0;
+    throw error;
+  }
+}
+
+async function readSessionIndex(path: string): Promise<{ segments: SessionMemoryIndexSegment[] }> {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8")) as {
+      segments?: unknown;
+    };
+    if (!Array.isArray(parsed.segments)) return { segments: [] };
+    return {
+      segments: parsed.segments.filter(isSessionIndexSegment),
+    };
+  } catch (error) {
+    if (isNotFoundError(error)) return { segments: [] };
+    throw error;
+  }
+}
+
+function isSessionIndexSegment(value: unknown): value is SessionMemoryIndexSegment {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const item = value as Record<string, unknown>;
+  return (
+    typeof item.id === "string" &&
+    typeof item.reason === "string" &&
+    typeof item.strength === "string" &&
+    typeof item.createdAt === "string" &&
+    typeof item.reviewState === "string"
+  );
+}
+
+function parseSessionEvidenceSegment(value: unknown): SessionEvidenceSegmentV1 {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new SessionMemoryEvidenceError("invalid", "Session evidence must be an object.");
+  }
+  const segment = value as Partial<SessionEvidenceSegmentV1>;
+  if (
+    segment.schemaVersion !== 1 ||
+    segment.kind !== "session-evidence-segment" ||
+    typeof segment.id !== "string" ||
+    typeof segment.projectKey !== "string" ||
+    typeof segment.sessionKey !== "string" ||
+    typeof segment.createdAt !== "string" ||
+    typeof segment.normalized !== "object" ||
+    segment.normalized === null ||
+    typeof segment.rawExcerpt !== "object" ||
+    segment.rawExcerpt === null
+  ) {
+    throw new SessionMemoryEvidenceError("invalid", "Session evidence fields are invalid.");
+  }
+  return segment as SessionEvidenceSegmentV1;
+}
+
+function parseSessionMemoryState(value: unknown): SessionMemoryStateV1 {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new SessionMemoryEvidenceError("invalid", "Session Memory state must be an object.");
+  }
+  const state = value as Partial<SessionMemoryStateV1>;
+  if (
+    state.schemaVersion !== 1 ||
+    state.kind !== "session-memory-state" ||
+    typeof state.projectKey !== "string" ||
+    typeof state.sessionKey !== "string" ||
+    !(state.runId === null || typeof state.runId === "string") ||
+    !(state.roleId === null || typeof state.roleId === "string") ||
+    typeof state.createdAt !== "string" ||
+    typeof state.updatedAt !== "string" ||
+    typeof state.counters !== "object" ||
+    state.counters === null
+  ) {
+    throw new SessionMemoryEvidenceError("invalid", "Session Memory state fields are invalid.");
+  }
+  return state as SessionMemoryStateV1;
+}
+
+async function listDirectoryNames(path: string): Promise<string[]> {
+  try {
+    return (await readdir(path, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    throw error;
+  }
+}
+
+async function listJsonFiles(path: string): Promise<string[]> {
+  try {
+    return (await readdir(path, { withFileTypes: true }))
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => join(path, entry.name))
+      .sort();
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    throw error;
+  }
+}