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
30.2 KB
Raw Blame
/**
 * The counterparty brief core (dated commitments, t_43b0a379).
 *
 * One deterministic question: given a prompt, an operator-declared trigger
 * vocabulary and a vault, is there exactly ONE canonical counterparty the
 * prompt names, and if so, what dated, shareable facts does the vault hold
 * about them. The hook (hooks/counterparty-brief.ts) renders the answer
 * into a UserPromptSubmit `additionalContext` envelope; this module knows
 * nothing about hooks.
 *
 * Every refusal is a typed abstention, never a weaker match:
 *   - an empty trigger list abstains as `no_trigger` (the hook is inert
 *     without a vocabulary the operator declared);
 *   - a prompt carrying no trigger token abstains as `no_trigger`
 *     (deterministic WHOLE-token containment - a trigger never fires
 *     inside a longer word; the tokens are the operator's, in the
 *     operator's language; nothing here ships a natural-language
 *     word list, the standing refusal in status-scope.ts and
 *     visibility.ts);
 *   - zero canonical-scope entity matches abstain as `no_match`, and
 *     several as `ambiguous` (the exactly-one rule: a brief that fires
 *     on a weak match injects the wrong person's facts, so anything
 *     weaker than one confident match is silence).
 *
 * Items are shareable-only and dated: open pledges promised to the entity
 * (due-sorted, through `listPledges`) first, then recent preference pages
 * whose bodies anchor the entity, under named caps. A page whose
 * `visibility:` carries the reserved token is excluded REGARDLESS of the
 * caller's reach, because a hook-injected block leaves the machine; the
 * rule covers the counterparty's own entity page too, so a private record
 * can neither match nor block a match. An item drawn from two pages (a
 * pledge and the source it cites) inherits `strictestVisibilityOf`, so
 * disjoint token sets drop the item. A page the `readable` predicate
 * refuses contributes nothing and is not counted - identical to absent.
 *
 * Both walks are bounded: the preference walk reads at most
 * {@link BRIEF_PAGE_READ_CAP} pages and the pledge walk keeps at most
 * {@link BRIEF_PLEDGE_READ_CAP} and parses at most
 * {@link BRIEF_PLEDGE_SCAN_CAP}, each in the vault's stable (code-unit)
 * name order, so the hook's worst-case latency is bounded by the cap and
 * not by the size of the vault. The preference walk counts a page it
 * cannot read (`skippedReads` plus a typed degradation notice) - never
 * swallowed; the pledge walk inherits the family's soft-parse discipline
 * instead, so an unreadable or unparseable pledge page withholds its item
 * and drops out of the counterparty filter silently - the bounded window,
 * not the skip count, is the pledge walk's contract. The pledge walk's two
 * ceilings are separate on purpose: the kept window counts only the pages
 * the brief keeps, so a long tail of completed promises cannot crowd an
 * open one out, while the scan ceiling above it bounds the pages the walk
 * PARSES - the dropped ones included - so the filesystem work cannot grow
 * with the size of the pledge directory.
 *
 * Dates are dates: an item's date is a `YYYY-MM-DD` day, taken from a
 * pledge's due date or from the day a preference page was created. A value
 * that is not a calendar date renders as `undated`.
 */

import { readFileSync } from "node:fs";
import { join, relative, sep } from "node:path";
import { posix } from "node:path";

import { anchorEntityForms } from "./atomic-facts.ts";
import { type EntityLexiconHandle, type ValidateEntityLabelOptions } from "./entities/canonical.ts";
import { buildEntityIndex } from "./entities/index-builder.ts";
import { resolveEntityLexicon } from "./entities/lexicon.ts";
import { ENTITY_STATUS_SCOPE, entityStatusInScope } from "./entities/status-scope.ts";
import type { BrainEntity } from "./entities/types.ts";
import { readLifecycleState } from "./lifecycle/tombstone-read.ts";
import { BRAIN_PREFERENCES_REL } from "./path-constants.ts";
import { validateIsoDate } from "./paths.ts";
import {
  listPledges,
  isSourcePage,
  normalizePledgeSource,
  pledgeRel,
  type PledgeListItem,
} from "./pledges.ts";
import { neutralizeSingleLine, untrustedFramingHeader } from "./untrusted-source.ts";
import { REMOTE_DENY_VISIBILITY_TOKEN, strictestVisibilityOf } from "../graph/visibility.ts";
import { remoteDenyVisibilityTokens } from "../graph/privacy-markers.ts";
import {
  DEGRADATION_CODE,
  emitDegradationNotice,
  type DegradationNotice,
} from "../integrity/degradation.ts";
import {
  formatFrontmatter,
  parseFrontmatterTextWithNotices,
  parseFrontmatterWithNotices,
} from "../vault.ts";
import { memoryFolderPages } from "./memory-pages.ts";
import { laneEntryInPrivate, readLaneText } from "../store/lane-pages.ts";

