@remnic/core 9.3.623 → 9.3.625

package/src/wearables/speakers.test.ts

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { test } from "node:test";
+
+import {
+  DEFAULT_SELF_NAME,
+  distinctSpeakerLabels,
+  emptySpeakerRegistry,
+  loadSpeakerRegistry,
+  resolveSpeaker,
+  saveSpeakerRegistry,
+  speakerRegistryKey,
+} from "./speakers.js";
+
+test("resolution precedence: override > wearer flag > provider name > raw key", () => {
+  const registry = emptySpeakerRegistry();
+  registry.selfName = "Jordan";
+  registry.speakers[speakerRegistryKey("bee", "1")] = {
+    name: "Alex Sample",
+    updatedAt: "2026-06-10T00:00:00Z",
+  };
+
+  // 1. Registry override wins even over a provider name.
+  assert.deepEqual(
+    resolveSpeaker("bee", { speakerKey: "1", speakerName: "Speaker 1" }, registry),
+    { label: "Alex Sample", isSelf: false },
+  );
+  // 2. Provider wearer flag.
+  assert.deepEqual(
+    resolveSpeaker("limitless", { speakerKey: "user", isWearer: true }, registry),
+    { label: "Jordan (you)", isSelf: true },
+  );
+  // 3. Provider display name.
+  assert.deepEqual(
+    resolveSpeaker("limitless", { speakerKey: "Speaker 2", speakerName: "Speaker 2" }, registry),
+    { label: "Speaker 2", isSelf: false },
+  );
+  // 4. Raw key fallbacks.
+  assert.deepEqual(resolveSpeaker("bee", { speakerKey: "0" }, registry), {
+    label: "Speaker 0",
+    isSelf: false,
+  });
+  assert.deepEqual(resolveSpeaker("omi", { speakerKey: "" }, registry), {
+    label: "Unknown speaker",
+    isSelf: false,
+  });
+});
+
+test("an override can mark a diarization label as the wearer", () => {
+  const registry = emptySpeakerRegistry();
+  registry.speakers[speakerRegistryKey("bee", "0")] = {
+    name: "Jordan",
+    isSelf: true,
+    updatedAt: "2026-06-10T00:00:00Z",
+  };
+  assert.deepEqual(resolveSpeaker("bee", { speakerKey: "0" }, registry), {
+    label: "Jordan (you)",
+    isSelf: true,
+  });
+});
+
+test("distinctSpeakerLabels keeps first-appearance order without duplicates", () => {
+  const registry = emptySpeakerRegistry();
+  const labels = distinctSpeakerLabels(
+    "limitless",
+    [
+      { speakerKey: "user", isWearer: true },
+      { speakerKey: "Speaker 2", speakerName: "Speaker 2" },
+      { speakerKey: "user", isWearer: true },
+    ],
+    registry,
+  );
+  assert.deepEqual(labels, [`${DEFAULT_SELF_NAME} (you)`, "Speaker 2"]);
+});
+
+test("registry round-trips through disk and tolerates absence", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "remnic-speakers-"));
+  try {
+    const fresh = await loadSpeakerRegistry(dir);
+    assert.equal(fresh.selfName, DEFAULT_SELF_NAME);
+
+    fresh.selfName = "Jordan";
+    fresh.speakers[speakerRegistryKey("omi", "SPEAKER_01")] = {
+      name: "Casey Sample",
+      updatedAt: "2026-06-10T00:00:00Z",
+    };
+    await saveSpeakerRegistry(dir, fresh);
+
+    const loaded = await loadSpeakerRegistry(dir);
+    assert.equal(loaded.selfName, "Jordan");
+    assert.equal(loaded.speakers["omi:SPEAKER_01"].name, "Casey Sample");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a malformed speakers file throws instead of silently resetting", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "remnic-speakers-"));
+  try {
+    const { promises: fsPromises } = await import("node:fs");
+    const filePath = path.join(dir, "state", "wearables", "speakers.json");
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+    await fsPromises.writeFile(filePath, JSON.stringify({ speakers: null }), "utf-8");
+    await assert.rejects(loadSpeakerRegistry(dir), /unexpected shape/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/wearables/speakers.ts

@@ -0,0 +1,174 @@
+/**
+ * Wearable speaker registry — maps provider diarization labels to
+ * human names, persistently, per source.
+ *
+ * Providers expose speakers differently (Limitless: names + a "user"
+ * marker; Bee: opaque labels like "0"/"1"; Omi: "SPEAKER_00" + is_user
+ * + optional person ids). The registry stores operator-confirmed
+ * mappings keyed `<sourceId>:<speakerKey>` in
+ * `state/wearables/speakers.json`, plus the wearer's display name.
+ *
+ * Resolution precedence (most-authoritative first):
+ *   1. registry override for `<sourceId>:<speakerKey>`
+ *   2. provider-identified wearer  -> selfName
+ *   3. provider-supplied speaker name
+ *   4. the raw speaker key, prefixed "Speaker" when it is bare digits
+ */
+
+import { promises as fsPromises } from "node:fs";
+import * as path from "node:path";
+
+export interface SpeakerOverride {
+  name: string;
+  /** Mark this speaker as the wearer (their words become "you"). */
+  isSelf?: boolean;
+  updatedAt: string;
+}
+
+export interface SpeakerRegistry {
+  version: 1;
+  /** Display name used for the wearer across all sources. */
+  selfName: string;
+  /** Overrides keyed `<sourceId>:<speakerKey>`. */
+  speakers: Record<string, SpeakerOverride>;
+}
+
+export const DEFAULT_SELF_NAME = "Me";
+
+export function emptySpeakerRegistry(): SpeakerRegistry {
+  return { version: 1, selfName: DEFAULT_SELF_NAME, speakers: {} };
+}
+
+export function speakersFilePath(memoryDir: string): string {
+  return path.join(memoryDir, "state", "wearables", "speakers.json");
+}
+
+export async function loadSpeakerRegistry(
+  memoryDir: string,
+): Promise<SpeakerRegistry> {
+  const filePath = speakersFilePath(memoryDir);
+  let raw: string;
+  try {
+    raw = await fsPromises.readFile(filePath, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return emptySpeakerRegistry();
+    }
+    throw err;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `wearables speakers file is not valid JSON (state/wearables/speakers.json): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    Array.isArray(parsed) ||
+    typeof (parsed as SpeakerRegistry).speakers !== "object" ||
+    (parsed as SpeakerRegistry).speakers === null
+  ) {
+    throw new Error(
+      'wearables speakers file has an unexpected shape (state/wearables/speakers.json); expected {"version":1,"selfName":"...","speakers":{}}',
+    );
+  }
+  const registry = parsed as SpeakerRegistry;
+  return {
+    version: 1,
+    selfName:
+      typeof registry.selfName === "string" && registry.selfName.trim().length > 0
+        ? registry.selfName.trim()
+        : DEFAULT_SELF_NAME,
+    speakers: registry.speakers,
+  };
+}
+
+export async function saveSpeakerRegistry(
+  memoryDir: string,
+  registry: SpeakerRegistry,
+): Promise<void> {
+  const filePath = speakersFilePath(memoryDir);
+  await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now().toString(36)}`;
+  await fsPromises.writeFile(
+    tmpPath,
+    `${JSON.stringify(registry, null, 2)}\n`,
+    "utf-8",
+  );
+  try {
+    await fsPromises.rename(tmpPath, filePath);
+  } catch (err) {
+    await fsPromises.unlink(tmpPath).catch(() => undefined);
+    throw err;
+  }
+}
+
+export function speakerRegistryKey(
+  sourceId: string,
+  speakerKey: string,
+): string {
+  return `${sourceId}:${speakerKey}`;
+}
+
+export interface ResolvedSpeaker {
+  /** Display label used in transcripts, e.g. "Jane" or "Me (you)". */
+  label: string;
+  /** Whether this speaker is the wearer. */
+  isSelf: boolean;
+}
+
+export function resolveSpeaker(
+  sourceId: string,
+  segment: { speakerKey: string; speakerName?: string; isWearer?: boolean },
+  registry: SpeakerRegistry,
+): ResolvedSpeaker {
+  const override = registry.speakers[speakerRegistryKey(sourceId, segment.speakerKey)];
+  if (override) {
+    const isSelf = override.isSelf === true;
+    return {
+      label: isSelf ? `${override.name} (you)` : override.name,
+      isSelf,
+    };
+  }
+  if (segment.isWearer === true) {
+    return { label: `${registry.selfName} (you)`, isSelf: true };
+  }
+  if (
+    typeof segment.speakerName === "string" &&
+    segment.speakerName.trim().length > 0
+  ) {
+    return { label: segment.speakerName.trim(), isSelf: false };
+  }
+  const key = segment.speakerKey.trim();
+  // Bare diarization indexes read better with a prefix.
+  if (/^\d+$/.test(key)) {
+    return { label: `Speaker ${key}`, isSelf: false };
+  }
+  return { label: key.length > 0 ? key : "Unknown speaker", isSelf: false };
+}
+
+/**
+ * Distinct speaker labels for a set of segments, in first-appearance
+ * order — used for day-transcript frontmatter.
+ */
+export function distinctSpeakerLabels(
+  sourceId: string,
+  segments: Array<{ speakerKey: string; speakerName?: string; isWearer?: boolean }>,
+  registry: SpeakerRegistry,
+): string[] {
+  const labels: string[] = [];
+  const seen = new Set<string>();
+  for (const segment of segments) {
+    const { label } = resolveSpeaker(sourceId, segment, registry);
+    if (!seen.has(label)) {
+      seen.add(label);
+      labels.push(label);
+    }
+  }
+  return labels;
+}

package/src/wearables/storage-io.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { test } from "node:test";
+
+import { StorageManager } from "../storage.js";
+
+function makeStorage(): { storage: StorageManager; dir: string } {
+  const dir = mkdtempSync(path.join(tmpdir(), "remnic-wearable-io-"));
+  return { storage: new StorageManager(dir), dir };
+}
+
+test("wearable transcript write/read/list round-trips", async () => {
+  const { storage, dir } = makeStorage();
+  try {
+    assert.equal(await storage.readWearableDayTranscript("limitless", "2026-06-10"), null);
+    assert.deepEqual(await storage.listWearableTranscriptDays(), []);
+
+    await storage.writeWearableDayTranscript("limitless", "2026-06-10", "---\nkind: wearable-transcript\n---\n\nbody A\n");
+    await storage.writeWearableDayTranscript("limitless", "2026-06-11", "---\nkind: wearable-transcript\n---\n\nbody B\n");
+    await storage.writeWearableDayTranscript("bee", "2026-06-11", "---\nkind: wearable-transcript\n---\n\nbody C\n");
+
+    const raw = await storage.readWearableDayTranscript("limitless", "2026-06-10");
+    assert.ok(raw?.includes("body A"));
+
+    const allDays = await storage.listWearableTranscriptDays();
+    assert.deepEqual(allDays, [
+      { source: "bee", date: "2026-06-11" },
+      { source: "limitless", date: "2026-06-11" },
+      { source: "limitless", date: "2026-06-10" },
+    ]);
+    const scoped = await storage.listWearableTranscriptDays("limitless");
+    assert.equal(scoped.length, 2);
+    assert.ok(scoped.every((entry) => entry.source === "limitless"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("rewriting a day replaces content atomically", async () => {
+  const { storage, dir } = makeStorage();
+  try {
+    await storage.writeWearableDayTranscript("omi", "2026-06-10", "first version\n");
+    await storage.writeWearableDayTranscript("omi", "2026-06-10", "second version\n");
+    const raw = await storage.readWearableDayTranscript("omi", "2026-06-10");
+    assert.equal(raw, "second version\n");
+    assert.equal((await storage.listWearableTranscriptDays("omi")).length, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("malicious source ids and dates are rejected before any path math", async () => {
+  const { storage, dir } = makeStorage();
+  try {
+    await assert.rejects(
+      storage.writeWearableDayTranscript("../escape", "2026-06-10", "x"),
+      /invalid wearable source id/,
+    );
+    await assert.rejects(
+      storage.readWearableDayTranscript("limitless", "../../etc/passwd"),
+      /invalid wearable transcript date/,
+    );
+    await assert.rejects(
+      storage.readWearableDayTranscript("Limitless", "2026-06-10"),
+      /invalid wearable source id/,
+    );
+    assert.throws(
+      () => storage.wearableTranscriptPath("a/b", "2026-06-10"),
+      /invalid wearable source id/,
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("transcript files never surface from readAllMemories", async () => {
+  const { storage, dir } = makeStorage();
+  try {
+    await storage.writeWearableDayTranscript(
+      "limitless",
+      "2026-06-10",
+      "---\nkind: wearable-transcript\nsource: \"limitless\"\n---\n\ntranscript body\n",
+    );
+    const memories = await storage.readAllMemories();
+    assert.equal(memories.length, 0, "wearables/ must stay outside memory scan roots");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("non-transcript files in the wearables tree are ignored by listing", async () => {
+  const { storage, dir } = makeStorage();
+  try {
+    const { promises: fsPromises } = await import("node:fs");
+    await fsPromises.mkdir(path.join(dir, "wearables", "limitless"), { recursive: true });
+    await fsPromises.writeFile(path.join(dir, "wearables", "limitless", "notes.md"), "x", "utf-8");
+    await fsPromises.writeFile(path.join(dir, "wearables", "limitless", "2026-06-10.md.tmp"), "x", "utf-8");
+    await fsPromises.mkdir(path.join(dir, "wearables", "NotASource"), { recursive: true });
+    assert.deepEqual(await storage.listWearableTranscriptDays(), []);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/wearables/sync-state.test.ts

@@ -0,0 +1,134 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { test } from "node:test";
+
+import {
+  emptySyncState,
+  loadSyncState,
+  saveSyncState,
+  syncStateFilePath,
+  updateSourceSyncState,
+} from "./sync-state.js";
+
+test("round-trips through disk and tolerates absence", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "remnic-syncstate-"));
+  try {
+    assert.deepEqual(await loadSyncState(dir), emptySyncState());
+    const updated = updateSourceSyncState(emptySyncState(), "limitless", {
+      syncedAt: "2026-06-11T01:00:00.000Z",
+      days: ["2026-06-10", "2026-06-11"],
+      dayHashes: { "2026-06-10": "aaa", "2026-06-11": "bbb" },
+      importedNativeMemoryIds: ["n1", "n2"],
+    });
+    await saveSyncState(dir, updated);
+    const loaded = await loadSyncState(dir);
+    assert.equal(loaded.sources.limitless.lastDateSynced, "2026-06-11");
+    assert.equal(loaded.sources.limitless.dayHashes["2026-06-10"], "aaa");
+    assert.deepEqual(loaded.sources.limitless.importedNativeMemoryIds, ["n1", "n2"]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a corrupt state file cold-starts instead of bricking sync", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "remnic-syncstate-"));
+  try {
+    const { promises: fsPromises } = await import("node:fs");
+    const filePath = syncStateFilePath(dir);
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+    await fsPromises.writeFile(filePath, "{broken", "utf-8");
+    assert.deepEqual(await loadSyncState(dir), emptySyncState());
+    await fsPromises.writeFile(filePath, "null", "utf-8");
+    assert.deepEqual(await loadSyncState(dir), emptySyncState());
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("lastDateSynced never moves backwards", () => {
+  let state = updateSourceSyncState(emptySyncState(), "bee", {
+    syncedAt: "2026-06-11T01:00:00.000Z",
+    days: ["2026-06-11"],
+    dayHashes: { "2026-06-11": "x" },
+  });
+  state = updateSourceSyncState(state, "bee", {
+    syncedAt: "2026-06-12T01:00:00.000Z",
+    days: ["2026-06-01"],
+    dayHashes: { "2026-06-01": "y" },
+  });
+  assert.equal(state.sources.bee.lastDateSynced, "2026-06-11");
+  assert.equal(state.sources.bee.lastSyncAt, "2026-06-12T01:00:00.000Z");
+});
+
+test("native memory ids are deduplicated and bounded", () => {
+  const manyIds = Array.from({ length: 6_000 }, (_, index) => `id-${index}`);
+  let state = updateSourceSyncState(emptySyncState(), "omi", {
+    syncedAt: "2026-06-11T01:00:00.000Z",
+    days: [],
+    dayHashes: {},
+    importedNativeMemoryIds: manyIds,
+  });
+  state = updateSourceSyncState(state, "omi", {
+    syncedAt: "2026-06-11T02:00:00.000Z",
+    days: [],
+    dayHashes: {},
+    importedNativeMemoryIds: ["id-5999", "fresh"],
+  });
+  const ids = state.sources.omi.importedNativeMemoryIds;
+  assert.ok(ids.length <= 5_000);
+  assert.equal(new Set(ids).size, ids.length, "ids must be unique");
+  assert.ok(ids.includes("fresh"));
+  assert.ok(ids.includes("id-5999"));
+});
+
+test("clearMemoryDays removes stale completion records", () => {
+  let state = updateSourceSyncState(emptySyncState(), "limitless", {
+    syncedAt: "2026-06-11T01:00:00.000Z",
+    days: ["2026-06-10"],
+    dayHashes: { "2026-06-10": "h1" },
+    memoryDayHashes: { "2026-06-10": "h1" },
+  });
+  assert.equal(state.sources.limitless.memoryDayHashes?.["2026-06-10"], "h1");
+
+  // A later run where the day's memory pass failed must clear the
+  // earlier completion record even though the body hash is unchanged.
+  state = updateSourceSyncState(state, "limitless", {
+    syncedAt: "2026-06-12T01:00:00.000Z",
+    days: ["2026-06-10"],
+    dayHashes: { "2026-06-10": "h1" },
+    clearMemoryDays: ["2026-06-10"],
+  });
+  assert.equal(state.sources.limitless.memoryDayHashes?.["2026-06-10"], undefined);
+
+  // A clear for a day that completed in the same run is a no-op.
+  state = updateSourceSyncState(state, "limitless", {
+    syncedAt: "2026-06-13T01:00:00.000Z",
+    days: ["2026-06-10"],
+    dayHashes: { "2026-06-10": "h1" },
+    memoryDayHashes: { "2026-06-10": "h1" },
+    clearMemoryDays: ["2026-06-10"],
+  });
+  assert.equal(state.sources.limitless.memoryDayHashes?.["2026-06-10"], "h1");
+});
+
+test("day hashes are bounded to the most recent dates", () => {
+  const hashes: Record<string, string> = {};
+  for (let index = 0; index < 900; index++) {
+    const day = new Date(Date.UTC(2024, 0, 1) + index * 86_400_000)
+      .toISOString()
+      .slice(0, 10);
+    hashes[day] = `h${index}`;
+  }
+  const state = updateSourceSyncState(emptySyncState(), "limitless", {
+    syncedAt: "2026-06-11T01:00:00.000Z",
+    days: [],
+    dayHashes: hashes,
+  });
+  const keys = Object.keys(state.sources.limitless.dayHashes).sort();
+  assert.equal(keys.length, 800);
+  // The oldest dates were evicted, the newest retained.
+  assert.equal(keys.includes("2024-01-01"), false);
+  assert.ok(keys[keys.length - 1] > "2026-01-01");
+});