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
20.6 KB
Raw Blame
/**
 * One-shot design notes (salience-lifecycle-enrichment, unit 7,
 * t_c87644b4).
 *
 * `o2b brain panel` already deliberates: it opens a durable write session,
 * walks personas over several turns, and commits under
 * `Brain/decisions/panels/`. That is the right shape when a decision is
 * worth several rounds, and the wrong one when somebody wants a design note
 * now. This module is the one-shot sibling, built like `diarization.ts`:
 * read-only grounding, no session, no model, and exactly one
 * needs-llm-step envelope handed back to the caller.
 *
 * What "grounded" means here is the whole point. A design note written from
 * nothing is prose; this one is written from three vault stores that
 * already know what the project has argued about, decided, and asserted:
 *
 *   - TENSIONS - the contradictions the vault has materialized and, in
 *     particular, the ones nobody has resolved.
 *   - DECISIONS - what was chosen before on a similar question, and how it
 *     turned out.
 *   - TRUTH - the claim-ledger projection: what is currently asserted about
 *     the entities in play, and which of those slots are contested.
 *
 * Matching is the vault's own deterministic token overlap - `tokenise` and
 * `jaccard` from `similarity.ts`, the same pair `findSimilarDecisions`
 * ranks with - so a topic reaches the same records from every surface and
 * no model is consulted to decide relevance.
 *
 * An EMPTY store is not a failure and not an absence: it is named. A vault
 * with no decisions yet and a vault whose decisions all missed the topic
 * are different answers to "what grounds this note", and a report that
 * rendered both as an empty list would be the misleading silence this
 * project forbids.
 *
 * The payload contract is one recommendation. A design note listing three
 * alternatives and recommending none has not been written yet, and one
 * recommending two has not been decided; both are refused by the semantic
 * check, which states the count it found.
 */

import { join, posix } from "node:path";

import { slugify } from "../vault.ts";
import {
  DECISION_SIMILARITY_THRESHOLD,
  findSimilarDecisions,
  listDecisions,
} from "./decisions/record.ts";
import { buildNeedsLlmStep, type NeedsLlmStep } from "./llm-step.ts";
import {
  buildLinkCandidateManifest,
  linkCandidateSchemaHint,
  type LinkCandidateManifest,
} from "./notes/link-candidates.ts";
import { ownerScopeView } from "./owner-scope-view.ts";
import { BRAIN_TENSIONS_REL, decisionsDir } from "./paths.ts";
import {
  assertResponseCheck,
  registerResponseCheck,
  SEMANTIC_VIOLATION_CODES,
  semanticViolation,
  type SemanticViolation,
} from "./response-checks.ts";
import {
  assertResponseShape,
  DESIGN_NOTE_SHAPE,
  DESIGN_NOTE_SURFACE,
  SHAPE_ROOT_PATH,
} from "./response-shape.ts";
import { jaccard, tokenise } from "./similarity.ts";
import { isoDate } from "./time.ts";
import { listTensions, TENSION_UNRESOLVED_STATUSES, type TensionRecord } from "./tensions.ts";
import { readTruthState } from "./truth/store.ts";
import type { ClaimSlot, TruthConflict } from "./truth/types.ts";
import { assertLaneWrite, writeLanePage } from "../store/lane-pages.ts";

/** Vault-relative directory a committed design note lands in. */
export const DESIGN_NOTE_DIR_REL = "Brain/decisions";

/** The needs-llm-step step name for the deferred design note. */
export const DESIGN_NOTE_STEP = "design-note";

/** Frontmatter discriminator of a committed design note. */
export const DESIGN_NOTE_KIND = "brain-design-note";

/**
 * Token-overlap floor a record must clear to ground the note. The decision
 * store's own floor is reused for all three stores rather than three
 * numbers being picked: a topic that reaches a decision should reach the
 * tension arguing about the same words, and a second threshold would make
 * "related" mean two things in one report.
 */
export const DESIGN_NOTE_MATCH_THRESHOLD = DECISION_SIMILARITY_THRESHOLD;

/** Most records per store the grounding carries into one prompt. */
export const DESIGN_NOTE_PER_STORE_LIMIT = 10;

/**
 * The three grounding stores, named so an empty one can be reported as
 * itself. "The decision store is empty" and "no decision matched" are
 * different facts about the vault and lead to different next moves.
 */