/**
 * The most items one brief may carry. Three dated lines is the injection
 * budget the hook contract promises ("at most three"); everything past it
 * stays in the vault, where search can still reach it.
 */
export const DEFAULT_BRIEF_ITEM_LIMIT = 3;

/** Per-item character cap (code points) on the rendered fact text. */
export const BRIEF_ITEM_CHAR_CAP = 280;

/**
 * Total character budget (code points) across the item texts. Once the
 * budget is spent - or the next item would not fit whole - the walk stops.
 * The budget is a backstop above the structural ceiling
 * (`DEFAULT_BRIEF_ITEM_LIMIT * (BRIEF_ITEM_CHAR_CAP + 1)`), so the item
 * limit - not the budget - is what normally clips a brief; a caller that
 * raises the limit past the ceiling hands the clipping to the budget.
 */
export const BRIEF_CHAR_BUDGET = 900;

/**
 * Page-read cap on the preference walk (the morning-brief discipline): at
 * most this many preference pages are read per brief, in the vault's
 * stable name order, before the walk gives up. The cap bounds the hook's
 * worst-case latency on a large vault; recency orders what was read.
 */
export const BRIEF_PAGE_READ_CAP = 24;

/**
 * Kept-window cap on the pledge walk, the same discipline as
 * {@link BRIEF_PAGE_READ_CAP} and the same value: at most this many pledge
 * pages the brief KEEPS, in the vault's stable name order. The cap bounds
 * the hook's worst-case latency on a large pledge directory - the arm used
 * to read every page in `Brain/pledges/` before the item limit applied,
 * while the sibling preference walk was already capped. Counted after the
 * fulfilled filter, so a completed promise spends no window an open one
 * needs; the pages the walk PARSES are bounded separately, by
 * {@link BRIEF_PLEDGE_SCAN_CAP}.
 */
export const BRIEF_PLEDGE_READ_CAP = 24;

/**
 * Scan ceiling on the pledge walk: at most this many pledge pages the walk
 * may PARSE, the pages it parses and then drops included. The kept window
 * ({@link BRIEF_PLEDGE_READ_CAP}) counts only the pages the brief keeps, so
 * without a scan ceiling a long tail of completed promises would make the
 * walk's filesystem work grow with the size of `Brain/pledges/` even though
 * it keeps nothing. The ceiling sits above the kept window, so the window
 * still has room to fill before the scan budget runs out.
 */
export const BRIEF_PLEDGE_SCAN_CAP = 96;

/** The length of the `YYYY-MM-DD` head of a date or timestamp. */
const ISO_DATE_HEAD_LENGTH = 10;

/**
 * The separator a POSIX-joined vault path never carries. A stored path
 * that carries it was spelled for another platform, so it names a path
 * the vault never wrote.
 */
const WINDOWS_PATH_SEPARATOR = "\\";

/**
 * A Windows drive-letter absolute path, in either separator spelling. A
 * stored vault path is POSIX-joined by convention, so a drive letter can
 * only mean a path outside the vault.
 */
const DRIVE_LETTER_PATH_RE = /^[A-Za-z]:[\\/]/u;

/** The degradation site the preference walk reports its read failures at. */
const DEGRADATION_SITE = "brain.counterpartyBrief.preferenceWalk";

/** One dated, shareable fact about the counterparty. */
export interface CounterpartyBriefItem {
  /** The item's date (`YYYY-MM-DD`): a pledge's due date, or the day a preference page was created; "" when undated. */
  readonly date: string;
  /** The bounded fact text (a pledge title, or a preference's principle). */
  readonly text: string;
  /** Vault-relative POSIX path of the page the fact is shown from. */
  readonly sourceRel: string;
}

/**
 * A typed abstention: the core's refusal, naming its cause. The reason
 * travels to the hook's audit line, so a prompt that named nobody stays
 * distinguishable from a prompt that named two.
 */
