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
29.4 KB
Raw Blame
/**
 * Tension objects: persisted contradiction lifecycle (Belief lifecycle
 * suite, S2, t_0e3f2bee).
 *
 * A detected contradiction is a fleeting finding today - the semantic
 * health detectors surface it and it silently re-fires on the next pass.
 * A tension object gives that finding a durable home: a Markdown note
 * under `Brain/tensions/tension-<slug>.md` whose `_status` walks a small
 * state machine `open -> confirmed | dismissed | resolved`. The slug is
 * derived from a deterministic DEDUP KEY (the subject pair plus the
 * stance signature), so re-detecting the same contradiction UPDATES the
 * existing note in place instead of spawning a duplicate.
 *
 * This module CONSUMES the existing contradiction detector
 * (`health/contradiction.ts` - {@link detectNoteContradictions}); it does
 * not re-implement detection. The dedup key is built purely from
 * structural signals (ids + derived stance signs), so it stays
 * language-agnostic and identical on every Syncthing peer.
 *
 * Injection-time warning: {@link tensionWarningsForContextItems} lets the
 * context-pack builder flag when it is about to inject a memory that is a
 * subject of an UNRESOLVED (open or confirmed) tension. Dismissed and
 * resolved tensions warn about nothing.
 *
 * Import direction: this module imports from health/contradiction /
 * paths / log / vault helpers, never the reverse.
 */

import { createHash } from "node:crypto";

import { normalizeAgentArgument } from "../agent-identity.ts";
import { resolveAgentName } from "../config.ts";
import { sanitiseTextField } from "../redactor.ts";
import { strictestVisibility } from "../graph/visibility.ts";
import { remoteDenyVisibilityTokens } from "../graph/privacy-markers.ts";
import type { FrontmatterMap } from "../types.ts";
import { parseFrontmatter } from "../vault.ts";
import {
  detectNoteContradictions,
  type DetectNoteContradictionsOptions,
  type NoteContradictionFinding,
  type NoteForContradiction,
} from "./health/contradiction.ts";
import { appendLogEvent } from "./log.ts";
import { withOperationPrivacy } from "../store/operation-scope.ts";
import { isPrivateFrontmatter } from "../store/private-page.ts";
import { buildNoteWalkRules, resolveNoteRoots, walkMarkdownFiles } from "./notes/note-walk.ts";
import { tensionPath, tensionsDir } from "./paths.ts";
import { BRAIN_HEALTH_DEFAULTS } from "./policy.ts";
import { isoSecond } from "./time.ts";
import { BRAIN_LOG_EVENT_KIND, type BrainSignalSign } from "./types.ts";
import {
  assertLaneWrite,
  laneEntryInPrivate,
  lanePageExists,
  listLaneFiles,
  parseLanePage,
  writeLaneText,
} from "../store/lane-pages.ts";

// ----- Constants ------------------------------------------------------------

/** Frontmatter `type` discriminator carried by every tension note. */
export const TENSION_TYPE = "tension";
/** On-disk frontmatter key holding a tension's lifecycle status. */
export const TENSION_STATUS_KEY = "_status";
/** Cap on the operator-supplied resolution/dismiss reason. */
const REASON_MAX_LEN = 512;
/** Cap on a quoted subject-bearing span stored in the note body. */
const QUOTE_MAX_LEN = 512;
/** Length of the dedup-hash suffix appended to the readable slug stem. */
const DEDUP_HASH_LEN = 12;
/** Readable-stem cap so the composed slug stays a sane filename length. */
const SLUG_STEM_MAX_LEN = 48;
/**
 * Byte cap for a note read during a vault scan. Files over the cap are
 * skipped (and not counted as scanned), matching the open-loop scanner's
 * 1 MiB ceiling so one pathological file cannot stall detection.
 */
const NOTE_SCAN_MAX_BYTES = 1024 * 1024;

