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
25.4 KB
Raw Blame
/**
 * Read-only export of `Brain/preferences/` for backup, prompt
 * injection, or sharing. Only the three active statuses
 * (`confirmed | unconfirmed | quarantine`) are included; retired
 * and signal artifacts are deliberately excluded.
 *
 * A preference the privacy deny markers reserve (`visibility: private`,
 * or an informal `access` / `confidentiality` / `sensitivity` marker) is
 * still collected and reported - in {@link PreferenceCollection.denied} -
 * but the shared lanes built on this module leave it out and name the
 * omission; there is no flag that carries a reserved rule through.
 *
 * llms-txt follows the [llmstxt.org](https://llmstxt.org) shape;
 * empty status sections are omitted so a single-status vault
 * renders one H2 rather than three.
 *
 * {@link BRAIN_EXPORT_SCHEMA_VERSION} versions the ENVELOPE, not the
 * row. A row gains fields additively - readers tolerate their absence
 * exactly as the frontmatter parsers do - so a consumer written against
 * an earlier export keeps working and no version dispatch is needed on
 * either side. A field that ever changes meaning or disappears is what
 * would force the version.
 */

import { existsSync, readdirSync } from "node:fs";
import { join, relative } from "node:path";

import { isStoreOnly } from "../store/store-only.ts";
import { toPosix } from "../path-safety.ts";
import type { FrontmatterMap } from "../types.ts";
import { hostPathFreeReason } from "./host-path-free.ts";
import { legacyMemoryPage, storeMemoryPages } from "./memory-pages.ts";
import { parsePreferenceMeta } from "./preference.ts";
import { brainDirs } from "./paths.ts";
import { vaultDisplayName } from "./templates.ts";
import { isoSecond } from "./time.ts";
import { BRAIN_PREFERENCE_STATUS, type BrainPreference } from "./types.ts";
import {
  hasPrivacyDenyMarker,
  PRIVACY_DENY_MARKER_VALUES,
  PRIVACY_MARKER_KEYS,
} from "../graph/privacy-markers.ts";
import { REMOTE_DENY_VISIBILITY_TOKEN, normToken, pageVisibility } from "../graph/visibility.ts";

export const BRAIN_EXPORT_SCHEMA_VERSION = 1 as const;

/**
 * Why the collector denied a preference from the shared lanes. One value
 * today, matching `pageBlockReason`'s vocabulary in
 * `portability/knowledge-pack.ts`: a deny here is a visibility
 * reservation - the reserved token declared under `visibility:`, or an
 * informal privacy marker saying the same thing - and never a content
 * class, which this lane does not read.
 */
export const PREFERENCE_DENY_REASON = "visibility" as const;

/**
 * The frontmatter key whose value denied a shared lane a preference.
 *
 * `visibility` names the reserved token's own key; the other three are the
 * informal marker keys of {@link PRIVACY_MARKER_KEYS} (kept in sync by
 * construction - the runtime list below is built from that constant, and a
 * key added there flows into the denial vocabulary with it).
 */
export type PreferenceDenyKey = "visibility" | "access" | "confidentiality" | "sensitivity";

/** The denial keys, in the order the docs list them. */
export const PREFERENCE_DENY_KEYS: ReadonlyArray<PreferenceDenyKey> = Object.freeze([
  "visibility",
  ...PRIVACY_MARKER_KEYS,
]) as ReadonlyArray<PreferenceDenyKey>;

/** One preference a shared lane leaves out, named the way the rows name them. */
export interface PreferenceDenial {
  /** The denied row's id (`pref-<slug>`), as it appears in `rows`. */
  readonly id: string;
  /**
   * The reason CLASS, always the reserved-token class: a deny here is a
   * visibility reservation, never a content class. Kept verbatim so the
   * machine readers of the json envelope's `omitted`, the bundle's
   * `preferences_omitted` and the knowledge pack's `blocked` list keep
   * their vocabulary; the key below is the specific half.
   */
  readonly reason: typeof PREFERENCE_DENY_REASON;
  /**
   * The frontmatter key whose value made the denial, named `denied_by`
   * rather than `key` because the egress guard redacts every value under
   * a field name containing "key" - a denial report must survive its own
   * boundary. `visibility` when the reserved token under `visibility:`
   * denied, or the informal marker key (`access` / `confidentiality` /
   * `sensitivity`) that said the same thing. Canonical lower-case
   * spelling, whatever case the file used.
   */
  readonly denied_by: PreferenceDenyKey;
}

