Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

35.3 KB
Raw Blame
import { VectorIndex, base64ToFloat32, float32ToBase64, type VectorEntry } from "./vector-index.js";
import type { StateKV } from "./kv.js";
import { KV } from "./schema.js";
import { logger } from "../logger.js";
import { safeAudit } from "../functions/audit.js";
import { getIndexSaveIntervalMs, getVectorBucketSize } from "../config.js";

const FAILURE_LOG_THROTTLE_MS = 60_000;
const INDEX_PERSISTENCE_FUNCTION_ID = "mem::index-persistence";
const LEGACY_BM25_KEY = "data";
const LEGACY_BM25_MANIFEST_KEY = "data:manifest";
const LEGACY_VECTOR_KEY = "vectors";
const LEGACY_VECTOR_MANIFEST_KEY = "vectors:manifest";
const VECTOR_META_KEY = "vectors:meta";
const VECTOR_BUCKET_SCOPE_PREFIX = `${KV.bm25Index}:vec:`;
const WRITE_CONCURRENCY = 32;
const LOAD_CONCURRENCY = 8;
const FIRST_CHECKPOINT_DELAY_MS = 5_000;
const PENDING_CLEAR_KEY = "~clear";
const PENDING_LOG_SAVE_THRESHOLD = 500;
const EARLY_SAVE_MIN_GAP_MS = 5_000;
const BACKFILL_MARKER_KEY = "vectors:backfill";
const MEMORY_ID_PREFIX = "mem_";

function auditIndexPersistEnabled(): boolean {
  const raw = process.env.AGENTMEMORY_AUDIT_INDEX_PERSIST;
  if (!raw) return false;
  const normalized = raw.trim().toLowerCase();
  return normalized === "1" || normalized === "true";
}

type IndexShardManifest = {
  v: 1;
  generation?: string;
  shards: Array<{ scope: string; key: string; chars: number }>;
  chars: number;
};

type VectorMeta = {
  v: 3;
  bucketCount: number;
  savedAt: string;
  count: number;
  backfillSince?: string | null;
};

type PersistedVector = {
  id: string;
  s: string;
  e: string;
};

type PendingVectorRow = {
  q: number;
  id?: string;
  s?: string;
  k?: "memory" | "observation";
  e?: string;
  t?: 1;
  c?: 1;
};

type BackfillMarker = {
  v: 1 | 2;
  since: string | null;
};

export interface PendingReplayResult {
  entries: number;
  added: number;
  removed: number;
  cleared: boolean;
  skipped: number;
}

type IndexPersistenceOptions = {
  saveIntervalMs?: number;
  bucketSize?: number;
  now?: () => number;
  requireRecoveryPlan?: boolean;
};

export interface IndexLegStatus {
  lastSavedAt: string | null;
  lastError: string | null;
  lastErrorAt: string | null;
  dirtySince: string | null;
}

export interface VectorCountShortfall {
  expected: number;
  loaded: number;
}

export interface IndexPersistenceStatus {
  saveIntervalMs: number;
  firstCheckpointPending?: boolean;
  nextSaveAt?: string | null;
  saving: boolean;
  buckets: number;
  pendingChanges: number;
  vector: IndexLegStatus | null;
  vectorCountShortfall: VectorCountShortfall | null;
  pendingLog?: number;
  pendingLogAcknowledged?: number;
  pendingLogError?: string | null;
}

export type VectorLoadState = "buckets" | "migrated" | "none" | "unavailable";

export interface VectorLoadResult {
  vector: VectorIndex | null;
  state: VectorLoadState;
  savedAt: string | null;
  expectedCount?: number;
  backfillSince?: string | null;
}

export function vectorBucketScope(bucket: number): string {
  return `${VECTOR_BUCKET_SCOPE_PREFIX}${String(bucket).padStart(4, "0")}`;
}

function statePath(scope: string, key: string): string {
  return `${scope}/${key}`;
}

function errorMessage(err: unknown): string {
  return err instanceof Error ? err.message : String(err);
}

function earliestBackfillSince(...cutoffs: Array<string | null | undefined>): string | null | undefined {
  let earliest: string | undefined;
  for (const cutoff of cutoffs) {
    if (cutoff === null) return null;
    if (cutoff !== undefined && (earliest === undefined || Date.parse(cutoff) < Date.parse(earliest))) earliest = cutoff;
  }
  return earliest;
}

function generationTime(generation: string | undefined): string | null {
  const stamp = generation?.split("_")[1];
  if (!stamp) return null;
  const ms = parseInt(stamp, 36);
  return Number.isFinite(ms) && ms > 0 ? new Date(ms).toISOString() : null;
}

