@remnic/core 10.0.48 → 10.0.50

package/src/embedding-generation-marker.ts

@@ -0,0 +1,51 @@
+// Node-local warm-cache generation marker (`<stateDir>/embeddings.generation`).
+// Two-phase publication barrier: in-flight before a publication's first
+// destructive write, fresh unique value after its last write (PR #3176), so a
+// completed stamp is only ever stable while generation bytes are unchanged.
+// Single owner of the atomic protocol and logging — the store's own mutations
+// and the offline-sync direct write/delete paths (issue #3182) share it.
+// Plain fs always (tmp + rename): the marker is node-local raw bytes, never
+// sync traffic or secure-store content.
+import { randomUUID } from "node:crypto";
+import { rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { log } from "./logger.js";
+
+export const GENERATION_MARKER_BASENAME = "embeddings.generation";
+
+/** Reserved in-flight marker value; never equals a completion marker. */
+export const GENERATION_MARKER_IN_FLIGHT = "in-flight";
+
+export function generationMarkerPath(stateDirAbs: string): string {
+  return path.join(stateDirAbs, GENERATION_MARKER_BASENAME);
+}
+
+/** Strict atomic marker write; recovery uses it for a fresh completed value. */
+export async function writeGenerationMarkerRaw(markerAbs: string, value: string): Promise<void> {
+  const tempPath = `${markerAbs}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    await writeFile(tempPath, value, "utf-8");
+    await rename(tempPath, markerAbs);
+  } catch (err) {
+    await rm(tempPath, { force: true }).catch(() => undefined);
+    throw err;
+  }
+}
+
+/** Barrier first half: strict, so bytes can never change under a stable stamp. */
+export async function beginGenerationMarker(markerAbs: string): Promise<void> {
+  await writeGenerationMarkerRaw(markerAbs, GENERATION_MARKER_IN_FLIGHT);
+}
+
+/**
+ * Barrier second half: written after the last content write. Best-effort:
+ * a failure leaves the in-flight marker, whose stamp identityStamp()
+ * never repeats, so cached probes revalidate on every search until a
+ * publication completes.
+ */
+export async function completeGenerationMarker(markerAbs: string): Promise<void> {
+  await writeGenerationMarkerRaw(markerAbs, randomUUID()).catch((err) => {
+    log.warn(`embedding index: could not write generation completion marker: ${err instanceof Error ? err.message : String(err)}`);
+  });
+}

package/src/embedding-index-storage.ts

@@ -18,6 +18,13 @@ import { randomUUID } from "node:crypto";
 import { constants as bufferConstants } from "node:buffer";
 import { lstat, mkdir, mkdtemp, realpath, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { log } from "./logger.js";
+import {
+  GENERATION_MARKER_IN_FLIGHT,
+  beginGenerationMarker as writeGenerationMarkerInFlight,
+  completeGenerationMarker as writeGenerationMarkerComplete,
+  generationMarkerPath,
+  writeGenerationMarkerRaw,
+} from "./embedding-generation-marker.js";
 import { readEnvVar } from "./runtime/env.js";
 import type { EmbeddingGenerationFence } from "./embedding-generation-lock.js";
 
@@ -166,21 +173,6 @@ function replacementBackupPath(shardDir: string): string {
   return path.join(path.dirname(shardDir), "embeddings.pre-replace.tmp");
 }
 
-/**
- * Warm-cache generation marker (`<stateDir>/embeddings.generation`).
- * Two-phase publication barrier: in-flight before a publication's first
- * destructive write, fresh unique value after its last write. A stamp is
- * therefore stable only for a completed generation — readers can never
- * cache a stamp that stays stable while generation bytes change, and an
- * in-flight stamp never repeats, so probes cached during a failed
- * completion keep revalidating (PR #3176 codex P2). Plain fs like the
- * status file.
- */
-const GENERATION_MARKER_BASENAME = "embeddings.generation";
-
-/** Reserved in-flight marker value; never equals a completion marker. */
-const GENERATION_MARKER_IN_FLIGHT = "in-flight";
-
 /**
  * Stable FNV-1a shard assignment: an entry always hashes to the same shard,
  * so an update or removal never needs a manifest to find its file.
@@ -535,34 +527,26 @@ export class EmbeddingIndexFileStore {
 
   /** Barrier first half: strict, so bytes can never change under a stable stamp. */
   private async beginGenerationMarker(): Promise<void> {
-    await this.writeGenerationMarker(GENERATION_MARKER_IN_FLIGHT);
+    await writeGenerationMarkerInFlight(generationMarkerPath(path.dirname(this.shardDir)));
   }
 
   /**
-   * Barrier second half: written after the last content write. Best-effort:
-   * a failure leaves the in-flight marker, whose stamp identityStamp()
-   * never repeats, so cached probes revalidate on every search until a
-   * publication completes.
+   * Barrier second half: written after the last content write. Best-effort;
+   * the in-flight fallback semantics live in the shared marker module.
    */
   private async completeGenerationMarker(): Promise<void> {
-    await this.writeGenerationMarker(randomUUID()).catch((err) => {
-      log.warn(`embedding index: could not write generation completion marker: ${err instanceof Error ? err.message : String(err)}`);
-    });
+    await writeGenerationMarkerComplete(generationMarkerPath(path.dirname(this.shardDir)));
   }
 
   private async writeGenerationMarker(value: string): Promise<void> {
-    await this.writeAtomicFile(
-      path.join(path.dirname(this.shardDir), GENERATION_MARKER_BASENAME),
-      value,
-      { bypassSecureIo: true },
-    );
+    await writeGenerationMarkerRaw(generationMarkerPath(path.dirname(this.shardDir)), value);
   }
 
   /** Marker value, or null when absent/unreadable (pre-marker stores keep the stat stamp). */
   private async readGenerationMarker(): Promise<string | null> {
     try {
       const raw = await readFile(
-        path.join(path.dirname(this.shardDir), GENERATION_MARKER_BASENAME),
+        generationMarkerPath(path.dirname(this.shardDir)),
         "utf-8",
       );
       const value = raw.trim();

package/src/entity-lazy-compatibility.test.ts

@@ -0,0 +1,229 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { StorageManager, parseEntityFile } from "./storage.js";
+import { sleep } from "./utils/sleep.js";
+
+async function legacyStore() {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-lazy-compat-"));
+  const seed = new StorageManager(dir);
+  const id = await seed.writeEntity("Legacy Person", "person", ["Keeps a synthetic task."]);
+  await rename(path.join(dir, "entities", `${id}.md`), path.join(dir, "entities", "legacy-person.md"));
+  const journal = path.join(dir, "state", "entity-canonical-id-migration-v1.json");
+  await rm(journal, { force: true });
+  const lock = path.join(dir, "state", "entity-canonical-id-migration.lock");
+  await writeFile(lock, `${process.pid} test-holder ${new Date().toISOString()}\n`);
+  const storage = new StorageManager(dir);
+  await storage.ensureDirectories({ waitForEntityMigration: false });
+  return { dir, id, journal, lock, storage };
+}
+
+test("canonical reads find a legacy file without a journal or migration", async () => {
+  const fixture = await legacyStore();
+  try {
+    assert.match(await fixture.storage.readEntity(fixture.id), /Keeps a synthetic task/);
+    await assert.rejects(() => readFile(fixture.journal), { code: "ENOENT" });
+    assert.ok(await readFile(fixture.lock));
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(fixture.dir, { recursive: true, force: true });
+  }
+});
+
+test("ambiguous legacy canonical matches are refused rather than picking a claimant", async () => {
+  const fixture = await legacyStore();
+  try {
+    const raw = await readFile(path.join(fixture.dir, "entities", "legacy-person.md"));
+    await writeFile(path.join(fixture.dir, "entities", "other-legacy-person.md"), raw);
+    await assert.rejects(() => fixture.storage.readEntity(fixture.id), /ambiguous/i);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(fixture.dir, { recursive: true, force: true });
+  }
+});
+
+test("completed migration skips corpus reads on repeated misses in a fresh read-only store", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-completed-miss-"));
+  try {
+    const seed = new StorageManager(dir);
+    await seed.writeEntity("Existing Person", "person", ["Synthetic fact."]);
+    await seed.ensureDirectories();
+    const reader = new StorageManager(dir);
+    await reader.ensureDirectories({ waitForEntityMigration: false });
+    // Bracket access is TypeScript's typed escape hatch for the private reader.
+    const originalRead = reader["readStorageSecureFile"].bind(reader);
+    const reads: string[] = [];
+    reader["readStorageSecureFile"] = async (filePath: string) => {
+      reads.push(path.basename(filePath));
+      return originalRead(filePath);
+    };
+    assert.equal(await reader.readEntity("person-missing"), "");
+    assert.equal(await reader.readEntity("person-missing"), "");
+    assert.deepEqual(reads, ["person-missing.md", "person-missing.md"], "completed-store misses must not scan entity contents");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("an external entities change invalidates the amortized completion verdict on the same reader", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-completed-cache-"));
+  try {
+    const seed = new StorageManager(dir);
+    const id = await seed.writeEntity("Café", "project", ["Synthetic legacy fact."]);
+    await seed.ensureDirectories();
+    const reader = new StorageManager(dir);
+    await reader.ensureDirectories({ waitForEntityMigration: false });
+    const canonical = reader.normalizeEntityName("Café", "project");
+    // First miss computes and caches the completion verdict.
+    assert.equal(await reader.readEntity("project-missing"), "");
+    // An external rename changes the entities directory; the cached verdict
+    // must not keep hiding the now-legacy file from the same reader.
+    await rename(path.join(dir, "entities", `${id}.md`), path.join(dir, "entities", "legacy-cafe.md"));
+    assert.match(await reader.readEntity(canonical), /Synthetic legacy fact/);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("an external aliases change invalidates the amortized completion verdict on the same reader", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-completed-alias-cache-"));
+  try {
+    const seed = new StorageManager(dir);
+    const previousId = await seed.writeEntity("Café", "project", ["Synthetic legacy fact."]);
+    await seed.ensureDirectories();
+    const journalPath = path.join(dir, "state", "entity-canonical-id-migration-v1.json");
+    const journal = await readFile(journalPath, "utf8");
+    assert.equal(JSON.parse(journal).complete, true);
+
+    const reader = new StorageManager(dir);
+    await reader.ensureDirectories({ waitForEntityMigration: false });
+    // Warm amortized completion (and any same-reader completion memo) on a miss.
+    assert.equal(await reader.readEntity("project-missing"), "");
+
+    // Block migration repair so fingerprint drift stays visible to reads.
+    const lock = path.join(dir, "state", "entity-canonical-id-migration.lock");
+    await writeFile(lock, `${process.pid} test-holder ${new Date().toISOString()}\n`);
+
+    // External aliases.json is a getFingerprint input. It must invalidate a
+    // warm completed verdict without entities membership or mutation-version change.
+    // The entity file stays at previousId; only the alias-derived canonical id moves.
+    await mkdir(path.join(dir, "config"), { recursive: true });
+    await writeFile(path.join(dir, "config", "aliases.json"), JSON.stringify({ café: "coffee" }));
+    await reader.loadAliases();
+    const canonical = reader.normalizeEntityName("Café", "project");
+    assert.notEqual(canonical, previousId);
+
+    assert.match(await reader.readEntity(canonical), /Synthetic legacy fact/);
+    assert.equal(await readFile(journalPath, "utf8"), journal, "read compatibility must not replay migration");
+    assert.ok(await readFile(lock));
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+
+for (const change of ["aliases", "raw legacy write"]) {
+  test(`stale completed journals do not hide canonical reads after ${change}`, async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-stale-completion-"));
+    try {
+      const seed = new StorageManager(dir);
+      const previousId = await seed.writeEntity("Café", "project", ["Synthetic legacy fact."]);
+      await seed.ensureDirectories();
+      const journalPath = path.join(dir, "state", "entity-canonical-id-migration-v1.json");
+      const journal = await readFile(journalPath, "utf8");
+      assert.equal(JSON.parse(journal).complete, true);
+      if (change === "aliases") {
+        await mkdir(path.join(dir, "config"), { recursive: true });
+        await writeFile(path.join(dir, "config", "aliases.json"), JSON.stringify({ café: "coffee" }));
+      } else {
+        await rename(path.join(dir, "entities", `${previousId}.md`), path.join(dir, "entities", "legacy-cafe.md"));
+        await writeFile(path.join(dir, "state", "entity-canonical-id-reconcile.pending"), "synthetic raw writer\n");
+      }
+      const lock = path.join(dir, "state", "entity-canonical-id-migration.lock");
+      await writeFile(lock, `${process.pid} test-holder ${new Date().toISOString()}\n`);
+      const reader = new StorageManager(dir);
+      await reader.ensureDirectories({ waitForEntityMigration: false });
+      const canonical = reader.normalizeEntityName("Café", "project");
+      if (change === "aliases") assert.notEqual(canonical, previousId);
+      assert.match(await reader.readEntity(canonical), /Synthetic legacy fact/);
+      assert.equal(await readFile(journalPath, "utf8"), journal, "read compatibility must not replay migration");
+      assert.ok(await readFile(lock));
+    } finally {
+      StorageManager.clearAllStaticCaches();
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+}
+
+const mutations = [
+  {
+    name: "relationship",
+    run: (s: StorageManager, id: string) => s.addEntityRelationship(id, { target: "person-peer", label: "knows" }),
+    check: (raw: string) => assert.ok(parseEntityFile(raw).relationships.some((r) => r.label === "knows")),
+  },
+  {
+    name: "activity",
+    run: (s: StorageManager, id: string) => s.addEntityActivity(id, { date: "2026-01-01", note: "Synthetic activity" }, 10),
+    check: (raw: string) => assert.ok(parseEntityFile(raw).activity.some((a) => a.note === "Synthetic activity")),
+  },
+  {
+    name: "alias",
+    run: (s: StorageManager, id: string) => s.addEntityAlias(id, "synthetic-alias"),
+    check: (raw: string) => assert.ok(parseEntityFile(raw).aliases.includes("synthetic-alias")),
+  },
+  {
+    name: "synthesis",
+    run: (s: StorageManager, id: string) => s.updateEntitySynthesis(id, "Synthetic synthesis"),
+    check: (raw: string) => assert.equal(parseEntityFile(raw).synthesis, "Synthetic synthesis"),
+  },
+  {
+    name: "fragment merge",
+    run: (s: StorageManager) => s.mergeFragmentedEntities(),
+    check: (raw: string) => assert.match(raw, /Keeps a synthetic task/),
+  },
+  {
+    name: "timeline migration",
+    run: (s: StorageManager) => s.migrateEntityFilesToCompiledTruthTimeline(),
+    check: (raw: string) => assert.match(raw, /Keeps a synthetic task/),
+  },
+];
+
+for (const caller of ["canonical", "legacy"]) {
+for (const mutation of mutations) {
+  test(`${mutation.name} awaits migration for a ${caller} caller`, async () => {
+    const fixture = await legacyStore();
+    let settled = false;
+    let failure: Error | undefined;
+    const operation = mutation.run(fixture.storage, caller === "legacy" ? "legacy-person" : fixture.id).then(
+      () => { settled = true; },
+      (error: Error) => { failure = error; settled = true; },
+    );
+    let probeFailure: unknown;
+    try {
+      await sleep(100);
+      assert.equal(settled, false, "a public entity mutation must wait behind the migration lock");
+    } catch (error) {
+      probeFailure = error;
+    } finally {
+      await rm(fixture.lock, { force: true });
+    }
+    try {
+      await operation;
+      if (probeFailure) throw probeFailure;
+      assert.equal(failure, undefined);
+      const raw = await readFile(path.join(fixture.dir, "entities", `${fixture.id}.md`), "utf8");
+      mutation.check(raw);
+      const journal = JSON.parse(await readFile(fixture.journal, "utf8"));
+      assert.equal(journal.complete, true);
+    } finally {
+      StorageManager.clearAllStaticCaches();
+      await rm(fixture.dir, { recursive: true, force: true });
+    }
+  });
+}
+}

package/src/entity-migration-completion-notification.test.ts

@@ -0,0 +1,148 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rename, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import { Orchestrator } from "./orchestrator.js";
+import { StorageManager } from "./storage.js";
+
+// #3240 follow-up: the host's onEntityMigrationComplete slot must fire once
+// per migration pass that rewrote entities (never on no-op replays or ensure() no-ops), fail open on a
+// throwing hook, reach router-created storages independent of auto-embed, and
+// be inert after Orchestrator.destroy(). No direct QMD calls; the re-arm is
+// observed through a requestQmdMaintenance spy.
+
+async function legacyEntityStore(prefix: string): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), prefix));
+  const seed = new StorageManager(dir);
+  const id = await seed.writeEntity("Legacy Person", "person", ["Keeps a synthetic task."]);
+  await rename(path.join(dir, "entities", `${id}.md`), path.join(dir, "entities", "legacy-person.md"));
+  await rm(path.join(dir, "state", "entity-canonical-id-migration-v1.json"), { force: true });
+  return dir;
+}
+
+test("real storage fires the completion slot only for a pass that rewrote entities, and fails open on a throwing hook", async () => {
+  const dir = await legacyEntityStore("remnic-migration-complete-");
+  const emptyDir = await mkdtemp(path.join(os.tmpdir(), "remnic-migration-noop-"));
+  const throwingDir = await legacyEntityStore("remnic-migration-throwing-");
+  try {
+    const storage = new StorageManager(dir);
+    let completions = 0;
+    storage.onEntityMigrationComplete = () => {
+      completions += 1;
+    };
+    await storage.ensureDirectories();
+    assert.equal(completions, 1, "a migration pass that renamed a legacy entity must fire the completion slot");
+    await storage.ensureDirectories();
+    assert.equal(completions, 1, "a second ensureDirectories must not re-fire the slot");
+
+    const noop = new StorageManager(emptyDir);
+    let noopCompletions = 0;
+    noop.onEntityMigrationComplete = () => {
+      noopCompletions += 1;
+    };
+    await noop.ensureDirectories();
+    assert.equal(noopCompletions, 0, "a no-op replay must not ask search maintenance to run");
+
+    const throwing = new StorageManager(throwingDir);
+    let hookCalls = 0;
+    throwing.onEntityMigrationComplete = () => {
+      hookCalls += 1;
+      throw new Error("consumer hook exploded");
+    };
+    await throwing.ensureDirectories();
+    assert.equal(hookCalls, 1, "the throwing hook must still be invoked");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+    await rm(emptyDir, { recursive: true, force: true });
+    await rm(throwingDir, { recursive: true, force: true });
+  }
+});
+
+test("orchestrator wires completion with auto-embed off and blocks it from teardown admission", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-migration-complete-orch-"));
+  const orchestrator = new Orchestrator(
+    parseConfig({
+      memoryDir: dir,
+      workspaceDir: path.join(dir, "workspace"),
+      qmdEnabled: false,
+      qmdAutoEmbedEnabled: false,
+      namespacesEnabled: true,
+      namespaceCatalogEnabled: true,
+      defaultNamespace: "default",
+      sharedNamespace: "shared",
+      namespacePolicies: [],
+      embeddingFallbackEnabled: false,
+      identityContinuityEnabled: false,
+      transcriptEnabled: false,
+      hourlySummariesEnabled: false,
+      compoundingEnabled: false,
+      knowledgeIndexEnabled: false,
+    }),
+  );
+  // Test-only access to the Orchestrator's private wiring fields: bracket access
+  // is TypeScript's typed escape hatch for private members, so no assertion.
+  const internals = {
+    get storage() { return orchestrator["storage"]; },
+    get storageRouter() { return orchestrator["storageRouter"]; },
+    get maintenanceScheduler() { return orchestrator["maintenanceScheduler"]; },
+    set requestQmdMaintenance(fn: () => void) { orchestrator["requestQmdMaintenance"] = fn; },
+  };
+  try {
+    // Wiring must exist independent of auto-embed.
+    const onMigrationComplete = internals.storage.onEntityMigrationComplete;
+    assert.ok(
+      onMigrationComplete instanceof Function,
+      "the default storage must carry the migration completion slot without auto-embed",
+    );
+    const namespaceStorage = await internals.storageRouter.storageFor("proj-a");
+    const onNamespaceMigrationComplete = namespaceStorage.onEntityMigrationComplete;
+    assert.ok(
+      onNamespaceMigrationComplete instanceof Function,
+      "a router-created namespace storage must carry the slot without auto-embed",
+    );
+
+    const rearmRequests: string[] = [];
+    internals.requestQmdMaintenance = () => {
+      rearmRequests.push("rearm");
+    };
+    assert.ok(onMigrationComplete);
+    onMigrationComplete();
+    assert.ok(onNamespaceMigrationComplete);
+    onNamespaceMigrationComplete();
+    assert.deepEqual(rearmRequests, ["rearm", "rearm"], "a completion must re-arm QMD maintenance");
+
+    const { promise: disposeGate, resolve: releaseDispose } = Promise.withResolvers<void>();
+    const { promise: disposing, resolve: signalDispose } = Promise.withResolvers<void>();
+    const originalDispose = internals.maintenanceScheduler.dispose.bind(internals.maintenanceScheduler);
+    internals.maintenanceScheduler.dispose = async () => {
+      signalDispose();
+      await disposeGate;
+      await originalDispose();
+    };
+    const teardown = orchestrator.destroy();
+    try {
+      await disposing;
+      onMigrationComplete();
+      onNamespaceMigrationComplete();
+      assert.deepEqual(rearmRequests, ["rearm", "rearm"], "teardown admission must stop completion re-arms before drains");
+    } finally {
+      releaseDispose();
+      await teardown;
+    }
+    onMigrationComplete();
+    onNamespaceMigrationComplete();
+    assert.deepEqual(
+      rearmRequests,
+      ["rearm", "rearm"],
+      "a completion after destroy must not re-arm maintenance",
+    );
+  } finally {
+    await orchestrator.destroy().catch(() => undefined);
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/index.ts

@@ -657,7 +657,7 @@ export {
   type ParsedBriefingWindow,
   type BriefingFormatValue,
 } from "./briefing.js";
-
+export { withBriefingDeadline, BriefingTimeoutError, BRIEFING_DEADLINE_MS } from "./briefing-deadline.js";
 // ---------------------------------------------------------------------------
 // Binary lifecycle management (#367)
 // ---------------------------------------------------------------------------
@@ -880,7 +880,7 @@ export {
   type OfflineSyncSnapshot,
   type OfflineSyncState,
 } from "./offline-sync.js";
-export { embeddingGenerationMembership, divergedEmbeddingGenerationDeferrals } from "./offline-sync-embedding-generation.js";
+export { advanceEmbeddingGenerationMarker, embeddingGenerationMembership, divergedEmbeddingGenerationDeferrals } from "./offline-sync-embedding-generation.js";
 export { EmbeddingIndexCapacityError, EmbeddingIndexFileStore, EmbeddingIndexStorageError, parseEmbeddingIndexDocument, serializeEmbeddingShard, shardEntriesForIndex, shardIndexOf, validateShardMembership } from "./embedding-index-storage.js";
 
 // ---------------------------------------------------------------------------

package/src/location/tagging.ts

@@ -21,7 +21,7 @@
 
 import type { StorageManager } from "../index.js";
 import { log } from "../logger.js";
-import type { MemoryFile } from "../types.js";
+import type { BriefingResult, MemoryFile } from "../types.js";
 import type { WearableConversation } from "../wearables/types.js";
 import { localDayKey, placeDurations } from "./intervals.js";
 import {
@@ -294,23 +294,25 @@ export async function briefingLocationSection(
   );
 }
 
-export async function applyBriefingLocationContext<
-  T extends { markdown: string; json: Record<string, unknown> },
->(
-  result: T,
+/**
+ * Append the opt-in location section to a briefing. The section is read BEFORE
+ * `build` runs: buildBriefing drains correction notifications at most once, so
+ * a deadline during this read must not lose them.
+ */
+export async function buildWithBriefingLocation<T extends Pick<BriefingResult, "markdown" | "json">>(
   includeLocation: boolean | undefined,
   memoryDir: string,
   windowStartUtc: string,
   location: LocationConfig,
+  build: () => Promise<T>,
 ): Promise<T> {
-  if (includeLocation !== true || !locationTaggingEnabled(location)) return result;
-  const section = await briefingLocationSection(memoryDir, windowStartUtc, location);
+  const section =
+    includeLocation === true && locationTaggingEnabled(location)
+      ? await briefingLocationSection(memoryDir, windowStartUtc, location)
+      : null;
+  const result = await build();
   if (!section) return result;
-  return {
-    ...result,
-    markdown: `${result.markdown}\n\n${section}\n`,
-    json: { ...result.json, locationContext: section },
-  };
+  return { ...result, markdown: `${result.markdown}\n\n${section}\n`, json: { ...result.json, locationContext: section } };
 }
 
 /**

package/src/offline-sync-embedding-delete-digest.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { withEmbeddingGenerationLock } from "./embedding-generation-lock.js";
+import { advanceEmbeddingGenerationMarker, embeddingGenerationMembership } from "./offline-sync-embedding-generation.js";
+
+// Issue #3182 review: a peer can publish a newer shard while converge waits
+// for the generation lock; the stale pre-lock digest must not delete it.
+test("a stale-digest deletion is rejected under the generation lock", async (t) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-3182-delete-digest-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const stateDir = path.join(root, "state");
+  const relative = "state/embeddings/shard-0000.json";
+  const target = path.join(root, relative);
+  const marker = path.join(stateDir, "embeddings.generation");
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, "older shard");
+  await writeFile(marker, "peer completed generation");
+  const staleSha256 = createHash("sha256").update("older shard").digest("hex");
+
+  let signalHeld: () => void;
+  const held = new Promise<void>((resolve) => { signalHeld = resolve; });
+  let releaseWriter: (() => void) | undefined;
+  const release = new Promise<void>((resolve) => { releaseWriter = resolve; });
+  assert.ok(releaseWriter);
+  const writer = withEmbeddingGenerationLock(stateDir, async () => {
+    signalHeld();
+    await release;
+    await writeFile(target, "newer peer shard");
+  });
+  await held;
+
+  let validated = false;
+  const deletion = advanceEmbeddingGenerationMarker(
+    root,
+    embeddingGenerationMembership(relative),
+    async () => {
+      assert.fail("deletion must never run when the digest is stale");
+    },
+    async () => {
+      validated = true;
+      if ((await readFile(target, "utf8")) !== "older shard") {
+        throw new Error("converge file changed before deletion");
+      }
+    },
+  );
+  const rejected = assert.rejects(deletion, /changed before deletion/);
+  releaseWriter();
+  await writer;
+  await rejected;
+
+  assert.equal(validated, true, "the digest precondition must run inside the lock");
+  assert.equal(await readFile(target, "utf8"), "newer peer shard");
+  assert.equal(await readFile(marker, "utf8"), "peer completed generation");
+});