/** How many unreadable files the error names before it stops listing. */
const MAX_NAMED_PARSE_FAILURES = 10;

/**
 * One preference file the collector could not turn into a row, named the
 * way the operator sees it - relative to the vault, so the message is the
 * path they can open. Same shape as `ExplorerParseFailure`, because the
 * two surfaces report the same event over the same directory.
 */
export interface PreferenceParseFailure {
  readonly path: string;
  readonly reason: string;
}

/**
 * A preference file that could not be read into a row.
 *
 * Raised rather than skipped. The collector used to `continue` past a
 * caught parse error, which produced `"preferences": []` on a vault that
 * held rules, under exit code 0 and an empty stderr - an export that omits
 * a rule reads exactly like a vault that never had it, and the file that
 * would say otherwise is the one the recipient does not have. Every caller
 * of {@link collectExportRows} is composing something for a reader
 * (a bundle, a context pack, the topic map an import merges against), so
 * there is no caller for whom a shorter list is the right answer.
 */
export class PreferenceParseError extends Error {
  /** Vault-relative paths that failed, with the parser's own message. */
  readonly failures: ReadonlyArray<PreferenceParseFailure>;
  constructor(failures: ReadonlyArray<PreferenceParseFailure>) {
    const named = failures
      .slice(0, MAX_NAMED_PARSE_FAILURES)
      .map((f) => `${f.path} (${f.reason})`)
      .join("; ");
    const rest =
      failures.length > MAX_NAMED_PARSE_FAILURES
        ? ` and ${failures.length - MAX_NAMED_PARSE_FAILURES} more`
        : "";
    super(
      // Not "this export": the same collector backs the import's
      // topic map, and an import told its EXPORT is incomplete sends
      // the operator to the wrong end of the round trip.
      `${failures.length} preference file(s) could not be parsed, so Brain/preferences/ ` +
        `cannot be read completely: ${named}${rest}. Repair or remove them, then re-run; ` +
        "`o2b brain doctor` reports the same files.",
    );
    this.name = "PreferenceParseError";
    this.failures = failures;
  }
}

/**
 * What `o2b brain export --format` accepts.
 *
 * Closed, and a vocabulary rather than the type alias it used to be: the
 * alias was declared here and imported by nobody, while the verb compared
 * the raw argv string against two inline literals. A contract with nothing
 * behind it is not a contract - adding a third format meant editing a
 * comparison in the CLI and hoping this line was noticed. The guard is now
 * the boundary the argv value crosses, and the object's key set is what the
 * verb's dispatch table is typed against, so a format with no handler is a
 * compile error.
 *
 * `transcripts-jsonl` names its shape on purpose. `json` and `llms-txt`
 * each produce ONE document; this one produces a stream of records, and an
 * operator who redirects it into a `.json` file learns that from the flag
 * rather than from a parse error downstream.
 */
export const EXPORT_FORMAT = Object.freeze({
  json: "json",
  llmsTxt: "llms-txt",
  transcriptsJsonl: "transcripts-jsonl",
} as const);

export type ExportFormat = (typeof EXPORT_FORMAT)[keyof typeof EXPORT_FORMAT];

/** The formats, in the order the help text and the refusal message list them. */
export const EXPORT_FORMATS: ReadonlyArray<ExportFormat> = Object.freeze([
  EXPORT_FORMAT.json,
  EXPORT_FORMAT.llmsTxt,
  EXPORT_FORMAT.transcriptsJsonl,
]);

/** Takes `unknown`: the value arrives as a raw `--format` argument. */
export function isExportFormat(value: unknown): value is ExportFormat {
  return typeof value === "string" && (EXPORT_FORMATS as ReadonlyArray<string>).includes(value);
}