/** The lifecycle states a tension can occupy. */
export const TENSION_STATUS = {
  open: "open",
  confirmed: "confirmed",
  dismissed: "dismissed",
  resolved: "resolved",
} as const;
export type TensionStatus = (typeof TENSION_STATUS)[keyof typeof TENSION_STATUS];

/**
 * The states in which a tension still demands attention. Only these
 * produce an injection-time warning; dismissed and resolved are terminal
 * and silent.
 */
export const TENSION_UNRESOLVED_STATUSES: ReadonlySet<TensionStatus> = new Set([
  TENSION_STATUS.open,
  TENSION_STATUS.confirmed,
]);

/** The three operator transition verbs. */
export const TENSION_TRANSITION = {
  confirm: "confirm",
  dismiss: "dismiss",
  resolve: "resolve",
} as const;
export type TensionTransition = (typeof TENSION_TRANSITION)[keyof typeof TENSION_TRANSITION];

/**
 * The state machine: each transition maps to its resulting status and the
 * set of source states it is legal from. Any transition whose current
 * status is not in `from` raises {@link TensionError}.
 */
const TRANSITIONS: Readonly<
  Record<
    TensionTransition,
    { readonly to: TensionStatus; readonly from: ReadonlySet<TensionStatus> }
  >
> = {
  confirm: { to: TENSION_STATUS.confirmed, from: new Set([TENSION_STATUS.open]) },
  dismiss: {
    to: TENSION_STATUS.dismissed,
    from: new Set([TENSION_STATUS.open, TENSION_STATUS.confirmed]),
  },
  resolve: {
    to: TENSION_STATUS.resolved,
    from: new Set([TENSION_STATUS.open, TENSION_STATUS.confirmed]),
  },
};

// ----- Errors ---------------------------------------------------------------

/** Every failure path in this module raises this typed error. */
export class TensionError extends Error {
  constructor(message: string, options?: ErrorOptions) {
    super(message, options);
    this.name = "TensionError";
  }
}

// ----- Shapes ---------------------------------------------------------------

export interface TensionRecord {
  readonly slug: string;
  /** Filename basename without `.md`. Equals `tension-<slug>`. */
  readonly id: string;
  readonly type: typeof TENSION_TYPE;
  readonly status: TensionStatus;
  /** Lower-sorted subject id of the contradicting pair. */
  readonly subjectA: string;
  /** Higher-sorted subject id of the contradicting pair. */
  readonly subjectB: string;
  /** Sorted shared subject tokens, space-joined, for display. */
  readonly subject: string;
  /** Derived stance of {@link subjectA}. */
  readonly stanceA: BrainSignalSign;
  /** Derived stance of {@link subjectB}. */
  readonly stanceB: BrainSignalSign;
  /** Prose token overlap that put the pair over the detector threshold. */
  readonly jaccard: number;
  /** Deterministic dedup key (subject pair + stance signature). */
  readonly dedupKey: string;
  /** How many times this contradiction has been detected. */
  readonly detectedCount: number;
  readonly createdAt: string;
  /** ISO second of the most recent detection. */
  readonly detectedAt: string;
  /** ISO second of the most recent status transition, or null. */
  readonly statusChangedAt: string | null;
  /** Operator reason recorded on dismiss/resolve, or null. */
  readonly resolutionReason: string | null;
  readonly agent: string;
  /** Subject-bearing span quoted from {@link subjectA}. */
  readonly quoteA: string;
  /** Subject-bearing span quoted from {@link subjectB}. */
  readonly quoteB: string;
  /**
   * The `visibility:` tokens the tension page carries: the stricter of
   * its two source notes' ({@link strictestVisibility}), so a page that
   * quotes a note is read under that note's rule. Empty is default
   * visibility.
   */
  readonly visibility: ReadonlyArray<string>;
  readonly path: string;
}

export interface PersistTensionOptions {
  readonly agent?: string;
  readonly now?: Date;
  readonly configPath?: string;
  /**
   * The `visibility:` tokens to stamp on the page, normally the stricter
   * of the two source notes'. Absent, a new page carries none and a
   * refreshed page keeps what it had.
   */
  readonly visibility?: ReadonlyArray<string>;
}