function isValidShardDescriptor(
  shard: unknown,
): shard is IndexShardManifest["shards"][number] {
  if (!shard || typeof shard !== "object") return false;
  const candidate = shard as { scope?: unknown; key?: unknown; chars?: unknown };
  return (
    typeof candidate.scope === "string" &&
    candidate.scope.length > 0 &&
    typeof candidate.key === "string" &&
    candidate.key.length > 0 &&
    Number.isInteger(candidate.chars) &&
    (candidate.chars as number) >= 0
  );
}

function isPersistedVector(row: unknown): row is PersistedVector {
  if (!row || typeof row !== "object") return false;
  const candidate = row as Partial<PersistedVector>;
  return typeof candidate.id === "string" && typeof candidate.s === "string" && typeof candidate.e === "string";
}

async function inBatches<T>(items: T[], size: number, run: (item: T) => Promise<void>): Promise<unknown[]> {
  const failures: unknown[] = [];
  for (let offset = 0; offset < items.length; offset += size) {
    const results = await Promise.allSettled(items.slice(offset, offset + size).map(run));
    for (const result of results) {
      if (result.status === "rejected") failures.push(result.reason);
    }
  }
  return failures;
}

function isPendingVectorRow(row: unknown): row is PendingVectorRow {
  if (!row || typeof row !== "object") return false;
  const candidate = row as PendingVectorRow;
  if (typeof candidate.q !== "number" || !Number.isFinite(candidate.q)) return false;
  if (candidate.c === 1) return true;
  if (typeof candidate.id !== "string" || candidate.id.length === 0) return false;
  return candidate.t === 1 || typeof candidate.e === "string";
}

function emptyLegStatus(): IndexLegStatus {
  return { lastSavedAt: null, lastError: null, lastErrorAt: null, dirtySince: null };
}

export class IndexPersistence {
  private timer: ReturnType<typeof setTimeout> | null = null;
  private lastFailureLogAt = 0;
  private running: Promise<void> | null = null;
  private queued: Promise<void> | null = null;
  private stopped = false;
  private lastSaveAt: number;
  private dirtyEpoch = 0;
  private markedDuringRunAt: number | null = null;
  private hasVectorCheckpoint = false;
  private firstVectorSaveAttempted = false;
  private nextSaveAt: number | null = null;
  private leg: IndexLegStatus = emptyLegStatus();
  private readonly saveIntervalMs: number;
  private readonly bucketSize: number;
  private readonly now: () => number;
  private bucketOfId: Map<string, number> = new Map();
  private bucketCounts: Map<number, number> = new Map();
  private highestBucket = 0;
  private hasOpenBucket = false;
  private vectorCountShortfall: VectorCountShortfall | null = null;
  private seq = 0;
  private pendingLog: Map<string, number> = new Map();
  private acknowledgedLog: Map<string, number> = new Map();
  private logChains: Map<string, Promise<void>> = new Map();
  private logSuppressed = false;
  private pendingLogUnknown = false;
  private pendingLogError: string | null = null;
  private earlySaveQueued = false;
  private backfillQueue: Promise<void> = Promise.resolve();
  private recoveryError: string | null = null;
  private backfillRevision = 0;
  private recoveryReady: boolean;
  private backfillSince: string | null | undefined;
  private checkpointBackfillSince: string | null | undefined;
  private completingBackfill = false;

  constructor(
    private kv: StateKV,
    private vector: VectorIndex | null,
    options: IndexPersistenceOptions = {},
  ) {
    this.recoveryReady = !options.requireRecoveryPlan || !vector;
    this.vector?.setChangeListener((id, entry) => this.logChange(id, entry));
    this.now = options.now ?? Date.now;
    const interval = options.saveIntervalMs;
    this.saveIntervalMs =
      typeof interval === "number" && Number.isFinite(interval) && interval > 0
        ? interval
        : getIndexSaveIntervalMs();
    const bucketSize = options.bucketSize;
    this.bucketSize =
      typeof bucketSize === "number" && Number.isInteger(bucketSize) && bucketSize > 0
        ? bucketSize
        : getVectorBucketSize();
    this.lastSaveAt = this.now();
  }

  scheduleSave(): void {
    if (this.stopped || !this.recoveryReady || this.recoveryError || !this.vector?.pendingChanges) return;
    const now = this.now();
    this.dirtyEpoch++;
    if (this.running && this.markedDuringRunAt === null) this.markedDuringRunAt = now;
    if (this.leg.dirtySince === null) this.leg.dirtySince = new Date(now).toISOString();
    this.queueSave();
  }

  save(): Promise<void> {
    this.clearTimer();
    if (this.queued) return this.queued;
    if (this.running) {
      const queued = this.running.then(() => {
        this.queued = null;
        return this.startRun();
      });
      this.queued = queued;
      return queued;
    }
    return this.startRun();
  }