export const DESIGN_NOTE_STORE = Object.freeze({
  tensions: "tensions",
  decisions: "decisions",
  truth: "truth",
} as const);

export type DesignNoteStore = (typeof DESIGN_NOTE_STORE)[keyof typeof DESIGN_NOTE_STORE];

/** A design note could not be produced, and the reason is in the message. */
export class DesignNoteError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "DesignNoteError";
  }
}

/** One tension the topic reaches. */
export interface GroundedTension {
  readonly id: string;
  readonly slug: string;
  readonly subject: string;
  readonly status: string;
  /** True while the tension is open or confirmed - nobody has settled it. */
  readonly unresolved: boolean;
  readonly jaccard: number;
}

/** One prior decision the topic reaches, with how it turned out. */
export interface GroundedDecision {
  readonly id: string;
  readonly slug: string;
  readonly title: string;
  readonly chosen: string;
  /** Hindsight outcome; empty until a backfill records one. */
  readonly outcome: string;
  readonly jaccard: number;
}

/** One claim slot the topic reaches. */
export interface GroundedClaim {
  readonly entity: string;
  readonly aspect: string;
  readonly value: string;
  /** True when an unresolved conflict involves this slot. */
  readonly contested: boolean;
  readonly jaccard: number;
}

/** One materialized contradiction in the claim ledger. */
export interface GroundedConflict {
  readonly entity: string;
  readonly aspect: string;
  readonly values: ReadonlyArray<string>;
}

export interface DesignNoteGrounding {
  readonly topic: string;
  readonly tensions: ReadonlyArray<GroundedTension>;
  readonly decisions: ReadonlyArray<GroundedDecision>;
  readonly truthSlots: ReadonlyArray<GroundedClaim>;
  readonly conflicts: ReadonlyArray<GroundedConflict>;
  readonly counts: {
    readonly tensions: number;
    readonly decisions: number;
    readonly truthSlots: number;
    readonly conflicts: number;
  };
  /**
   * Stores that hold NOTHING AT ALL in this vault, named. A store absent
   * from this list held records and simply matched none of them.
   */
  readonly emptyStores: ReadonlyArray<DesignNoteStore>;
}

/**
 * The one deferred generation step: the shared spine plus the wikilink
 * targets the note may cite. A design note grounded in named records is
 * the case the manifest exists for - the grounding below tells the agent
 * WHAT the vault already argued, and this tells it which of those records
 * a link can actually reach.
 */
export interface DesignNoteLlmStep extends NeedsLlmStep {
  readonly link_candidates: LinkCandidateManifest;
}

export interface DesignNoteReport {
  readonly topic: string;
  readonly slug: string;
  readonly generatedAt: string;
  readonly grounding: DesignNoteGrounding;
  /** Vault-relative path the committed note will occupy. */
  readonly targetPath: string;
  readonly llmStep: DesignNoteLlmStep;
}

export interface PlanDesignNoteOptions {
  readonly now: Date;
  /**
   * Enforced owner scope for this caller, or null when none applies. It
   * filters the envelope's link candidates - see
   * {@link DesignNoteLlmStep} and `notes/link-candidates.ts` for why a
   * candidate list is a disclosure. Required, so a surface cannot forget
   * it and leak in silence.
   */
  readonly ownerScope: string | null;
  /**
   * May the caller read the page at this vault-relative path at its
   * reach? ANDed into the link-candidate filter beside the owner scope, so
   * a page withheld from the caller is not offered as a citation target
   * nor counted in the manifest's total, exactly as an absent page. The
   * MCP handler binds it to `readableAtContextReach(ctx)`; absent (the
   * CLI) filters nothing beyond the owner scope.
   */
  readonly readable?: (rel: string) => boolean;
}

export interface CommitDesignNoteOptions {
  readonly agent: string;
  readonly now: Date;
}

/** One alternative the note weighs. */
export interface DesignNoteAlternative {
  readonly name: string;
  readonly approach: string;
  readonly tradeoffs: string;
  readonly recommended: boolean;
}

export interface CommitDesignNoteResult {
  readonly topic: string;
  readonly slug: string;
  /** Absolute path of the committed note. */
  readonly path: string;
  /** Name of the single recommended alternative. */
  readonly recommended: string;
  readonly alternativeCount: number;
}

// ----- The cardinality rule the descriptor language cannot express ----------