export interface PersistTensionResult {
  readonly record: TensionRecord;
  /** False when an existing tension for this dedup key was refreshed. */
  readonly created: boolean;
}

export interface DetectTensionsOptions extends DetectNoteContradictionsOptions {
  readonly agent?: string;
  readonly now?: Date;
  readonly configPath?: string;
  /**
   * The `visibility:` tokens of the source note with this id. Each
   * persisted tension carries the stricter of its two subjects'. Absent,
   * no tension page carries any.
   */
  readonly visibilityOf?: (id: string) => ReadonlyArray<string>;
}

export interface DetectTensionsResult {
  readonly records: ReadonlyArray<TensionRecord>;
  /** How many tensions were newly created this run. */
  readonly created: number;
  /** How many existing tensions were refreshed this run. */
  readonly updated: number;
}

export interface TransitionOptions {
  readonly reason?: string;
  readonly agent?: string;
  readonly now?: Date;
  readonly configPath?: string;
}

// ----- Dedup key + slug -----------------------------------------------------

/**
 * Canonicalise a finding into `{ idLow, idHigh, signLow, signHigh, ... }`
 * with the pair ordered by id, so the two orderings of one contradiction
 * yield one identity. Stances travel with their id under the sort.
 */
function canonicalPair(finding: NoteContradictionFinding): {
  idLow: string;
  idHigh: string;
  signLow: BrainSignalSign;
  signHigh: BrainSignalSign;
  quoteLow: string;
  quoteHigh: string;
} {
  const aFirst = finding.aId <= finding.bId;
  return aFirst
    ? {
        idLow: finding.aId,
        idHigh: finding.bId,
        signLow: finding.aSign,
        signHigh: finding.bSign,
        quoteLow: finding.aQuote,
        quoteHigh: finding.bQuote,
      }
    : {
        idLow: finding.bId,
        idHigh: finding.aId,
        signLow: finding.bSign,
        signHigh: finding.aSign,
        quoteLow: finding.bQuote,
        quoteHigh: finding.aQuote,
      };
}

/**
 * Deterministic dedup key: the id-sorted subject pair joined with the
 * stance signature. Two detections of the same pair with the same stances
 * collapse onto one key; a stance flip produces a distinct key (and note),
 * because the belief at stake genuinely changed.
 */
export function tensionDedupKey(finding: NoteContradictionFinding): string {
  const { idLow, idHigh, signLow, signHigh } = canonicalPair(finding);
  return `${idLow} ${idHigh} ${signLow}-${signHigh}`;
}

/**
 * Filesystem-safe slug for a dedup key: a readable stem (the sorted id
 * pair) plus a short sha256 suffix of the full key. The suffix guarantees
 * uniqueness (so two pairs whose stems collide after truncation stay
 * distinct) and stance-sensitivity, while staying deterministic across
 * peers.
 */
function tensionSlug(finding: NoteContradictionFinding): string {
  const { idLow, idHigh } = canonicalPair(finding);
  const dedupKey = tensionDedupKey(finding);
  const stem = `${stripId(idLow)}-${stripId(idHigh)}`
    .replace(/[^a-z0-9]+/gu, "-")
    .replace(/^-+|-+$/gu, "")
    .slice(0, SLUG_STEM_MAX_LEN)
    .replace(/-+$/gu, "");
  const hash = createHash("sha256").update(dedupKey, "utf8").digest("hex").slice(0, DEDUP_HASH_LEN);
  return stem ? `${stem}-${hash}` : hash;
}

/** Lowercase an id for the readable slug stem (structural, not semantic). */
function stripId(id: string): string {
  return id.trim().toLowerCase();
}

// ----- (De)serialization ----------------------------------------------------