  status(): IndexPersistenceStatus {
    return {
      saveIntervalMs: this.saveIntervalMs,
      firstCheckpointPending: Boolean(this.vector && !this.hasVectorCheckpoint && (this.vector.pendingChanges > 0 || this.running)),
      nextSaveAt: this.nextSaveAt === null ? null : new Date(this.nextSaveAt).toISOString(),
      saving: this.running !== null,
      buckets: this.bucketCountInUse(),
      pendingChanges: this.vector?.pendingChanges ?? 0,
      vector: this.vector ? { ...this.leg } : null,
      vectorCountShortfall: this.vectorCountShortfall,
      pendingLog: this.vector ? this.pendingLog.size : 0,
      pendingLogAcknowledged: this.vector ? this.acknowledgedLog.size : 0,
      pendingLogError: this.pendingLogError,
    };
  }

  async replayPendingLog(expectedDimensions = 0): Promise<PendingReplayResult> {
    const result: PendingReplayResult = { entries: 0, added: 0, removed: 0, cleared: false, skipped: 0 };
    const vector = this.vector;
    if (!vector || this.recoveryError) return result;
    let rows: unknown[];
    try {
      rows = await this.kv.list<unknown>(KV.vectorPendingLog);
    } catch (err) {
      this.pendingLogUnknown = true;
      this.pendingLogError = errorMessage(err);
      logger.warn("index persistence: could not read the pending vector log", { message: this.pendingLogError });
      return result;
    }
    const valid = (Array.isArray(rows) ? rows : []).filter(isPendingVectorRow).sort((a, b) => a.q - b.q);
    this.logSuppressed = true;
    try {
      for (const row of valid) {
        result.entries++;
        const key = row.c === 1 ? PENDING_CLEAR_KEY : row.id!;
        if ((this.pendingLog.get(key) ?? -Infinity) < row.q) this.pendingLog.set(key, row.q);
        if (this.pendingLog.get(key) === row.q) this.acknowledgedLog.set(key, row.q);
        if (row.q > this.seq) this.seq = row.q;
        if (row.c === 1) {
          vector.clear();
          result.cleared = true;
          continue;
        }
        const id = row.id!;
        if (row.t === 1) {
          if (vector.has(id)) {
            vector.remove(id);
            result.removed++;
          }
          continue;
        }
        let embedding: Float32Array;
        try {
          embedding = base64ToFloat32(row.e!);
        } catch {
          result.skipped++;
          continue;
        }
        if (embedding.length === 0 || (expectedDimensions > 0 && embedding.length !== expectedDimensions)) {
          result.skipped++;
          continue;
        }
        vector.add(id, typeof row.s === "string" ? row.s : "", embedding);
        result.added++;
      }
    } finally {
      this.logSuppressed = false;
    }
    if (result.skipped > 0) {
      try { await this.markBackfillSince(null); } catch (err) { this.pauseRecovery(err); }
    }
    if (result.added + result.removed > 0 || result.cleared) this.scheduleSave();
    return result;
  }

  async readBackfillMarker(): Promise<string | null | undefined> {
    if (!this.vector) return undefined;
    const marker = await this.kv.get<BackfillMarker>(KV.bm25Index, BACKFILL_MARKER_KEY);
    if (!marker) return undefined;
    if (marker.v === 2 && marker.since === null) return null;
    if ((marker.v === 1 || marker.v === 2) && typeof marker.since === "string" && Number.isFinite(Date.parse(marker.since))) return marker.since;
    throw new Error("Invalid persisted vector backfill marker");
  }

  markBackfillSince(since: string | null): Promise<void> {
    this.backfillRevision++;
    return this.queueBackfillChange(async () => {
      if (!this.vector || (since !== null && !Number.isFinite(Date.parse(since)))) return;
      const current = await this.readBackfillMarker();
      const next = earliestBackfillSince(current, this.backfillSince, since)!;
      if (current !== next) await this.kv.set<BackfillMarker>(KV.bm25Index, BACKFILL_MARKER_KEY, { v: 2, since: next });
      this.backfillSince = next;
    });
  }

  private queueBackfillChange(change: () => Promise<void>): Promise<void> {
    const run = this.backfillQueue.then(change);
    this.backfillQueue = run.catch(() => {});
    return run;
  }

  isRecoveryPaused(): boolean {
    return this.recoveryError !== null || !this.recoveryReady;
  }

  private pauseRecovery(error: unknown): void {
    this.recoveryReady = false;
    this.recoveryError = `Vector recovery paused until restart: ${errorMessage(error)}`;
    this.leg.lastError = this.recoveryError;
    this.leg.lastErrorAt = new Date(this.now()).toISOString();
    this.clearTimer();
    logger.warn(this.recoveryError);
  }