/**
 * Exactly one alternative may carry `recommended: true`.
 *
 * This is the canonical case for the semantic registry: the rule reads
 * every element of an array at once, so no per-value descriptor can state
 * it, and the refusal has to carry the COUNT - "zero" and "three" are
 * different mistakes with different fixes.
 */
registerResponseCheck(DESIGN_NOTE_SURFACE, (payload) => {
  const violations: SemanticViolation[] = [];
  if (typeof payload !== "object" || payload === null) return violations;
  const alternatives = (payload as { alternatives?: unknown }).alternatives;
  if (!Array.isArray(alternatives)) return violations;
  const recommended = alternatives.filter(
    (item) =>
      typeof item === "object" &&
      item !== null &&
      (item as { recommended?: unknown }).recommended === true,
  );
  if (recommended.length !== 1) {
    violations.push(
      semanticViolation(
        SEMANTIC_VIOLATION_CODES.cardinality,
        `${SHAPE_ROOT_PATH}.alternatives`,
        `exactly one alternative must set recommended: true; found ${recommended.length} of ${alternatives.length}`,
      ),
    );
  }
  return violations;
});

// ----- Grounding ------------------------------------------------------------

/**
 * Read the three stores and keep what the topic reaches. Pure read; writes
 * nothing, calls no model, and never fails on an empty vault.
 *
 * `visible` is asked about each tension and decision page by its
 * vault-relative path before the page is scored or counted, so a page
 * the caller may not read is matched, listed and counted exactly as an
 * absent one (an empty store included). Absent, every page is visible.
 */
export function designNoteGrounding(
  vault: string,
  topic: string,
  visible?: (rel: string) => boolean,
): DesignNoteGrounding {
  const trimmed = requireTopic(topic);
  const queryTokens = tokenise(trimmed);
  const emptyStores: DesignNoteStore[] = [];
  const reads = visible !== undefined ? { readable: visible } : {};

  const allTensions = listTensions(vault).filter(
    (record) => visible === undefined || visible(`${BRAIN_TENSIONS_REL}/tension-${record.slug}.md`),
  );
  if (allTensions.length === 0) emptyStores.push(DESIGN_NOTE_STORE.tensions);
  const tensions = allTensions
    .map((record) => ({ record, score: tensionScore(queryTokens, record) }))
    .filter((row) => row.score >= DESIGN_NOTE_MATCH_THRESHOLD)
    .toSorted((a, b) => b.score - a.score || a.record.slug.localeCompare(b.record.slug))
    .slice(0, DESIGN_NOTE_PER_STORE_LIMIT)
    .map(({ record, score }) =>
      Object.freeze({
        id: record.id,
        slug: record.slug,
        subject: record.subject,
        status: record.status,
        unresolved: TENSION_UNRESOLVED_STATUSES.has(record.status),
        jaccard: score,
      }),
    );

  // The decision store owns its own matcher; reusing it keeps one ranking
  // rule for "a decision like this one" across every surface that asks.
  if (listDecisions(vault, reads).length === 0) emptyStores.push(DESIGN_NOTE_STORE.decisions);
  const decisions = findSimilarDecisions(
    vault,
    { title: trimmed },
    { threshold: DESIGN_NOTE_MATCH_THRESHOLD, limit: DESIGN_NOTE_PER_STORE_LIMIT, ...reads },
  ).map((match) =>
    Object.freeze({
      id: match.id,
      slug: match.slug,
      title: match.title,
      chosen: match.chosen,
      outcome: match.outcome,
      jaccard: match.jaccard,
    }),
  );

  const truth = readTruthState(vault);
  // A truth state that is absent and one that is unreadable are the same
  // fact for this report - there is no projection to ground anything in -
  // and `readTruthState` already collapses them to null by design.
  if (truth === null || truth.slots.length === 0) emptyStores.push(DESIGN_NOTE_STORE.truth);
  const truthSlots = (truth?.slots ?? [])
    .map((slot) => ({ slot, score: claimScore(queryTokens, slot) }))
    .filter((row) => row.score >= DESIGN_NOTE_MATCH_THRESHOLD)
    .toSorted(
      (a, b) =>
        b.score - a.score ||
        `${a.slot.entity}/${a.slot.aspect}`.localeCompare(`${b.slot.entity}/${b.slot.aspect}`),
    )
    .slice(0, DESIGN_NOTE_PER_STORE_LIMIT)
    .map(({ slot, score }) =>
      Object.freeze({
        entity: slot.entity,
        aspect: slot.aspect,
        value: slot.current.value,
        contested: slot.contested,
        jaccard: score,
      }),
    );
  const conflicts = (truth?.conflicts ?? [])
    .filter((conflict) => conflictScore(queryTokens, conflict) >= DESIGN_NOTE_MATCH_THRESHOLD)
    .slice(0, DESIGN_NOTE_PER_STORE_LIMIT)
    .map((conflict) =>
      Object.freeze({
        entity: conflict.entity,
        aspect: conflict.aspect,
        values: Object.freeze(conflict.values.map((v) => v.value)),
      }),
    );

  return Object.freeze({
    topic: trimmed,
    tensions: Object.freeze(tensions),
    decisions: Object.freeze(decisions),
    truthSlots: Object.freeze(truthSlots),
    conflicts: Object.freeze(conflicts),
    counts: Object.freeze({
      tensions: tensions.length,
      decisions: decisions.length,
      truthSlots: truthSlots.length,
      conflicts: conflicts.length,
    }),
    emptyStores: Object.freeze(emptyStores),
  });
}

