@remnic/core 9.15.3 → 9.16.0

package/src/activity/pipeline.test.ts

@@ -0,0 +1,379 @@
+import assert from "node:assert/strict";
+import { access, mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { activityDigestPath } from "./digest.js";
+import { activityCursorKey, syncActivitySource } from "./pipeline.js";
+import { ActivityStore } from "./store.js";
+import type { ActivitySnapshot, ActivitySourceClient } from "./types.js";
+
+function snapshot(overrides: Partial<ActivitySnapshot> = {}): ActivitySnapshot {
+  return {
+    machine: "untrusted-source-value",
+    capturedAtUtc: "2026-07-22T14:00:00.000Z",
+    app: "Browser",
+    windowTitle: "Example",
+    text: "A synthetic activity snapshot",
+    textSource: "ax",
+    contentHash: "hash-1",
+    ...overrides,
+  };
+}
+
+function source(
+  machineLabel: string,
+  pages: Map<string | null, ActivitySnapshot[]>,
+  cursors: Map<string | null, string | null>,
+): ActivitySourceClient {
+  return {
+    machineLabel,
+    async verify() {
+      return { ok: true };
+    },
+    async fetchSnapshots({ cursor }) {
+      return { snapshots: pages.get(cursor ?? null) ?? [], nextCursor: cursors.get(cursor ?? null) ?? null };
+    },
+  };
+}
+
+test("syncActivitySource persists every page, renders the digest, then advances the cursor", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    const client = source(
+      "workstation-a",
+      new Map([
+        [null, [snapshot()]],
+        ["cursor-1", [snapshot({ capturedAtUtc: "2026-07-22T14:01:00.000Z", contentHash: "hash-2" })]],
+      ]),
+      new Map([
+        [null, "cursor-1"],
+        ["cursor-1", "cursor-2"],
+      ]),
+    );
+
+    const result = await syncActivitySource(client, { date: "2026-07-22", timezone: "UTC", memoryDir, store });
+
+    assert.deepEqual(result, {
+      machine: "workstation-a",
+      fetched: 2,
+      inserted: 2,
+      duplicates: 0,
+      cursor: "cursor-2",
+      digestWritten: true,
+    });
+    assert.equal(store.getCursor(activityCursorKey("workstation-a", "2026-07-22")), "cursor-2");
+    assert.deepEqual(
+      store.listSnapshotsForDay(null, "2026-07-22T00:00:00.000Z", "2026-07-23T00:00:00.000Z").map((item) => item.machine),
+      ["workstation-a", "workstation-a"],
+      "the source identity, not a remote payload label, owns the persisted machine field",
+    );
+    assert.match(await readFile(activityDigestPath(memoryDir, "2026-07-22"), "utf8"), /snapshotCount: 2/);
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("syncActivitySource leaves the cursor unchanged when a later page cannot persist", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    const client = source(
+      "workstation-a",
+      new Map([
+        [null, [snapshot()]],
+        ["cursor-1", [snapshot({ capturedAtUtc: "not-a-timestamp", contentHash: "bad-hash" })]],
+      ]),
+      new Map([
+        [null, "cursor-1"],
+        ["cursor-1", "cursor-2"],
+      ]),
+    );
+
+    await assert.rejects(
+      syncActivitySource(client, { date: "2026-07-22", timezone: "UTC", memoryDir, store }),
+      /capture timestamp/,
+    );
+
+    assert.equal(store.getCursor(activityCursorKey("workstation-a", "2026-07-22")), null);
+    assert.equal(store.listSnapshotsForDay(null, "2026-07-22T00:00:00.000Z", "2026-07-23T00:00:00.000Z").length, 1);
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("syncActivitySource completes normally when the final page lands on the page cap", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    const client = source(
+      "workstation-a",
+      new Map([
+        [null, [snapshot()]],
+        ["cursor-1", [snapshot({ capturedAtUtc: "2026-07-22T14:01:00.000Z", contentHash: "hash-2" })]],
+      ]),
+      new Map([
+        [null, "cursor-1"],
+        ["cursor-1", null],
+      ]),
+    );
+
+    // Two pages with a page budget of exactly two: the terminal null cursor
+    // arrives on the last allowed page, which must not be treated as a runaway.
+    const result = await syncActivitySource(client, { date: "2026-07-22", timezone: "UTC", memoryDir, store, maxPages: 2 });
+    assert.equal(result.inserted, 2);
+    assert.equal(result.cursor, "cursor-1");
+    assert.equal(store.getCursor(activityCursorKey("workstation-a", "2026-07-22")), "cursor-1");
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("syncActivitySource rejects runaway pagination and leaves the cursor unadvanced", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    let issued = 0;
+    const runaway: ActivitySourceClient = {
+      machineLabel: "workstation-a",
+      async verify() {
+        return { ok: true };
+      },
+      async fetchSnapshots() {
+        issued += 1;
+        return { snapshots: [], nextCursor: `cursor-${issued}` };
+      },
+    };
+
+    await assert.rejects(
+      syncActivitySource(runaway, { date: "2026-07-22", timezone: "UTC", memoryDir, store, maxPages: 3 }),
+      /exceeded 3 pages/,
+    );
+    assert.equal(store.getCursor(activityCursorKey("workstation-a", "2026-07-22")), null);
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("concurrent same-day syncs from two sources persist without corrupting the digest", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    const clientA = source("workstation-a", new Map([[null, [snapshot({ contentHash: "a-1" })]]]), new Map([[null, null]]));
+    const clientB = source("workstation-b", new Map([[null, [snapshot({ contentHash: "b-1" })]]]), new Map([[null, null]]));
+
+    await Promise.all([
+      syncActivitySource(clientA, { date: "2026-07-22", timezone: "UTC", memoryDir, store }),
+      syncActivitySource(clientB, { date: "2026-07-22", timezone: "UTC", memoryDir, store }),
+    ]);
+
+    const digest = await readFile(activityDigestPath(memoryDir, "2026-07-22"), "utf8");
+    assert.match(digest, /kind: activity-digest/);
+    assert.match(digest, /snapshotCount: 2/);
+    assert.equal(store.getCursor(activityCursorKey("workstation-a", "2026-07-22")), null);
+    assert.equal(store.getCursor(activityCursorKey("workstation-b", "2026-07-22")), null);
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("syncActivitySource reindexes after a digest write, with the digest already durable", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    const client = source("workstation-a", new Map([[null, [snapshot()]]]), new Map([[null, null]]));
+    let reindexed = 0;
+    let digestAtReindex = "";
+    const result = await syncActivitySource(client, {
+      date: "2026-07-22",
+      timezone: "UTC",
+      memoryDir,
+      store,
+      afterWrites: async () => {
+        reindexed += 1;
+        // The reindex must see the durable digest already on disk — that is
+        // what makes the new day discoverable (rule 31).
+        digestAtReindex = await readFile(activityDigestPath(memoryDir, "2026-07-22"), "utf8");
+      },
+    });
+
+    assert.equal(result.digestWritten, true);
+    assert.equal(reindexed, 1, "reindex fires exactly once after the digest write");
+    assert.match(digestAtReindex, /snapshotCount: 1/, "the written digest is visible to the reindex");
+    assert.equal(result.reindexError, undefined);
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("syncActivitySource skips the reindex when the digest is unchanged", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    let reindexed = 0;
+    const opts = {
+      date: "2026-07-22",
+      timezone: "UTC",
+      memoryDir,
+      store,
+      afterWrites: async () => {
+        reindexed += 1;
+      },
+    };
+    const first = source("workstation-a", new Map([[null, [snapshot()]]]), new Map([[null, null]]));
+    await syncActivitySource(first, opts);
+    const second = source("workstation-a", new Map([[null, [snapshot()]]]), new Map([[null, null]]));
+    const result = await syncActivitySource(second, opts);
+
+    assert.equal(result.digestWritten, false, "an unchanged day rewrites nothing");
+    assert.equal(reindexed, 1, "no reindex when the digest did not change");
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("syncActivitySource isolates a reindex failure: rows, digest, and cursor still commit", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    const client = source("workstation-a", new Map([[null, [snapshot()]]]), new Map([[null, null]]));
+    const result = await syncActivitySource(client, {
+      date: "2026-07-22",
+      timezone: "UTC",
+      memoryDir,
+      store,
+      afterWrites: async () => {
+        // A backend error whose message embeds an absolute path must be
+        // sanitized to a name+code in the exported reindexError, not echoed.
+        throw Object.assign(new Error("ENOENT: /abs/qmd/index.sqlite missing"), { code: "ENOENT" });
+      },
+    });
+
+    assert.equal(result.digestWritten, true, "the digest is durable despite the reindex failure");
+    assert.match(result.reindexError ?? "", /ENOENT/);
+    assert.ok(!result.reindexError?.includes("/abs/qmd"), "reindexError does not leak the absolute path");
+    assert.equal(result.inserted, 1);
+    await access(activityDigestPath(memoryDir, "2026-07-22"));
+    assert.equal(
+      store.getCursor(activityCursorKey("workstation-a", "2026-07-22")),
+      null,
+      "cursor still advanced; reindex is best-effort",
+    );
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("syncActivitySource honors an abort before committing the digest and cursor", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    const controller = new AbortController();
+    const client: ActivitySourceClient = {
+      machineLabel: "workstation-a",
+      async verify() {
+        return { ok: true };
+      },
+      async fetchSnapshots() {
+        // Abort fires after the last page returns but before the digest write.
+        controller.abort();
+        return { snapshots: [snapshot()], nextCursor: null };
+      },
+    };
+
+    await assert.rejects(
+      syncActivitySource(client, {
+        date: "2026-07-22",
+        timezone: "UTC",
+        memoryDir,
+        store,
+        signal: controller.signal,
+      }),
+    );
+
+    assert.equal(
+      store.getCursor(activityCursorKey("workstation-a", "2026-07-22")),
+      null,
+      "an aborted tick never advances the cursor",
+    );
+    await assert.rejects(
+      readFile(activityDigestPath(memoryDir, "2026-07-22"), "utf8"),
+      "an aborted tick never writes the digest",
+    );
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("syncActivitySource persists out-of-window snapshots under their own day, never the requested day's digest", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    const client = source(
+      "workstation-a",
+      new Map([
+        [
+          null,
+          [
+            snapshot({ capturedAtUtc: "2026-07-22T14:00:00.000Z", contentHash: "in-window" }),
+            // A snapshot the daemon misplaced onto a different day (replay /
+            // timezone bug). It must be retained under its own day, not lost.
+            snapshot({ capturedAtUtc: "2026-07-20T10:00:00.000Z", contentHash: "out-of-window" }),
+          ],
+        ],
+      ]),
+      new Map([[null, null]]),
+    );
+
+    const result = await syncActivitySource(client, { date: "2026-07-22", timezone: "UTC", memoryDir, store });
+
+    assert.equal(result.fetched, 2, "both snapshots were fetched");
+    assert.equal(result.inserted, 2, "both snapshots are durably persisted (no data loss)");
+    // The requested day's digest is a window query: only its in-window row.
+    const day = store.listSnapshotsForDay(null, "2026-07-22T00:00:00.000Z", "2026-07-23T00:00:00.000Z");
+    assert.deepEqual(day.map((s) => s.contentHash), ["in-window"], "the requested day contains only its in-window row");
+    assert.match(await readFile(activityDigestPath(memoryDir, "2026-07-22"), "utf8"), /snapshotCount: 1/);
+    // The misplaced row is durable under ITS OWN day, surfacing when that day syncs.
+    const ownDay = store.listSnapshotsForDay(null, "2026-07-20T00:00:00.000Z", "2026-07-21T00:00:00.000Z");
+    assert.deepEqual(ownDay.map((s) => s.contentHash), ["out-of-window"], "the misplaced row is retained under its own day, not dropped");
+    // Nothing was skipped, so the cursor advancing past the page is correct.
+    assert.equal(store.getCursor(activityCursorKey("workstation-a", "2026-07-22")), null, "cursor advances after a fully-persisted page");
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("syncActivitySource rejects a calendar-overflow timestamp instead of skipping it", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-pipeline-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    const client = source(
+      "workstation-a",
+      // 2026-02-30 is impossible; Date.parse rolls it to Mar 2, which would fall
+      // outside a Feb 28 sync window. It must fail loudly, not be silently skipped.
+      new Map([[null, [snapshot({ capturedAtUtc: "2026-02-30T12:00:00.000Z", contentHash: "overflow" })]]]),
+      new Map([[null, null]]),
+    );
+
+    await assert.rejects(
+      syncActivitySource(client, { date: "2026-02-28", timezone: "UTC", memoryDir, store }),
+      /capture timestamp/,
+    );
+    assert.equal(store.getCursor(activityCursorKey("workstation-a", "2026-02-28")), null, "cursor never advances on a rejected page");
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/activity/pipeline.ts

@@ -0,0 +1,223 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+
+import { displayErrorDetail } from "../runtime/better-sqlite.js";
+
+import {
+  activityDayWindow,
+  activityDigestPath,
+  composeActivityDigestBody,
+  composeActivityDigestMeta,
+  isValidActivityDate,
+  serializeActivityDigest,
+} from "./digest.js";
+import type { ActivityStore } from "./store.js";
+import type { ActivitySnapshot, ActivitySourceClient } from "./types.js";
+
+const MAX_SYNC_PAGES = 10_000;
+
+/**
+ * Sync cursors are scoped per (machine, local day): each date resumes its own
+ * pagination independently, so a multi-day window never inherits an earlier
+ * day's cursor (which could skip backfill). Encoded into the store's single
+ * key column with a NUL separator that cannot occur in a machine label.
+ */
+export function activityCursorKey(machine: string, date: string): string {
+  return `${machine}\u0000${date}`;
+}
+
+// Serializes the list -> compose -> write digest section per (memoryDir, date)
+// so two sources syncing the same day cannot lose-update each other's digest:
+// the last writer in the chain lists every row present and wins.
+const digestLocks = new Map<string, Promise<unknown>>();
+
+function withDigestLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const prior = digestLocks.get(key) ?? Promise.resolve();
+  const next = prior.then(fn, fn);
+  const tail = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  digestLocks.set(key, tail);
+  void tail.then(() => {
+    if (digestLocks.get(key) === tail) digestLocks.delete(key);
+  });
+  return next;
+}
+
+export interface ActivitySyncOptions {
+  date: string;
+  timezone: string;
+  memoryDir: string;
+  store: ActivityStore;
+  signal?: AbortSignal;
+  /** Runaway-pagination guard; defaults to MAX_SYNC_PAGES. */
+  maxPages?: number;
+  /**
+   * Search-index refresh, run after a digest is (re)written so the durable
+   * markdown becomes discoverable (AGENTS.md rule 31; the digest lives in the
+   * QMD collection root but bypasses the extraction->persist->index pipeline).
+   * Host-agnostic: the caller injects the core index seam (SearchBackend.update).
+   * Best-effort — a failure never fails the sync (rows/digest are durable and
+   * index on the next update); it surfaces as `reindexError`.
+   */
+  afterWrites?: (signal?: AbortSignal) => Promise<void>;
+}
+
+export interface ActivitySyncResult {
+  machine: string;
+  fetched: number;
+  inserted: number;
+  duplicates: number;
+  cursor: string | null;
+  digestWritten: boolean;
+  /** Set when the post-write reindex threw; the sync still succeeded. */
+  reindexError?: string;
+}
+
+function snapshotForMachine(snapshot: ActivitySnapshot, machine: string): ActivitySnapshot {
+  return {
+    machine,
+    capturedAtUtc: snapshot.capturedAtUtc,
+    app: snapshot.app,
+    windowTitle: snapshot.windowTitle,
+    ...(snapshot.browserUrl === undefined ? {} : { browserUrl: snapshot.browserUrl }),
+    text: snapshot.text,
+    textSource: snapshot.textSource,
+    contentHash: snapshot.contentHash,
+    ...(snapshot.simhash === undefined ? {} : { simhash: snapshot.simhash }),
+  };
+}
+
+async function writeDigestIfChanged(memoryDir: string, date: string, serialized: string): Promise<boolean> {
+  const target = activityDigestPath(memoryDir, date);
+  try {
+    if ((await readFile(target, "utf8")) === serialized) return false;
+  } catch (error: unknown) {
+    if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
+  }
+
+  await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, serialized, { encoding: "utf8", mode: 0o600 });
+  await rename(temporary, target);
+  return true;
+}
+
+/**
+ * Pull one source's local-day snapshots and persist its cursor only after every
+ * page and the derived digest are durable. Replays after a partial failure are
+ * safe because ActivityStore deduplicates an exact captured snapshot.
+ */
+export async function syncActivitySource(
+  source: ActivitySourceClient,
+  options: ActivitySyncOptions,
+): Promise<ActivitySyncResult> {
+  if (!isValidActivityDate(options.date)) {
+    throw new RangeError(`Invalid activity date "${options.date}"; expected a real YYYY-MM-DD day.`);
+  }
+  if (source.machineLabel.trim().length === 0) {
+    throw new RangeError("activity source machine label must not be empty");
+  }
+  const maxPages = options.maxPages ?? MAX_SYNC_PAGES;
+  if (!Number.isInteger(maxPages) || maxPages < 1) {
+    throw new RangeError("activity sync maxPages must be a positive integer");
+  }
+
+  const cursorKey = activityCursorKey(source.machineLabel, options.date);
+  let cursor = options.store.getCursor(cursorKey);
+  let pages = 0;
+  let fetched = 0;
+  let inserted = 0;
+  let duplicates = 0;
+  const seenCursors = new Set<string>();
+  let completed = false;
+
+  while (pages < maxPages) {
+    options.signal?.throwIfAborted();
+    const page = await source.fetchSnapshots({
+      date: options.date,
+      timezone: options.timezone,
+      cursor,
+      signal: options.signal,
+    });
+    pages += 1;
+    fetched += page.snapshots.length;
+
+    for (const snapshot of page.snapshots) {
+      // Persist every row keyed by its own timestamp: an out-of-window snapshot
+      // (replay file, timezone-boundary bug) is durable under its own day and
+      // never lost, while the day digest below is a window query so it never
+      // pollutes options.date. A malformed instant is rejected loudly here.
+      const result = options.store.insertSnapshot(snapshotForMachine(snapshot, source.machineLabel));
+      if (result.inserted) inserted += 1;
+      else duplicates += 1;
+    }
+    if (page.nextCursor === null) {
+      completed = true;
+      break;
+    }
+    if (typeof page.nextCursor !== "string" || page.nextCursor.length === 0) {
+      throw new TypeError("activity source returned an invalid cursor");
+    }
+    if (seenCursors.has(page.nextCursor)) {
+      throw new Error("activity source returned a repeated cursor");
+    }
+    seenCursors.add(page.nextCursor);
+    cursor = page.nextCursor;
+  }
+
+  // Only a loop that ran out of its page budget without seeing a terminal
+  // null cursor is a runaway; completing on the final allowed page is normal.
+  if (!completed) {
+    throw new Error(`activity source exceeded ${maxPages} pages`);
+  }
+
+  // Re-check abort before the durable write section: stop() may have fired after
+  // the last page returned, or while this date waited behind digestLocks. An
+  // aborted tick must not compose/write a digest or advance the cursor.
+  options.signal?.throwIfAborted();
+  const digestWritten = await withDigestLock(`${options.memoryDir}\u0000${options.date}`, async () => {
+    options.signal?.throwIfAborted();
+    const { startUtc, endUtc } = activityDayWindow(options.date, options.timezone);
+    const snapshots = options.store.listSnapshotsForDay(null, startUtc, endUtc);
+    const body = composeActivityDigestBody(options.date, options.timezone, snapshots);
+    const machines = [...new Set(snapshots.map((snapshot) => snapshot.machine))].sort((a, b) =>
+      a < b ? -1 : a > b ? 1 : 0,
+    );
+    const serialized = serializeActivityDigest(composeActivityDigestMeta(options.date, machines, snapshots, body), body);
+    return writeDigestIfChanged(options.memoryDir, options.date, serialized);
+  });
+
+  options.signal?.throwIfAborted();
+  options.store.setCursor(cursorKey, cursor);
+
+  // Rows and digest are durable and the cursor has advanced; refresh the search
+  // index so the new digest is discoverable (rule 31). Best-effort: a failure
+  // is reported, not thrown — the data indexes on the next update.
+  let reindexError: string | undefined;
+  if (digestWritten && options.afterWrites !== undefined) {
+    try {
+      await options.afterWrites(options.signal);
+    } catch (error: unknown) {
+      // reindexError is part of the exported ActivitySyncResult. Keep our
+      // controlled QMD strict messages, but reduce opaque backend errors (which
+      // can embed absolute paths / loader stacks) to a sanitized name+code.
+      reindexError =
+        error instanceof Error && error.message.startsWith("QMD ")
+          ? error.message
+          : displayErrorDetail(error) || "reindex failed";
+    }
+  }
+
+  return {
+    machine: source.machineLabel,
+    fetched,
+    inserted,
+    duplicates,
+    cursor,
+    digestWritten,
+    ...(reindexError === undefined ? {} : { reindexError }),
+  };
+}

package/src/activity/reindex.test.ts

@@ -0,0 +1,97 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { refreshActivityIndex, type ActivityIndexRefresher } from "./reindex.js";
+
+function refresher(overrides: Partial<ActivityIndexRefresher>, calls: string[]): ActivityIndexRefresher {
+  return {
+    async update() {
+      calls.push("update");
+    },
+    ...overrides,
+  };
+}
+
+test("refreshActivityIndex prefers the forced+strict collection refresh", async () => {
+  const calls: string[] = [];
+  const qmd = refresher(
+    {
+      async updateStrict() {
+        calls.push("updateStrict");
+      },
+      async updateCollectionStrict(collection: string) {
+        calls.push(`updateCollectionStrict:${collection}`);
+      },
+    },
+    calls,
+  );
+
+  await refreshActivityIndex(qmd, "openclaw-engram");
+  assert.deepEqual(calls, ["updateCollectionStrict:openclaw-engram"], "forces past the fail-open min-interval gate");
+});
+
+test("refreshActivityIndex falls back to updateStrict, then update", async () => {
+  const strictCalls: string[] = [];
+  await refreshActivityIndex(
+    refresher(
+      {
+        async updateStrict() {
+          strictCalls.push("updateStrict");
+        },
+      },
+      strictCalls,
+    ),
+    "openclaw-engram",
+  );
+  assert.deepEqual(strictCalls, ["updateStrict"], "uses strict global refresh when no collection-strict path exists");
+
+  const plainCalls: string[] = [];
+  await refreshActivityIndex(refresher({}, plainCalls), "openclaw-engram");
+  assert.deepEqual(plainCalls, ["update"], "falls back to plain update when no strict path exists");
+});
+
+test("refreshActivityIndex skips collection-strict for an empty collection name", async () => {
+  const calls: string[] = [];
+  await refreshActivityIndex(
+    refresher(
+      {
+        async updateStrict() {
+          calls.push("updateStrict");
+        },
+        async updateCollectionStrict(collection: string) {
+          calls.push(`updateCollectionStrict:${collection}`);
+        },
+      },
+      calls,
+    ),
+    "   ",
+  );
+  assert.deepEqual(calls, ["updateStrict"], "no collection -> strict global refresh, never a blank-collection call");
+});
+
+test("refreshActivityIndex propagates a strict-refresh failure (no fake success)", async () => {
+  const calls: string[] = [];
+  const qmd = refresher(
+    {
+      async updateCollectionStrict() {
+        calls.push("updateCollectionStrict");
+        throw new Error("QMD update skipped by per-collection failure backoff");
+      },
+    },
+    calls,
+  );
+  await assert.rejects(refreshActivityIndex(qmd, "openclaw-engram"), /failure backoff/);
+});
+
+test("refreshActivityIndex forwards the abort signal to the backend refresh", async () => {
+  const controller = new AbortController();
+  let seenSignal: AbortSignal | undefined;
+  const qmd: ActivityIndexRefresher = {
+    async update() {},
+    async updateCollectionStrict(_collection, execution) {
+      seenSignal = execution?.signal;
+    },
+  };
+  await refreshActivityIndex(qmd, "openclaw-engram", controller.signal);
+  assert.equal(seenSignal, controller.signal, "the tick's abort signal reaches the QMD refresh");
+});