  async prepareBackfill(loaded: VectorLoadResult | null, forceFull = false): Promise<string | null | undefined> {
    if (!this.vector || this.recoveryError) return undefined;
    if (!loaded || loaded.state === "unavailable") {
      this.pauseRecovery(new Error("Persisted vector checkpoint is unavailable"));
      return undefined;
    }
    const shortfall = loaded.expectedCount !== undefined && (loaded.vector?.size ?? 0) < loaded.expectedCount;
    const since = forceFull || loaded.state === "none" || shortfall || !Number.isFinite(Date.parse(loaded.savedAt ?? "")) ? null : loaded.savedAt;
    try {
      const fallback = loaded.backfillSince;
      if (fallback !== undefined && fallback !== null && (typeof fallback !== "string" || !Number.isFinite(Date.parse(fallback)))) {
        throw new Error("Invalid persisted vector recovery cutoff");
      }
      await this.markBackfillSince(earliestBackfillSince(since, fallback)!);
      const marker = await this.readBackfillMarker();
      this.recoveryReady = true;
      this.scheduleSave();
      return marker;
    } catch (err) {
      this.pauseRecovery(err);
      return undefined;
    }
  }

  async beginBackfill(): Promise<boolean> {
    if (this.isRecoveryPaused()) return false;
    try {
      await this.markBackfillSince(null);
      return true;
    } catch (err) {
      this.pauseRecovery(err);
      return false;
    }
  }

  private checkpointRecoveryCutoff(): string | null | undefined {
    return this.completingBackfill ? null : this.backfillSince;
  }

  private needsRecoveryCheckpoint(): boolean {
    const cutoff = this.checkpointRecoveryCutoff();
    return cutoff !== undefined && cutoff !== this.checkpointBackfillSince;
  }

  async completeBackfill(isCovered: () => boolean = () => true): Promise<boolean> {
    if (this.isRecoveryPaused()) return false;
    const revision = this.backfillRevision;
    const since = this.backfillSince;
    this.completingBackfill = since !== undefined;
    await this.save();
    if (this.leg.lastError || this.vector?.pendingChanges || !isCovered()) return false;
    let cleared = false;
    try {
      await this.queueBackfillChange(async () => {
        if (this.recoveryError || this.backfillRevision !== revision || !isCovered()) return;
        await this.kv.delete(KV.bm25Index, BACKFILL_MARKER_KEY);
        cleared = true;
      });
      if (!cleared) return false;
      if (this.backfillRevision !== revision || !isCovered()) {
        if (since !== undefined) await this.markBackfillSince(since);
        return false;
      }
      // The checkpoint retains the cutoff through the delete/crash window. A later
      // ordinary checkpoint can remove it once this recovery has completed.
      this.backfillSince = undefined;
      this.completingBackfill = false;
      return true;
    } catch (err) {
      this.pauseRecovery(err);
      return false;
    }
  }

  clearBackfillMarker(): Promise<void> {
    return this.queueBackfillChange(async () => {
      if (this.vector) await this.kv.delete(KV.bm25Index, BACKFILL_MARKER_KEY);
    });
  }

  async flushPendingLog(): Promise<void> {
    await Promise.all([...this.logChains.values()]);
  }

  private nextSeq(): number {
    this.seq = Math.max(this.seq + 1, this.now() * 1000);
    return this.seq;
  }

  private logChange(id: string | null, entry: VectorEntry | null): void {
    if (this.logSuppressed || !this.recoveryReady || this.recoveryError) return;
    const key = id ?? PENDING_CLEAR_KEY;
    const q = this.nextSeq();
    let row: PendingVectorRow;
    if (id === null) {
      row = { q, c: 1 };
    } else if (entry) {
      row = {
        q,
        id,
        s: entry.sessionId,
        k: id.startsWith(MEMORY_ID_PREFIX) ? "memory" : "observation",
        e: float32ToBase64(entry.embedding),
      };
    } else {
      row = { q, id, t: 1 };
    }
    this.pendingLog.set(key, q);
    this.acknowledgedLog.delete(key);
    this.enqueueLog(key, async () => {
      await this.kv.set<PendingVectorRow>(KV.vectorPendingLog, key, row);
      if (this.pendingLog.get(key) === q) this.acknowledgedLog.set(key, q);
    }).then(
      () => {
        this.pendingLogError = null;
      },
      (err) => {
        this.pendingLogError = errorMessage(err);
        this.logFailure(err);
      },
    );
    this.maybeEarlySave();
  }

  private enqueueLog(key: string, op: () => Promise<void>): Promise<void> {
    const run = (this.logChains.get(key) ?? Promise.resolve()).then(op);
    const tail = run.then(
      () => undefined,
      () => undefined,
    );
    this.logChains.set(key, tail);
    void tail.then(() => {
      if (this.logChains.get(key) === tail) this.logChains.delete(key);
    });
    return run;
  }