function render(record: Omit<TensionRecord, "path">): string {
  const lines = [
    "---",
    `type: ${TENSION_TYPE}`,
    `id: ${record.id}`,
    `${TENSION_STATUS_KEY}: ${record.status}`,
    `subject_a: ${record.subjectA}`,
    `subject_b: ${record.subjectB}`,
    `subject: ${JSON.stringify(record.subject)}`,
    `stance_a: ${record.stanceA}`,
    `stance_b: ${record.stanceB}`,
    `jaccard: ${record.jaccard}`,
    `dedup_key: ${JSON.stringify(record.dedupKey)}`,
    `detected_count: ${record.detectedCount}`,
    `created_at: ${record.createdAt}`,
    `detected_at: ${record.detectedAt}`,
  ];
  if (record.statusChangedAt !== null) lines.push(`status_changed_at: ${record.statusChangedAt}`);
  if (record.resolutionReason !== null) {
    lines.push(`resolution_reason: ${JSON.stringify(record.resolutionReason)}`);
  }
  lines.push(`agent: ${JSON.stringify(record.agent)}`);
  if (record.visibility.length > 0) {
    lines.push(`visibility: [${record.visibility.map((t) => JSON.stringify(t)).join(", ")}]`);
  }
  lines.push("---", "");
  lines.push(`- ${record.subjectA}: ${record.quoteA}`);
  lines.push(`- ${record.subjectB}: ${record.quoteB}`);
  lines.push("");
  return lines.join("\n");
}

function coerceStatus(value: unknown): TensionStatus {
  if (
    typeof value === "string" &&
    (Object.values(TENSION_STATUS) as ReadonlyArray<string>).includes(value)
  ) {
    return value as TensionStatus;
  }
  // A hand-edit that corrupts the status reads as `open` (the safe,
  // still-demands-attention default) rather than silently vanishing.
  return TENSION_STATUS.open;
}

function coerceSign(value: unknown): BrainSignalSign {
  return value === "negative" ? "negative" : "positive";
}

function scalarString(meta: Readonly<Record<string, unknown>>, key: string): string {
  const value = meta[key];
  return typeof value === "string" ? value : "";
}

function parsePage(vault: string, slug: string): TensionRecord | null {
  const path = tensionPath(vault, slug);
  if (!lanePageExists(vault, path)) return null;
  const [meta, body] = parseLanePage(vault, path);
  if (meta["type"] !== TENSION_TYPE) return null;
  const statusChangedRaw = scalarString(meta, "status_changed_at");
  const reasonRaw = scalarString(meta, "resolution_reason");
  const detectedCount = Number(meta["detected_count"]);
  const jaccard = Number(meta["jaccard"]);
  // Body carries the two quote bullets; parse them back for round-trip.
  const quotes = parseQuoteBody(body);
  const subjectA = scalarString(meta, "subject_a");
  const subjectB = scalarString(meta, "subject_b");
  return Object.freeze({
    slug,
    id: `tension-${slug}`,
    type: TENSION_TYPE,
    status: coerceStatus(meta[TENSION_STATUS_KEY]),
    subjectA,
    subjectB,
    subject: scalarString(meta, "subject"),
    stanceA: coerceSign(meta["stance_a"]),
    stanceB: coerceSign(meta["stance_b"]),
    jaccard: Number.isFinite(jaccard) ? jaccard : 0,
    dedupKey: scalarString(meta, "dedup_key"),
    detectedCount: Number.isInteger(detectedCount) && detectedCount > 0 ? detectedCount : 1,
    createdAt: scalarString(meta, "created_at"),
    detectedAt: scalarString(meta, "detected_at"),
    statusChangedAt: statusChangedRaw.length > 0 ? statusChangedRaw : null,
    resolutionReason: reasonRaw.length > 0 ? reasonRaw : null,
    agent: scalarString(meta, "agent"),
    quoteA: quotes.get(subjectA) ?? "",
    quoteB: quotes.get(subjectB) ?? "",
    // The declared tokens and an informal privacy marker's reservation
    // (`access: private`, a hand edit): the verdict of a transition and
    // the page it renders both keep a reservation however it was spelled.
    visibility: remoteDenyVisibilityTokens(meta),
    path,
  });
}