export interface ExportedPreferenceRow {
  readonly id: string;
  readonly topic: string;
  readonly scope: string | null;
  readonly status: BrainPreference["status"];
  readonly principle: string;
  readonly applied_count: number;
  readonly violated_count: number;
  readonly confidence: BrainPreference["confidence"];
  readonly confidence_value: number | null;
  readonly pinned: boolean;
  readonly last_evidence_at: string | null;
  readonly created_at: string;
  readonly confirmed_at: string | null;
  /**
   * End of the trial window. Every preference write requires it and no
   * other exported field can stand in for it, so an export without it
   * cannot be restored: the restore would have to invent a window, and
   * an invented trial window silently re-dates a rule's promotion
   * deadline. Carried so `importBankBundle` can hand it back to
   * `writePreferenceTxn` verbatim.
   */
  readonly unconfirmed_until: string;
  /**
   * Monotonic write counter (`_revision`). The only ordering that lets a
   * restore tell "this bundle is ahead of the vault" from "this bundle
   * would rewind an edit the operator has since made". Absent on disk
   * reads as `0`, the same absent-as-zero convention the parser uses.
   */
  readonly revision: number;
  readonly aliases: ReadonlyArray<string> | null;
  readonly tags: ReadonlyArray<string>;
  readonly evidenced_by: ReadonlyArray<string>;
  /**
   * Markdown body after the frontmatter — carries the `## Principle`,
   * `## Origin`, `## How to apply` (and similar) narrative sections.
   * The `principle` field above is the headline copy; the body is the
   * fuller context a consumer needs when sharing or injecting the
   * rule into a system prompt.
   */
  readonly body: string;
}

export interface ExportedPreferencesJson {
  readonly schema: typeof BRAIN_EXPORT_SCHEMA_VERSION;
  readonly generated_at: string;
  readonly vault_basename: string;
  readonly preferences: ReadonlyArray<ExportedPreferenceRow>;
  /**
   * The preferences the privacy deny markers kept out of this export,
   * each named with its id and reason. Absent when empty, so a vault
   * with no reservation serialises byte-identically to the field-less
   * envelope and the schema stays 1 - an additive field, per the module's
   * own versioning rule. There is no override: the field reports what a
   * shared lane must never carry, so no flag fills it back in.
   */
  readonly omitted?: ReadonlyArray<PreferenceDenial>;
}

/**
 * Every row the walk produced, every file it could not read, and every
 * row the privacy deny markers keep out of the SHARED lanes.
 *
 * The triple, never one of them alone: a caller holding this has been
 * told how much it got, how much it missed, and what it must not carry.
 * `rows` stays complete on purpose - the import-side topic maps
 * (`preference-restore.ts`, `knowledge-pack.ts`) read the DESTINATION
 * vault to learn which topics existing rules claim, and a marker on a
 * rule does not unmake the rule - so denial is a report beside the rows,
 * not a filter inside the collector. The shared lanes filter at their
 * own composition seam and name what they leave out.
 */
export interface PreferenceCollection {
  readonly rows: ReadonlyArray<ExportedPreferenceRow>;
  readonly failures: ReadonlyArray<PreferenceParseFailure>;
  readonly denied: ReadonlyArray<PreferenceDenial>;
}

/**
 * Which frontmatter key, if any, denies this preference a shared lane?
 *
 * The same judgment `pageBlockReason` makes for pages in the knowledge
 * pack, read once here from the frontmatter map the collector already
 * parsed: a `visibility:` declaration carrying the reserved token, or an
 * informal privacy marker (`access: private` and its siblings) saying
 * what the reserved token says. A preference that declares only a
 * caller-scope token is a shared decision, not a reservation, and is
 * carried. The answer is the KEY that spoke, not just the fact of a
 * denial, so the stderr notice can name what the docs promise - the
 * reservation key that denied the row.
 */
export function deniedReservationKey(meta: FrontmatterMap): PreferenceDenyKey | null {
  if (pageVisibility(meta).includes(REMOTE_DENY_VISIBILITY_TOKEN)) return "visibility";
  if (!hasPrivacyDenyMarker(meta)) return null;
  // `hasPrivacyDenyMarker` just said some informal marker denies; name the
  // key that carries the deny value. The value reading mirrors the marker
  // module's own (a string, or an array of strings, normalised the same
  // way) - that reader is not exported there, and this module needs it
  // once, to answer WHICH key spoke rather than only whether one did.
  for (const key of Object.keys(meta)) {
    const canonical = PRIVACY_MARKER_KEYS.find((k) => normToken(k) === normToken(key));
    if (canonical === undefined) continue;
    const raw = meta[key];
    const values =
      typeof raw === "string"
        ? [raw]
        : Array.isArray(raw)
          ? raw.filter((v): v is string => typeof v === "string")
          : [];
    if (values.some((v) => PRIVACY_DENY_MARKER_VALUES.includes(normToken(v)))) {
      return canonical as PreferenceDenyKey;
    }
  }
  // Unreachable: `hasPrivacyDenyMarker` was true, so one of the marker
  // keys above carries a deny value and the loop already returned it.
  return null;
}