  private maybeEarlySave(): void {
    if (this.stopped || !this.recoveryReady || this.recoveryError || this.running || this.earlySaveQueued) return;
    if (this.pendingLog.size < PENDING_LOG_SAVE_THRESHOLD) return;
    if (this.now() - this.lastSaveAt < EARLY_SAVE_MIN_GAP_MS) return;
    this.earlySaveQueued = true;
    setTimeout(() => {
      this.earlySaveQueued = false;
      this.save().catch((err) => this.logFailure(err));
    }, 0);
  }

  private deletePendingKey(key: string, q: number | undefined): Promise<void> {
    return this.enqueueLog(key, async () => {
      if (this.pendingLog.get(key) !== q) return;
      await this.kv.delete(KV.vectorPendingLog, key);
      if (this.pendingLog.get(key) === q) {
        this.pendingLog.delete(key);
        this.acknowledgedLog.delete(key);
      }
    });
  }

  private async clearCoveredPendingLog(coveredSeq: number): Promise<void> {
    const clearSeq = this.pendingLog.get(PENDING_CLEAR_KEY);
    if (clearSeq !== undefined ? clearSeq <= coveredSeq : this.pendingLogUnknown) {
      await this.deletePendingKey(PENDING_CLEAR_KEY, clearSeq);
    }
    const covered = [...this.pendingLog].filter(([key, q]) => key !== PENDING_CLEAR_KEY && q <= coveredSeq);
    const failures = await inBatches(covered, WRITE_CONCURRENCY, ([key, q]) => this.deletePendingKey(key, q));
    if (failures.length > 0) {
      throw new Error(`${failures.length} of ${covered.length} pending vector log deletes failed: ${errorMessage(failures[0])}`);
    }
    this.pendingLogUnknown = false;
  }

  stop(): void {
    this.stopped = true;
    this.clearTimer();
  }

  async load(): Promise<VectorLoadResult> {
    if (!this.vector) {
      await this.removeLegacyBm25Snapshot();
      return { vector: null, state: "none", savedAt: null };
    }

    let meta: VectorMeta | null;
    try {
      meta = await this.kv.get<VectorMeta>(KV.bm25Index, VECTOR_META_KEY);
    } catch (err) {
      logger.warn("index persistence: vector metadata read failed", { message: errorMessage(err) });
      return { vector: null, state: "unavailable", savedAt: null };
    }

    if (meta && meta.v === 3 && Number.isInteger(meta.bucketCount) && meta.bucketCount >= 0) {
      const loaded = await this.loadBuckets(meta.bucketCount);
      if (!loaded) return { vector: null, state: "unavailable", savedAt: null };
      this.hasVectorCheckpoint = loaded.size > 0;
      this.checkpointBackfillSince = meta.backfillSince;
      await this.removeLegacyVectorSnapshotIfPresent();
      await this.removeLegacyBm25Snapshot();
      const expectedCount = Number.isInteger(meta.count) ? meta.count : undefined;
      this.vectorCountShortfall =
        expectedCount !== undefined && loaded.size < expectedCount
          ? { expected: expectedCount, loaded: loaded.size }
          : null;
      if (this.vectorCountShortfall) {
        logger.warn("index persistence: loaded fewer vectors than the last save recorded", {
          ...this.vectorCountShortfall,
        });
      }
      return { vector: loaded, state: "buckets", savedAt: meta.savedAt ?? null, expectedCount, backfillSince: meta.backfillSince };
    }

    return this.migrateLegacy();
  }

  private bucketCountInUse(): number {
    return this.hasOpenBucket ? this.highestBucket + 1 : 0;
  }

  private assignBucket(id: string): number {
    const existing = this.bucketOfId.get(id);
    if (existing !== undefined) return existing;
    if (!this.hasOpenBucket) {
      this.hasOpenBucket = true;
      this.highestBucket = 0;
    } else if ((this.bucketCounts.get(this.highestBucket) ?? 0) >= this.bucketSize) {
      this.highestBucket++;
    }
    this.bucketOfId.set(id, this.highestBucket);
    this.bucketCounts.set(this.highestBucket, (this.bucketCounts.get(this.highestBucket) ?? 0) + 1);
    return this.highestBucket;
  }

  private releaseBucket(id: string): void {
    const bucket = this.bucketOfId.get(id);
    if (bucket === undefined) return;
    this.bucketOfId.delete(id);
    const remaining = (this.bucketCounts.get(bucket) ?? 1) - 1;
    if (remaining > 0) this.bucketCounts.set(bucket, remaining);
    else this.bucketCounts.delete(bucket);
  }

  private clearTimer(): void {
    if (this.timer) {
      clearTimeout(this.timer);
      this.timer = null;
    }
    this.nextSaveAt = null;
  }

