Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
10.6 KB
Raw Blame
/**
 * A4 (t_f79b4fe0): write-time conflict advisory seam.
 *
 * `adviseIncomingFeedback` loads confirmed same-scope preferences, runs
 * the pure `adviseOnIncoming` kernel, logs a `write-conflict-advisory`
 * event, and returns the advisory (or null). It never throws into the
 * write path: an advisory-computation failure degrades to a warning and a
 * null result while the surrounding write still succeeds.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { brainDirs } from "../../../src/core/brain/paths.ts";
import { writePreference } from "../../../src/core/brain/preference.ts";
import { readAllLogEntries } from "../../../src/core/brain/query.ts";
import { routeExtractedFacts } from "../../../src/core/brain/fact-extract.ts";
import type { DedupIndexEntry } from "../../../src/core/brain/dedup-hash.ts";
import { BRAIN_LOG_EVENT_KIND, BRAIN_PREFERENCE_STATUS } from "../../../src/core/brain/types.ts";
import { adviseIncomingFeedback } from "../../../src/core/brain/write-advisory.ts";
import {
  adviseOnIncoming,
  type PreferenceForContradiction,
} from "../../../src/core/brain/health/contradiction.ts";
import { NEAR_DUPLICATE_MIN_TOKENS } from "../../../src/core/brain/near-duplicate.ts";
import { BRAIN_HEALTH_DEFAULTS } from "../../../src/core/brain/policy.ts";
import { createRouteScope, ROUTE_STAGE } from "../../../src/core/route-scope.ts";

let tmp: string;
let vault: string;

const NOW = new Date("2026-07-18T12:00:00Z");

function confirmPref(slug: string, principle: string, scope?: string): void {
  writePreference(vault, {
    slug,
    topic: slug,
    principle,
    created_at: NOW.toISOString(),
    unconfirmed_until: NOW.toISOString(),
    confirmed_at: NOW.toISOString(),
    status: BRAIN_PREFERENCE_STATUS.confirmed,
    evidenced_by: ["[[sig-2026-07-18-seed]]"],
    ...(scope !== undefined ? { scope } : {}),
  });
}

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-advisory-"));
  vault = join(tmp, "vault");
  const configPath = join(tmp, "config.yaml");
  writeFileSync(configPath, `vault: ${vault}\n`);
  bootstrapBrain(vault, { configPath });
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
});

describe("adviseIncomingFeedback", () => {
  test("returns an advisory naming a conflicting confirmed same-scope preference", () => {
    confirmPref("tabs", "always indent source with tabs not spaces", "coding");
    const advisory = adviseIncomingFeedback(vault, {
      principle: "always indent source with tabs not spaces",
      scope: "coding",
      agent: "test-agent",
      now: NOW,
    });
    expect(advisory).not.toBeNull();
    expect(advisory!.scope).toBe("coding");
    expect(advisory!.conflicts.map((c) => c.pref_id)).toEqual(["pref-tabs"]);
    expect(advisory!.conflicts[0]!.jaccard).toBeGreaterThanOrEqual(0.5);
  });

  test("returns null for a non-conflicting incoming principle", () => {
    confirmPref("tabs", "always indent source with tabs not spaces", "coding");
    const advisory = adviseIncomingFeedback(vault, {
      principle: "prefer semantic HTML over generic containers",
      scope: "coding",
      agent: "test-agent",
      now: NOW,
    });
    expect(advisory).toBeNull();
  });

  test("does not fire across scopes", () => {
    confirmPref("tabs", "always indent source with tabs not spaces", "coding");
    const advisory = adviseIncomingFeedback(vault, {
      principle: "always indent source with tabs not spaces",
      scope: "writing",
      agent: "test-agent",
      now: NOW,
    });
    expect(advisory).toBeNull();
  });

  test("logs a write-conflict-advisory event when it fires", () => {
    confirmPref("tabs", "always indent source with tabs not spaces", "coding");
    adviseIncomingFeedback(vault, {
      principle: "always indent source with tabs not spaces",
      scope: "coding",
      agent: "test-agent",
      now: NOW,
    });
    const entries = readAllLogEntries(vault);
    const advisoryEvents = entries.filter(
      (e) => e.eventType === BRAIN_LOG_EVENT_KIND.writeConflictAdvisory,
    );
    expect(advisoryEvents.length).toBe(1);
    const conflicts = advisoryEvents[0]!.body["conflicts"];
    expect(Array.isArray(conflicts)).toBe(true);
    expect((conflicts as ReadonlyArray<string>)[0]).toContain("[[pref-tabs]]");
  });

  test("degrades to a warning (returns null) when the preferences dir is unreadable", () => {
    // Replace the preferences directory with a FILE so readdirSync throws
    // ENOTDIR: the advisory computation must swallow the failure into a
    // warning and return null, never propagate an exception.
    const prefsDir = brainDirs(vault).preferences;
    rmSync(prefsDir, { recursive: true, force: true });
    writeFileSync(prefsDir, "not a directory");
    // Capture stderr so we can assert the degradation is VISIBLE, not a
    // silently-swallowed failure.
    const originalStderrWrite = process.stderr.write.bind(process.stderr);
    let captured = "";
    process.stderr.write = ((chunk: string | Uint8Array): boolean => {
      captured += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
      return true;
    }) as typeof process.stderr.write;
    try {
      const advisory = adviseIncomingFeedback(vault, {
        principle: "always indent source with tabs not spaces",
        scope: "coding",
        agent: "test-agent",
        now: NOW,
      });
      expect(advisory).toBeNull();
      expect(captured).toContain("write-conflict advisory computation failed");
    } finally {
      process.stderr.write = originalStderrWrite;
    }
  });

  test("the extracted-fact path never fires the advisory (no double-fire)", () => {
    // A confirmed preference exists that an extracted fact could resemble,
    // but routeExtractedFacts must NOT compute the advisory - it attaches
    // to the operator-facing feedback path only.
    confirmPref("url", "https://techmeat.dev", "coding");
    routeExtractedFacts(vault, {
      facts: [{ family: "url", text: "https://techmeat.dev", line: 1 }],
      agent: "claude-dev-agent",
      now: NOW,
      sessionRef: "s#1",
      dedup: new Map<string, DedupIndexEntry>(),
    });
    const advisoryEvents = readAllLogEntries(vault).filter(
      (e) => e.eventType === BRAIN_LOG_EVENT_KIND.writeConflictAdvisory,
    );
    expect(advisoryEvents.length).toBe(0);
  });
});

/** A confirmed `coding` preference as `adviseOnIncoming` reads it. */
function codingPref(id: string, principle: string): PreferenceForContradiction {
  return {
    id,
    principle,
    status: BRAIN_PREFERENCE_STATUS.confirmed,
    scope: "coding",
    evidenced_by: [],
  };
}