/**
 * Walk `Brain/preferences/`, parse every `pref-*.md`, and project to
 * the export row shape sorted by `id` for deterministic output.
 *
 * A file that cannot be read raises {@link PreferenceParseError} rather
 * than being skipped. Every failure in the directory is collected first,
 * so one run names all of them instead of making the operator repair one
 * file per re-run.
 *
 * @throws PreferenceParseError when any `pref-*.md` in the directory
 * cannot be parsed into a row.
 */
export function collectExportRows(vault: string): ReadonlyArray<ExportedPreferenceRow> {
  const { rows, failures } = collectPreferenceRows(vault);
  if (failures.length > 0) throw new PreferenceParseError(failures);
  return rows;
}

/**
 * The same walk, reporting its failures instead of raising them.
 *
 * Reserved for a caller that has a use for a partial answer AND reports
 * the gap. There is exactly one - the bank import's prior-topic map, which
 * reads the DESTINATION vault to learn which topics existing rules already
 * claim. `collectExportRows`' refusal is right for an export and wrong
 * there: one malformed rule already sitting in the destination would abort
 * an entire import, wholesale, on a condition unrelated to the bundle
 * being carried.
 *
 * Taking the failures without rendering them is the silent-drop defect
 * this module's refusal exists to prevent, so
 * {@link PreferenceRestoreResult.topicScanUnreadable} carries them all the
 * way to the operator's terminal.
 *
 * The directory LISTING failure still raises: it is a permission or
 * filesystem fault over the whole directory, not a per-file parse, and no
 * partial answer exists to give.
 *
 * A row the privacy deny markers reserve is reported in `denied` while
 * still parsed whole into `rows`; see {@link PreferenceCollection} for
 * why the split lives beside the rows and not inside them.
 */
export function collectPreferenceRows(vault: string): PreferenceCollection {
  const dir = brainDirs(vault).preferences;
  // D14 item 12: an export reads the folds once the machine is switched,
  // and keeps the legacy page layout as its interchange format.
  const stored = storeMemoryPages(vault, "preferences");
  if (stored === null && !existsSync(dir)) return { rows: [], failures: [], denied: [] };
  const rows: ExportedPreferenceRow[] = [];
  const failures: PreferenceParseFailure[] = [];
  const denied: PreferenceDenial[] = [];
  let entries: ReadonlyArray<string>;
  try {
    entries = stored === null ? readdirSync(dir) : stored.map((page) => page.name);
  } catch (err) {
    // The directory exists (or the store answered), so a listing failure
    // is a permission or filesystem fault, not an empty Brain.
    // Returning `[]` here reported the second while the first was true.
    // Named vault-relative for the same reason the per-file failures are:
    // this collector is reachable from an MCP error path. Forward-slash on
    // every host, the one spelling a vault-relative path has on the wire.
    const rel = toPosix(relative(vault, dir));
    throw new Error(`cannot list ${rel}: ${hostPathFreeReason(err, vault, dir, rel)}`, {
      cause: err,
    });
  }
  const storedByName = stored === null ? null : new Map(stored.map((p) => [p.name, p] as const));
  for (const name of entries) {
    if (!name.startsWith("pref-") || !name.endsWith(".md")) continue;
    const abs = join(dir, name);
    const page = storedByName?.get(name) ?? legacyMemoryPage(vault, "preferences", name);
    const record = (err: unknown): void => {
      const rel = toPosix(relative(vault, abs));
      // The parser's own message carries the absolute host path
      // (`BrainParseError` composes `<detail> (<path>)`, and a raw `node:fs`
      // failure embeds it too), and this refusal is reachable from an MCP
      // error path, where `src/mcp/tools.ts` forbids one. The `path` field
      // beside it is already vault-relative; the reason now matches.
      failures.push({ path: rel, reason: hostPathFreeReason(err, vault, abs, rel) });
    };
    let pref: BrainPreference;
    try {
      pref = parsePreferenceMeta(page.read()[0], abs);
    } catch (err) {
      record(err);
      continue;
    }
    // `parsePreference` deliberately drops the body. We re-parse the
    // file here to capture the markdown sections the agent wrote
    // (`## Principle`, `## Origin`, …) — those are the bytes a
    // consumer wants when sharing or system-prompt-injecting the
    // rule. A read failure here is the same defect as a frontmatter
    // one: the row would go out missing what the agent wrote.
    // The frontmatter map is already in hand at this line, so the
    // deny judgment reads it here rather than paying a second read.
    let body = "";
    let meta: FrontmatterMap = {};
    try {
      const [parsedMeta, parsedBody] = page.read();
      meta = parsedMeta;
      body = parsedBody;
    } catch (err) {
      record(err);
      continue;
    }
    // A record the store holds in `private` is reserved whatever its
    // fields say (`store-record-visibility.ts`): fail closed.
    const denyKey = deniedReservationKey(meta) ?? (page.private ? "visibility" : null);
    if (denyKey !== null) {
      denied.push({ id: pref.id, reason: PREFERENCE_DENY_REASON, denied_by: denyKey });
    }
    rows.push(toRow(pref, body));
  }
  rows.sort((a, b) => a.id.localeCompare(b.id));
  // The denial list sorts like the rows: it rides the json envelope's
  // `omitted`, the bank bundle's `preferences_omitted` and the stderr
  // notice, and a byte-deterministic export cannot leave it in
  // readdir order.
  denied.sort((a, b) => a.id.localeCompare(b.id));
  return { rows, failures, denied };
}

