@remnic/core 9.66.7 → 9.66.9

package/src/activity/config.ts

@@ -1,5 +1,6 @@
 import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
 import { assertValidTimezone } from "./digest.js";
+import { resolveJournalSource } from "./journal-source.js";
 import type { ImportanceLevel } from "../types.js";
 import type {
   ActivityConfig,
@@ -29,7 +30,7 @@ export function defaultActivityConfig(): ActivityConfig {
     minConfidence: 0.7,
     minImportance: "normal",
     maxMemoriesPerDay: 0,
-    timeline: { enabled: false, journal: { enabled: false }, qa: { enabled: false, maxRangeDays: 31 } },
+    timeline: { enabled: false, journal: { enabled: false, source: "file" }, qa: { enabled: false, maxRangeDays: 31 } },
   };
 }
 
@@ -200,7 +201,7 @@ export function parseActivityConfig(raw: unknown): ActivityConfig {
  * is malformed and must fail rather than silently disabling the layer.
  */
 function parseTimelineConfig(raw: unknown): ActivityTimelineConfig {
-  if (raw === undefined) return { enabled: false, journal: { enabled: false }, qa: parseTimelineQaConfig(undefined) };
+  if (raw === undefined) return { enabled: false, journal: { enabled: false, source: "file" }, qa: parseTimelineQaConfig(undefined) };
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new TypeError("activity.timeline must be an object");
   }
@@ -217,7 +218,7 @@ function parseTimelineConfig(raw: unknown): ActivityTimelineConfig {
 }
 
 function parseTimelineJournalConfig(raw: unknown): ActivityTimelineJournalConfig {
-  if (raw === undefined) return { enabled: false };
+  if (raw === undefined) return { enabled: false, source: "file" };
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new TypeError("activity.timeline.journal must be an object");
   }
@@ -226,7 +227,22 @@ function parseTimelineJournalConfig(raw: unknown): ActivityTimelineJournalConfig
   if (journal.enabled !== undefined && enabledValue === undefined) {
     throw new TypeError("activity.timeline.journal.enabled must be a boolean");
   }
-  return { enabled: enabledValue ?? false };
+  const heading = journal.heading;
+  if (heading !== undefined && typeof heading !== "string") {
+    throw new TypeError("activity.timeline.journal.heading must be a string");
+  }
+  const source = journal.source === undefined ? "file" : typeof journal.source === "string" ? journal.source : "";
+  const resolved = resolveJournalSource({ source, heading: heading ?? "" });
+  if (!resolved.ok) {
+    if (resolved.error === "unknown_source") {
+      throw new RangeError('activity.timeline.journal.source must be one of "file", "vault"');
+    }
+    throw new RangeError('activity.timeline.journal.heading must be a non-empty string when source is "vault"');
+  }
+  if (resolved.mode === "vault") {
+    return { enabled: enabledValue ?? false, source: "vault", heading: resolved.heading };
+  }
+  return { enabled: enabledValue ?? false, source: "file" };
 }
 
 function parseTimelineQaConfig(raw: unknown): ActivityTimelineQaConfig {

package/src/activity/journal.test.ts

@@ -32,6 +32,46 @@ test("activity.timeline.journal.enabled defaults off", () => {
   );
 });
 