export type CounterpartyBriefAbstention = {
  readonly abstain: "no_trigger" | "no_match" | "ambiguous";
};

/** A brief for exactly one counterparty, or the typed abstention. */
export interface CounterpartyBrief {
  readonly entityId: string;
  readonly entityName: string;
  readonly items: ReadonlyArray<CounterpartyBriefItem>;
  /** Preference pages the walk could not read. Counted, never swallowed. */
  readonly skippedReads: number;
  /** One typed degradation notice per unreadable page. */
  readonly notices: ReadonlyArray<DegradationNotice>;
}

export interface CounterpartyBriefInput {
  /** The prompt text (or any text) the counterparty and trigger are read from. */
  readonly text: string;
  /** The operator-declared trigger vocabulary (machine-local config). */
  readonly triggers: ReadonlyArray<string>;
  /** Injected clock for the pledge listing's due math. */
  readonly now: Date;
  /**
   * May the caller read the vault page at this vault-relative path? A page
   * the predicate refuses contributes nothing and is not counted:
   * identical to absent.
   */
  readonly readable?: (rel: string) => boolean;
  /**
   * The most items the brief may carry. Defaults to
   * {@link DEFAULT_BRIEF_ITEM_LIMIT}; a caller may raise it, and the
   * character budget then becomes the binding clip.
   */
  readonly itemLimit?: number;
}

/** The one normalization the trigger containment compares through. */
function normalizeToken(raw: string): string {
  return raw.normalize("NFC").trim().toLowerCase();
}

/**
 * One Unicode letter-or-number run: the unit a trigger token matches
 * WHOLE. The segmentation is letter/number aware, so a non-ASCII word
 * stays one token and a trigger never matches inside a longer word.
 */
const TOKEN_RE = /[\p{L}\p{N}]+/gu;

/**
 * The tokens of a normalized string, in order. A string that holds no
 * letter and no number holds no token at all.
 */
function tokenize(normalized: string): ReadonlyArray<string> {
  return normalized.match(TOKEN_RE) ?? [];
}

/**
 * Does the prompt carry the trigger's tokens, whole? A one-token trigger
 * matches a whole token of the prompt; a trigger the operator spelled
 * with a space names a SEQUENCE and matches a contiguous run of the
 * prompt's tokens. Nothing matches inside a longer word: "meet" fires on
 * "meet", never on "homeet" or "meetup".
 */
function promptCarriesTrigger(promptTokens: ReadonlyArray<string>, trigger: string): boolean {
  const triggerTokens = tokenize(trigger);
  if (triggerTokens.length === 0) return false;
  if (triggerTokens.length === 1) return promptTokens.includes(triggerTokens[0]!);
  for (let start = 0; start + triggerTokens.length <= promptTokens.length; start += 1) {
    const held = triggerTokens.every((token, offset) => promptTokens[start + offset] === token);
    if (held) return true;
  }
  return false;
}

/** A vault-relative POSIX path from an absolute one, whatever the host separator. */
function vaultRel(vault: string, abs: string): string {
  return relative(vault, abs).split(sep).join("/");
}

/**
 * Code-unit string order: the same order on every host, where
 * `localeCompare` varies with the host locale and would make the read
 * window - and with it the brief - depend on where the process runs.
 */
function compareCodeUnits(left: string, right: string): number {
  if (left < right) return -1;
  if (left > right) return 1;
  return 0;
}

/** Clip to the per-item cap on code points, so astral letters stay whole. */
function clipText(text: string): string {
  const codePoints = Array.from(text);
  if (codePoints.length <= BRIEF_ITEM_CHAR_CAP) return text;
  return `${codePoints.slice(0, BRIEF_ITEM_CHAR_CAP).join("")}…`;
}

/** The length of a string in code points, the unit the budget is specified in. */
function codePointLength(text: string): number {
  let length = 0;
  for (const _ of text) length += 1;
  return length;
}

/**
 * The one character-budget predicate, used by both arms: the next item's
 * text must fit WHOLE inside what is left of the budget. Tested before the
 * push, so a brief never carries more text than the budget allows.
 */
function fitsCharBudget(spent: number, text: string): boolean {
  return spent + codePointLength(text) <= BRIEF_CHAR_BUDGET;
}

/**
 * The `YYYY-MM-DD` day of a date or timestamp, or "" when the head is not a
 * valid calendar date. Soft by design: a hand-edited value degrades to an
 * undated item instead of crashing the walk, exactly like an undated
 * pledge. Only the head is read, so a value carrying extra characters
 * (a timestamp's time part, a forged second line) cannot widen the day.
 */