function toRow(p: BrainPreference, body: string): ExportedPreferenceRow {
  return Object.freeze({
    id: p.id,
    topic: p.topic,
    scope: p.scope ?? null,
    status: p.status,
    principle: p.principle,
    applied_count: p.applied_count,
    violated_count: p.violated_count,
    confidence: p.confidence,
    confidence_value: p.confidence_value,
    pinned: p.pinned,
    last_evidence_at: p.last_evidence_at,
    created_at: p.created_at,
    confirmed_at: p.confirmed_at,
    unconfirmed_until: p.unconfirmed_until,
    // Absent-as-zero, the convention `BrainPreference.revision`'s reader
    // already uses: a file written before `_revision` existed is at 0,
    // which is behind every later write and ahead of nothing.
    revision: p.revision ?? 0,
    aliases: p.aliases ? Object.freeze([...p.aliases]) : null,
    tags: Object.freeze([...p.tags]),
    evidenced_by: Object.freeze([...p.evidenced_by]),
    body,
  });
}

/**
 * The denying detail path beside {@link collectExportRows}: the same
 * walk, the same parse-failure refusal, and the denial list handed back
 * with `rows` still complete. For a caller that must see every row to
 * answer - the knowledge pack's selector resolution, which reports a
 * reserved rule as a named block rather than an unmatched selector.
 */
export function collectExportRowsWithDenials(vault: string): {
  readonly rows: ReadonlyArray<ExportedPreferenceRow>;
  readonly denied: ReadonlyArray<PreferenceDenial>;
} {
  const { rows, failures, denied } = collectPreferenceRows(vault);
  if (failures.length > 0) throw new PreferenceParseError(failures);
  return { rows, denied };
}

/**
 * The composition seam for everything handed to another reader - the
 * json envelope, the llms-txt document, the bank bundle: the denying
 * walk with `rows` narrowed to what a shared lane may carry. The
 * collector keeps `rows` complete for the import topic maps; the shared
 * lanes narrow here, where the omission is at hand to be named.
 */
export function collectSharedExportRows(vault: string): {
  readonly rows: ReadonlyArray<ExportedPreferenceRow>;
  readonly denied: ReadonlyArray<PreferenceDenial>;
} {
  const { rows, denied } = collectExportRowsWithDenials(vault);
  const reserved = new Set(denied.map((d) => d.id));
  return { rows: rows.filter((row) => !reserved.has(row.id)), denied };
}

/**
 * The stderr note naming the preferences a shared lane left out on a
 * visibility reservation, in the `contentClassOmissionNotice` shape:
 * counted, each item named with the reservation key that denied it, and a
 * remedy. The remedy names the reservation itself rather than an export
 * flag - a reserved rule never rides a shared lane, so the only way to
 * share it is to clear the reservation on the file, and the keys listed
 * are the ones this module reads.
 */
