@remnic/core 9.69.87 → 9.69.89

package/dist/chunk-UCPGOUDZ.js

@@ -0,0 +1,726 @@
+import {
+  readEnvVar
+} from "./chunk-P2QRMMVQ.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
+
+// src/embedding-index-storage.ts
+import path from "path";
+import { constants as bufferConstants } from "buffer";
+import { lstat, mkdir, mkdtemp, realpath, readFile, readdir, rename, rm, stat, writeFile } from "fs/promises";
+var EmbeddingIndexCapacityError = class extends Error {
+  constructor(message, memoryId) {
+    super(message);
+    this.memoryId = memoryId;
+  }
+  memoryId;
+  name = "EmbeddingIndexCapacityError";
+};
+var EmbeddingIndexStorageError = class extends Error {
+  name = "EmbeddingIndexStorageError";
+};
+var DEFAULT_INDEX_FILE_CHAR_LIMIT = bufferConstants.MAX_STRING_LENGTH - 16 * 1024 * 1024;
+function resolveIndexHardReadCharLimit() {
+  const soft = resolveIndexFileCharLimit();
+  const raw = readEnvVar("REMNIC_EMBEDDING_INDEX_HARD_READ_LIMIT_CHARS");
+  if (raw) {
+    const parsed = Number(raw);
+    if (Number.isInteger(parsed) && parsed >= soft) return parsed;
+  }
+  return bufferConstants.MAX_STRING_LENGTH;
+}
+var SHARD_COUNT = 64;
+var SHARD_FILE_PATTERN = /^shard-\d{4}\.json$/;
+function resolveIndexFileCharLimit() {
+  const raw = readEnvVar("REMNIC_EMBEDDING_INDEX_FILE_CHAR_LIMIT");
+  if (raw) {
+    const parsed = Number(raw);
+    if (Number.isInteger(parsed) && parsed >= 1024) return parsed;
+  }
+  return DEFAULT_INDEX_FILE_CHAR_LIMIT;
+}
+function shardFileName(shardIndex) {
+  return `shard-${String(shardIndex).padStart(4, "0")}.json`;
+}
+function replacementBackupPath(shardDir) {
+  return path.join(path.dirname(shardDir), "embeddings.pre-replace.tmp");
+}
+function shardIndexOf(memoryId, shardCount) {
+  let hash = 2166136261;
+  for (let i = 0; i < memoryId.length; i++) {
+    hash ^= memoryId.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash % shardCount;
+}
+function validateShardMembership(shardName, file) {
+  const match = /^shard-(\d{4})\.json$/.exec(shardName);
+  if (!match) return;
+  const shardIndex = Number(match[1]);
+  for (const id of Object.keys(file.entries)) {
+    if (shardIndexOf(id, SHARD_COUNT) !== shardIndex) {
+      throw new EmbeddingIndexStorageError(
+        `refusing embedding index shard ${shardName}: id ${id} hashes to shard ${shardIndexOf(id, SHARD_COUNT)}, not ${shardIndex}; file preserved in place`
+      );
+    }
+  }
+}
+function isInvalidStringLengthError(err) {
+  return err instanceof RangeError && /invalid string length/i.test(err.message);
+}
+function parseEmbeddingIndexDocument(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return {
+      outcome: "unreadable",
+      reason: `JSON parse failed: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || parsed.version !== 1 || typeof parsed.provider !== "string" || typeof parsed.model !== "string" || parsed.model.length === 0) {
+    return { outcome: "foreign" };
+  }
+  if (parsed.provider !== "openai" && parsed.provider !== "local" && parsed.provider !== "host") {
+    return { outcome: "foreign" };
+  }
+  const entries = parsed.entries;
+  if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+    return {
+      outcome: "unreadable",
+      reason: "entries must be a plain record of memory id -> entry"
+    };
+  }
+  for (const [id, entry] of Object.entries(entries)) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      return { outcome: "unreadable", reason: `entry ${id} must be an object` };
+    }
+    const candidate = entry;
+    if (typeof candidate.path !== "string") {
+      return { outcome: "unreadable", reason: `entry ${id}.path must be a string` };
+    }
+    if (!Array.isArray(candidate.vector)) {
+      return { outcome: "unreadable", reason: `entry ${id}.vector must be an array` };
+    }
+    for (const component of candidate.vector) {
+      if (!Number.isFinite(component)) {
+        return {
+          outcome: "unreadable",
+          reason: `entry ${id}.vector must contain only finite numbers`
+        };
+      }
+    }
+  }
+  return { outcome: "ok", file: parsed };
+}
+function shardEntriesForIndex(index) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const id of Object.keys(index.entries)) {
+    const shardIndex = shardIndexOf(id, SHARD_COUNT);
+    const group = groups.get(shardIndex);
+    if (group) group[id] = index.entries[id];
+    else groups.set(shardIndex, { [id]: index.entries[id] });
+  }
+  return groups;
+}
+function serializeEmbeddingShard(index, shardIndex, entries, limit = resolveIndexFileCharLimit()) {
+  let body;
+  try {
+    body = JSON.stringify({
+      version: 1,
+      provider: index.provider,
+      model: index.model,
+      entries
+    });
+  } catch (err) {
+    throw new EmbeddingIndexCapacityError(
+      `embedding index shard ${shardFileName(shardIndex)} exceeded the single-string ceiling while serializing: ${err instanceof Error ? err.message : String(err)}`,
+      largestEntryId(entries) || void 0
+    );
+  }
+  if (body.length > limit) {
+    const worstId = largestEntryId(entries);
+    const worstLength = worstId && entries[worstId] ? JSON.stringify(entries[worstId]).length : 0;
+    throw new EmbeddingIndexCapacityError(
+      `embedding index shard ${shardFileName(shardIndex)} needs ${body.length} chars, over the ${limit}-char single-file limit; largest entry ${worstId || "(unknown)"} serializes to ${worstLength} chars`,
+      worstId || void 0
+    );
+  }
+  return body;
+}
+function largestEntryId(entries) {
+  let worstId = "";
+  let worstLength = 0;
+  for (const [id, entry] of Object.entries(entries)) {
+    let length;
+    try {
+      length = JSON.stringify(entry).length;
+    } catch {
+      return id;
+    }
+    if (length > worstLength) {
+      worstLength = length;
+      worstId = id;
+    }
+  }
+  return worstId;
+}
+var EmbeddingIndexFileStore = class _EmbeddingIndexFileStore {
+  constructor(indexPath, shardDir, statusPath, io) {
+    this.indexPath = indexPath;
+    this.shardDir = shardDir;
+    this.statusPath = statusPath;
+    this.io = io;
+    if (io && Boolean(io.readUtf8) !== Boolean(io.writeUtf8)) {
+      throw new EmbeddingIndexStorageError(
+        "embedding index store io requires both readUtf8 and writeUtf8; a half-wired io would mix encrypted and plaintext files"
+      );
+    }
+  }
+  indexPath;
+  shardDir;
+  statusPath;
+  io;
+  /** Legacy single-file layout path (public for error messages). */
+  get legacyPath() {
+    return this.indexPath;
+  }
+  /** Record an unreadable-authoritative-file reason (both read and mutation paths). */
+  async recordIndexStatusForLoad(reason) {
+    await this.recordIndexStatus({
+      lastReadRecovery: { ts: (/* @__PURE__ */ new Date()).toISOString(), message: reason }
+    });
+  }
+  /**
+   * Which generation owns the index right now. The published
+   * `state/embeddings/` directory IS the layout marker: until it exists the
+   * legacy file is authoritative; from the atomic rename onward it never
+   * merges again.
+   */
+  async detectLayout() {
+    try {
+      const info = await lstat(this.shardDir);
+      if (info.isSymbolicLink()) {
+        throw new EmbeddingIndexStorageError(
+          `embedding index shard directory is a symlink; refusing to read or write through it: ${this.shardDir}`
+        );
+      }
+      return "sharded";
+    } catch (err) {
+      if (err instanceof EmbeddingIndexStorageError) throw err;
+      if (err.code !== "ENOENT") {
+        log.warn(`embedding index: shard dir stat failed (${err instanceof Error ? err.message : String(err)}); assuming sharded layout`);
+        return "sharded";
+      }
+      if (await this.replacementBackupExists()) return "sharded";
+      return this.legacyOrEmptyLayout();
+    }
+  }
+  /**
+   * Roll the fixed transaction backup back into the published position.
+   * Returns true when a rollback happened.
+   */
+  async replacementBackupExists() {
+    const backupPath = replacementBackupPath(this.shardDir);
+    try {
+      await stat(backupPath);
+      return true;
+    } catch (err) {
+      if (err.code === "ENOENT") return false;
+      throw new EmbeddingIndexStorageError(
+        `cannot stat embedding index replacement backup ${backupPath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  /**
+   * The fixed transaction backup is a path with well-known semantics; a
+   * planted symlink must never be restored into the published position (it
+   * would point the generation outside the memory dir) nor removed through
+   * as if it were the former generation. Symlinks are rejected outright.
+   */
+  async assertBackupNotSymlink(backupPath) {
+    const info = await lstat(backupPath).catch((err) => {
+      if (err.code === "ENOENT") return null;
+      throw err;
+    });
+    if (info?.isSymbolicLink()) {
+      throw new EmbeddingIndexStorageError(
+        `embedding index replacement backup is a symlink; refusing to touch it: ${backupPath}`
+      );
+    }
+  }
+  /**
+   * Mutation-queue entry point: roll the fixed transaction backup back into
+   * the published position after an interrupted replacement. Returns true
+   * when a rollback happened. Only fires in the actual rename gap
+   * (published directory absent); callers must invalidate any cached index
+   * view when this returns true.
+   */
+  async recoverIfInterrupted(fence) {
+    try {
+      await stat(this.shardDir);
+      return false;
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        log.warn(`embedding index: recovery skipped because shard dir stat failed: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+      }
+    }
+    const backupPath = replacementBackupPath(this.shardDir);
+    if (!await this.replacementBackupExists()) return false;
+    await this.assertBackupNotSymlink(backupPath);
+    await fence?.();
+    await rename(backupPath, this.shardDir);
+    log.warn(
+      `embedding index: recovered interrupted replacement; former generation restored from ${backupPath}`
+    );
+    await this.recordIndexStatus({
+      lastReadRecovery: {
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        message: "interrupted identity replacement rolled back to the former generation"
+      }
+    });
+    return true;
+  }
+  async legacyOrEmptyLayout() {
+    try {
+      await stat(this.indexPath);
+      return "legacy";
+    } catch (err) {
+      if (err.code === "ENOENT") return "empty";
+      throw err;
+    }
+  }
+  /** Header identity of the authoritative generation, read leniently. */
+  async identityFromDisk() {
+    const layout = await this.detectLayout();
+    if (layout === "sharded") {
+      for (const name of await this.readShardNames()) {
+        const read = await this.readFileAt(path.join(this.shardDir, name));
+        if (read.outcome === "ok") {
+          return { provider: read.file.provider, model: read.file.model };
+        }
+      }
+      return null;
+    }
+    if (layout === "legacy") {
+      const read = await this.readFileAt(this.indexPath);
+      if (read.outcome === "ok") {
+        return { provider: read.file.provider, model: read.file.model };
+      }
+    }
+    return null;
+  }
+  /**
+   * Load every readable shard into `merged`. Returns the generation identity.
+   * Unreadable shards record durable diagnostics; `strict` additionally
+   * fails the mutation closed.
+   */
+  async readShardGenerationInto(merged) {
+    let identity = null;
+    for (const name of await this.readShardNames()) {
+      const read = await this.readFileAt(path.join(this.shardDir, name));
+      if (read.outcome !== "ok") {
+        if (read.outcome === "unreadable") {
+          await this.recordIndexStatus({
+            lastReadRecovery: { ts: (/* @__PURE__ */ new Date()).toISOString(), message: `${name}: ${read.reason}` }
+          });
+          throw new EmbeddingIndexStorageError(
+            `refusing to continue from unreadable embedding index shard ${name}: ${read.reason}`
+          );
+        }
+        await this.recordIndexStatus({
+          lastReadRecovery: { ts: (/* @__PURE__ */ new Date()).toISOString(), message: `${name}: unrecognized index format` }
+        });
+        throw new EmbeddingIndexStorageError(
+          `refusing to continue from malformed embedding index shard ${name} (unrecognized format); file preserved in place`
+        );
+      }
+      try {
+        validateShardMembership(name, read.file);
+      } catch (error) {
+        await this.recordIndexStatus({
+          lastReadRecovery: { ts: (/* @__PURE__ */ new Date()).toISOString(), message: String(error) }
+        });
+        throw error;
+      }
+      const shardIdentity = { provider: read.file.provider, model: read.file.model };
+      if (!identity) identity = shardIdentity;
+      if (!sameIndexIdentity(shardIdentity, identity)) {
+        throw new EmbeddingIndexStorageError(
+          `refusing to continue from mixed-identity embedding index generation: ${name} is ${shardIdentity.provider}/${shardIdentity.model} but the generation identity is ${identity.provider}/${identity.model}; files preserved in place`
+        );
+      }
+      Object.assign(merged, read.file.entries);
+    }
+    return identity;
+  }
+  async readLegacy() {
+    return this.readFileAt(this.indexPath);
+  }
+  /**
+   * Read one managed index file (legacy or shard). The file is never
+   * modified or moved here: an unreadable file stays in place for recovery
+   * and is reported through the returned outcome (mutation paths fail
+   * closed on it; read-only paths fail open and record the reason).
+   */
+  /**
+   * Read/mutation boundary for any generation member or the legacy marker
+   * (codex PRRT_kwDORJXyws6mZ72r): a symlinked member is rejected outright
+   * and its real target must stay inside the canonical state directory —
+   * following a planted link would read or write outside the memory root.
+   * Runs BEFORE the secure IO so storage-backed reads are covered too.
+   */
+  async assertGenerationFileNotSymlinked(filePath) {
+    const info = await lstat(filePath).catch((err) => {
+      if (err.code === "ENOENT") return null;
+      throw new EmbeddingIndexStorageError(
+        `cannot lstat embedding index file ${filePath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    });
+    const stateDir = path.dirname(this.shardDir);
+    const real = await realpath(filePath).catch(() => null);
+    if (real) {
+      const scope = await realpath(stateDir).catch(() => stateDir);
+      const rel = path.relative(scope, real);
+      if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new EmbeddingIndexStorageError(
+          `embedding index file escapes the state directory via symlink; refusing: ${filePath} -> ${real}`
+        );
+      }
+    }
+    if (!info || !info.isSymbolicLink()) return;
+    throw new EmbeddingIndexStorageError(
+      `embedding index file is a symlink; refusing to read or write through it: ${filePath}`
+    );
+  }
+  async readFileAt(filePath) {
+    await this.assertGenerationFileNotSymlinked(filePath);
+    const hardLimit = resolveIndexHardReadCharLimit();
+    let size = 0;
+    try {
+      size = (await stat(filePath)).size;
+    } catch (err) {
+      if (err.code === "ENOENT") return { outcome: "absent" };
+      return { outcome: "unreadable", reason: `stat failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (size > hardLimit) {
+      return {
+        outcome: "unreadable",
+        reason: `file is ${size} bytes, over the ${hardLimit}-char hard single-string read ceiling (V8 RangeError territory); bytes preserved in place \u2014 move or prune the file to recover`
+      };
+    }
+    let raw;
+    try {
+      raw = this.io ? await this.io.readUtf8(filePath) : await readFile(filePath, "utf-8");
+    } catch (err) {
+      return { outcome: "unreadable", reason: `read failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    return parseEmbeddingIndexDocument(raw);
+  }
+  async readShardNames() {
+    try {
+      return (await readdir(this.shardDir)).filter((name) => SHARD_FILE_PATTERN.test(name)).sort();
+    } catch (err) {
+      if (err.code === "ENOENT") return [];
+      throw new EmbeddingIndexStorageError(
+        `cannot enumerate embedding index shard directory ${this.shardDir}: ${err instanceof Error ? `${err.message} (${err.code ?? "unknown"})` : String(err)}`
+      );
+    }
+  }
+  /**
+   * Persist the index. Layout decisions, in order:
+   *   - published generation: rewrite only the shards this mutation touched;
+   *   - legacy/empty generation and the whole index fits one bounded JSON
+   *     string: stay the single `state/embeddings.json` file;
+   *   - over budget: ONE-WAY migration — stage a complete shard set, publish
+   *     it with a single directory rename, then rename the legacy file aside
+   *     as a non-authoritative recovery artifact (issue #3146).
+   */
+  async persist(index, opts = {}) {
+    const stateDir = path.dirname(this.indexPath);
+    await mkdir(stateDir, { recursive: true });
+    await this.cleanForeignStagingDirs();
+    const groups = shardEntriesForIndex(index);
+    const layout = await this.detectLayout();
+    if (layout === "sharded") {
+      const limit2 = resolveIndexFileCharLimit();
+      const diskIdentity = await this.identityFromDisk();
+      if (groups.size === 0) {
+        groups.set(0, {});
+        await this.publishReplacementGeneration(index, groups, limit2, opts.fence);
+        return;
+      }
+      const identityChanged = diskIdentity !== null && (diskIdentity.provider !== index.provider || diskIdentity.model !== index.model);
+      if (identityChanged) {
+        await this.publishReplacementGeneration(index, groups, limit2, opts.fence);
+        return;
+      }
+      const dirtyShards = opts.touchedIds?.length ? new Set(opts.touchedIds.map((id) => shardIndexOf(id, SHARD_COUNT))) : null;
+      const targets = dirtyShards ? [...dirtyShards] : [...groups.keys()];
+      const payloads = targets.filter((shardIndex) => groups.has(shardIndex)).map((shardIndex) => ({
+        shardIndex,
+        body: serializeEmbeddingShard(index, shardIndex, groups.get(shardIndex), limit2)
+      }));
+      await opts.fence?.();
+      for (const payload of payloads) {
+        await this.writeAtomicFile(
+          path.join(this.shardDir, shardFileName(payload.shardIndex)),
+          payload.body
+        );
+      }
+      for (const shardIndex of targets) {
+        if (!groups.has(shardIndex)) {
+          await rm(path.join(this.shardDir, shardFileName(shardIndex)), { force: true });
+        }
+      }
+      return;
+    }
+    let whole;
+    try {
+      whole = JSON.stringify(index);
+    } catch (err) {
+      if (!isInvalidStringLengthError(err)) throw err;
+      whole = null;
+    }
+    const limit = resolveIndexFileCharLimit();
+    if (whole !== null && whole.length <= limit) {
+      await opts.fence?.();
+      await this.writeAtomicFile(this.indexPath, whole);
+      return;
+    }
+    const stagingDir = path.join(
+      stateDir,
+      `embeddings.staging.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+    );
+    await mkdir(stagingDir, { recursive: true });
+    try {
+      await this.stageShardSet(stagingDir, index, groups, limit);
+      await this.publishSwappedGeneration(stagingDir, opts.fence);
+    } catch (err) {
+      await rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+      throw err;
+    }
+    await rename(
+      this.indexPath,
+      `${this.indexPath}.pre-migration.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`
+    ).catch(() => void 0);
+  }
+  /**
+   * Replace a published generation wholesale after a provider/model identity
+   * change (replacement semantics — the former entries are obsolete by
+   * definition). Crash-safe by the same construction as the migration: the
+   * COMPLETE new-identity set is staged and validated first (old bytes are
+   * not touched until staging succeeds), then published atomically through
+   * `publishSwappedGeneration`.
+   */
+  async publishReplacementGeneration(index, groups, limit, fence) {
+    const stateDir = path.dirname(this.indexPath);
+    const stagingDir = path.join(
+      stateDir,
+      `embeddings.staging.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+    );
+    await mkdir(stagingDir, { recursive: true });
+    try {
+      await this.stageShardSet(stagingDir, index, groups, limit);
+      await this.publishSwappedGeneration(stagingDir, fence);
+    } catch (err) {
+      await rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+      throw err;
+    }
+  }
+  /**
+   * Write a complete shard set into a staging directory. Every shard is
+   * serialized before the first write, so a capacity failure cannot leave a
+   * partial stage behind.
+   */
+  async stageShardSet(stagingDir, index, groups, limit) {
+    const payloads = [...groups].map(([shardIndex, entries]) => ({
+      shardIndex,
+      body: serializeEmbeddingShard(index, shardIndex, entries, limit)
+    }));
+    for (const payload of payloads) {
+      const finalAadFilePath = path.join(this.shardDir, shardFileName(payload.shardIndex));
+      await this.writeAtomicFile(
+        path.join(stagingDir, shardFileName(payload.shardIndex)),
+        payload.body,
+        { finalAadFilePath }
+      );
+    }
+  }
+  /**
+   * Atomically remove the published generation (offline-sync: the remote
+   * deleted the whole index) by publishing an EMPTY staged directory
+   * through the shared swap: the rename is atomic, so the former generation
+   * moves whole into the fixed backup and back — a failure before the
+   * commit rolls the former generation back intact, and a post-commit
+   * backup-cleanup failure is non-fatal (the empty published directory
+   * stays the authoritative one-way layout marker). The fixed backup is
+   * symlink-checked first (round 5).
+   */
+  async removePublishedGeneration(fence) {
+    const backupPath = replacementBackupPath(this.shardDir);
+    await this.assertBackupNotSymlink(backupPath);
+    await rm(backupPath, { recursive: true, force: true });
+    await mkdir(path.dirname(this.shardDir), { recursive: true });
+    const emptyStaging = await mkdtemp(
+      path.join(path.dirname(this.shardDir), "embeddings.staging.tmp-empty-")
+    );
+    try {
+      await this.publishSwappedGeneration(emptyStaging, fence);
+    } catch (err) {
+      await rm(emptyStaging, { recursive: true, force: true }).catch(() => void 0);
+      throw err;
+    }
+  }
+  /**
+   * Atomically publish a fully staged generation directory as THE published
+   * generation. The former published directory is demoted to the FIXED
+   * transaction backup and the staging dir is renamed in with a single
+   * rename; if the publish rename fails the former generation is rolled
+   * back, and if the process dies in the rename gap `detectLayout()` /
+   * `recoverIfInterrupted()` perform the same rollback on next use.
+   * Shared by the mutation-side migration/replacement and the offline-sync
+   * generation transaction (issue #3148, round 4) so there is exactly one
+   * swap state machine. Staging-dir cleanup stays with the caller.
+   */
+  async publishSwappedGeneration(stagingDir, fence) {
+    const backupPath = replacementBackupPath(this.shardDir);
+    await this.assertBackupNotSymlink(backupPath);
+    await fence?.();
+    await rm(backupPath, { recursive: true, force: true });
+    await fence?.();
+    let demoted = false;
+    try {
+      await stat(this.shardDir);
+      await rename(this.shardDir, backupPath);
+      demoted = true;
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+    try {
+      await rename(stagingDir, this.shardDir);
+    } catch (err) {
+      if (demoted) await rename(backupPath, this.shardDir).catch(() => void 0);
+      throw err;
+    }
+    await rm(backupPath, { recursive: true, force: true }).catch((err) => {
+      log.warn(`embedding index: could not remove replacement backup ${backupPath}: ${err}`);
+    });
+  }
+  /** Remove staging dirs orphaned by crashed migrations. A foreign dir younger than the grace window may belong to a live writer mid-migration, so only older dirs are removed (issue #3148 review, round 3). */
+  static STAGING_CLEANUP_GRACE_MS = 10 * 60 * 1e3;
+  async cleanForeignStagingDirs() {
+    const stateDir = path.dirname(this.indexPath);
+    let names = [];
+    try {
+      names = await readdir(stateDir);
+    } catch {
+      return;
+    }
+    const ownPrefix = `embeddings.staging.tmp-${process.pid}-`;
+    const cutoff = Date.now() - _EmbeddingIndexFileStore.STAGING_CLEANUP_GRACE_MS;
+    for (const name of names) {
+      if (!name.startsWith("embeddings.staging.tmp-") || name.startsWith(ownPrefix)) continue;
+      try {
+        const stats = await stat(path.join(stateDir, name));
+        if (stats.mtimeMs > cutoff) continue;
+      } catch {
+        continue;
+      }
+      await rm(path.join(stateDir, name), { recursive: true, force: true }).catch(() => void 0);
+    }
+  }
+  /**
+   * Temp-file + rename write. The temp name carries `.tmp-` so offline sync
+   * ignores in-flight files under `state/`. With a wired io, the write goes
+   * through the canonical secure-store contract instead, optionally binding
+   * the ciphertext to the FINAL published path (staged shards).
+   */
+  async writeAtomicFile(filePath, contents, opts) {
+    if (this.io && opts?.bypassSecureIo !== true) {
+      await this.io.writeUtf8(filePath, contents, opts?.finalAadFilePath === void 0 ? void 0 : { finalAadFilePath: opts.finalAadFilePath });
+      return;
+    }
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    try {
+      await writeFile(tempPath, contents, "utf-8");
+      await rename(tempPath, filePath);
+    } catch (err) {
+      await rm(tempPath, { force: true }).catch(() => void 0);
+      throw err;
+    }
+  }
+  /**
+   * Record the outcome of one index mutation durably. This is diagnostics,
+   * NOT recovery: write failures are recorded and then re-thrown by the
+   * caller so the extraction/consolidation task fails explicitly instead of
+   * declaring success over an index that could not be persisted (issue
+   * #3146).
+   */
+  async recordIndexWriteOutcome(err, memoryId) {
+    if (!err) {
+      await this.recordIndexStatus({
+        lastWriteFailure: null,
+        lastSuccessAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      return;
+    }
+    const kind = err instanceof EmbeddingIndexCapacityError || isInvalidStringLengthError(err) ? "capacity" : "io";
+    await this.recordIndexStatus({
+      failureCountIncrement: 1,
+      lastWriteFailure: {
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        kind,
+        message: err instanceof Error ? err.message : String(err),
+        ...memoryId ? { memoryId } : {}
+      }
+    });
+  }
+  /**
+   * Merge diagnostic state into `state/embedding-fallback-status.json`.
+   * Best-effort: a diagnostics failure never masks the real outcome.
+   */
+  async recordIndexStatus(patch) {
+    try {
+      let current = { version: 1, failureCount: 0 };
+      try {
+        const parsed = JSON.parse(await readFile(this.statusPath, "utf-8"));
+        if (parsed && typeof parsed === "object" && typeof parsed.failureCount === "number") {
+          current = { ...parsed, version: 1, failureCount: parsed.failureCount };
+        }
+      } catch {
+      }
+      const next = { ...current };
+      if (patch.failureCountIncrement) next.failureCount += patch.failureCountIncrement;
+      if (patch.lastWriteFailure !== void 0) {
+        if (patch.lastWriteFailure === null) delete next.lastWriteFailure;
+        else next.lastWriteFailure = patch.lastWriteFailure;
+      }
+      if (patch.lastReadRecovery !== void 0) next.lastReadRecovery = patch.lastReadRecovery;
+      if (patch.lastSuccessAt !== void 0) next.lastSuccessAt = patch.lastSuccessAt;
+      await mkdir(path.dirname(this.statusPath), { recursive: true });
+      await this.writeAtomicFile(this.statusPath, JSON.stringify(next), { bypassSecureIo: true });
+    } catch (err) {
+      log.debug(`embedding fallback status write failed: ${err}`);
+    }
+  }
+};
+function sameIndexIdentity(left, right) {
+  return left.provider === right.provider && left.model === right.model;
+}
+
+export {
+  EmbeddingIndexCapacityError,
+  EmbeddingIndexStorageError,
+  resolveIndexFileCharLimit,
+  shardIndexOf,
+  validateShardMembership,
+  isInvalidStringLengthError,
+  parseEmbeddingIndexDocument,
+  shardEntriesForIndex,
+  serializeEmbeddingShard,
+  EmbeddingIndexFileStore
+};
+//# sourceMappingURL=chunk-UCPGOUDZ.js.map