function isoDateHead(value: unknown): string {
  if (typeof value !== "string") return "";
  const head = value.trim().slice(0, ISO_DATE_HEAD_LENGTH);
  try {
    validateIsoDate(head);
    return head;
  } catch {
    return "";
  }
}

/**
 * Does the entity page carry the reserved visibility token? The check is
 * reach-independent, like the preference arm's: a hook-injected block
 * leaves the machine, so a private record may neither match nor block a
 * match. The gate FAILS CLOSED, the same discipline the pledge-source
 * gate applies: a page that cannot be read, or whose frontmatter parse
 * reports dropped lines, is treated as carrying the token - an unreadable
 * record is not shareable, so it may neither match nor block a match.
 */
function entityCarriesReservedToken(vault: string, entity: BrainEntity): boolean {
  // The page file on an unswitched machine, the lane record once switched
  // (no file exists there); a page that cannot be read is reserved.
  let text: string | null;
  try {
    // Once switched, a record the store holds in `private` is reserved
    // whatever its fields say: it can be private by partition alone (it
    // names a private page, or a merge's one verdict put it there), as
    // the preferences half of the brief already honours.
    if (laneEntryInPrivate(vault, entity.path)) return true;
    text = readLaneText(vault, entity.path);
  } catch {
    return true;
  }
  if (text === null) return true;
  const [meta, , notices] = parseFrontmatterTextWithNotices(text);
  if (notices.length > 0) return true;
  // The full union (declared tokens plus any informal marker's
  // reservation), so a page stating `access: private` under the informal
  // key is reserved exactly as a formally declared one would be - the
  // marker is the same claim in an older spelling, and the brief leaves
  // the machine either way.
  return remoteDenyVisibilityTokens(meta).includes(REMOTE_DENY_VISIBILITY_TOKEN);
}

/**
 * The exactly-one canonical entity the text names, or the abstention it
 * earned. Canonical scope only (`entityStatusInScope` - a quarantined
 * record never holds an identity a read resolves to), anchored by name or
 * alias through the shared occurrence kernel with the vault's
 * store-learned lexicon (resolved by the caller and threaded in, so the
 * brief reads the derived artifact once). An entity page the caller's
 * view refuses is treated as absent, so a withheld record can neither
 * match nor block a match; the same holds for an entity page carrying
 * the reserved visibility token, whatever the caller's reach. Zero
 * shareable matches abstain as `no_match`, more than one as `ambiguous`.
 */
function matchExactlyOneEntity(
  vault: string,
  input: CounterpartyBriefInput,
  lexicon: EntityLexiconHandle | null,
): BrainEntity | CounterpartyBriefAbstention {
  const trimmed = input.text.trim();
  if (trimmed === "") return { abstain: "no_match" };
  const matched: BrainEntity[] = [];
  for (const entity of buildEntityIndex(vault).entities) {
    if (!entityStatusInScope(entity.status, ENTITY_STATUS_SCOPE.canonical)) continue;
    if (input.readable !== undefined && !input.readable(vaultRel(vault, entity.path))) continue;
    if (anchorEntityForms(trimmed, [entity.name, ...entity.aliases], { lexicon }).length === 0) {
      continue;
    }
    matched.push(entity);
  }
  // The reserved-token gate is applied AFTER the matching, so only the
  // pages that actually matched are read for it - and it removes a private
  // record from the set instead of letting it block the match beside it.
  const shareable = matched.filter((entity) => !entityCarriesReservedToken(vault, entity));
  if (shareable.length === 1) return shareable[0]!;
  return { abstain: shareable.length === 0 ? "no_match" : "ambiguous" };
}

/**
 * The stored pledge source as the vault-relative path it names, or null
 * when the stored value escapes the vault.
 *
 * A stored vault path is POSIX-joined by convention, so a stored source
 * that carries a backslash separator was spelled for another platform:
 * it is refused before anything is read from it, whatever it would
 * resolve to. So is a source that is absolute in ANY spelling - a drive
 * letter (Windows) or a POSIX root - and so is one that still escapes
 * after normalization. The value is normalized exactly as the writers
 * normalize it, so the check and the read that follows agree on one
 * path.
 */