export function preferenceDenialNotice(denied: ReadonlyArray<PreferenceDenial>): string {
  const list = denied.map((d) => `${d.id} (${d.denied_by})`).join(", ");
  return (
    `note: ${denied.length} preference(s) left out on a visibility reservation: ${list}; ` +
    "no export flag carries them - clear the reservation " +
    "(visibility / access / confidentiality / sensitivity) on the preference file to share it\n"
  );
}

export function exportPreferencesJson(vault: string): ExportedPreferencesJson {
  const { rows, denied } = collectSharedExportRows(vault);
  return Object.freeze({
    schema: BRAIN_EXPORT_SCHEMA_VERSION,
    generated_at: isoSecond(),
    vault_basename: vaultDisplayName(vault),
    preferences: rows,
    // Absent-when-empty keeps a reservation-free vault's bytes exactly
    // what they always were.
    ...(denied.length > 0 ? { omitted: denied } : {}),
  });
}

const LLMS_TXT_SECTION_ORDER: ReadonlyArray<BrainPreference["status"]> = [
  BRAIN_PREFERENCE_STATUS.confirmed,
  BRAIN_PREFERENCE_STATUS.unconfirmed,
  BRAIN_PREFERENCE_STATUS.quarantine,
];

const LLMS_TXT_SECTION_LABEL: Readonly<Record<BrainPreference["status"], string>> = {
  [BRAIN_PREFERENCE_STATUS.confirmed]: "Confirmed",
  [BRAIN_PREFERENCE_STATUS.unconfirmed]: "Unconfirmed",
  [BRAIN_PREFERENCE_STATUS.quarantine]: "Quarantine",
};

/** The llms-txt document beside the omissions its privacy policy made. */
export interface LlmsTxtExport {
  readonly text: string;
  readonly omitted: ReadonlyArray<PreferenceDenial>;
}

/**
 * Render the export as an [llmstxt.org](https://llmstxt.org) markdown
 * file: H1 title, blockquote summary, then an H2 per non-empty
 * status. Each preference becomes one bullet line of the form
 * `- <id> (topic: <topic>[, scope: <scope>]): <principle>`. Status
 * sections without any rows are omitted entirely.
 *
 * Reserved preferences (see {@link PreferenceCollection.denied}) appear
 * in neither the sections nor the bullets; the detailed variant returns
 * the omissions beside the text so a caller can name them, the same
 * additive report the json envelope carries.
 */
export function exportPreferencesLlmsTxtDetailed(vault: string): LlmsTxtExport {
  const { rows, denied } = collectSharedExportRows(vault);
  const name = vaultDisplayName(vault);
  // A store-only machine keeps its preferences as brain store records, so
  // the header points at the store, not at a directory nothing writes.
  const where = isStoreOnly({ vault })
    ? [
        `> by \`o2b brain export --format llms-txt\`. The canonical records`,
        `> live in the brain store (\`o2b store path\`).`,
      ]
    : [
        `> by \`o2b brain export --format llms-txt\`. The canonical files`,
        `> live under \`<vault>/Brain/preferences/\`.`,
      ];
  const lines: string[] = [
    `# ${name} — Brain preferences`,
    "",
    `> Active preferences captured by Open Second Brain. Auto-generated`,
    ...where,
    "",
  ];
  for (const status of LLMS_TXT_SECTION_ORDER) {
    const subset = rows.filter((r) => r.status === status);
    if (subset.length === 0) continue;
    lines.push(`## ${LLMS_TXT_SECTION_LABEL[status]}`);
    lines.push("");
    for (const r of subset) {
      const scopeBit = r.scope ? `, scope: ${r.scope}` : "";
      lines.push(`- ${r.id} (topic: ${r.topic}${scopeBit}): ${r.principle}`);
    }
    lines.push("");
  }
  return { text: lines.join("\n"), omitted: denied };
}

/**
 * The stable string signature, kept for the SDK façade and every
 * existing reader: the detailed variant's text, unchanged in shape and
 * byte-for-byte identical when nothing is denied. The string variant
 * carries no denial report - visibility-reserved rows are left out
 * silently - so a caller that must name what stayed out uses
 * {@link exportPreferencesLlmsTxtDetailed}.
 */
export function exportPreferencesLlmsTxt(vault: string): string {
  return exportPreferencesLlmsTxtDetailed(vault).text;
}