/** Parse the `- <id>: <quote>` body bullets back into a per-id map. */
function parseQuoteBody(body: string): Map<string, string> {
  const out = new Map<string, string>();
  for (const line of body.split("\n")) {
    const m = /^-\s+([^:]+):\s*(.*)$/u.exec(line.trim());
    if (m) out.set(m[1]!.trim(), m[2]!.trim());
  }
  return out;
}

// ----- Agent + reason helpers -----------------------------------------------

function resolveAgent(explicit: string | undefined, configPath: string | undefined): string {
  return normalizeAgentArgument(explicit ?? null) ?? resolveAgentName(configPath);
}

function cleanReason(reason: string | undefined): string | null {
  if (reason === undefined) return null;
  const cleaned = sanitiseTextField(reason, { maxLen: REASON_MAX_LEN, singleLine: true }).trim();
  return cleaned.length > 0 ? cleaned : null;
}

function cleanQuote(quote: string): string {
  return sanitiseTextField(quote, { maxLen: QUOTE_MAX_LEN, singleLine: true }).trim();
}

// ----- Persist --------------------------------------------------------------

/**
 * Persist one detected contradiction as a tension note. On first sight of
 * a dedup key this creates an `open` note and logs a `tension` (detected)
 * event; on re-detection it refreshes the existing note (jaccard, quotes,
 * `detected_at`, `detected_count`) WITHOUT touching its `_status`,
 * `created_at`, or transition history, and emits nothing.
 */
export function persistTension(
  vault: string,
  finding: NoteContradictionFinding,
  opts: PersistTensionOptions = {},
): PersistTensionResult {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const { idLow, idHigh, signLow, signHigh, quoteLow, quoteHigh } = canonicalPair(finding);
  const slug = tensionSlug(finding);
  const dedupKey = tensionDedupKey(finding);
  const now = opts.now ?? new Date();
  const stampedAt = isoSecond(now);
  const agent = resolveAgent(opts.agent, opts.configPath);

  const prior = parsePage(vault, slug);
  if (prior !== null) {
    // Idempotent refresh: bump detection bookkeeping, preserve lifecycle.
    const next: Omit<TensionRecord, "path"> = {
      ...prior,
      subject: finding.subject,
      stanceA: signLow,
      stanceB: signHigh,
      jaccard: finding.jaccard,
      dedupKey,
      detectedCount: prior.detectedCount + 1,
      detectedAt: stampedAt,
      quoteA: cleanQuote(quoteLow),
      quoteB: cleanQuote(quoteHigh),
      // A re-detection never lowers the page's own reservation.
      visibility:
        opts.visibility === undefined
          ? prior.visibility
          : strictestVisibility(opts.visibility, prior.visibility),
    };
    writeLaneText(vault, prior.path, render(next));
    return { record: Object.freeze({ ...next, path: prior.path }), created: false };
  }

  const record: Omit<TensionRecord, "path"> = {
    slug,
    id: `tension-${slug}`,
    type: TENSION_TYPE,
    status: TENSION_STATUS.open,
    subjectA: idLow,
    subjectB: idHigh,
    subject: finding.subject,
    stanceA: signLow,
    stanceB: signHigh,
    jaccard: finding.jaccard,
    dedupKey,
    detectedCount: 1,
    createdAt: stampedAt,
    detectedAt: stampedAt,
    statusChangedAt: null,
    resolutionReason: null,
    agent,
    quoteA: cleanQuote(quoteLow),
    quoteB: cleanQuote(quoteHigh),
    visibility: opts.visibility ?? [],
  };

  const path = tensionPath(vault, slug);
  // One operation, one verdict: the page and its log event go to the
  // partition the page's visibility decides. Once switched there is no
  // page file for the event's `[[tension-...]]` link to be judged by.
  withOperationPrivacy(tensionIsPrivate(record), () => {
    writeLaneText(vault, path, render(record));
    appendLogEvent(vault, {
      timestamp: stampedAt,
      eventType: BRAIN_LOG_EVENT_KIND.tension,
      body: {
        tension: `[[${record.id}]]`,
        action: "detected",
        status: record.status,
        subject_a: idLow,
        subject_b: idHigh,
        agent,
      },
    });
  });

  return { record: Object.freeze({ ...record, path }), created: true };
}