// ----- Phase one: the request -----------------------------------------------

/**
 * Ground a topic and return the one envelope that asks for the note.
 * Read-only. An empty vault yields a report, not a refusal: the caller can
 * still write a design note, and the report says exactly how little it
 * rests on.
 */
export function planDesignNote(
  vault: string,
  topic: string,
  opts: PlanDesignNoteOptions,
): DesignNoteReport {
  const trimmed = requireTopic(topic);
  const ownerView = ownerScopeView(vault, opts.ownerScope);
  const visible = (rel: string): boolean =>
    ownerView.visible(rel) && (opts.readable?.(rel) ?? true);
  const grounding = designNoteGrounding(vault, trimmed, visible);
  const slug = slugify(trimmed);
  const targetPath = posix.join(DESIGN_NOTE_DIR_REL, noteBasename(slug, opts.now));
  const linkCandidates = buildLinkCandidateManifest(vault, {
    query: trimmed,
    visible,
  });
  return Object.freeze({
    topic: trimmed,
    slug,
    generatedAt: opts.now.toISOString(),
    grounding,
    targetPath,
    llmStep: buildNeedsLlmStep({
      step: DESIGN_NOTE_STEP,
      prompt:
        `Write a design note on '${trimmed}'. Weigh at least two NAMED alternatives, each with ` +
        "its approach and its tradeoffs, and mark EXACTLY ONE of them recommended - a note that " +
        "recommends none has not been written and one that recommends two has not been decided. " +
        "Ground every claim in the records below; where they say nothing, say so rather than " +
        "filling the gap.\n\n" +
        renderGrounding(grounding),
      schema_hints: [
        'payload: { "title", "summary"?, "alternatives": [ { "name", "approach", "tradeoffs", "recommended" } ] }',
        "alternatives: at least two, each field non-empty",
        "recommended: boolean; exactly one alternative may set it true",
        linkCandidateSchemaHint(linkCandidates),
      ],
      target_path: targetPath,
      link_candidates: linkCandidates,
    }),
  });
}

// ----- Phase two: the note --------------------------------------------------

/**
 * Validate the returned note and commit it beside the panel outputs.
 *
 * The write is exclusive. A second note for the same topic on the same day
 * is refused by name rather than overwriting the first: two design notes
 * that disagree are a fact worth keeping, and silently replacing one is
 * how the disagreement disappears.
 */
