@remnic/core 1.1.31 → 9.3.516

package/src/search/orama-backend.ts

@@ -4,6 +4,7 @@ import { log } from "../logger.js";
 import type { SearchBackend, SearchExecutionOptions, SearchQueryOptions, SearchResult } from "./port.js";
 import type { EmbedHelper } from "./embed-helper.js";
 import { scanMemoryDir } from "./document-scanner.js";
+import { isSearchAborted, throwIfSearchAborted } from "./abort.js";
 
 export interface OramaBackendOptions {
   dbPath: string;
@@ -13,6 +14,30 @@ export interface OramaBackendOptions {
   embeddingDimension: number;
 }
 
+const ORAMA_COLLECTION_FILENAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function pathIsInside(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function resolveOramaCollectionDbFilePath(dbPath: string, collection: string): string {
+  if (!ORAMA_COLLECTION_FILENAME_PATTERN.test(collection)) {
+    throw new Error(
+      `Invalid Orama collection name ${JSON.stringify(collection)}. ` +
+        "Collection names must match [A-Za-z0-9][A-Za-z0-9._-]*.",
+    );
+  }
+  const resolvedDbPath = path.resolve(dbPath);
+  const filePath = path.resolve(resolvedDbPath, `${collection}.msp`);
+  if (!pathIsInside(resolvedDbPath, filePath)) {
+    throw new Error(
+      `Invalid Orama collection path for ${JSON.stringify(collection)}: resolved outside dbPath.`,
+    );
+  }
+  return filePath;
+}
+
 /**
  * Orama search backend — embedded hybrid FTS+vector, pure JS.
  *
@@ -64,21 +89,23 @@ export class OramaBackend implements SearchBackend {
     _collection?: string,
     maxResults?: number,
     _options?: SearchQueryOptions,
-    _execution?: SearchExecutionOptions,
+    execution?: SearchExecutionOptions,
   ): Promise<SearchResult[]> {
-    return this.hybridSearch(query, _collection, maxResults);
+    return this.hybridSearch(query, _collection, maxResults, execution);
   }
 
-  async searchGlobal(query: string, maxResults?: number, _execution?: SearchExecutionOptions): Promise<SearchResult[]> {
+  async searchGlobal(query: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]> {
     const limit = maxResults ?? 10;
     if (!this.available) return [];
     try {
+      throwIfSearchAborted(execution, "OramaBackend global search aborted");
       const files = await this.listDbFiles();
       const allResults: SearchResult[] = [];
       for (const file of files) {
+        throwIfSearchAborted(execution, "OramaBackend global search aborted");
         const db = await this.loadDbFromFile(file);
         if (!db) continue;
-        const results = await this.searchDb(db, query, "hybrid", limit);
+        const results = await this.searchDb(db, query, "hybrid", limit, execution);
         allResults.push(...results);
       }
       allResults.sort((a, b) => b.score - a.score);
@@ -89,34 +116,43 @@ export class OramaBackend implements SearchBackend {
     }
   }
 
-  async bm25Search(query: string, collection?: string, maxResults?: number, _execution?: SearchExecutionOptions): Promise<SearchResult[]> {
+  async bm25Search(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]> {
+    if (isSearchAborted(execution)) return [];
     const db = await this.ensureDbForCollection(collection ?? this.collection);
+    if (isSearchAborted(execution)) return [];
     if (!db) return [];
-    return this.searchDb(db, query, "fulltext", maxResults ?? 10);
+    return this.searchDb(db, query, "fulltext", maxResults ?? 10, execution);
   }
 
-  async vectorSearch(query: string, collection?: string, maxResults?: number, _execution?: SearchExecutionOptions): Promise<SearchResult[]> {
+  async vectorSearch(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]> {
+    if (isSearchAborted(execution)) return [];
     const db = await this.ensureDbForCollection(collection ?? this.collection);
+    if (isSearchAborted(execution)) return [];
     if (!db) return [];
-    return this.searchDb(db, query, "vector", maxResults ?? 10);
+    return this.searchDb(db, query, "vector", maxResults ?? 10, execution);
   }
 
-  async hybridSearch(query: string, collection?: string, maxResults?: number, _execution?: SearchExecutionOptions): Promise<SearchResult[]> {
+  async hybridSearch(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]> {
+    if (isSearchAborted(execution)) return [];
     const db = await this.ensureDbForCollection(collection ?? this.collection);
+    if (isSearchAborted(execution)) return [];
     if (!db) return [];
-    return this.searchDb(db, query, "hybrid", maxResults ?? 10);
+    return this.searchDb(db, query, "hybrid", maxResults ?? 10, execution);
   }
 
   async update(execution?: SearchExecutionOptions): Promise<void> {
     await this.updateCollection(this.collection, execution);
   }
 
-  async updateCollection(collection: string, _execution?: SearchExecutionOptions): Promise<void> {
+  async updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void> {
+    if (isSearchAborted(execution)) return;
     const db = await this.ensureDbForCollection(collection);
+    if (isSearchAborted(execution)) return;
     if (!db) return;
     const { search: oramaSearch, insert, remove, count } = this.oramaModule;
 
     const docs = await scanMemoryDir(this.memoryDir);
+    if (isSearchAborted(execution)) return;
     const docMap = new Map(docs.map((d) => [d.docid, d]));
     const { update: oramaUpdate } = this.oramaModule;
 
@@ -126,6 +162,7 @@ export class OramaBackend implements SearchBackend {
     if (existingCount > 0) {
       const allHits = await oramaSearch(db, { term: "", limit: existingCount + 100 });
       for (const hit of allHits.hits) {
+        if (isSearchAborted(execution)) return;
         if (!docMap.has(hit.document.id)) {
           await remove(db, hit.id);
         } else {
@@ -139,6 +176,7 @@ export class OramaBackend implements SearchBackend {
 
     // Insert new docs, update existing ones (preserving vectors since update is remove+insert)
     for (const doc of docs) {
+      if (isSearchAborted(execution)) return;
       const existing = existingDocs.get(doc.docid);
       if (existing) {
         const payload: Record<string, unknown> = {
@@ -169,6 +207,7 @@ export class OramaBackend implements SearchBackend {
       }
     }
 
+    if (isSearchAborted(execution)) return;
     await this.persistDbForCollection(db, collection);
   }
 
@@ -212,7 +251,10 @@ export class OramaBackend implements SearchBackend {
     await this.persistDbForCollection(db, collection);
   }
 
-  async ensureCollection(_memoryDir: string): Promise<"present" | "missing" | "unknown" | "skipped"> {
+  async ensureCollection(
+    _memoryDir: string,
+    _execution?: SearchExecutionOptions,
+  ): Promise<"present" | "missing" | "unknown" | "skipped"> {
     try {
       await this.ensureModules();
       await this.ensureDb();
@@ -293,7 +335,7 @@ export class OramaBackend implements SearchBackend {
   }
 
   private dbFilePath(collection: string): string {
-    return path.join(this.dbPath, `${collection}.msp`);
+    return resolveOramaCollectionDbFilePath(this.dbPath, collection);
   }
 
   private async listDbFiles(): Promise<string[]> {
@@ -317,16 +359,24 @@ export class OramaBackend implements SearchBackend {
     }
   }
 
-  private async searchDb(db: any, query: string, mode: "fulltext" | "vector" | "hybrid", limit: number): Promise<SearchResult[]> {
+  private async searchDb(
+    db: any,
+    query: string,
+    mode: "fulltext" | "vector" | "hybrid",
+    limit: number,
+    execution?: SearchExecutionOptions,
+  ): Promise<SearchResult[]> {
     const { search: oramaSearch } = this.oramaModule;
 
     try {
+      throwIfSearchAborted(execution, `OramaBackend ${mode} search aborted`);
       let searchParams: any;
 
       if (mode === "fulltext") {
         searchParams = { term: query, limit };
       } else if (mode === "vector") {
-        const vec = await this.embedHelper.embed(query);
+        const vec = await this.embedHelper.embed(query, { signal: execution?.signal });
+        throwIfSearchAborted(execution, `OramaBackend ${mode} search aborted`);
         if (!vec) {
           // Fall back to fulltext if no embeddings available
           searchParams = { term: query, limit };
@@ -335,7 +385,8 @@ export class OramaBackend implements SearchBackend {
         }
       } else {
         // hybrid
-        const vec = await this.embedHelper.embed(query);
+        const vec = await this.embedHelper.embed(query, { signal: execution?.signal });
+        throwIfSearchAborted(execution, `OramaBackend ${mode} search aborted`);
         if (!vec) {
           searchParams = { term: query, limit };
         } else {
@@ -343,7 +394,9 @@ export class OramaBackend implements SearchBackend {
         }
       }
 
+      throwIfSearchAborted(execution, `OramaBackend ${mode} search aborted`);
       const result = await oramaSearch(db, searchParams);
+      throwIfSearchAborted(execution, `OramaBackend ${mode} search aborted`);
       return (result.hits ?? []).map((hit: any) => ({
         docid: hit.document?.id ?? "",
         path: hit.document?.path ?? "",

package/src/search/port.ts

@@ -82,5 +82,8 @@ export interface SearchBackend {
   embedCollection(collection: string): Promise<void>;
 
   // ── Collection management ──
-  ensureCollection(memoryDir: string): Promise<"present" | "missing" | "unknown" | "skipped">;
+  ensureCollection(
+    memoryDir: string,
+    execution?: SearchExecutionOptions,
+  ): Promise<"present" | "missing" | "unknown" | "skipped">;
 }

package/src/search/remote-backend.ts

@@ -82,7 +82,7 @@ export class RemoteSearchBackend implements SearchBackend {
   async embed(): Promise<void> {}
   async embedCollection(_collection: string): Promise<void> {}
 
-  async ensureCollection(_memoryDir: string): Promise<"skipped"> {
+  async ensureCollection(_memoryDir: string, _execution?: SearchExecutionOptions): Promise<"skipped"> {
     return "skipped";
   }
 

package/src/secure-store/cli-handlers.ts

@@ -193,13 +193,21 @@ export function runSecureStoreLock(options: SecureStoreLockOptions): SecureStore
 
 // ─── migrate ─────────────────────────────────────────────────────────
 
-export interface SecureStoreMigrateOptions extends SecureStoreHandlerCommon {}
+export interface SecureStoreMigrateOptions extends SecureStoreHandlerCommon {
+  /**
+   * Optional passphrase reader for standalone CLI migration. A prior
+   * `secure-store unlock` command only unlocks that process-local keyring, so
+   * standalone migrate can prompt and install the key in this process instead
+   * of pretending another process still has it.
+   */
+  readPassphrase?: PassphraseReader;
+}
 
 export type SecureStoreMigrateReport =
   | ({ ok: true } & MigrateResult)
   | ({
       ok: false;
-      reason: "not-initialized" | "locked" | "file-errors";
+      reason: "not-initialized" | "locked" | "wrong-passphrase" | "file-errors";
     } & MigrateResult);
 
 export async function runSecureStoreMigrate(
@@ -218,7 +226,13 @@ export async function runSecureStoreMigrate(
   }
 
   const id = options.keyringId ?? secureStoreDir(memoryDir);
-  const key = keyring.getKey(id);
+  const key = keyring.getKey(id) ?? await unlockForThisProcess({
+    memoryDir,
+    header,
+    keyringId: id,
+    readPassphrase: options.readPassphrase,
+    now: options.now,
+  });
   if (key === null) {
     return {
       ok: false,
@@ -228,6 +242,15 @@ export async function runSecureStoreMigrate(
       errors: [],
     };
   }
+  if (key === "wrong-passphrase") {
+    return {
+      ok: false,
+      reason: "wrong-passphrase",
+      encrypted: 0,
+      skipped: 0,
+      errors: [],
+    };
+  }
 
   const result = await migrateMemoryDirToEncrypted(memoryDir, key);
   if (result.errors.length > 0) {
@@ -238,13 +261,20 @@ export async function runSecureStoreMigrate(
 
 // ─── disable/decrypt ─────────────────────────────────────────────────
 
-export interface SecureStoreDisableOptions extends SecureStoreHandlerCommon {}
+export interface SecureStoreDisableOptions extends SecureStoreHandlerCommon {
+  /**
+   * Optional passphrase reader for standalone CLI decrypt/disable. See
+   * SecureStoreMigrateOptions.readPassphrase for the process-local keyring
+   * contract.
+   */
+  readPassphrase?: PassphraseReader;
+}
 
 export type SecureStoreDisableReport =
   | ({ ok: true } & DecryptResult)
   | ({
       ok: false;
-      reason: "not-initialized" | "locked" | "file-errors";
+      reason: "not-initialized" | "locked" | "wrong-passphrase" | "file-errors";
     } & DecryptResult);
 
 export async function runSecureStoreDisable(
@@ -263,7 +293,13 @@ export async function runSecureStoreDisable(
   }
 
   const id = options.keyringId ?? secureStoreDir(memoryDir);
-  const key = keyring.getKey(id);
+  const key = keyring.getKey(id) ?? await unlockForThisProcess({
+    memoryDir,
+    header,
+    keyringId: id,
+    readPassphrase: options.readPassphrase,
+    now: options.now,
+  });
   if (key === null) {
     return {
       ok: false,
@@ -273,6 +309,15 @@ export async function runSecureStoreDisable(
       errors: [],
     };
   }
+  if (key === "wrong-passphrase") {
+    return {
+      ok: false,
+      reason: "wrong-passphrase",
+      decrypted: 0,
+      skipped: 0,
+      errors: [],
+    };
+  }
 
   const result = await decryptMemoryDirToPlaintext(memoryDir, key);
   if (result.errors.length > 0) {
@@ -353,3 +398,22 @@ function resolveParams(
   if (algorithm === "scrypt") return { ...DEFAULT_SCRYPT_PARAMS };
   return { ...DEFAULT_ARGON2ID_PARAMS };
 }
+
+async function unlockForThisProcess(options: {
+  memoryDir: string;
+  header: SecureStoreHeader;
+  keyringId: string;
+  readPassphrase?: PassphraseReader;
+  now?: () => Date;
+}): Promise<Buffer | null | "wrong-passphrase"> {
+  if (!options.readPassphrase) return null;
+  const passphrase = await options.readPassphrase("Enter passphrase: ");
+  validatePassphrase(passphrase);
+  const candidateKey = deriveKeyFromHeader(options.header, passphrase);
+  if (!verifyKey(options.header, candidateKey)) {
+    candidateKey.fill(0);
+    return "wrong-passphrase";
+  }
+  keyring.unlock(options.keyringId, candidateKey, options.now ?? (() => new Date()));
+  return candidateKey;
+}

package/src/secure-store/cli-renderer.ts

@@ -27,13 +27,13 @@ export function renderInitReport(report: SecureStoreInitReport): string {
   lines.push("");
   lines.push("Note: init does NOT auto-unlock the store. Run");
   lines.push("  remnic engram secure-store unlock");
-  lines.push("to register the master key with the running daemon.");
+  lines.push("to register the master key in the current Remnic process.");
   return lines.join("\n");
 }
 
 export function renderUnlockReport(report: SecureStoreUnlockReport): string {
   if (report.ok) {
-    return `OK — secure-store unlocked at ${report.unlockedAt} (algorithm=${report.algorithm}).`;
+    return `OK — secure-store unlocked in this process at ${report.unlockedAt} (algorithm=${report.algorithm}).`;
   }
   if (report.reason === "not-initialized") {
     return "ERR — secure-store is not initialized. Run 'remnic engram secure-store init' first.";
@@ -43,9 +43,9 @@ export function renderUnlockReport(report: SecureStoreUnlockReport): string {
 
 export function renderLockReport(report: SecureStoreLockReport): string {
   if (report.cleared) {
-    return "OK — secure-store key cleared from in-memory keyring.";
+    return "OK — secure-store key cleared from this process's in-memory keyring.";
   }
-  return "OK — secure-store was already locked (no in-memory key to clear).";
+  return "OK — secure-store was already locked in this process (no in-memory key to clear).";
 }
 
 export function renderMigrateReport(report: SecureStoreMigrateReport): string {
@@ -53,7 +53,10 @@ export function renderMigrateReport(report: SecureStoreMigrateReport): string {
     return "ERR — secure-store is not initialized. Run 'remnic engram secure-store init' first.";
   }
   if (!report.ok && report.reason === "locked") {
-    return "ERR — secure-store is locked. Run 'remnic engram secure-store unlock' before migrate.";
+    return "ERR — secure-store is locked in this process. Run migrate from an interactive CLI so it can prompt for the passphrase, or unlock inside the daemon process that will perform the migration.";
+  }
+  if (!report.ok && report.reason === "wrong-passphrase") {
+    return "ERR — wrong passphrase.";
   }
 
   const lines: string[] = [];
@@ -75,7 +78,10 @@ export function renderDisableReport(report: SecureStoreDisableReport): string {
     return "ERR — secure-store is not initialized. Run 'remnic engram secure-store init' first.";
   }
   if (!report.ok && report.reason === "locked") {
-    return "ERR — secure-store is locked. Run 'remnic engram secure-store unlock' before disable.";
+    return "ERR — secure-store is locked in this process. Run disable from an interactive CLI so it can prompt for the passphrase, or unlock inside the daemon process that will decrypt files.";
+  }
+  if (!report.ok && report.reason === "wrong-passphrase") {
+    return "ERR — wrong passphrase.";
   }
 
   const lines: string[] = [];
@@ -105,7 +111,7 @@ export function renderStatusReport(report: SecureStoreStatusReport): string {
     return lines.join("\n");
   }
   lines.push(`createdAt: ${report.createdAt ?? "n/a"}`);
-  lines.push(`locked: ${report.locked ? "yes" : "no"}`);
+  lines.push(`lockedInThisProcess: ${report.locked ? "yes" : "no"}`);
   if (!report.locked) {
     lines.push(`lastUnlockAt: ${report.unlockedAt ?? "n/a"}`);
   }

package/src/secure-store/secure-fs.ts

@@ -43,7 +43,7 @@
  * Naming: `secure-fs.ts` (not `vault-fs.ts`) — see `kdf.ts` naming note.
  */
 
-import { createCipheriv, randomBytes } from "node:crypto";
+import { createCipheriv, randomBytes, randomUUID } from "node:crypto";
 import { lstat, mkdir, open as openFile, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 
@@ -56,6 +56,7 @@ import {
   IV_LENGTH,
   generateSalt,
   open as openEnvelope,
+  parseEnvelope,
   seal,
 } from "./cipher.js";
 
@@ -167,6 +168,7 @@ export function decryptFileBody(buf: Buffer, key: Buffer, aad?: Buffer): Buffer
     throw new Error(`decryptFileBody: unknown flags byte 0x${flags.toString(16).padStart(2, "0")}`);
   }
   const envelope = buf.subarray(MAGIC_HEADER_SIZE);
+  parseEnvelope(envelope);
   try {
     return openEnvelope(key, envelope, aad ? { aad } : {});
   } catch (err) {
@@ -270,7 +272,7 @@ export interface WriteMaybeEncryptedFileOptions {
  * - If `key` is provided and non-null, encrypt the content first.
  * - If `key` is null, write the content as plain UTF-8 (unencrypted store).
  *
- * Writes atomically: content is written to a `.tmp-<pid>-<ts>` file
+ * Writes atomically: content is written to a unique temp file
  * first, then renamed into place (CLAUDE.md gotcha #54 — never delete
  * before write).
  */
@@ -293,7 +295,7 @@ export async function writeMaybeEncryptedFile(
   }
 
   if (atomic) {
-    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    const tempPath = uniqueAtomicTempPath(filePath, "tmp");
     try {
       await writeFile(tempPath, data, { mode });
       await rename(tempPath, filePath);
@@ -445,7 +447,7 @@ export async function migrateMemoryDirToEncrypted(
       const encrypted = encryptFileBody(content, key, aad);
 
       // Atomic write: temp → rename (gotcha #54).
-      const tempPath = `${filePath}.enc-tmp-${process.pid}-${Date.now()}`;
+      const tempPath = uniqueAtomicTempPath(filePath, "enc-tmp");
       try {
         await writeFile(tempPath, encrypted, { mode: 0o600 });
         await rename(tempPath, filePath);
@@ -498,7 +500,7 @@ export async function decryptMemoryDirToPlaintext(
 
       const aad = filePathAad(filePath, storageAadRootForFile(filePath, dir));
       const plaintext = decryptFileBody(buf, key, aad);
-      const tempPath = `${filePath}.dec-tmp-${process.pid}-${Date.now()}`;
+      const tempPath = uniqueAtomicTempPath(filePath, "dec-tmp");
       try {
         await writeFile(tempPath, plaintext, { mode: 0o600 });
         await rename(tempPath, filePath);
@@ -526,6 +528,10 @@ export async function decryptMemoryDirToPlaintext(
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+function uniqueAtomicTempPath(filePath: string, label: string): string {
+  return `${filePath}.${label}-${process.pid}-${Date.now()}-${randomUUID()}`;
+}
+
 /**
  * Recursively collect files under `dir` that are read through the
  * storage-layer secure-store helpers, excluding symlinked entries and

package/src/secure-store/secure-store.test.ts

@@ -36,6 +36,13 @@ import {
   parseHeader,
   validateHeader,
 } from "./header.js";
+import {
+  FILE_FORMAT_FLAGS,
+  FILE_FORMAT_VERSION,
+  MAGIC_BYTES,
+  SecureStoreDecryptError,
+  decryptFileBody,
+} from "./secure-fs.js";
 import {
   DEFAULT_ARGON2ID_PARAMS,
   DEFAULT_SCRYPT_PARAMS,
@@ -60,6 +67,12 @@ import {
   validateMetadata,
 } from "./metadata.js";
 import { createPassphraseReader } from "./passphrase-reader.js";
+import {
+  renderInitReport,
+  renderLockReport,
+  renderStatusReport,
+  renderUnlockReport,
+} from "./cli-renderer.js";
 
 /** Cheap scrypt params for tests — still hex-correct but ~milliseconds. */
 const FAST_SCRYPT: ScryptParams = {
@@ -112,6 +125,46 @@ test("deriveKeyScrypt with default OWASP-acceptable params produces a 32-byte ke
   assert.equal(DEFAULT_SCRYPT_PARAMS.N, 1 << 17);
 });
 
+test("secure-store CLI renderers describe process-local unlock scope, not daemon state", () => {
+  const init = renderInitReport({
+    ok: true,
+    headerPath: "/tmp/memory/.secure-store/header.json",
+    createdAt: "2026-05-21T00:00:00.000Z",
+    kdf: {
+      algorithm: "scrypt",
+      params: FAST_SCRYPT,
+      salt: Buffer.alloc(KDF_SALT_LENGTH, 0x11).toString("hex"),
+    },
+  });
+  assert.match(init, /current Remnic process/);
+  assert.doesNotMatch(init, /running daemon/);
+
+  assert.match(
+    renderUnlockReport({
+      ok: true,
+      unlockedAt: "2026-05-21T00:00:01.000Z",
+      algorithm: "scrypt",
+    }),
+    /unlocked in this process/,
+  );
+  assert.match(renderLockReport({ ok: true, cleared: true }), /this process's in-memory keyring/);
+  assert.match(
+    renderStatusReport({
+      initialized: true,
+      headerPath: "/tmp/memory/.secure-store/header.json",
+      locked: false,
+      unlockedAt: "2026-05-21T00:00:01.000Z",
+      createdAt: "2026-05-21T00:00:00.000Z",
+      kdf: {
+        algorithm: "scrypt",
+        params: FAST_SCRYPT,
+        salt: Buffer.alloc(KDF_SALT_LENGTH, 0x22).toString("hex"),
+      },
+    }),
+    /lockedInThisProcess: no/,
+  );
+});
+
 test("deriveKeyScrypt rejects empty passphrase", () => {
   const salt = Buffer.alloc(KDF_SALT_LENGTH, 0);
   assert.throws(() => deriveKeyScrypt("", salt, FAST_SCRYPT), /passphrase/);
@@ -238,6 +291,23 @@ test("seal/open round-trip on an empty payload", () => {
   assert.equal(opened.length, 0);
 });
 
+test("decryptFileBody reports truncated envelopes as structural errors", () => {
+  const truncated = Buffer.concat([
+    MAGIC_BYTES,
+    Buffer.from([FILE_FORMAT_VERSION, FILE_FORMAT_FLAGS]),
+    Buffer.alloc(ENVELOPE_HEADER_SIZE - 1),
+  ]);
+  assert.throws(
+    () => decryptFileBody(truncated, Buffer.alloc(KDF_KEY_LENGTH, 0x11)),
+    (error) => {
+      assert.ok(error instanceof Error);
+      assert.equal(error instanceof SecureStoreDecryptError, false);
+      assert.match(error.message, /envelope too short/);
+      return true;
+    },
+  );
+});
+
 test("seal produces a different ciphertext for the same plaintext (random IV)", () => {
   const salt = generateSalt();
   const key = deriveKeyScrypt("pw", salt, FAST_SCRYPT);

package/src/semantic-consolidation.test.ts

@@ -8,12 +8,14 @@ import assert from "node:assert/strict";
 
 import {
   CONSOLIDATION_OPERATORS,
+  findSimilarClusters,
   isConsolidationOperator,
   isSemanticConsolidationLlmOperator,
   isValidDerivedFromEntry,
   type ConsolidationOperator,
   type SemanticConsolidationLlmOperator,
 } from "./semantic-consolidation.js";
+import type { MemoryCategory, MemoryFile } from "./types.js";
 // The standalone module is the source of truth; semantic-consolidation.ts
 // re-exports it.  This test import proves both surfaces work.
 import {
@@ -180,3 +182,46 @@ test("SemanticConsolidationLlmOperator type literally excludes pattern-reinforce
   const update: SemanticConsolidationLlmOperator = "update";
   assert.equal([split, merge, update].length, 3);
 });
+
+test("findSimilarClusters never exceeds maxPerRun after prior clusters consume budget", () => {
+  const memories = [
+    consolidationMemory("a-1", "fact", "atlas cache latency shared alpha"),
+    consolidationMemory("a-2", "fact", "atlas cache latency shared beta"),
+    consolidationMemory("a-3", "fact", "atlas cache latency shared gamma"),
+    consolidationMemory("a-4", "fact", "atlas cache latency shared delta"),
+    consolidationMemory("b-1", "preference", "aurora rollout dependency shared alpha"),
+    consolidationMemory("b-2", "preference", "aurora rollout dependency shared beta"),
+  ];
+
+  const clusters = findSimilarClusters(memories, {
+    threshold: 0.1,
+    minClusterSize: 2,
+    excludeCategories: [],
+    maxPerRun: 5,
+  });
+
+  const totalMemories = clusters.reduce((sum, cluster) => sum + cluster.memories.length, 0);
+  assert.equal(totalMemories, 4);
+  assert.deepEqual(
+    clusters.map((cluster) => cluster.memories.map((memory) => memory.frontmatter.id)),
+    [["a-1", "a-2", "a-3", "a-4"]],
+  );
+});
+
+function consolidationMemory(id: string, category: MemoryCategory, content: string): MemoryFile {
+  return {
+    path: `${category}/${id}.md`,
+    content,
+    frontmatter: {
+      id,
+      category,
+      created: "2026-05-21T00:00:00.000Z",
+      updated: "2026-05-21T00:00:00.000Z",
+      source: "test",
+      confidence: 1,
+      confidenceTier: "explicit",
+      tags: [],
+      status: "active",
+    },
+  };
+}

package/src/semantic-consolidation.ts

@@ -95,13 +95,15 @@ export function findSimilarClusters(
     const clustered = new Set<string>();
 
     for (let i = 0; i < tokenized.length && totalCandidates < config.maxPerRun; i++) {
+      const remainingBudget = config.maxPerRun - totalCandidates;
+      if (remainingBudget < config.minClusterSize) break;
       if (clustered.has(tokenized[i].memory.frontmatter.id)) continue;
 
       const cluster: MemoryFile[] = [tokenized[i].memory];
       let totalOverlap = 0;
       let comparisons = 0;
 
-      for (let j = i + 1; j < tokenized.length; j++) {
+      for (let j = i + 1; j < tokenized.length && cluster.length < remainingBudget; j++) {
         if (clustered.has(tokenized[j].memory.frontmatter.id)) continue;
 
         const aTokens = tokenized[i].tokens;
@@ -117,8 +119,6 @@ export function findSimilarClusters(
           cluster.push(tokenized[j].memory);
           totalOverlap += score;
           comparisons++;
-          // Enforce maxPerRun within a single cluster
-          if (totalCandidates + cluster.length >= config.maxPerRun) break;
         }
       }