  private queueSave(): void {
    if (this.stopped || !this.recoveryReady || this.recoveryError || this.timer || !this.vector?.pendingChanges) return;
    const now = this.now();
    const remaining = Math.max(0, this.lastSaveAt + this.saveIntervalMs - now);
    const delay = !this.hasVectorCheckpoint && !this.firstVectorSaveAttempted
      ? Math.min(FIRST_CHECKPOINT_DELAY_MS, remaining)
      : remaining;
    this.nextSaveAt = now + delay;
    this.timer = setTimeout(() => {
      this.timer = null;
      this.nextSaveAt = null;
      this.save().catch((err) => this.logFailure(err));
    }, delay);
  }

  private startRun(): Promise<void> {
    const run = this.runSave().finally(() => {
      if (this.running === run) this.running = null;
      if (!this.queued) this.queueSave();
    });
    this.running = run;
    return run;
  }

  private async runSave(): Promise<void> {
    const vector = this.vector;
    if (!vector || this.isRecoveryPaused()) return;
    if (!vector.pendingChanges && !this.needsRecoveryCheckpoint()) return;
    const hasVectorChanges = vector.pendingChanges > 0;
    const epoch = this.dirtyEpoch;
    this.markedDuringRunAt = null;
    if (hasVectorChanges) {
      this.lastSaveAt = this.now();
      this.firstVectorSaveAttempted = true;
    }
    const coveredSeq = this.seq;
    try {
      await this.writeChanges(vector);
      await this.clearCoveredPendingLog(coveredSeq).catch((err) => {
        this.pendingLogError = errorMessage(err);
        this.logFailure(err);
      });
      this.leg.lastSavedAt = new Date(this.now()).toISOString();
      this.leg.lastError = null;
      this.leg.lastErrorAt = null;
      if (this.dirtyEpoch === epoch || vector.pendingChanges === 0) {
        this.leg.dirtySince = null;
      } else if (this.markedDuringRunAt !== null) {
        this.leg.dirtySince = new Date(this.markedDuringRunAt).toISOString();
      }
    } catch (err) {
      this.leg.lastError = errorMessage(err);
      this.leg.lastErrorAt = new Date(this.now()).toISOString();
      if (this.leg.dirtySince === null) this.leg.dirtySince = this.leg.lastErrorAt;
      if (hasVectorChanges) this.lastSaveAt = this.now();
      this.clearTimer();
      this.logFailure(err);
    }
  }

  private async writeChanges(vector: VectorIndex): Promise<void> {
    const changes = vector.takeChanges();
    if (changes.size === 0 && !this.needsRecoveryCheckpoint()) return;
    const failed = new Map<string, boolean>();
    const failures = await inBatches([...changes], WRITE_CONCURRENCY, async ([id, present]) => {
      const entry = present ? vector.get(id) : undefined;
      try {
        if (entry) {
          const bucket = this.assignBucket(id);
          await this.kv.set<PersistedVector>(vectorBucketScope(bucket), id, {
            id,
            s: entry.sessionId,
            e: float32ToBase64(entry.embedding),
          });
        } else {
          const bucket = this.bucketOfId.get(id);
          if (bucket !== undefined) {
            await this.kv.delete(vectorBucketScope(bucket), id);
            this.releaseBucket(id);
          }
        }
      } catch (err) {
        failed.set(id, present);
        throw err;
      }
    });
    if (failures.length > 0) {
      vector.returnChanges(failed);
      throw new Error(
        `${failures.length} of ${changes.size} vector writes failed: ${errorMessage(failures[0])}`,
      );
    }
    const backfillSince = this.checkpointRecoveryCutoff();
    try {
      await this.kv.set<VectorMeta>(KV.bm25Index, VECTOR_META_KEY, {
        v: 3,
        bucketCount: this.bucketCountInUse(),
        savedAt: new Date(this.now()).toISOString(),
        count: vector.size,
        ...(backfillSince !== undefined ? { backfillSince } : {}),
      });
      this.checkpointBackfillSince = backfillSince;
    } catch (err) {
      vector.returnChanges(changes);
      throw err;
    }
    this.hasVectorCheckpoint = this.bucketOfId.size > 0;
    if (!this.hasVectorCheckpoint) this.firstVectorSaveAttempted = false;
  }