function pledgeSourceWithinVault(stored: string): string | null {
  if (stored.includes(WINDOWS_PATH_SEPARATOR)) return null;
  const source = normalizePledgeSource(stored);
  if (source.length === 0) return null;
  if (DRIVE_LETTER_PATH_RE.test(source)) return null;
  if (posix.isAbsolute(source)) return null;
  if (source.startsWith("..")) return null;
  return source;
}

/**
 * True when the absolute path names an existing regular file - the
 * predicate the pledge writers use for a cited source. A path that
 * cannot be stat'ed at all (a missing page, a directory, a path whose
 * parent is a file) is not a page, and the caller fails closed on it.
 */
function isRegularFile(abs: string): boolean {
  try {
    return isSourcePage(abs);
  } catch {
    return false;
  }
}

/**
 * One pledge item, or null when the item is not shareable. The item is
 * drawn from TWO pages - the pledge page and the source it cites - so the
 * strictest visibility of the two governs: either carrying the reserved
 * token, or two non-empty token sets that share nothing, drops the item
 * (the folded list is exactly the reserved token then). The pledge page's
 * OWN frontmatter is read with the notices its parse produced: a page whose
 * parse reports a dropped line - a hand edit that corrupted the
 * `visibility:` key - cannot be shown to be shareable, so the gate fails
 * closed and withholds the item. A source page the
 * `readable` predicate refuses withholds the whole item: a pledge citing
 * bytes the caller cannot see is not shown second-hand. The stored source
 * is normalized exactly as the writers normalize it before anything is
 * read from it, and an item whose source escapes the vault is dropped -
 * the walk never reads, nor renders, a path from outside the vault, in any
 * spelling (a backslash separator, a drive letter, a POSIX root, a `..`
 * escape). The cited source must also EXIST as a regular page inside the
 * vault: a source that was renamed, deleted or never written cannot be
 * shown to be shareable, so the item is withheld exactly like an
 * unreadable one. A cited source that cannot be read (or whose frontmatter
 * parse reports dropped lines) withholds the item too: the gate decides
 * whether the item may leave the machine, so it fails closed, the same
 * discipline the preference walk applies to its own pages. The item names
 * the cited source page, which is where the promise was read.
 */
function pledgeItem(
  vault: string,
  pledge: PledgeListItem,
  readable: ((rel: string) => boolean) | undefined,
): CounterpartyBriefItem | null {
  const [meta, , pledgeNotices] = parseFrontmatterWithNotices(pledge.path);
  // The pledge page decides whether its OWN item may leave the machine, so
  // the gate fails closed: a frontmatter parse that reports a dropped line
  // (a hand edit that corrupted the `visibility:` key) cannot be shown to
  // be shareable, so the item is withheld - the same discipline the
  // cited-source gate applies.
  if (pledgeNotices.length > 0) return null;
  // Each tag list is the page's declared tokens plus any informal marker's
  // reservation (`remoteDenyVisibilityTokens`), so a page saying
  // `access: private` under the informal key folds exactly as a formally
  // reserved one would - the brief leaves the machine, and the marker is
  // the same claim in an older spelling.
  const tagLists: ReadonlyArray<string>[] = [[...remoteDenyVisibilityTokens(meta)]];
  let sourceRel = pledgeRel(pledge.slug);
  if (pledge.source.length > 0) {
    const source = pledgeSourceWithinVault(pledge.source);
    if (source === null) return null;
    if (readable !== undefined && !readable(source)) return null;
    const sourceAbs = join(vault, source);
    // The cited page must be there: the item is drawn from two pages,
    // and a source that is gone (deleted, renamed, never written) leaves
    // its own shareability unprovable. The gate fails closed, so the
    // item is withheld rather than shared on the pledge page alone.
    if (!isRegularFile(sourceAbs)) return null;
    const [sourceMeta, , sourceNotices] = parseFrontmatterWithNotices(sourceAbs);
    if (sourceNotices.length > 0) return null;
    tagLists.push([...remoteDenyVisibilityTokens(sourceMeta)]);
    sourceRel = source;
  }
  const folded = strictestVisibilityOf(tagLists);
  if (folded.includes(REMOTE_DENY_VISIBILITY_TOKEN)) return null;
  return Object.freeze({
    date: pledge.due,
    text: clipText(pledge.title),
    sourceRel,
  });
}