+test("activity.timeline.journal source defaults to file with no heading", () => {
+  const journal = parseActivityConfig(undefined).timeline.journal;
+  assert.equal(journal.source, "file");
+  assert.equal(journal.heading, undefined);
+});
+
+test("activity.timeline.journal vault mode trims and stores the heading", () => {
+  const journal = parseActivityConfig({ timeline: { journal: { enabled: true, source: "vault", heading: " Journal " } } }).timeline.journal;
+  assert.deepEqual(journal, { enabled: true, source: "vault", heading: "Journal" });
+});
+
+test("activity.timeline.journal vault mode requires a non-empty heading", () => {
+  for (const heading of [undefined, "", "   "]) {
+    assert.throws(
+      () => parseActivityConfig({ timeline: { journal: { source: "vault", heading } } }),
+      RangeError,
+    );
+  }
+});
+
+test("activity.timeline.journal rejects an unknown source", () => {
+  assert.throws(
+    () => parseActivityConfig({ timeline: { journal: { source: "memoryDir" } } }),
+    /activity\.timeline\.journal\.source must be one of "file", "vault"/,
+  );
+});
+
+test("activity.timeline.journal rejects a non-string heading", () => {
+  assert.throws(
+    () => parseActivityConfig({ timeline: { journal: { heading: 5 } } }),
+    /activity\.timeline\.journal\.heading must be a string/,
+  );
+});
+
+test("activity.timeline.journal file mode ignores a provided heading", () => {
+  const journal = parseActivityConfig({ timeline: { journal: { source: "file", heading: "Ignored" } } }).timeline.journal;
+  assert.deepEqual(journal, { enabled: false, source: "file" });
+  assert.equal("heading" in journal, false);
+});
+
 test("seed is a hard no-op without force", () => {
   withMemoryDir((memoryDir) => {
     const first = seedJournal({

package/src/activity/timeline/index.ts

@@ -19,3 +19,4 @@ export * from "./analysis-evidence.js";
 export * from "./analysis-prompt.js";
 export * from "./analysis-claim.js";
 export * from "./analysis-order.js";
+export * from "./recap-window.js";

package/src/activity/timeline/recap-window.test.ts

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  clipCardsToRecapWindow,
+  type RecapWindowCard,
+} from "./recap-window.js";
+
+const MINUTE = 60_000;
+const DAY_START = Date.UTC(2026, 0, 15); // 2026-01-15T00:00:00Z
+const DAY_END = DAY_START + 24 * 60 * 60_000;
+
+const iso = (ms: number): string => new Date(ms).toISOString();
+
+const card = (id: string, startMs: number, endMs: number): RecapWindowCard => ({
+  id,
+  startUtc: iso(startMs),
+  endUtc: iso(endMs),
+});
+
+describe("clipCardsToRecapWindow", () => {
+  it("returns [] for empty input", () => {
+    assert.deepEqual(clipCardsToRecapWindow([], DAY_START, DAY_END), []);
+  });
+
+  it("excludes a card ending exactly at windowStart and one starting exactly at windowEnd", () => {
+    const before = card("before", DAY_START - 2 * MINUTE, DAY_START);
+    const after = card("after", DAY_END, DAY_END + 2 * MINUTE);
+    const inside = card("inside", DAY_START, DAY_END);
+
+    const result = clipCardsToRecapWindow([before, after, inside], DAY_START, DAY_END);
+
+    assert.deepEqual(
+      result.map((c) => c.id),
+      ["inside"],
+    );
+    assert.equal(result[0]?.startMs, DAY_START);
+    assert.equal(result[0]?.endMs, DAY_END);
+    assert.equal(result[0]?.durationMs, DAY_END - DAY_START);
+
+    // Each midnight-touching card lands in exactly one adjacent window.
+    const windowMs = DAY_END - DAY_START;
+    const prevDay = clipCardsToRecapWindow([before], DAY_START - windowMs, DAY_START);
+    const nextDay = clipCardsToRecapWindow([after], DAY_END, DAY_END + windowMs);
+    assert.equal(prevDay[0]?.id, "before");
+    assert.equal(nextDay[0]?.id, "after");
+  });
+
+  it("clips a card straddling the window start", () => {
+    const straddle = card("straddle", DAY_START - 30 * MINUTE, DAY_START + 90 * MINUTE);
+
+    const result = clipCardsToRecapWindow([straddle], DAY_START, DAY_END);
+
+    assert.equal(result.length, 1);
+    assert.equal(result[0]?.startMs, DAY_START);
+    assert.equal(result[0]?.endMs, DAY_START + 90 * MINUTE);
+    assert.equal(result[0]?.durationMs, 90 * MINUTE);
+  });
+
+  it("clips a card straddling the window end", () => {
+    const straddle = card("tail", DAY_END - 5 * MINUTE, DAY_END + 45 * MINUTE);
+
+    const result = clipCardsToRecapWindow([straddle], DAY_START, DAY_END);
+
+    assert.equal(result.length, 1);
+    assert.equal(result[0]?.endMs, DAY_END);
+    assert.equal(result[0]?.durationMs, 5 * MINUTE);
+  });
+
+  it("skips cards with unparseable timestamps without throwing", () => {
+    const good = card("good", DAY_START + MINUTE, DAY_START + 10 * MINUTE);
+    const bad: RecapWindowCard[] = [
+      { id: "bad-start", startUtc: "not-a-date", endUtc: iso(DAY_START + 5 * MINUTE) },
+      { id: "bad-end", startUtc: iso(DAY_START), endUtc: "" },
+      good,
+    ];
+
+    const result = clipCardsToRecapWindow(bad, DAY_START, DAY_END);
+
+    assert.deepEqual(
+      result.map((c) => c.id),
+      ["good"],
+    );
+    assert.equal(result[0]?.durationMs, 9 * MINUTE);
+  });
+
+  it("throws RangeError on inverted or empty window", () => {
+    assert.throws(
+      () => clipCardsToRecapWindow([], DAY_END, DAY_START),
+      RangeError,
+    );
+    assert.throws(
+      () => clipCardsToRecapWindow([], DAY_START, DAY_START),
+      RangeError,
+    );
+  });
+
+  it("throws RangeError on non-finite window bounds", () => {
+    // NaN and Infinity pass `end <= start`, so without an explicit finite
+    // check they would produce NaN timestamps instead of an error.
+    for (const [start, end] of [
+      [Number.NaN, DAY_END],
+      [DAY_START, Number.NaN],
+      [Number.POSITIVE_INFINITY, DAY_END],
+      [DAY_START, Number.POSITIVE_INFINITY],
+    ] as const) {
+      assert.throws(() => clipCardsToRecapWindow([], start, end), /finite/);
+    }
+  });
+
+  it("sorts by startMs then id, byte-identical across calls", () => {
+    const same = DAY_START + 60 * MINUTE;
+    const cards: RecapWindowCard[] = [
+      card("z-late", DAY_START + 120 * MINUTE, DAY_START + 130 * MINUTE),
+      card("b-tie", same, same + 10 * MINUTE),
+      card("a-tie", same, same + 10 * MINUTE),
+      card("early", DAY_START + 5 * MINUTE, DAY_START + 6 * MINUTE),
+    ];
+
+    const first = clipCardsToRecapWindow(cards, DAY_START, DAY_END);
+    const second = clipCardsToRecapWindow(cards, DAY_START, DAY_END);
+
+    assert.deepEqual(
+      first.map((c) => c.id),
+      ["early", "a-tie", "b-tie", "z-late"],
+    );
+    assert.deepEqual(first, second);
+  });
+});

package/src/activity/timeline/recap-window.ts

@@ -0,0 +1,55 @@
+/**
+ * Deterministic half-open recap window clip (issue #2051).
+ *
+ * Clips cards to [windowStartMs, windowEndMs) so recap renderers share one
+ * day-boundary derivation instead of re-deriving it per renderer.
+ */
+export interface RecapWindowCard {
+  id: string;
+  startUtc: string;
+  endUtc: string;
+}
+
+export interface ClippedRecapCard {
+  id: string;
+  startMs: number;
+  endMs: number;
+  durationMs: number;
+}
+
+export function clipCardsToRecapWindow(
+  cards: readonly RecapWindowCard[],
+  windowStartMs: number,
+  windowEndMs: number,
+): ClippedRecapCard[] {
+  // NaN fails every comparison, so an unchecked non-finite bound slips past the
+  // ordering guard and emits NaN timestamps and durations — `durationMs <= 0`
+  // is also false for NaN, so the card is not even dropped.
+  if (!Number.isFinite(windowStartMs) || !Number.isFinite(windowEndMs)) {
+    throw new RangeError(
+      `recap window bounds must be finite; got start ${windowStartMs} and end ${windowEndMs}`,
+    );
+  }
+  if (windowEndMs <= windowStartMs) {
+    throw new RangeError(
+      `recap window end ${windowEndMs} must be greater than start ${windowStartMs}`,
+    );
+  }
+  const out: ClippedRecapCard[] = [];
+  for (const card of cards) {
+    const startMs = Date.parse(card.startUtc);
+    const endMs = Date.parse(card.endUtc);
+    if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) {
+      continue;
+    }
+    const clippedStart = Math.max(startMs, windowStartMs);
+    const clippedEnd = Math.min(endMs, windowEndMs);
+    const durationMs = clippedEnd - clippedStart;
+    if (durationMs <= 0) {
+      continue;
+    }
+    out.push({ id: card.id, startMs: clippedStart, endMs: clippedEnd, durationMs });
+  }
+  out.sort((a, b) => a.startMs - b.startMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return out;
+}

package/src/activity/types.ts

@@ -99,6 +99,10 @@ export interface ActivitySourceConfig {
 /** Opt-in daily journal settings (issue #1984). Default off. */
 export interface ActivityTimelineJournalConfig {
   enabled: boolean;
+  /** Where the journal text is read from (issue #1987). */
+  source: "file" | "vault";
+  /** Vault section heading, trimmed. Required when `source` is `"vault"`; not stored in `"file"` mode. */
+  heading?: string;
 }
 
 /** Opt-in timeline Q&A range/search settings (issue #1983 PR1). Default off. */

package/src/config.test.ts

@@ -2569,7 +2569,7 @@ test("parseConfig forwards activity source settings", () => {
     minConfidence: 0.7,
     minImportance: "normal",
     maxMemoriesPerDay: 0,
-    timeline: { enabled: false, journal: { enabled: false }, qa: { enabled: false, maxRangeDays: 31 } },
+    timeline: { enabled: false, journal: { enabled: false, source: "file" }, qa: { enabled: false, maxRangeDays: 31 } },
   });
 });
 

package/src/dedup/index.ts

@@ -460,3 +460,10 @@ function walkMdFiles(
     }
   }
 }
+
+export {
+  decideMergeOnWrite,
+  type MergeCandidate,
+  type MergeDecision,
+  type MergeDecisionOptions,
+} from "./merge-decision.js";

package/src/dedup/merge-decision.test.ts

@@ -0,0 +1,157 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  decideMergeOnWrite,
+  type MergeCandidate,
+  type MergeDecisionOptions,
+} from "./merge-decision.js";
+
+const OPTS: MergeDecisionOptions = { updateThreshold: 0.8, duplicateThreshold: 0.92 };
+
+function candidate(overrides: Partial<MergeCandidate> = {}): MergeCandidate {
+  return {
+    id: "fact-1",
+    similarity: 0.85,
+    updatedAt: "2026-01-02T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+test("no candidates creates", () => {
+  assert.deepEqual(decideMergeOnWrite([], OPTS), { action: "create" });
+});
+
+test("best similarity at or above duplicateThreshold skips as duplicate", () => {
+  assert.deepEqual(
+    decideMergeOnWrite(
+      [candidate({ id: "low", similarity: 0.5 }), candidate({ id: "dup", similarity: 0.92 })],
+      OPTS,
+    ),
+    { action: "skip", reason: "duplicate" },
+  );
+});
+
+test("best similarity between thresholds updates the best candidate", () => {
+  assert.deepEqual(
+    decideMergeOnWrite(
+      [candidate({ id: "best", similarity: 0.9 }), candidate({ id: "worst", similarity: 0.81 })],
+      OPTS,
+    ),
+    { action: "update", targetId: "best" },
+  );
+});
+
+test("best similarity below updateThreshold creates", () => {
+  assert.deepEqual(
+    decideMergeOnWrite([candidate({ similarity: 0.79 })], OPTS),
+    { action: "create" },
+  );
+});
+
+test("invalid thresholds throw RangeError", () => {
+  const bad: MergeDecisionOptions[] = [
+    { updateThreshold: Number.NaN, duplicateThreshold: 0.9 },
+    { updateThreshold: 0.8, duplicateThreshold: Number.POSITIVE_INFINITY },
+    { updateThreshold: -0.1, duplicateThreshold: 0.9 },
+    { updateThreshold: 0.8, duplicateThreshold: 1.1 },
+    { updateThreshold: 0.92, duplicateThreshold: 0.8 }, // duplicate < update
+  ];
+  for (const options of bad) {
+    assert.throws(() => decideMergeOnWrite([], options), RangeError);
+  }
+});
+
+test("updateThreshold 0 is honored, never coerced up", () => {
+  const zero = { updateThreshold: 0, duplicateThreshold: 0.92 };
+  // similarity 0 is >= 0 -> update, not create and not default-band behavior
+  assert.deepEqual(
+    decideMergeOnWrite([candidate({ similarity: 0 })], zero),
+    { action: "update", targetId: "fact-1" },
+  );
+  // no candidates still creates
+  assert.deepEqual(decideMergeOnWrite([], zero), { action: "create" });
+});
+
+test("malformed candidates are ignored, never thrown on", () => {
+  assert.deepEqual(
+    decideMergeOnWrite(
+      [
+        { id: "", similarity: 0.99, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "  ", similarity: 0.99, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "nan", similarity: Number.NaN, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "inf", similarity: Number.POSITIVE_INFINITY, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "high", similarity: 1.5, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "neg", similarity: -0.2, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "good", similarity: 0.85, updatedAt: "2026-01-02T00:00:00.000Z" },
+      ],
+      OPTS,
+    ),
+    { action: "update", targetId: "good" },
+  );
+  // all-malformed behaves like no candidates
+  assert.deepEqual(
+    decideMergeOnWrite([{ id: "nan", similarity: Number.NaN, updatedAt: "x" }], OPTS),
+    { action: "create" },
+  );
+});
+
+test("identical similarity and updatedAt tie-breaks on id ascending, deterministically", () => {
+  const candidates = [
+    candidate({ id: "b", similarity: 0.9, updatedAt: "2026-03-01T00:00:00.000Z" }),
+    candidate({ id: "a", similarity: 0.9, updatedAt: "2026-03-01T00:00:00.000Z" }),
+    candidate({ id: "c", similarity: 0.9, updatedAt: "2026-03-01T00:00:00.000Z" }),
+  ];
+  const first = decideMergeOnWrite(candidates, OPTS);
+  const second = decideMergeOnWrite([...candidates].reverse(), OPTS);
+  assert.deepEqual(first, second);
+  assert.deepEqual(first, { action: "update", targetId: "a" });
+});
+
+test("unparseable updatedAt sorts last", () => {
+  const candidates = [
+    candidate({ id: "bad-date", similarity: 0.9, updatedAt: "not-a-timestamp" }),
+    candidate({ id: "good-date", similarity: 0.9, updatedAt: "2026-03-01T00:00:00.000Z" }),
+  ];
+  assert.deepEqual(decideMergeOnWrite(candidates, OPTS), { action: "update", targetId: "good-date" });
+  // newer timestamp wins when both parse
+  assert.deepEqual(
+    decideMergeOnWrite(
+      [
+        candidate({ id: "older", updatedAt: "2026-01-01T00:00:00.000Z" }),
+        candidate({ id: "newer", updatedAt: "2026-06-01T00:00:00.000Z" }),
+      ],
+      OPTS,
+    ),
+    { action: "update", targetId: "newer" },
+  );
+});
+
+// Two unparseable timestamps must not make the comparator asymmetric: testing
+// each side against NaN independently returned 1 for both orderings, so the
+// winner depended on array order.
+test("two unparseable updatedAt values break the tie by id, whatever the order", () => {
+  const options = { updateThreshold: 0.5, duplicateThreshold: 0.95 };
+  const alpha = { id: "alpha", similarity: 0.7, updatedAt: "not-a-date" };
+  const beta = { id: "beta", similarity: 0.7, updatedAt: "also-not-a-date" };
+
+  for (const candidates of [[alpha, beta], [beta, alpha]]) {
+    assert.deepEqual(decideMergeOnWrite(candidates, options), {
+      action: "update",
+      targetId: "alpha",
+    });
+  }
+});
+
+test("a parseable updatedAt still outranks an unparseable one in both orders", () => {
+  const options = { updateThreshold: 0.5, duplicateThreshold: 0.95 };
+  const dated = { id: "zeta", similarity: 0.7, updatedAt: "2026-08-19T00:00:00.000Z" };
+  const undated = { id: "alpha", similarity: 0.7, updatedAt: "nope" };
+
+  for (const candidates of [[dated, undated], [undated, dated]]) {
+    assert.deepEqual(decideMergeOnWrite(candidates, options), {
+      action: "update",
+      targetId: "zeta",
+    });
+  }
+});

package/src/dedup/merge-decision.ts

@@ -0,0 +1,78 @@
+/**
+ * Pure create/update/skip decision for merge-on-write (issue #2330 slice).
+ *
+ * No I/O, no LLM. Invalid thresholds throw RangeError; bad candidates are
+ * ignored, never thrown on. `below_threshold` is reserved for a later slice.
+ */
+
+export type MergeDecision =
+  | { action: "create" }
+  | { action: "update"; targetId: string }
+  | { action: "skip"; reason: "duplicate" | "below_threshold" };
+
+export interface MergeCandidate {
+  id: string;
+  similarity: number; // 0..1
+  updatedAt: string; // ISO
+}
+
+export interface MergeDecisionOptions {
+  updateThreshold: number; // >= this similarity -> update
+  duplicateThreshold: number; // >= this similarity -> skip as duplicate
+}
+
+function assertThreshold(value: number, name: string): void {
+  if (!Number.isFinite(value) || value < 0 || value > 1) {
+    throw new RangeError(`invalid ${name}: ${value}`);
+  }
+}
+
+/** Total order: similarity desc, then updatedAt desc, then id asc. NaN times sort last. */
+function compareCandidates(a: MergeCandidate, b: MergeCandidate): number {
+  if (a.similarity !== b.similarity) return b.similarity - a.similarity;
+  // Date.parse never throws; unparseable timestamps yield NaN and sort last.
+  // NaN !== NaN, so the two sides must be classified as a pair: testing each
+  // independently returned 1 for BOTH orderings when both were unparseable,
+  // which breaks antisymmetry and made the winner depend on array order.
+  const aTime = Date.parse(a.updatedAt);
+  const bTime = Date.parse(b.updatedAt);
+  const aUnparseable = Number.isNaN(aTime);
+  const bUnparseable = Number.isNaN(bTime);
+  if (aUnparseable !== bUnparseable) return aUnparseable ? 1 : -1;
+  if (!aUnparseable && aTime !== bTime) return bTime - aTime;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+export function decideMergeOnWrite(
+  candidates: readonly MergeCandidate[],
+  options: MergeDecisionOptions,
+): MergeDecision {
+  assertThreshold(options.updateThreshold, "updateThreshold");
+  assertThreshold(options.duplicateThreshold, "duplicateThreshold");
+  if (options.duplicateThreshold < options.updateThreshold) {
+    throw new RangeError(
+      `duplicateThreshold ${options.duplicateThreshold} < updateThreshold ${options.updateThreshold}`,
+    );
+  }
+
+  const valid = candidates.filter(
+    (c) =>
+      typeof c.id === "string" &&
+      c.id.trim() !== "" &&
+      typeof c.similarity === "number" &&
+      Number.isFinite(c.similarity) &&
+      c.similarity >= 0 &&
+      c.similarity <= 1,
+  );
+  if (valid.length === 0) return { action: "create" };
+
+  const best = valid.reduce((acc, c) => (compareCandidates(c, acc) < 0 ? c : acc));
+
+  if (best.similarity >= options.duplicateThreshold) {
+    return { action: "skip", reason: "duplicate" };
+  }
+  if (best.similarity >= options.updateThreshold) {
+    return { action: "update", targetId: best.id };
+  }
+  return { action: "create" };
+}

package/src/lcm/engine.ts

@@ -12,6 +12,7 @@ import { LcmWorkQueue, type LcmObserveMessage } from "./queue.js";
 import type { PluginConfig } from "../types.js";
 import { estimateTokenCount } from "../token-estimate.js";
 import { log } from "../logger.js";
+import { nativeBindingRecoveryHint } from "../native-binding-hint.js";
 export interface LcmEngineConfig {
   enabled: boolean;
   leafBatchSize: number;
@@ -225,7 +226,9 @@ export class LcmEngine {
       })
       .catch((err) => {
         if (this.closed) return;
-        log.error(`LCM observe enqueue initialization error: ${err}`);
+        log.error(
+          `LCM observe enqueue initialization error: ${err}${nativeBindingRecoveryHint(err)}`,
+        );
       })
       .finally(() => {
         this.releasePendingObserveInit(normalizedSessionId);

package/src/native-binding-hint.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isNativeBindingError, nativeBindingRecoveryHint } from "./native-binding-hint.js";
+
+test("recognizes the bindings-resolution failure operators actually see", () => {
+  const error = new Error(
+    "Could not locate the bindings file. Tried:\n → .../better-sqlite3/build/Release/better_sqlite3.node",
+  );
+  assert.equal(isNativeBindingError(error), true);
+  const hint = nativeBindingRecoveryHint(error);
+  assert.match(hint, /npm rebuild better-sqlite3 --build-from-source/);
+  assert.match(hint, new RegExp(`ABI ${process.versions.modules}\\b`));
+  assert.match(hint, new RegExp(`Node ${process.versions.node.split(".")[0]}\\b`));
+});
+
+test("recognizes an ABI mismatch reported as NODE_MODULE_VERSION", () => {
+  const error = new Error(
+    "The module was compiled against a different Node.js version using NODE_MODULE_VERSION 127. " +
+      "This version of Node.js requires NODE_MODULE_VERSION 141.",
+  );
+  assert.equal(isNativeBindingError(error), true);
+  assert.match(nativeBindingRecoveryHint(error), /--build-from-source/);
+});
+
+test("an unrelated error yields no hint so its message reads unchanged", () => {
+  const error = new Error("SQLITE_BUSY: database is locked");
+  assert.equal(isNativeBindingError(error), false);
+  assert.equal(nativeBindingRecoveryHint(error), "");
+});
+
+test("non-Error inputs are handled without throwing", () => {
+  assert.equal(isNativeBindingError(undefined), false);
+  assert.equal(isNativeBindingError(null), false);
+  assert.equal(nativeBindingRecoveryHint({}), "");
+  assert.equal(isNativeBindingError("could not locate the bindings file"), true);
+  assert.match(nativeBindingRecoveryHint("invalid ELF header"), /--build-from-source/);
+});

package/src/native-binding-hint.ts

@@ -0,0 +1,51 @@
+/**
+ * Actionable recovery hint for a missing or ABI-mismatched better-sqlite3
+ * native binding (issue #2719).
+ *
+ * `better-sqlite3` publishes prebuilds for LTS Node only, so a newer runtime
+ * installs the package with no loadable binding and every SQLite-backed path
+ * fails with a bindings-resolution error. The raw error names neither the
+ * running ABI nor the command that fixes it, so operators saw only
+ * "Could not locate the bindings file" at first use.
+ *
+ * The repair itself lives in the `@remnic/core` postinstall script — an
+ * OpenClaw plugin package may not ship a child-process-spawning file, so the
+ * host-facing packages surface this hint instead of re-implementing a rebuild.
+ */
+
+/** Substrings that identify a native-binding load failure, lowercased. */
+const BINDING_ERROR_MARKERS = [
+  "could not locate the bindings file",
+  "was compiled against a different node.js version",
+  "node_module_version",
+  "invalid elf header",
+  "better_sqlite3.node",
+];
+
+function messageOf(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  return "";
+}
+
+/** True when the error is a better-sqlite3 native-binding load failure. */
+export function isNativeBindingError(error: unknown): boolean {
+  const message = messageOf(error).toLowerCase();
+  if (message.length === 0) return false;
+  return BINDING_ERROR_MARKERS.some((marker) => message.includes(marker));
+}
+
+/**
+ * Suffix naming the running Node ABI and the exact rebuild command, or an
+ * empty string when the error is unrelated. Callers append it to their own
+ * message so an unrelated failure reads exactly as before.
+ */
+export function nativeBindingRecoveryHint(error: unknown): string {
+  if (!isNativeBindingError(error)) return "";
+  const major = process.versions.node.split(".")[0] ?? process.versions.node;
+  return (
+    ` — better-sqlite3 has no loadable native binding for Node ${major}` +
+    ` (ABI ${process.versions.modules}); rebuild it with` +
+    " `npm rebuild better-sqlite3 --build-from-source`"
+  );
+}