  private async loadBuckets(bucketCount: number): Promise<VectorIndex | null> {
    const loaded = new VectorIndex();
    const bucketOfId = new Map<string, number>();
    const bucketCounts = new Map<number, number>();
    const bucketIds = Array.from({ length: bucketCount }, (_, bucket) => bucket);
    const failures = await inBatches(bucketIds, LOAD_CONCURRENCY, async (bucket) => {
      const rows = await this.kv.list<unknown>(vectorBucketScope(bucket));
      let count = 0;
      for (const row of rows) {
        if (!isPersistedVector(row)) continue;
        try {
          loaded.loadPersisted(row.id, row.s, base64ToFloat32(row.e));
        } catch {
          continue;
        }
        bucketOfId.set(row.id, bucket);
        count++;
      }
      if (count > 0) bucketCounts.set(bucket, count);
    });
    if (failures.length > 0) {
      logger.warn("index persistence: vector bucket read failed", {
        failed: failures.length,
        message: errorMessage(failures[0]),
      });
      return null;
    }
    this.bucketOfId = bucketOfId;
    this.bucketCounts = bucketCounts;
    this.highestBucket = bucketCount > 0 ? bucketCount - 1 : 0;
    this.hasOpenBucket = bucketCount > 0;
    return loaded;
  }

  private async migrateLegacy(): Promise<VectorLoadResult> {
    const manifest = await this.readIndexValue<IndexShardManifest>(
      KV.bm25Index,
      LEGACY_VECTOR_MANIFEST_KEY,
      "vector",
      "manifest",
    );
    const legacyKey = await this.readIndexValue<string>(KV.bm25Index, LEGACY_VECTOR_KEY, "vector", "legacy");
    if (!manifest.ok || !legacyKey.ok) return { vector: null, state: "unavailable", savedAt: null };
    const legacyPresent = manifest.value != null || (typeof legacyKey.value === "string" && legacyKey.value.length > 0);
    if (!legacyPresent) {
      await this.removeLegacyBm25Snapshot();
      return { vector: null, state: "none", savedAt: null };
    }

    const data = await this.loadShardedData(LEGACY_VECTOR_KEY, LEGACY_VECTOR_MANIFEST_KEY, "vector");
    if (typeof data !== "string") {
      logger.warn("index persistence: legacy vector snapshot is unreadable; keeping it and skipping migration");
      return { vector: null, state: "unavailable", savedAt: null };
    }
    const legacy = VectorIndex.deserialize(data);
    const savedAt =
      (manifest.value && typeof manifest.value === "object" ? generationTime(manifest.value.generation) : null) ??
      new Date(this.now()).toISOString();

    const staging = new VectorIndex();
    for (const [id, entry] of legacy.entries()) staging.add(id, entry.sessionId, entry.embedding);
    try {
      await this.markBackfillSince(savedAt);
      await this.writeChanges(staging);
    } catch (err) {
      logger.warn("index persistence: migrating the legacy vector snapshot failed; it stays in place and the next save retries", {
        message: errorMessage(err),
      });
      legacy.markAllChanged();
      return { vector: legacy, state: "unavailable", savedAt };
    }

    await this.removeLegacyVectorSnapshot(manifest.value);
    await this.removeLegacyBm25Snapshot();
    await this.auditIndexPersistence("migrate", [statePath(KV.bm25Index, VECTOR_META_KEY)], {
      vectors: legacy.size,
      buckets: this.bucketCountInUse(),
    });
    logger.info("index persistence: migrated the vector index to bucketed storage", {
      vectors: legacy.size,
      buckets: this.bucketCountInUse(),
    });
    const migrated = new VectorIndex();
    for (const [id, entry] of legacy.entries()) migrated.loadPersisted(id, entry.sessionId, entry.embedding);
    return { vector: migrated, state: "migrated", savedAt };
  }

  private async removeLegacyVectorSnapshot(manifest: IndexShardManifest | null): Promise<void> {
    if (manifest && Array.isArray(manifest.shards)) {
      await this.deleteShards(manifest.shards.filter(isValidShardDescriptor), "legacy_vector_cleanup");
    }
    await this.deleteKey(KV.bm25Index, LEGACY_VECTOR_MANIFEST_KEY, "legacy_vector_cleanup");
    await this.deleteKey(KV.bm25Index, LEGACY_VECTOR_KEY, "legacy_vector_cleanup");
  }

  private async removeLegacyVectorSnapshotIfPresent(): Promise<void> {
    const manifest = await this.readIndexValue<IndexShardManifest>(KV.bm25Index, LEGACY_VECTOR_MANIFEST_KEY, "vector", "manifest");
    const legacy = await this.readIndexValue<string>(KV.bm25Index, LEGACY_VECTOR_KEY, "vector", "legacy");
    if (!manifest.ok || !legacy.ok) return;
    if (manifest.value == null && legacy.value == null) return;
    await this.removeLegacyVectorSnapshot(manifest.value ?? null);
  }

