ds4-context-engine 0.1.2 → 0.2.0-beta.2

package/src/pi-adapter/local-embedding.ts

@@ -0,0 +1,132 @@
+import type {
+  EmbeddingModelIdentity,
+  EmbeddingPort,
+} from "ds4-context-core/retrieval/embedding";
+import { sha256 } from "ds4-context-core/shared/hash";
+
+const CONCEPTS: Readonly<Record<string, string>> = {
+  auth: "auth",
+  authentication: "auth",
+  authorize: "auth",
+  authorization: "auth",
+  credential: "credential",
+  credentials: "credential",
+  password: "credential",
+  secret: "credential",
+  token: "credential",
+  cache: "cache",
+  cached: "cache",
+  caching: "cache",
+  reuse: "cache",
+  memoize: "cache",
+  database: "database",
+  datastore: "database",
+  persistence: "database",
+  sqlite: "database",
+  storage: "database",
+  crash: "failure",
+  error: "failure",
+  errors: "failure",
+  fail: "failure",
+  failed: "failure",
+  failure: "failure",
+  exception: "failure",
+  delete: "remove",
+  deleted: "remove",
+  deletion: "remove",
+  purge: "remove",
+  remove: "remove",
+  refresh: "renew",
+  renew: "renew",
+  renewal: "renew",
+  rotate: "renew",
+  expiry: "expire",
+  expired: "expire",
+  expiration: "expire",
+  timeout: "timeout",
+  timedout: "timeout",
+  latency: "performance",
+  performance: "performance",
+  slow: "performance",
+  optimize: "performance",
+  optimization: "performance",
+  validate: "validate",
+  validation: "validate",
+  verify: "validate",
+  verification: "validate",
+  check: "validate",
+  config: "configuration",
+  configuration: "configuration",
+  setting: "configuration",
+  settings: "configuration",
+  index: "index",
+  indexing: "index",
+  search: "retrieval",
+  retrieve: "retrieval",
+  retrieval: "retrieval",
+  lookup: "retrieval",
+};
+
+function stem(token: string): string {
+  if (token.length > 6 && token.endsWith("ing")) return token.slice(0, -3);
+  if (token.length > 5 && token.endsWith("ed")) return token.slice(0, -2);
+  if (token.length > 5 && token.endsWith("es")) return token.slice(0, -2);
+  if (token.length > 4 && token.endsWith("s")) return token.slice(0, -1);
+  return token;
+}
+
+function canonical(token: string): string {
+  const lower = token.toLocaleLowerCase("en-US");
+  return CONCEPTS[lower] ?? CONCEPTS[stem(lower)] ?? stem(lower);
+}
+
+function tokens(text: string): string[] {
+  const separated = text
+    .replace(/([a-z0-9])([A-Z])/gu, "$1 $2")
+    .replace(/[_./\\:-]+/gu, " ")
+    .toLocaleLowerCase("en-US");
+  return [...separated.matchAll(/[\p{L}\p{N}]{2,}/gu)]
+    .map((match) => canonical(match[0]))
+    .filter((token) => token.length >= 2)
+    .slice(0, 20_000);
+}
+
+function addFeature(vector: number[], feature: string, weight: number): void {
+  const hash = sha256(feature);
+  const bucket = Number.parseInt(hash.slice(0, 8), 16) % vector.length;
+  const sign = Number.parseInt(hash.slice(8, 10), 16) % 2 === 0 ? 1 : -1;
+  vector[bucket] = (vector[bucket] ?? 0) + weight * sign;
+}
+
+function embedText(text: string, dimensions: number): readonly number[] {
+  const vector = Array.from({ length: dimensions }, () => 0);
+  const values = tokens(text);
+  const frequencies = new Map<string, number>();
+  for (const value of values) frequencies.set(value, (frequencies.get(value) ?? 0) + 1);
+  for (const [value, frequency] of frequencies) {
+    addFeature(vector, `token:${value}`, 1 + Math.log(frequency));
+  }
+  for (let index = 0; index + 1 < values.length; index++) {
+    addFeature(vector, `pair:${values[index]}:${values[index + 1]}`, 0.35);
+  }
+  if (values.length === 0) addFeature(vector, "empty", 1);
+  const magnitude = Math.sqrt(vector.reduce((total, value) => total + value * value, 0));
+  return magnitude > 0 ? vector.map((value) => value / magnitude) : vector;
+}
+
+export class LocalFeatureHashEmbedding implements EmbeddingPort {
+  readonly identity: EmbeddingModelIdentity;
+
+  constructor(dimensions = 256) {
+    this.identity = {
+      provider: "ds4-local",
+      model: "feature-hash-v1",
+      dimensions,
+      destination: "local",
+    };
+  }
+
+  embed(texts: readonly string[]): readonly (readonly number[])[] {
+    return texts.map((text) => embedText(text, this.identity.dimensions));
+  }
+}