/**
 * Run the note contradiction detector over `notes` and persist every
 * finding as a tension. Consumes {@link detectNoteContradictions}; does
 * not re-implement detection. Returns the persisted records plus how many
 * were created vs refreshed.
 */
export function detectTensions(
  vault: string,
  notes: ReadonlyArray<NoteForContradiction>,
  opts: DetectTensionsOptions,
): DetectTensionsResult {
  const findings = detectNoteContradictions(notes, {
    jaccard: opts.jaccard,
    ...(opts.negationMarkers !== undefined ? { negationMarkers: opts.negationMarkers } : {}),
  });
  const records: TensionRecord[] = [];
  let created = 0;
  let updated = 0;
  const visibilityOf = opts.visibilityOf;
  for (const finding of findings) {
    const res = persistTension(vault, finding, {
      ...(visibilityOf !== undefined
        ? { visibility: strictestVisibility(visibilityOf(finding.aId), visibilityOf(finding.bId)) }
        : {}),
      ...(opts.agent !== undefined ? { agent: opts.agent } : {}),
      ...(opts.now !== undefined ? { now: opts.now } : {}),
      ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
    });
    records.push(res.record);
    if (res.created) created++;
    else updated++;
  }
  return { records, created, updated };
}

export interface DetectTensionsInVaultOptions {
  /**
   * Explicit note roots to scan. When omitted (or all-blank) the roots
   * come from `notes.read_paths` in `Brain/_brain.yaml`; a vault with no
   * configured read paths scans nothing and creates no tensions, so an
   * un-opted-in vault is byte-identical to today.
   */
  readonly paths?: ReadonlyArray<string>;
  /**
   * Minimum prose jaccard for two notes to count as the same subject.
   * Defaults to the shared health threshold
   * ({@link BRAIN_HEALTH_DEFAULTS.contradiction_jaccard}).
   */
  readonly jaccard?: number;
  readonly negationMarkers?: ReadonlySet<string>;
  readonly agent?: string;
  readonly now?: Date;
  readonly configPath?: string;
  /** Byte cap per scanned file; defaults to {@link NOTE_SCAN_MAX_BYTES}. */
  readonly maxFileSizeBytes?: number;
  /**
   * The vault-relative note paths the caller may read. A note it may not
   * read is skipped before it is opened: it is not counted in
   * `scannedFiles`, takes part in no pair and so names no tension.
   * Absent, every note under the roots is read.
   */
  readonly readable?: (rel: string) => boolean;
}

export interface DetectTensionsInVaultResult extends DetectTensionsResult {
  /** How many note files were read and fed to the detector. */
  readonly scannedFiles: number;
}

/**
 * Production entry point for tension detection: load the configured note
 * corpus (`notes.read_paths`) as prose notes and persist every detected
 * contradiction as a tension. This is the operator-triggerable scan behind
 * the `detect` action on the tension CLI verb and MCP tool; without it the
 * detector ({@link detectTensions}) had no production caller and the
 * operator could never create a tension.
 *
 * Each markdown file under a configured root becomes one
 * {@link NoteForContradiction}: `id` is the frontmatter `id` when present
 * (else the vault-relative path), `subject` is the optional frontmatter
 * `subject` bucket, and `text` is the note body. The Brain machinery root
 * and `vault.ignore_paths` are excluded by the shared note walker.
 */