export function commitDesignNote(
  vault: string,
  topic: string,
  payload: unknown,
  opts: CommitDesignNoteOptions,
): CommitDesignNoteResult {
  // Vault-identity write guard (context-integrity-gates, Unit J): this is
  // the module's only write, and `tests/core/brain/vault-guard-census.test.ts`
  // counts every write-capable module in this tree.
  assertLaneWrite(vault);
  const trimmed = requireTopic(topic);
  // Structure first, then the cardinality rule. Nothing is written until
  // both pass.
  assertResponseShape(DESIGN_NOTE_SURFACE, DESIGN_NOTE_SHAPE, payload);
  assertResponseCheck(DESIGN_NOTE_SURFACE, payload);

  const note = payload as {
    title: string;
    summary?: string;
    alternatives: ReadonlyArray<DesignNoteAlternative>;
  };
  const recommended = note.alternatives.find((a) => a.recommended)!;
  const slug = slugify(trimmed);
  const dir = decisionsDir(vault);
  const path = join(dir, noteBasename(slug, opts.now));

  writeLanePage(
    vault,
    path,
    {
      schema_version: 1,
      kind: DESIGN_NOTE_KIND,
      slug,
      topic: trimmed,
      title: note.title.trim(),
      recommended: recommended.name.trim(),
      alternative_count: String(note.alternatives.length),
      agent: opts.agent,
      created_at: opts.now.toISOString(),
    },
    renderNote(trimmed, note),
    {
      overwrite: false,
      existsErrorKind: "design note",
      vaultForRelativePath: vault,
    },
  );

  return Object.freeze({
    topic: trimmed,
    slug,
    path,
    recommended: recommended.name.trim(),
    alternativeCount: note.alternatives.length,
  });
}

// ----- Internals ------------------------------------------------------------

function requireTopic(topic: string): string {
  const trimmed = topic.trim();
  if (trimmed.length === 0) throw new DesignNoteError("a design note needs a topic");
  return trimmed;
}

/** `design-<date>-<topic>.md`, the panel outputs' shape one directory up. */
function noteBasename(slug: string, now: Date): string {
  return `design-${isoDate(now)}-${slug}.md`;
}

function tensionScore(queryTokens: ReadonlySet<string>, record: TensionRecord): number {
  return jaccard(queryTokens, tokenise(`${record.subject} ${record.quoteA} ${record.quoteB}`));
}

function claimScore(queryTokens: ReadonlySet<string>, slot: ClaimSlot): number {
  return jaccard(queryTokens, tokenise(`${slot.entity} ${slot.aspect} ${slot.current.value}`));
}

function conflictScore(queryTokens: ReadonlySet<string>, conflict: TruthConflict): number {
  return jaccard(queryTokens, tokenise(`${conflict.entity} ${conflict.aspect}`));
}

/** The grounding set as the prompt shows it - identities, not prose. */
function renderGrounding(grounding: DesignNoteGrounding): string {
  const out: string[] = [];
  const section = (heading: string, lines: ReadonlyArray<string>, store: DesignNoteStore): void => {
    out.push(`## ${heading}`);
    if (grounding.emptyStores.includes(store)) {
      out.push(`(this vault holds no ${store} at all)`);
    } else if (lines.length === 0) {
      out.push(`(the ${store} store holds records, but none match this topic)`);
    } else {
      out.push(...lines);
    }
    out.push("");
  };

  section(
    "Unresolved and past tensions",
    grounding.tensions.map(
      (t) => `- ${t.id} [${t.status}${t.unresolved ? ", unresolved" : ""}] ${t.subject}`,
    ),
    DESIGN_NOTE_STORE.tensions,
  );
  section(
    "Prior decisions",
    grounding.decisions.map(
      (d) =>
        `- ${d.id} chose "${d.chosen}"${d.outcome ? ` -> ${d.outcome}` : " (no outcome recorded)"}`,
    ),
    DESIGN_NOTE_STORE.decisions,
  );
  const truthLines = [
    ...grounding.truthSlots.map(
      (s) => `- ${s.entity}/${s.aspect} = ${s.value}${s.contested ? " (contested)" : ""}`,
    ),
    ...grounding.conflicts.map(
      (c) => `- CONFLICT ${c.entity}/${c.aspect}: ${c.values.join(" vs ")}`,
    ),
  ];
  section("Current claims", truthLines, DESIGN_NOTE_STORE.truth);
  return out.join("\n");
}

function renderNote(
  topic: string,
  note: {
    title: string;
    summary?: string;
    alternatives: ReadonlyArray<DesignNoteAlternative>;
  },
): string {
  const out: string[] = [`# ${note.title.trim()}`, "", `Topic: ${topic}`, ""];
  if (note.summary?.trim()) out.push("## Summary", "", note.summary.trim(), "");
  out.push("## Alternatives", "");
  for (const alt of note.alternatives) {
    out.push(`### ${alt.name.trim()}${alt.recommended ? " (recommended)" : ""}`, "");
    out.push(alt.approach.trim(), "");
    out.push(`Tradeoffs: ${alt.tradeoffs.trim()}`, "");
  }
  return out.join("\n");
}