package/src/pi-adapter/memory-adapter.ts

@@ -1,5 +1,5 @@
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
-import { readJsonlRecords } from "./session-jsonl.ts";
+import { readJsonlRecords, type JsonlRecord } from "./session-jsonl.ts";
 import {
   MEMORY_CUSTOM_ENTRY_TYPE,
   PIN_CUSTOM_ENTRY_TYPE,
@@ -37,23 +37,31 @@ export function projectSessionFileMutations(
   sessionFile: string,
   sessionId: string,
 ): SessionMutationProjection {
-  const entries = readJsonlRecords(sessionFile).records.flatMap((record) => {
+  return projectJsonlMutations(readJsonlRecords(sessionFile).records, sessionId);
+}
+
+export function projectJsonlMutations(
+  records: readonly JsonlRecord[],
+  sessionId: string,
+  entryOrderOffset = 0,
+): SessionMutationProjection {
+  const entries = records.flatMap((record) => {
     const value = record.value;
-    if (value.type !== "custom"
+    if (value.type === "session"
       || typeof value.id !== "string"
       || (typeof value.parentId !== "string" && value.parentId !== null)
-      || typeof value.timestamp !== "string"
-      || typeof value.customType !== "string") {
+      || typeof value.timestamp !== "string") {
       return [];
     }
     return [value as unknown as SessionEntry];
   });
-  return projectSessionMutations(entries, sessionId);
+  return projectSessionMutations(entries, sessionId, entryOrderOffset);
 }
 
 export function projectSessionMutations(
   entries: readonly SessionEntry[],
   sessionId: string,
+  entryOrderOffset = 0,
 ): SessionMutationProjection {
   const memoryMutations: StoredMemoryMutation[] = [];
   const pinMutations: StoredPinMutation[] = [];
@@ -81,7 +89,8 @@ export function projectSessionMutations(
         mutationId: parsed.mutationId,
         sessionId,
         createdAt,
-        entryOrder,
+        entryOrder: entryOrderOffset + entryOrder,
+        ...(entry.parentId ? { sourceParentEntryId: entry.parentId } : {}),
         payload: normalizeMemoryTimestamp(parsed, createdAt),
       });
       continue;
@@ -103,7 +112,8 @@ export function projectSessionMutations(
         mutationId: parsed.mutationId,
         sessionId,
         createdAt,
-        entryOrder,
+        entryOrder: entryOrderOffset + entryOrder,
+        ...(entry.parentId ? { sourceParentEntryId: entry.parentId } : {}),
         payload: normalizePinTimestamp(parsed, createdAt),
       });
     }

package/src/pi-adapter/project-memory-sync.ts

@@ -0,0 +1,499 @@
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type {
+  CrossSessionMemoryDiagnostics,
+  MemoryMaterializationResult,
+  ProjectMemorySource,
+  SessionMutationProjection,
+} from "ds4-context-core/memory/memory-types";
+import type {
+  MemoryRepository,
+  ProjectMemorySourceCheckpoint,
+} from "ds4-context-core/persistence/repositories/memory-repository";
+import type { Logger } from "ds4-context-core/shared/logging";
+import { silentLogger } from "ds4-context-core/shared/logging";
+import { projectJsonlMutations } from "./memory-adapter.ts";
+import {
+  hashFileRange,
+  readJsonlRecords,
+  readSessionHeaderRecord,
+  type JsonlReadResult,
+  type SessionHeaderRecord,
+} from "./session-jsonl.ts";
+import { PiSessionIndexer } from "./session-indexer.ts";
+
+const SUPPORTED_SESSION_VERSION = 3;
+
+export interface ProjectMemorySynchronizerOptions {
+  projectPath: string;
+  activeSessionId: string;
+  activeSessionFile: string;
+  maxSessions: number;
+  logger?: Logger;
+  now?: () => number;
+}
+
+function canonicalPath(path: string): string {
+  const absolute = resolve(path);
+  try {
+    return realpathSync.native(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+function comparablePath(path: string): string {
+  const canonical = canonicalPath(path);
+  return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function sourceCheckpoint(
+  projectPath: string,
+  sessionId: string,
+  sessionFile: string,
+  header: SessionHeaderRecord,
+  read: JsonlReadResult,
+  indexedRecords: number,
+  indexedMutations: number,
+  malformedLines: number,
+  indexedAt: number,
+  previous?: ProjectMemorySourceCheckpoint,
+): ProjectMemorySourceCheckpoint {
+  const hasNewTerminatedLine = read.checkpointHash !== undefined;
+  return {
+    projectPath,
+    sessionId,
+    sessionFile,
+    headerHash: header.rawHash,
+    fileSize: read.fileSize,
+    fileMtimeMs: read.fileMtimeMs,
+    checkpointOffset: hasNewTerminatedLine
+      ? read.safeCheckpointOffset
+      : previous?.checkpointOffset ?? read.safeCheckpointOffset,
+    checkpointHashStart: hasNewTerminatedLine
+      ? read.checkpointHashStart
+      : previous?.checkpointHashStart ?? read.checkpointHashStart,
+    ...(hasNewTerminatedLine
+      ? { checkpointHash: read.checkpointHash }
+      : previous?.checkpointHash
+        ? { checkpointHash: previous.checkpointHash }
+        : {}),
+    indexedRecords,
+    indexedMutations,
+    malformedLines,
+    status: "ready",
+    indexedAt,
+  };
+}
+
+function mutationCount(projection: SessionMutationProjection): number {
+  const projectMemories = projection.memoryMutations.filter((stored) =>
+    stored.payload.operation === "status" || stored.payload.item.scope === "project"
+  ).length;
+  const projectPins = projection.pinMutations.filter((stored) =>
+    stored.payload.operation === "status" || stored.payload.item.scope === "project"
+  ).length;
+  return projectMemories + projectPins;
+}
+
+function diagnostics(
+  enabled: boolean,
+  sources: ProjectMemorySource[],
+  discoveredSessions: number,
+  refreshedSessions: number,
+  incrementalSessions: number,
+  rebuiltSessions: number,
+  warnings: string[],
+  lastSyncAt?: number,
+): CrossSessionMemoryDiagnostics {
+  return {
+    enabled,
+    status: enabled ? "ready" : "disabled",
+    discoveredSessions,
+    contributingSessions: sources.filter((source) =>
+      source.status === "ready" && source.indexedMutations > 0
+    ).length,
+    excludedSessions: sources.filter((source) => source.status === "excluded").length,
+    unavailableSessions: sources.filter((source) =>
+      source.status === "missing" || source.status === "corrupt"
+    ).length,
+    refreshedSessions,
+    incrementalSessions,
+    rebuiltSessions,
+    sources,
+    warnings,
+    ...(lastSyncAt !== undefined ? { lastSyncAt } : {}),
+  };
+}
+
+export class ProjectMemorySynchronizer {
+  private readonly projectPath: string;
+  private readonly comparableProjectPath: string;
+  private readonly logger: Logger;
+  private readonly now: () => number;
+
+  constructor(
+    private readonly repository: MemoryRepository,
+    private readonly indexer: PiSessionIndexer,
+    private readonly options: ProjectMemorySynchronizerOptions,
+  ) {
+    this.projectPath = canonicalPath(options.projectPath);
+    this.comparableProjectPath = comparablePath(this.projectPath);
+    this.logger = options.logger ?? silentLogger;
+    this.now = options.now ?? Date.now;
+  }
+
+  sync(): CrossSessionMemoryDiagnostics {
+    const warnings: string[] = [];
+    let discoveredSessions = 0;
+    let refreshedSessions = 0;
+    let incrementalSessions = 0;
+    let rebuiltSessions = 0;
+    let latestMaterializationWarnings: string[] = [];
+    const syncedAt = this.now();
+    const previousSources = this.repository.listProjectSources(this.projectPath);
+    const candidates = this.discoverCandidates(previousSources, warnings);
+    const seenSessionIds = new Set<string>();
+
+    for (const sessionFile of candidates) {
+      let header: SessionHeaderRecord;
+      try {
+        header = readSessionHeaderRecord(sessionFile);
+      } catch (error) {
+        const previous = previousSources.find((source) => source.sessionFile === sessionFile);
+        const message = `Project memory source ${sessionFile} has an invalid header: ${errorMessage(error)}`;
+        warnings.push(message);
+        if (previous) {
+          seenSessionIds.add(previous.sessionId);
+          const materialized = this.markSourceUnavailable(
+            previous.sessionId,
+            "corrupt",
+            message,
+            syncedAt,
+          );
+          if (materialized) latestMaterializationWarnings = materialized.warnings;
+        }
+        continue;
+      }
+
+      const headerCwd = header.value.cwd;
+      if (typeof headerCwd !== "string"
+        || comparablePath(headerCwd) !== this.comparableProjectPath) {
+        const previous = previousSources.find((source) => source.sessionFile === sessionFile);
+        if (previous) {
+          seenSessionIds.add(previous.sessionId);
+          const message = `Project memory source identity no longer matches ${this.projectPath}`;
+          warnings.push(`${sessionFile}: ${message}`);
+          const materialized = this.markSourceUnavailable(
+            previous.sessionId,
+            "corrupt",
+            message,
+            syncedAt,
+          );
+          if (materialized) latestMaterializationWarnings = materialized.warnings;
+        }
+        continue;
+      }
+      const version = header.value.version;
+      if (typeof version === "number" && version > SUPPORTED_SESSION_VERSION) {
+        const message = `Unsupported Pi session format v${version}`;
+        warnings.push(`${sessionFile}: ${message}`);
+        const previous = previousSources.find((source) => source.sessionFile === sessionFile);
+        if (previous) {
+          seenSessionIds.add(previous.sessionId);
+          const materialized = this.markSourceUnavailable(
+            previous.sessionId,
+            "corrupt",
+            message,
+            syncedAt,
+          );
+          if (materialized) latestMaterializationWarnings = materialized.warnings;
+        }
+        continue;
+      }
+      if (seenSessionIds.has(header.value.id)) {
+        warnings.push(`Duplicate Pi session id ${header.value.id} ignored at ${sessionFile}`);
+        continue;
+      }
+      seenSessionIds.add(header.value.id);
+      const crossSessionSource = header.value.id !== this.options.activeSessionId;
+      if (crossSessionSource) discoveredSessions++;
+
+      try {
+        const synced = this.syncSource(sessionFile, header, syncedAt, warnings);
+        if (synced.mode !== "noop") latestMaterializationWarnings = synced.materializationWarnings;
+        if (crossSessionSource && synced.mode !== "noop") refreshedSessions++;
+        if (crossSessionSource && synced.mode === "incremental") incrementalSessions++;
+        if (crossSessionSource && synced.mode === "rebuild") rebuiltSessions++;
+      } catch (error) {
+        const message = errorMessage(error);
+        const disposition = header.value.id === this.options.activeSessionId
+          ? "retained after refresh failure"
+          : "excluded";
+        warnings.push(`Project memory source ${header.value.id} ${disposition}: ${message}`);
+        const materialized = this.markSourceUnavailable(
+          header.value.id,
+          "corrupt",
+          message,
+          syncedAt,
+        );
+        if (materialized) latestMaterializationWarnings = materialized.warnings;
+        this.logger.warn("project_memory.source_failed", {
+          projectPath: this.projectPath,
+          sessionId: header.value.id,
+          sessionFile,
+          error: message,
+        });
+      }
+    }
+
+    const candidateSet = new Set(candidates.map((path) => resolve(path)));
+    for (const source of previousSources) {
+      if (seenSessionIds.has(source.sessionId)) continue;
+      const present = existsSync(source.sessionFile);
+      const message = present && !candidateSet.has(resolve(source.sessionFile))
+        ? `Project memory source is outside memory.maxProjectSessions: ${source.sessionFile}`
+        : `Canonical Pi session file is missing: ${source.sessionFile}`;
+      const materialized = this.markSourceUnavailable(
+        source.sessionId,
+        present ? "corrupt" : "missing",
+        message,
+        syncedAt,
+      );
+      if (materialized) latestMaterializationWarnings = materialized.warnings;
+      warnings.push(message);
+    }
+
+    const allSources = this.repository.listProjectSources(this.projectPath);
+    for (const source of allSources) {
+      if (source.malformedLines > 0) {
+        warnings.push(
+          `Project memory source ${source.sessionId} contains ${source.malformedLines} malformed JSONL line(s)`,
+        );
+      }
+      if (source.lastError && !warnings.some((warning) => warning.includes(source.lastError ?? ""))) {
+        warnings.push(`Project memory source ${source.sessionId}: ${source.lastError}`);
+      }
+    }
+    warnings.push(...latestMaterializationWarnings);
+    const uniqueWarnings = [...new Set(warnings)];
+    const sources = allSources.filter((source) =>
+      source.sessionId !== this.options.activeSessionId || source.status === "excluded"
+    );
+    const result = diagnostics(
+      true,
+      sources,
+      discoveredSessions,
+      refreshedSessions,
+      incrementalSessions,
+      rebuiltSessions,
+      uniqueWarnings,
+      syncedAt,
+    );
+    this.logger.debug("project_memory.synced", {
+      projectPath: this.projectPath,
+      discoveredSessions,
+      contributingSessions: result.contributingSessions,
+      refreshedSessions,
+      incrementalSessions,
+      rebuiltSessions,
+      warnings: uniqueWarnings.length,
+    });
+    return result;
+  }
+
+  setExcluded(sessionId: string, excluded: boolean, reason?: string): CrossSessionMemoryDiagnostics {
+    if (excluded && sessionId === this.options.activeSessionId) {
+      throw new Error("The active Pi session cannot be excluded as a project memory source");
+    }
+    const source = this.repository.listProjectSources(this.projectPath)
+      .find((candidate) => candidate.sessionId === sessionId);
+    if (!source) throw new Error(`Project memory source session ${sessionId} was not discovered`);
+    const materialized = this.repository.setProjectSourceExcluded(
+      this.projectPath,
+      sessionId,
+      excluded,
+      this.now(),
+      reason,
+    );
+    const result = this.sync();
+    return {
+      ...result,
+      warnings: [...new Set([...result.warnings, ...materialized.warnings])],
+    };
+  }
+
+  private markSourceUnavailable(
+    sessionId: string,
+    status: "missing" | "corrupt",
+    message: string,
+    indexedAt: number,
+  ): MemoryMaterializationResult | undefined {
+    if (sessionId === this.options.activeSessionId) {
+      this.logger.warn("project_memory.active_source_retained", {
+        projectPath: this.projectPath,
+        sessionId,
+        error: message,
+      });
+      return undefined;
+    }
+    return this.repository.markProjectSourceUnavailable(
+      this.projectPath,
+      sessionId,
+      status,
+      message,
+      indexedAt,
+    );
+  }
+
+  private discoverCandidates(
+    previousSources: readonly ProjectMemorySource[],
+    warnings: string[],
+  ): string[] {
+    const directory = dirname(this.options.activeSessionFile);
+    let names: string[] = [];
+    try {
+      names = readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .map((entry) => join(directory, entry.name))
+        .sort((left, right) => right.localeCompare(left));
+    } catch (error) {
+      warnings.push(`Unable to enumerate Pi project sessions in ${directory}: ${errorMessage(error)}`);
+    }
+
+    const active = resolve(this.options.activeSessionFile);
+    const siblings = names.filter((path) => resolve(path) !== active);
+    if (siblings.length > this.options.maxSessions) {
+      warnings.push(
+        `Project session discovery capped at memory.maxProjectSessions (${this.options.maxSessions})`,
+      );
+    }
+    names = [active, ...siblings.slice(0, this.options.maxSessions)];
+    for (const source of previousSources) {
+      if (source.sessionId === this.options.activeSessionId
+        || names.includes(source.sessionFile)
+        || !existsSync(source.sessionFile)) {
+        continue;
+      }
+      if (names.length - 1 >= this.options.maxSessions) break;
+      names.push(source.sessionFile);
+    }
+    return [...new Set(names)];
+  }
+
+  private syncSource(
+    sessionFile: string,
+    header: SessionHeaderRecord,
+    indexedAt: number,
+    warnings: string[],
+  ): { mode: "noop" | "incremental" | "rebuild"; materializationWarnings: string[] } {
+    const sessionId = header.value.id;
+    const previous = this.repository.getProjectSourceState(this.projectPath, sessionId);
+    const stat = statSync(sessionFile);
+    const rebuildReason = this.rebuildReason(sessionFile, header, stat.size, stat.mtimeMs, previous);
+
+    this.indexer.sync({
+      sessionId,
+      sessionFile,
+      projectPath: this.projectPath,
+      totalEntries: 0,
+      branchEntries: 0,
+    }, Boolean(rebuildReason));
+
+    if (!rebuildReason && previous
+      && stat.size === previous.fileSize
+      && stat.mtimeMs === previous.fileMtimeMs
+      && previous.status === "ready") {
+      return { mode: "noop", materializationWarnings: [] };
+    }
+
+    if (rebuildReason || !previous) {
+      const read = readJsonlRecords(sessionFile, 0);
+      const first = read.records[0];
+      if (!first || first.value.type !== "session" || first.rawHash !== header.rawHash) {
+        throw new Error("Pi session header changed during project memory replay");
+      }
+      const projection = projectJsonlMutations(read.records.slice(1), sessionId);
+      const records = read.records.filter((record) => record.value.type !== "session").length;
+      const materialized = this.repository.replaceProjectSource(
+        sourceCheckpoint(
+          this.projectPath,
+          sessionId,
+          sessionFile,
+          header,
+          read,
+          records,
+          mutationCount(projection),
+          read.malformedLines,
+          indexedAt,
+        ),
+        projection.memoryMutations,
+        projection.pinMutations,
+      );
+      warnings.push(
+        ...projection.warnings.map((warning) => `${sessionId}: ${warning}`),
+      );
+      return { mode: "rebuild", materializationWarnings: materialized.warnings };
+    }
+
+    const read = readJsonlRecords(sessionFile, previous.checkpointOffset);
+    const projection = projectJsonlMutations(read.records, sessionId, previous.indexedRecords);
+    const records = read.records.filter((record) => record.value.type !== "session").length;
+    const materialized = this.repository.appendProjectSource(
+      sourceCheckpoint(
+        this.projectPath,
+        sessionId,
+        sessionFile,
+        header,
+        read,
+        previous.indexedRecords + records,
+        previous.indexedMutations + mutationCount(projection),
+        previous.malformedLines + read.malformedLines,
+        indexedAt,
+        previous,
+      ),
+      projection.memoryMutations,
+      projection.pinMutations,
+    );
+    warnings.push(
+      ...projection.warnings.map((warning) => `${sessionId}: ${warning}`),
+    );
+    return { mode: "incremental", materializationWarnings: materialized.warnings };
+  }
+
+  private rebuildReason(
+    sessionFile: string,
+    header: SessionHeaderRecord,
+    fileSize: number,
+    fileMtimeMs: number,
+    previous?: ProjectMemorySourceCheckpoint,
+  ): string | undefined {
+    if (!previous) return "initial project memory replay";
+    if (previous.status !== "ready") return `source status is ${previous.status}`;
+    if (previous.sessionFile !== sessionFile) return "session file path changed";
+    if (previous.headerHash !== header.rawHash) return "session header changed";
+    if (fileSize < previous.fileSize) return "session file was truncated";
+    if (fileSize === previous.fileSize && fileMtimeMs !== previous.fileMtimeMs) {
+      return "session file changed in place";
+    }
+    if (fileSize > previous.fileSize && previous.checkpointOffset < previous.fileSize) {
+      return "session grew after an unterminated JSONL tail";
+    }
+    if (previous.checkpointOffset > 0) {
+      if (!previous.checkpointHash) return "project memory checkpoint hash is missing";
+      const currentHash = hashFileRange(
+        sessionFile,
+        previous.checkpointHashStart,
+        previous.checkpointOffset,
+      );
+      if (currentHash !== previous.checkpointHash) {
+        return "project memory checkpoint no longer matches the JSONL file";
+      }
+    }
+    return undefined;
+  }
+}