export function detectTensionsInVault(
  vault: string,
  opts: DetectTensionsInVaultOptions = {},
): DetectTensionsInVaultResult {
  const roots = resolveNoteRoots(vault, opts.paths);
  if (roots.length === 0) return { records: [], created: 0, updated: 0, scannedFiles: 0 };

  const rules = buildNoteWalkRules(vault);
  const cap = opts.maxFileSizeBytes ?? NOTE_SCAN_MAX_BYTES;
  const notes: NoteForContradiction[] = [];
  const visibilityById = new Map<string, ReadonlyArray<string>>();
  for (const file of walkMarkdownFiles(vault, roots, rules, { maxFileSizeBytes: cap })) {
    if (opts.readable !== undefined && !opts.readable(file.relPath)) continue;
    let meta: FrontmatterMap;
    let body: string;
    try {
      [meta, body] = parseFrontmatter(file.absPath);
    } catch {
      continue; // unreadable or malformed frontmatter - skip, do not count
    }
    const rawId = meta["id"];
    const id = typeof rawId === "string" && rawId.trim() !== "" ? rawId.trim() : file.relPath;
    const rawSubject = meta["subject"];
    const subject =
      typeof rawSubject === "string" && rawSubject.trim() !== "" ? rawSubject.trim() : undefined;
    notes.push({ id, ...(subject !== undefined ? { subject } : {}), text: body });
    // Two notes may share a frontmatter id; the id then reads under the
    // stricter of their rules. The fold is the full union, so a note
    // reserving itself under an informal key (`access: private`) reserves
    // every tension page drafted from it, not just a formally declared one.
    visibilityById.set(
      id,
      strictestVisibility(visibilityById.get(id) ?? [], [...remoteDenyVisibilityTokens(meta)]),
    );
  }

  const result = detectTensions(vault, notes, {
    jaccard: opts.jaccard ?? BRAIN_HEALTH_DEFAULTS.contradiction_jaccard,
    visibilityOf: (id) => visibilityById.get(id) ?? [],
    ...(opts.negationMarkers !== undefined ? { negationMarkers: opts.negationMarkers } : {}),
    ...(opts.agent !== undefined ? { agent: opts.agent } : {}),
    ...(opts.now !== undefined ? { now: opts.now } : {}),
    ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
  });
  return { ...result, scannedFiles: notes.length };
}

// ----- Transitions ----------------------------------------------------------

function transition(
  vault: string,
  slug: string,
  verb: TensionTransition,
  opts: TransitionOptions,
): TensionRecord {
  // Vault-identity write guard (context-integrity-gates, Unit J). The
  // page rewrite below precedes `appendLogEvent`, so leaning on that
  // call's guard would land the new status in the wrong store first -
  // the same defect `persistTension` was fixed for.
  assertLaneWrite(vault);
  const prior = parsePage(vault, slug);
  if (prior === null) throw new TensionError(`no tension: ${slug}`);
  const rule = TRANSITIONS[verb];
  if (!rule.from.has(prior.status)) {
    throw new TensionError(
      `invalid tension transition: cannot ${verb} a tension in state '${prior.status}'`,
    );
  }
  const now = opts.now ?? new Date();
  const stampedAt = isoSecond(now);
  const agent = resolveAgent(opts.agent, opts.configPath);
  const reason = cleanReason(opts.reason);

  const next: Omit<TensionRecord, "path"> = {
    ...prior,
    status: rule.to,
    statusChangedAt: stampedAt,
    resolutionReason: reason ?? prior.resolutionReason,
  };
  // The rewrite and its event under one verdict, as on create. A tension
  // private by its partition alone (written inside a private operation,
  // with no `visibility:`) stays private: its event must not reach shared.
  withOperationPrivacy(tensionIsPrivate(prior) || laneEntryInPrivate(vault, prior.path), () => {
    writeLaneText(vault, prior.path, render(next));
    appendLogEvent(vault, {
      timestamp: stampedAt,
      eventType: BRAIN_LOG_EVENT_KIND.tension,
      body: {
        tension: `[[${prior.id}]]`,
        action: verb,
        from: prior.status,
        status: rule.to,
        subject_a: prior.subjectA,
        subject_b: prior.subjectB,
        ...(reason !== null ? { reason } : {}),
        agent,
      },
    });
  });

  return Object.freeze({ ...next, path: prior.path });
}