  private async removeLegacyBm25Snapshot(): Promise<void> {
    const manifestRead = await this.readIndexValue<IndexShardManifest>(KV.bm25Index, LEGACY_BM25_MANIFEST_KEY, "bm25", "manifest");
    const legacyRead = await this.readIndexValue<string>(KV.bm25Index, LEGACY_BM25_KEY, "bm25", "legacy");
    if (!manifestRead.ok || !legacyRead.ok) return;
    const manifest = manifestRead.value ?? null;
    const legacy = legacyRead.value ?? null;
    if (manifest == null && legacy == null) return;
    if (manifest && Array.isArray(manifest.shards)) {
      await this.deleteShards(manifest.shards.filter(isValidShardDescriptor), "legacy_bm25_cleanup");
    }
    if (manifest != null) await this.deleteKey(KV.bm25Index, LEGACY_BM25_MANIFEST_KEY, "legacy_bm25_cleanup");
    if (legacy != null) await this.deleteKey(KV.bm25Index, LEGACY_BM25_KEY, "legacy_bm25_cleanup");
  }

  private logFailure(err: unknown): void {
    const now = this.now();
    if (now - this.lastFailureLogAt < FAILURE_LOG_THROTTLE_MS) return;
    this.lastFailureLogAt = now;
    const code = (err as { code?: string })?.code;
    logger.warn("index persistence: failed to save the vector index", {
      code,
      message: errorMessage(err),
      hint:
        code === "TIMEOUT"
          ? "iii-engine state::set timed out; unsaved vectors stay in memory and retry on the next save"
          : undefined,
    });
  }

  private async auditIndexPersistence(
    action: string,
    targetIds: string[],
    details: Record<string, unknown>,
  ): Promise<void> {
    if (!auditIndexPersistEnabled()) return;
    await safeAudit(this.kv, "index_persist", INDEX_PERSISTENCE_FUNCTION_ID, targetIds, {
      action,
      ...details,
    });
  }

  private async deleteKey(scope: string, key: string, reason: string): Promise<void> {
    let result = "deleted";
    let error: string | undefined;
    try {
      await this.kv.delete(scope, key);
    } catch (err) {
      result = "failed";
      error = errorMessage(err);
    }
    await this.auditIndexPersistence("delete", [statePath(scope, key)], {
      scope,
      key,
      reason,
      result,
      error,
    });
  }

  private async deleteShards(shards: IndexShardManifest["shards"], reason: string): Promise<void> {
    await inBatches(shards, WRITE_CONCURRENCY, (shard) => this.deleteKey(shard.scope, shard.key, reason));
  }

  private async loadShardedData(legacyKey: string, manifestKey: string, label: string): Promise<string | null> {
    const manifest = await this.readIndexValue<IndexShardManifest>(KV.bm25Index, manifestKey, label, "manifest");
    if (!manifest.ok) return null;
    if (manifest.value != null && typeof manifest.value === "object") {
      return this.loadManifestData(manifest.value, label);
    }
    const legacy = await this.readIndexValue<string>(KV.bm25Index, legacyKey, label, "legacy");
    if (!legacy.ok) return null;
    if (legacy.value && typeof legacy.value === "string") return legacy.value;
    return null;
  }

  private async readIndexValue<T>(
    scope: string,
    key: string,
    label: string,
    source: "manifest" | "legacy",
  ): Promise<{ ok: true; value: T | null } | { ok: false }> {
    try {
      return { ok: true, value: await this.kv.get<T>(scope, key) };
    } catch (err) {
      logger.warn(`index persistence: ${label} ${source} read failed`, {
        scope,
        key,
        message: errorMessage(err),
      });
      return { ok: false };
    }
  }

  private async loadManifestData(manifest: IndexShardManifest, label: string): Promise<string | null> {
    if (
      manifest.v !== 1 ||
      !Array.isArray(manifest.shards) ||
      manifest.shards.length === 0 ||
      !Number.isInteger(manifest.chars) ||
      manifest.chars < 0
    ) {
      logger.warn(`index persistence: ${label} shard manifest invalid`);
      return null;
    }
    for (const shard of manifest.shards) {
      if (!isValidShardDescriptor(shard)) {
        logger.warn(`index persistence: ${label} shard manifest invalid`);
        return null;
      }
    }
    const loadedShards = await Promise.all(
      manifest.shards.map(async (shard) => ({
        shard,
        chunk: await this.kv.get<string>(shard.scope, shard.key).catch(() => null),
      })),
    );
    const chunks: string[] = [];
    let chars = 0;
    for (const { shard, chunk } of loadedShards) {
      if (typeof chunk !== "string") {
        logger.warn(`index persistence: ${label} shard missing`, { scope: shard.scope, key: shard.key });
        return null;
      }
      if (chunk.length !== shard.chars) {
        logger.warn(`index persistence: ${label} shard length mismatch`, {
          scope: shard.scope,
          key: shard.key,
          expected: shard.chars,
          actual: chunk.length,
        });
        return null;
      }
      chunks.push(chunk);
      chars += chunk.length;
    }
    if (chars !== manifest.chars) {
      logger.warn(`index persistence: ${label} total length mismatch`, { expected: manifest.chars, actual: chars });
      return null;
    }
    return chunks.join("");
  }
}