/**
 * The advisory scores through the shared near-duplicate kernel. Its output
 * and its log line stay what they were, the threshold still comes from the
 * operator-configurable health default, and the one allowed change is that
 * a principle under the kernel's minimum token count no longer advises.
 */
describe("adviseIncomingFeedback - scored through the shared kernel", () => {
  const PRINCIPLE = "always indent source with tabs not spaces";

  test("the advisory and its log line are byte-identical to the shipped shape", () => {
    confirmPref("tabs", PRINCIPLE, "coding");
    const advisory = adviseIncomingFeedback(vault, {
      principle: PRINCIPLE,
      scope: "coding",
      agent: "test-agent",
      now: NOW,
    });
    expect(advisory).toEqual({
      scope: "coding",
      conflicts: [{ pref_id: "pref-tabs", jaccard: 1 }],
    });
    const events = readAllLogEntries(vault).filter(
      (e) => e.eventType === BRAIN_LOG_EVENT_KIND.writeConflictAdvisory,
    );
    expect(events.map((e) => e.body)).toEqual([
      {
        scope: "coding",
        conflicts: ["[[pref-tabs]] jaccard=1.000"],
        agent: "test-agent",
        origin_channel: "unset",
      },
    ]);
  });

  test("an unscoped principle compares against the unscoped bucket only", () => {
    confirmPref("tabs", PRINCIPLE);
    confirmPref("scoped", PRINCIPLE, "coding");
    const advisory = adviseIncomingFeedback(vault, { principle: PRINCIPLE, agent: "a", now: NOW });
    expect(advisory).toEqual({ scope: null, conflicts: [{ pref_id: "pref-tabs", jaccard: 1 }] });
  });

  test("the threshold is the health default, inclusive", () => {
    const threshold = BRAIN_HEALTH_DEFAULTS.contradiction_jaccard;
    expect(threshold).toBe(0.5);
    // 4 shared tokens over an 8-token union is exactly 0.5.
    const at = adviseOnIncoming("alpha bravo charlie delta echo foxtrot", "coding", [
      codingPref("pref-at", "alpha bravo charlie delta golf hotel"),
      // 3 shared over 9 is below the bar.
      codingPref("pref-below", "alpha bravo charlie golf hotel india"),
    ]);
    expect(at).toEqual({ scope: "coding", conflicts: [{ prefId: "pref-at", jaccard: 0.5 }] });
  });

  test("a principle under the kernel's minimum token count no longer advises", () => {
    const short = "use tabs always";
    expect(short.split(" ").length).toBeLessThan(NEAR_DUPLICATE_MIN_TOKENS);
    confirmPref("short", short, "coding");
    const advisory = adviseIncomingFeedback(vault, {
      principle: short,
      scope: "coding",
      agent: "test-agent",
      now: NOW,
    });
    expect(advisory).toBeNull();
    expect(
      readAllLogEntries(vault).filter(
        (e) => e.eventType === BRAIN_LOG_EVENT_KIND.writeConflictAdvisory,
      ),
    ).toEqual([]);
  });
});

describe("adviseIncomingFeedback - stage timing", () => {
  test("a feedback advisory records near_duplicate_lookup in the open route scope", async () => {
    confirmPref("tabs", "always indent source with tabs not spaces", "coding");
    const scope = createRouteScope();
    await scope.run(async () =>
      adviseIncomingFeedback(vault, {
        principle: "always indent source with tabs not spaces",
        scope: "coding",
        agent: "test-agent",
        now: NOW,
      }),
    );
    const stage = scope.stages()?.find((s) => s.name === ROUTE_STAGE.nearDuplicateLookup);
    expect(stage).toBeDefined();
    expect(Number.isFinite(stage!.ms)).toBe(true);
    expect(stage!.ms).toBeGreaterThanOrEqual(0);
  });

  test("with no scope open the advisory is unchanged", () => {
    confirmPref("tabs", "always indent source with tabs not spaces", "coding");
    const advisory = adviseIncomingFeedback(vault, {
      principle: "always indent source with tabs not spaces",
      scope: "coding",
      agent: "test-agent",
      now: NOW,
    });
    expect(advisory).toEqual({
      scope: "coding",
      conflicts: [{ pref_id: "pref-tabs", jaccard: 1 }],
    });
  });
});