/** Confirm a tension (`open -> confirmed`). Invalid otherwise. */
export function confirmTension(
  vault: string,
  slug: string,
  opts: TransitionOptions = {},
): TensionRecord {
  return transition(vault, slug, TENSION_TRANSITION.confirm, opts);
}

/** Dismiss a tension (`open | confirmed -> dismissed`). Invalid otherwise. */
export function dismissTension(
  vault: string,
  slug: string,
  opts: TransitionOptions = {},
): TensionRecord {
  return transition(vault, slug, TENSION_TRANSITION.dismiss, opts);
}

/** Resolve a tension (`open | confirmed -> resolved`). Invalid otherwise. */
export function resolveTension(
  vault: string,
  slug: string,
  opts: TransitionOptions = {},
): TensionRecord {
  return transition(vault, slug, TENSION_TRANSITION.resolve, opts);
}

/** Whether a tension's page reserves it (its `visibility:` holds the remote-deny token). */
function tensionIsPrivate(record: Pick<TensionRecord, "visibility">): boolean {
  return isPrivateFrontmatter({ visibility: [...record.visibility] });
}

// ----- Reads ----------------------------------------------------------------

/** One tension, or null. */
export function showTension(vault: string, slug: string): TensionRecord | null {
  return parsePage(vault, slug);
}

/** Every tension, sorted by slug. */
export function listTensions(vault: string): TensionRecord[] {
  // `listLaneFiles` answers [] for a missing folder in both modes.
  const dir = tensionsDir(vault);
  const out: TensionRecord[] = [];
  for (const name of listLaneFiles(vault, dir, "")) {
    if (!name.endsWith(".md") || !name.startsWith("tension-")) continue;
    const slug = name.replace(/^tension-/u, "").replace(/\.md$/u, "");
    const page = parsePage(vault, slug);
    if (page !== null) out.push(page);
  }
  return out.toSorted((a, b) => a.slug.localeCompare(b.slug));
}

/** Every tension still in an unresolved (open or confirmed) state. */
export function listUnresolvedTensions(vault: string): TensionRecord[] {
  return listTensions(vault).filter((t) => TENSION_UNRESOLVED_STATUSES.has(t.status));
}

// ----- Injection-time warnings ----------------------------------------------

/**
 * Warning lines for the context-pack builder: for every UNRESOLVED
 * tension whose subject pair intersects `itemIds`, one line naming the
 * tension and the injected subject(s) it touches. Dismissed and resolved
 * tensions contribute nothing. Returns `[]` when no vault tension matches,
 * so a tension-free vault keeps the pack output byte-identical.
 */
export function tensionWarningsForContextItems(
  vault: string,
  itemIds: ReadonlyArray<string>,
  /**
   * Subject ids the caller may not see. A tension id is derived from both
   * subject ids, so a tension touching one of these is reported without
   * its id - the injected memory is still flagged as contested.
   */
  withheldIds: ReadonlySet<string> = new Set(),
): string[] {
  const ids = new Set(itemIds);
  const out: string[] = [];
  for (const tension of listUnresolvedTensions(vault)) {
    const touched: string[] = [];
    if (ids.has(tension.subjectA)) touched.push(tension.subjectA);
    if (ids.has(tension.subjectB)) touched.push(tension.subjectB);
    if (touched.length === 0) continue;
    const named = !withheldIds.has(tension.subjectA) && !withheldIds.has(tension.subjectB);
    out.push(
      `unresolved tension ${named ? `[[${tension.id}]] ` : ""}(${tension.status}) involves injected memory ` +
        touched.join(", "),
    );
  }
  return out;
}