/** The bounded fact text of a preference page: its principle, else its first body line. */
function preferenceText(meta: Readonly<Record<string, unknown>>, body: string): string {
  const principle = meta["principle"];
  if (typeof principle === "string" && principle.trim().length > 0) return principle.trim();
  for (const line of body.split("\n")) {
    const trimmed = line.trim();
    if (trimmed.length > 0) return trimmed;
  }
  return "";
}

/** What one bounded walk of the preference directory found. */
interface PreferenceWalk {
  readonly items: ReadonlyArray<CounterpartyBriefItem>;
  /** Pages that could not be read (counted, never swallowed). */
  readonly skippedReads: number;
  /** One typed degradation notice per unreadable page. */
  readonly notices: ReadonlyArray<DegradationNotice>;
}

/**
 * The preference facts the bounded walk finds, newest first among the read
 * window. The walk reads at most {@link BRIEF_PAGE_READ_CAP} pages in the
 * vault's stable name order; a page the `readable` predicate refuses is
 * filtered BEFORE reading, so it spends neither a read nor an item. A page
 * whose frontmatter is malformed or missing contributes nothing, as does a
 * page carrying the reserved visibility token - the reserved-token check is
 * reach-independent by design, because the rendered block leaves the
 * machine - and as does a page that was tombstoned or superseded: the brief
 * renders current facts, so it wants the chain tips only, the same
 * exclusion the shared lifecycle predicate applies in recall / inject /
 * active.md / dream.
 */
function preferenceItems(
  vault: string,
  forms: ReadonlyArray<string>,
  anchorOpts: ValidateEntityLabelOptions,
  input: CounterpartyBriefInput,
): PreferenceWalk {
  const notices: DegradationNotice[] = [];
  // The preference pages: files when unswitched, the fold's once switched (task 2.10).
  const pages = memoryFolderPages(vault, "preferences", { regularFilesOnly: true });
  const read: Array<{ item: CounterpartyBriefItem; date: string; name: string }> = [];
  let reads = 0;
  let skippedReads = 0;
  // Code-unit name order, the same order listPledges walks its directory
  // in: the read window - and so the brief - must not depend on the host's
  // ICU locale.
  for (const entry of pages.toSorted((a, b) => compareCodeUnits(a.name, b.name))) {
    if (reads >= BRIEF_PAGE_READ_CAP) break;
    if (!entry.name.endsWith(".md")) continue;
    const rel = posix.join(BRAIN_PREFERENCES_REL, entry.name);
    if (input.readable !== undefined && !input.readable(rel)) continue;
    // A record the store holds in `private` is withheld whatever its
    // frontmatter says, as the reserved token would withhold it: the
    // rendered block leaves the machine.
    if (entry.private) continue;
    reads += 1;
    let text: string;
    try {
      text = entry.stored ? formatFrontmatter(...entry.read()) : readFileSync(entry.path, "utf8");
    } catch (err) {
      // A page that cannot be read is skipped, but never silently: the
      // skip is counted and reported through the typed degradation
      // channel, so "this page says nothing" and "this page could not be
      // read" stay distinguishable.
      skippedReads += 1;
      emitDegradationNotice(notices, {
        code: DEGRADATION_CODE.frontmatterUnreadable,
        site: DEGRADATION_SITE,
        path: rel,
        detail: `preference page read failed: ${err instanceof Error ? err.message : String(err)}`,
      });
      continue;
    }
    const [meta, body, pageNotices] = parseFrontmatterTextWithNotices(text);
    if (pageNotices.length > 0) continue;
    // The full union, so a preference page reserving itself under an
    // informal key (`confidentiality: secret`) is withheld exactly as a
    // formally declared one would be.
    if (remoteDenyVisibilityTokens(meta).includes(REMOTE_DENY_VISIBILITY_TOKEN)) continue;
    const lifecycle = readLifecycleState(meta);
    if (lifecycle.tombstoned || lifecycle.supersededBy !== null) continue;
    if (anchorEntityForms(body, forms, anchorOpts).length === 0) continue;
    const date = isoDateHead(meta["created_at"]);
    read.push({
      date,
      name: entry.name,
      item: Object.freeze({
        date,
        text: clipText(preferenceText(meta, body)),
        sourceRel: rel,
      }),
    });
  }
  // Recent first among what was read; an undated page sorts last, and the
  // slug breaks ties so the order never depends on readdir timing.
  const items = read
    .toSorted((a, b) => {
      if (a.date !== b.date) return a.date > b.date ? -1 : 1;
      return compareCodeUnits(a.name, b.name);
    })
    .map((entry) => entry.item);
  return { items, skippedReads, notices };
}

/**
 * Build the brief for the prompt, or abstain with the typed reason. See
 * the module docblock for the abstention, shareability and cap contract.
 */
export function buildCounterpartyBrief(
  vault: string,
  input: CounterpartyBriefInput,
): CounterpartyBrief | CounterpartyBriefAbstention {
  const triggers = input.triggers.map(normalizeToken).filter((token) => token.length > 0);
  if (triggers.length === 0) return { abstain: "no_trigger" };
  const promptTokens = tokenize(input.text.normalize("NFC").toLowerCase());
  if (!triggers.some((trigger) => promptCarriesTrigger(promptTokens, trigger))) {
    return { abstain: "no_trigger" };
  }
  // The lexicon is resolved ONCE and threaded into the match: the derived
  // artifact is read a single time per brief, not once per walk.
  const lexicon = resolveEntityLexicon(vault);
  const match = matchExactlyOneEntity(vault, input, lexicon);
  if ("abstain" in match) return match;
  const entity = match;

  // A caller-supplied limit is clamped: a NaN, a zero or a negative
  // number would otherwise disable the limit outright and hand an
  // unbounded brief to the hook.
  const rawItemLimit = input.itemLimit ?? DEFAULT_BRIEF_ITEM_LIMIT;
  const itemLimit =
    Number.isInteger(rawItemLimit) && rawItemLimit > 0 ? rawItemLimit : DEFAULT_BRIEF_ITEM_LIMIT;
  const items: CounterpartyBriefItem[] = [];
  const notices: DegradationNotice[] = [];
  let spent = 0;
  let skippedReads = 0;
  // Open pledges promised to the entity first (listPledges is due-sorted),
  // then undated preference facts - the dated supply leads. The pledge
  // walk keeps at most BRIEF_PLEDGE_READ_CAP pages and parses at most
  // BRIEF_PLEDGE_SCAN_CAP, so a large pledge directory cannot make the
  // hook's work unbounded; listPledges refuses a page the predicate
  // withholds before parsing it and does not count it against either cap,
  // the same discipline as the preference walk.
  for (const pledge of listPledges(vault, {
    now: input.now,
    ...(input.readable !== undefined ? { readable: input.readable } : {}),
    readCap: BRIEF_PLEDGE_READ_CAP,
    scanCap: BRIEF_PLEDGE_SCAN_CAP,
  })) {
    if (items.length >= itemLimit) break;
    if (!pledge.counterparties.includes(entity.id)) continue;
    const item = pledgeItem(vault, pledge, input.readable);
    if (item === null) continue;
    if (!fitsCharBudget(spent, item.text)) break;
    items.push(item);
    spent += codePointLength(item.text);
  }
  // The preference walk runs only when the budget can still hold an item:
  // with the budget spent, the one predicate refuses every item anyway.
  if (items.length < itemLimit && spent < BRIEF_CHAR_BUDGET) {
    const walk = preferenceItems(vault, [entity.name, ...entity.aliases], { lexicon }, input);
    skippedReads += walk.skippedReads;
    notices.push(...walk.notices);
    for (const item of walk.items) {
      if (items.length >= itemLimit) break;
      if (!fitsCharBudget(spent, item.text)) break;
      items.push(item);
      spent += codePointLength(item.text);
    }
  }
  return Object.freeze({
    entityId: entity.id,
    entityName: entity.name,
    items: Object.freeze(items),
    skippedReads,
    notices: Object.freeze(notices),
  });
}

/**
 * Render the brief for injection, or the empty string when there is nothing
 * to inject (the hook then emits nothing). Vault-derived text is framed
 * with the shared records-not-instructions header and every variable part
 * is neutralized single-line, so a hostile page cannot break the line shape
 * of the block.
 */
export function renderCounterpartyBrief(brief: CounterpartyBrief): string {
  if (brief.items.length === 0) return "";
  const lines = [
    untrustedFramingHeader(`counterparty-brief:${brief.entityId}`),
    `Counterparty brief for ${neutralizeSingleLine(brief.entityName)}:`,
    ...brief.items.map(
      (item) =>
        `- ${item.date === "" ? "undated" : neutralizeSingleLine(item.date)} ${neutralizeSingleLine(item.text)} ` +
        `(${neutralizeSingleLine(item.sourceRel)})`,
    ),
  ];
  return lines.join("\n");
}