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
92.1 KB
Raw Blame
/**
 * Preference (`pref-*.md`) and retired (`ret-*.md`) parsers, writer, and
 * the `preferences/ → retired/` mover.
 *
 * Preferences are rules promoted from clusters of signals (design doc
 * §5.3). They live in `Brain/preferences/` while active; they migrate
 * to `Brain/retired/` once they leave the loop, gaining retire metadata
 * but otherwise keeping the original slug — only the filename prefix
 * flips from `pref-` to `ret-`. The same identity slug is preserved
 * across the move so wikilinks pointing at `[[pref-foo]]` continue to
 * resolve (Obsidian indexes by basename regardless of folder, and the
 * retired file's frontmatter `id` flips to `ret-foo`).
 *
 * Four concerns matter:
 *
 *   1. **Default `pinned: false`** when parsing a file whose
 *      frontmatter omits the field. The design doc §5.3 makes this
 *      explicit; the type contract in `types.ts` says parsers MUST
 *      coerce missing/null/undefined to `false`.
 *
 *   2. **Status-vs-folder invariant.** A file in `preferences/` whose
 *      frontmatter `status` is `retired` (or a file in `retired/` whose
 *      kind is `brain-preference`) is corrupt — almost certainly the
 *      result of a half-completed move. Parsers throw
 *      {@link BrainStatusFolderMismatchError} on read so the doctor
 *      command (Task 4) can surface it as a warning. The parsers
 *      themselves throw because the typed return value would otherwise
 *      lie about the on-disk state.
 *
 *   3. **Atomic move.** `moveToRetired` performs the rename via two
 *      atomic operations (write the new file, unlink the old) to keep
 *      the filesystem consistent on a mid-run crash: the new file is
 *      complete before the old one disappears.
 *
 *   4. **Store-only** (task 2.10). Once the machine is switched
 *      (`../store/store-only.ts`) a preference is no page: the writer,
 *      the mover and {@link loadPreference} read the store's preference
 *      fold (`./preference-store.ts`) and write `preference-set` records
 *      only, so nothing under `Brain/` changes.
 */

import type { StorePreference } from "../store/read/store-entities.ts";
import { loadPermissionsDocumentFor } from "./permissions/document-source.ts";
import { legacyVaultOf } from "./no-vault.ts";
import type { Authority } from "../store/constants.ts";
import { authorityFromOrigin, dualWrite, type DualWriteRecord } from "../store/dual-write.ts";
import {
  isPrivateFrontmatter,
  preferenceFields,
  preferenceSetRecord,
} from "../store/dual-write-records.ts";
import {
  callerInput,
  operationPrivacy,
  PREFERENCE_OPAQUE_FIELDS,
  type JudgedContent,
  type OperationPrivacy,
} from "../store/operation-privacy.ts";
import { withOperationPrivacy } from "../store/operation-scope.ts";
import { existsSync, readFileSync, unlinkSync } from "node:fs";
import { basename, dirname, join, relative } from "node:path";

import type { FrontmatterMap } from "../types.ts";
import {
  formatFrontmatter,
  parseFrontmatter,
  parseFrontmatterWithNotices,
  slugify,
  writeFrontmatterAtomic,
} from "../vault.ts";
import { FileAlreadyExistsError } from "../fs-atomic.ts";
import { routeWrite, storeWrite } from "../store/store-write.ts";
import { DERIVED_FIELDS, storeEntryMeta } from "./preference-page-meta.ts";
import {
  fieldsUnchanged,
  isRetiredEntry,
  PREFERENCE_TEXT_FIELD,
  preferencesStoreOnly,
  storePreferenceEntry,
  textOfFields,
  typedPreferenceFields,
} from "./preference-store.ts";
import {
  appendRetiredSection,
  preferencePageProse,
  renderPreferenceBody,
} from "./preference-body.ts";
import { requireObsidianTagValue, scopeTagValues } from "./tag-syntax.ts";
import { BrainParseError } from "./parse-error.ts";
import { FrontmatterTierConflictError, mergeFrontmatterTiered } from "./frontmatter-tiers.ts";
import { loadSchemaPack } from "./schema-pack.ts";
import { DEFAULT_RELATION_TYPES, type DefaultRelationType } from "../graph/relation-vocab.ts";
import {
  isKnownSchemaToken,
  validateSchemaToken,
  type BrainSchemaVocabulary,
} from "./schema-vocab.ts";
import {
  brainDirsForWrite,
  brainDirsOf,
  preferencePath,
  preferencePathOf,
  retiredPath,
  retiredPathOf,
  validateSlug,
} from "./paths.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { OWNER_UNRESOLVED, normalizeAgentScope, ownerStampFor } from "../graph/agent-scope.ts";
import { normalizeAgentArgument } from "../agent-identity.ts";
import { resolveAgentName, UNCONFIGURED_AGENT_NAME } from "../config.ts";
import { DEGRADATION_CODE } from "../integrity/degradation.ts";
import { GATE_MODE } from "../integrity/stamp.ts";
import { loadIntegrityConfigForWrite, loadIntegrityConfigSafe } from "./policy.ts";
import { appendDecisionLedger } from "./permissions/ledger.ts";
import { OWNER_SCOPE_WRITES_KEY, refuseCrossOwnerWrite } from "./trust/owner-write-gate.ts";
import { substrateSubject, type WriteSubject } from "./write-disposition.ts";
import { asProvenanceLevel, type ProvenanceLevel } from "./provenance/provenance.ts";
import { sanitisePrinciple } from "./text/sanitize-principle.ts";
import {
  BRAIN_CONFIDENCE,
  BRAIN_MEMORY_LAYER,
  BRAIN_PREFERENCE_STATUS,
  BRAIN_RETIRED_REASON,
  BRAIN_TOMBSTONE_STATUS,
  type BrainConfidence,
  type BrainEvidenceSummary,
  type BrainMemoryLayer,
  type BrainPreference,
  type BrainPreferenceStatus,
  type BrainRetired,
  type BrainRetiredReason,
  type BrainCommitmentTier,
  isBrainMemoryLayer,
} from "./types.ts";
import { readCommitmentTier, validateCommitmentTier } from "./commitment.ts";
import { readMergedInto } from "./page-meta/page-id.ts";
import type { PageLifecycle } from "./page-meta/lifecycle.ts";
import type { PageTier } from "./page-meta/tier.ts";
import { computeContentHash } from "./content-hash.ts";
import { EXPIRATION_DATE_FIELD, normalizeExpirationDate } from "./expiration.ts";
import { KNOWLEDGE_PACK_FIELD, parseKnowledgePackStamp } from "./portability/pack-stamp.ts";
import {
  computePayloadHash,
  IdempotencyPayloadMismatchError,
  lookupKey,
  rememberKey,
} from "./idempotency-ledger.ts";
import { appendPrefAudit } from "./pref-audit.ts";
import { PREF_AUDIT_OP } from "./types.ts";

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

/**
 * Raised when a preference / retired file disagrees with the folder
 * it lives in. Surfaces both pieces of information so the caller (and
 * `o2b brain doctor`) can render an actionable message.
 *
 * A {@link BrainParseError}, so the path travels as a field and the
 * doctor's `status-folder-mismatch` branch reports it the same way as
 * every other parse failure. `status` and `folder` stay in the prose:
 * unlike the path, a `DoctorIssue` has no field for them.
 *
 * The sentence a bare caller reads is unchanged: `o2b brain reject`
 * prints `(exc as Error).message` with nowhere else to put a location,
 * and this message has always named the path INSIDE the data group,
 * before `status` and `folder`. Moving it to the end would gain nothing
 * and would break an operator matching on the text, so the composition
 * is supplied rather than left to the default appender.
 */
export class BrainStatusFolderMismatchError extends BrainParseError {
  readonly status: string;
  readonly folder: "preferences" | "retired";

  constructor(message: string, path: string, status: string, folder: "preferences" | "retired") {
    super(`${message} (${statusFolderFacts(status, folder)})`, path, {
      composedMessage: `${message} (path=${path}, ${statusFolderFacts(status, folder)})`,
    });
    this.name = "BrainStatusFolderMismatchError";
    this.status = status;
    this.folder = folder;
  }
}

/** The two facts a `DoctorIssue` has no field for, in their stored order. */
function statusFolderFacts(status: string, folder: "preferences" | "retired"): string {
  return `status=${status}, folder=${folder}`;
}

// ----- Writer inputs --------------------------------------------------------

export interface WritePreferenceInput {
  /** Slug stem (no `pref-` prefix). Used as the file basename. */
  readonly slug: string;
  readonly topic: string;
  readonly principle: string;
  readonly created_at: string;
  readonly unconfirmed_until: string;
  readonly status: BrainPreferenceStatus;
  readonly evidenced_by: ReadonlyArray<string>;
  readonly confirmed_at?: string | null;
  readonly scope?: string;
  /**
   * Compose the `brain/scope/...` tags leniently: a scope segment that
   * fails the shared tag rule is slugified (or dropped when the slug
   * fails too) instead of refusing the write. Set only when the scope is
   * re-read from a persisted record - the dream pass rewriting a stored
   * preference or promoting stored signals - so a legacy value written
   * before v1.78.0 cannot abort it. The `scope` field stays verbatim
   * either way; new caller input leaves this unset and stays strict.
   */
  readonly lenientScopeTags?: boolean;
  /**
   * Optional owner token (Knowledge Provenance suite, v1.7). When set, the
   * fact is owner-private: owner-scoped recall returns it only to its owner,
   * while ownerless facts stay shared. Stored verbatim; normalized for
   * comparison by the shared owner-visibility model.
   */
  readonly owner?: string;
  /**
   * Optional `visibility:` tokens (already normalised by `pageVisibility`).
   * Emitted only when non-empty, so a default-visibility preference stays
   * byte-identical. The dream pass stamps the strictest visibility of the
   * signals a preference is drafted from; a rewrite that omits it keeps the
   * file's own line through the tiered merge (it is a user-tier field).
   */
  readonly visibility?: ReadonlyArray<string>;
  /**
   * Optional provenance trust level (Knowledge Provenance suite, v1.7).
   * Absent reads as `stated` (operator-asserted) for every existing
   * preference. A derived fact is written `deduced` or `inferred` with its
   * premise links in `evidenced_by`.
   */
  readonly provenance?: ProvenanceLevel;
  readonly applied_count?: number;
  readonly violated_count?: number;
  readonly last_evidence_at?: string | null;
  readonly confidence?: BrainConfidence;
  /**
   * Numeric `confidence_value` (Wilson lower bound × freshness
   * decay). `null` or absent leaves the on-disk field as `null`,
   * signalling "not yet computed" to downstream readers. Dream's
   * refresh pass always supplies a finite value.
   */
  readonly confidence_value?: number | null;
  /**
   * Per-page lifecycle. Defaults to `stable` when unspecified so
   * legacy callers do not need to thread the field through. Dream
   * promotes `stable` → `verified` once a preference accumulates
   * enough independent applied-evidence events; the lint --consolidate
   * pass can demote `stable` → `draft` for very old, never-applied
   * pages.
   */
  readonly lifecycle?: PageLifecycle;
  /**
   * Per-page importance tier. User-editable, unprefixed in YAML
   * (next to `pinned`). Reader-side default is `supporting`; emitted
   * only when supplied so legacy fixtures stay byte-identical.
   */
  readonly tier?: PageTier;
  /**
   * Optional commitment tier (Belief lifecycle suite, B3, t_e112c63c):
   * `exploring | leaning | decided | locked`. User-editable, unprefixed
   * in YAML. Validated on write; emitted only when supplied so legacy
   * fixtures stay byte-identical.
   */
  readonly commitment?: BrainCommitmentTier;
  readonly pinned?: boolean;
  /**
   * Directional freshness trend (Time-Aware Recall & Activation Suite,
   * t_ee09a6ce). Stamped by the dream refresh pass from the evidence
   * time distribution; emitted only when supplied so legacy fixtures
   * stay byte-identical. Recall reads it as a bounded ranking
   * multiplier; absent means neutral.
   */
  readonly freshness_trend?: string;
  /**
   * Brain Integrity Suite (v0.12.0). Optional monotonic write counter
   * persisted as `_revision`. `writePreferenceTxn` auto-stamps the
   * next value when callers omit. Direct `writePreference` callers
   * that omit the field skip the emission entirely - legacy fixtures
   * stay byte-identical (the reader treats absent as `0`).
   */
  readonly revision?: number;
  /**
   * Brain Integrity Suite (v0.12.0). Optional sha256 of the canonical
   * `(principle, scope)` pair persisted as `_content_hash`. Dream
   * supplies on promotion to `confirmed`; emitted verbatim when
   * supplied, omitted otherwise.
   */
  readonly content_hash?: string;
  readonly supersedes?: string;
  readonly aliases?: ReadonlyArray<string>;
  readonly schema_type?: string;
  readonly memory_layer?: BrainMemoryLayer;
  readonly memory_branch?: string;
  readonly related?: ReadonlyArray<string>;
  readonly extends?: ReadonlyArray<string>;
  readonly depends_on?: ReadonlyArray<string>;
  readonly refines?: ReadonlyArray<string>;
  readonly contradicts?: ReadonlyArray<string>;
  /**
   * Brain lifecycle suite (F5). Bi-temporal validity window, filled by
   * the dream promotion path from the source signal's ISO temporal
   * text. Emitted verbatim when supplied; absent leaves the field off.
   */
  readonly valid_from?: string;
  readonly valid_until?: string;
  /**
   * Caller-settable expiration (C5 / t_a82b674e). ISO date
   * (`YYYY-MM-DD`) or full timestamp. Additive and optional: absent →
   * the write is byte-identical to the historical path. When present it
   * is validated and stamped into frontmatter; the default read/list
   * path drops a preference past this date unless the caller opts into
   * `showExpired`. Orthogonal to dream retirement — the file is never
   * moved to `Brain/retired/` on expiry.
   */
  readonly expiration_date?: string;
  /**
   * Knowledge-pack provenance stamp (`<name>@<digest12>`), supplied only
   * by the pack installer. Emitted only when supplied, so every other
   * write is byte-identical. The key is user-tier to the frontmatter
   * merge, so a later framework rewrite (the dream refresh) that does not
   * pass it keeps the stamp instead of dropping it.
   */
  readonly knowledge_pack?: string;
  /** Optional extra tags merged after the canonical set. */
  readonly extraTags?: ReadonlyArray<string>;
  /** Free-form "How to apply" prose (rendered as a section). */
  readonly howToApply?: string;
  /**
   * Client-supplied idempotency key (C1 / t_213f356b). Additive and
   * optional: absent → the write is byte-identical to the historical
   * path. When present, the writer hashes the identity-defining fields
   * (slug, topic, principle, scope, status, evidenced_by — never the
   * timestamps or dream-owned counters) and consults the idempotency
   * ledger. A repeat with the same key + same payload is a deduped no-op;
   * the same key + a different payload throws
   * {@link IdempotencyPayloadMismatchError}. Used by the force-confirmed
   * feedback path and by C4's session checkpoint.
   */
  readonly idempotency_key?: string;
  /**
   * Recent `apply-evidence applied` rows for this pref, derived from
   * `Brain/log/`. Newest first. Used by {@link renderPreferenceBody}
   * to render `## Recent applications` so the file mirrors what the
   * counters say.
   */
  readonly recentApplied?: ReadonlyArray<BrainEvidenceSummary>;
  /**
   * Recent `apply-evidence violated` / `outdated` rows. Newest first.
   */
  readonly recentViolated?: ReadonlyArray<BrainEvidenceSummary>;
}

export interface WritePreferenceOptions {
  /** When true, overwrite an existing file at the target path. */
  readonly overwrite?: boolean;
  /**
   * Plugin config the writing agent's identity is resolved from when the
   * ownership gate stamps a newly created preference. Absent falls back
   * to the default config discovery, which is what every other core
   * writer that takes an identity does (`note.ts`, `decisions/record.ts`).
   * A surface that runs against a non-default config - the MCP server
   * started with `--config`, any `o2b brain` verb - passes its own, so
   * the stamped owner is the identity that surface answers under.
   */
  readonly configPath?: string;
  /**
   * The credential-minted subject of the caller (write-side-trust, Task
   * 7), when the transport resolved one. When present it WINS over the
   * config resolution everywhere this writer resolves an identity: the
   * owner-write gate's resolved identity, the subject the permissions
   * document is consulted under, and the owner stamped onto a newly
   * created preference. Absent (stdio, the CLI) keeps the
   * config-derived identity.
   */
  readonly subject?: WriteSubject;
  /**
   * Who decided this write, for the brain store dual write (task 1.11):
   * `human` (an operator command), `agent` (an agent or an automatic pass
   * such as dream) or `model` (a decision-model verdict). Absent derives
   * it from the process's origin channel (`authorityFromOrigin`). It does
   * not change the legacy file.
   */
  readonly authority?: Authority;
}

export interface ParsePreferenceOptions {
  readonly schemaVocabulary?: BrainSchemaVocabulary;
}

export interface WritePreferenceResult {
  readonly path: string;
  readonly id: string;
  /**
   * Set to `true` when an `idempotency_key` matched a prior write with an
   * identical payload, so this call was a deduped no-op. Absent on a
   * normal write, so existing callers are unaffected.
   */
  readonly deduped?: boolean;
}

export interface MoveToRetiredOptions {
  readonly now: Date;
  readonly retired_by: string;
  readonly superseded_by?: string;
  /**
   * Free-form reason supplied by `o2b brain reject --reason <text>`.
   * Persisted to the retired frontmatter as `user_rejected_reason`
   * and rendered in the `## Retired` body block. Required by the CLI
   * for `user-rejected` retires; left undefined for automatic
   * retire-reasons emitted by dream.
   */
  readonly user_rejected_reason?: string;
  /**
   * Pre-collected evidence slice to render into the retired snapshot.
   * Dream passes this to avoid re-scanning the log when it already
   * computed evidence during the refresh phase; the CLI reject path
   * leaves it undefined and {@link moveToRetired} collects internally.
   */
  readonly evidenceApplied?: ReadonlyArray<BrainEvidenceSummary>;
  readonly evidenceViolated?: ReadonlyArray<BrainEvidenceSummary>;
  /**
   * Opt-in per-preference audit (Brain lifecycle suite F1). When
   * supplied, a `retire` record is appended to the original
   * preference's audit trail (`pref-<slug>.jsonl`) so the whole
   * lifecycle stays in one file. The retire reason is taken from the
   * `reason` argument, not from the sink. Omitting it preserves
   * pre-suite behaviour (no audit file).
   */
  readonly audit?: { readonly agent: string };
  /**
   * Who decided this write, for the brain store dual write (task 1.11):
   * `human` (an operator command), `agent` (an agent or an automatic pass
   * such as dream) or `model` (a decision-model verdict). Absent derives
   * it from the process's origin channel (`authorityFromOrigin`). It does
   * not change the legacy file.
   */
  readonly authority?: Authority;
}

export interface MoveToRetiredResult {
  readonly path: string;
  readonly id: string;
}

// ----- Writer ---------------------------------------------------------------

/**
 * Write a preference atomically to `Brain/preferences/pref-<slug>.md`.
 *
 * The frontmatter snapshot includes every field on `BrainPreference`,
 * with safe defaults for the optional counters (zero) and confidence
 * (`low`). The body is the canonical three-section layout described in
 * §5.3 — "## Principle", "## Origin", "## How to apply".
 */
export function writePreference(
  vault: string | null,
  input: WritePreferenceInput,
  options: WritePreferenceOptions = {},
): WritePreferenceResult {
  // Vault-identity guard (context-integrity-gates, Unit J). This writer
  // reaches the tree through `preferencePath`, not `brainDirs`, so
  // `brainDirsForWrite` cannot cover it - the assertion has to sit at
  // the entry point, ahead of the field validation and every write.
  // With no vault the store write checks the store identity instead.
  if (vault !== null) assertVaultIdentityForWrite(vault);
  if (!input.slug?.trim()) throw new Error("preference missing field: slug");
  if (!input.topic?.trim()) throw new Error("preference missing field: topic");
  if (!input.principle?.trim()) {
    throw new Error("preference missing field: principle");
  }
  if (!input.created_at?.trim()) {
    throw new Error("preference missing field: created_at");
  }
  if (!input.unconfirmed_until?.trim()) {
    throw new Error("preference missing field: unconfirmed_until");
  }
  if (
    input.status !== BRAIN_PREFERENCE_STATUS.unconfirmed &&
    input.status !== BRAIN_PREFERENCE_STATUS.confirmed &&
    input.status !== BRAIN_PREFERENCE_STATUS.quarantine
  ) {
    throw new Error(
      `preference field 'status' must be 'unconfirmed', 'confirmed', or 'quarantine'; got ${JSON.stringify(input.status)}`,
    );
  }

  const slug = validateSlug(input.slug);
  const path = preferencePathOf(vault, slug);
  const id = `pref-${slug}`;

  // Every store record written from here on (an owner-write decision row,
  // the idempotency receipt, the preference's records, anything a writer
  // below appends) carries one verdict (`store/operation-scope.ts`): the
  // caller's fields as the page will carry them and its whole input, and
  // the page the write lands on, as it reads when the first record is
  // judged. Both sides of the merge a rewrite makes are so covered.
  const privacy = operationPrivacy(vault, {
    inherit: [
      () =>
        preferencePrivacy(vault, storeFieldsOf(preferenceFrontmatter(input, id)), [
          callerInput(input, PREFERENCE_OPAQUE_FIELDS),
        ])(),
      () =>
        vault !== null &&
        existsSync(path) &&
        preferencePrivacy(vault, storeFieldsOf(parseFrontmatter(path)[0]))(),
      // Store-only: the preference the write lands on, as the fold holds it.
      () =>
        preferencesStoreOnly(vault, options.configPath) &&
        (storePreferenceEntry(slug, options.configPath)?.private ?? false),
    ],
  });
  return withOperationPrivacy(privacy, () =>
    writeJudgedPreference(vault, input, options, slug, path, id),
  );
}

function writeJudgedPreference(
  vault: string | null,
  input: WritePreferenceInput,
  options: WritePreferenceOptions,
  slug: string,
  path: string,
  id: string,
): WritePreferenceResult {
  // Ownership (a-label-is-not-a-boundary, U1). Resolved BEFORE the
  // idempotency hash so a write that changes the owner cannot dedupe
  // against one that did not - the hash already folds `owner` in for
  // exactly that reason.
  const owned = withResolvedOwner(vault, path, input, options.configPath, options.subject);

  // Idempotency consult (C1): a repeat with the same key + same payload
  // dedupes; the same key + a different payload throws before any write.
  const idKey = owned.idempotency_key?.trim();
  let idContentHash: string | undefined;
  if (idKey) {
    idContentHash = computePayloadHash(preferencePayloadFields(owned, slug));
    const existing = lookupKey(vault, idKey);
    if (existing) {
      if (existing.contentHash === idContentHash) {
        return { path, id, deduped: true };
      }
      throw new IdempotencyPayloadMismatchError(idKey, existing.contentHash, idContentHash);
    }
  }

  if (vault === null || preferencesStoreOnly(vault, options.configPath)) {
    return writeStorePreference(vault, input, options, owned, path, id, idKey, idContentHash);
  }

  let metadata = preferenceFrontmatter(owned, id);
  const body = renderPreferenceBody(owned);

  if (options.overwrite && existsSync(path)) {
    // Tier guard (write-time-integrity-governance): rewrites merge
    // through the tier model so a user-tier field a human added by
    // hand survives, framework-owned legacy keys the writer no longer
    // emits are dropped, and a changed identity join key throws
    // instead of being silently re-accepted. An unreadable existing
    // file or schema pack falls back to the plain framework write.
    try {
      const [existingMeta] = parseFrontmatter(path);
      metadata = mergeFrontmatterTiered(existingMeta, metadata, {
        kind: "brain-preference",
        pack: loadSchemaPack(vault),
      });
    } catch (exc) {
      if (exc instanceof FrontmatterTierConflictError) throw exc;
    }
    // Content-level idempotency: skip the rename when the file would
    // be byte-identical. Keeps the dream invariant "a no-op rerun
    // must not rewrite preference files" even after v0.10.1 expanded
    // what dream recomputes per pass (evidence slices), and it spares
    // Syncthing peers from spurious sync events.
    try {
      const next = formatFrontmatter(metadata, body);
      const prev = readFileSync(path, "utf8");
      if (next === prev) {
        const unchanged = preferencePrivacy(vault, storeFieldsOf(metadata), [
          callerInput(input, PREFERENCE_OPAQUE_FIELDS),
        ]);
        recordPreferenceKey(vault, idKey, idContentHash, owned.created_at, id, path, unchanged);
        return { path, id };
      }
    } catch {
      // Fall through to the atomic write — a read failure should not
      // prevent a legitimate update.
    }
  }

  writeFrontmatterAtomic(path, metadata, body, {
    overwrite: options.overwrite ?? false,
    existsErrorKind: "preference",
    vaultForRelativePath: vault,
  });

  // One privacy verdict for every store record this write produces: the
  // idempotency receipt and the preference's human and derived records,
  // judged from the fields they carry and the caller's whole input.
  const written = withGuidance(storeFieldsOf(metadata), owned, metadata, body);
  const privacy = preferencePrivacy(vault, written, [callerInput(input, PREFERENCE_OPAQUE_FIELDS)]);
  recordPreferenceKey(vault, idKey, idContentHash, owned.created_at, id, path, privacy);
  // Brain store dual write (task 1.11): off by default, never fails this write.
  dualWrite(
    () =>
      preferenceStoreRecords(id, written, options.authority ?? authorityFromOrigin(), privacy()),
    { vault, ...(options.configPath !== undefined ? { configPath: options.configPath } : {}) },
  );
  return { path, id };
}

/**
 * The store-only preference write (task 2.10): no page, the preference's
 * records only. The rules the page writer keeps hold for the fold: a
 * create refuses a preference the fold already holds active (as the
 * exclusive create refuses an existing page), and an overwrite that would
 * change no field the fold holds writes nothing (the page writer's
 * byte-identical no-op), so a no-op dream rerun appends no record.
 */
function writeStorePreference(
  vault: string | null,
  input: WritePreferenceInput,
  options: WritePreferenceOptions,
  owned: WritePreferenceInput,
  path: string,
  id: string,
  idKey: string | undefined,
  idContentHash: string | undefined,
): WritePreferenceResult {
  const slug = id.slice("pref-".length);
  const found = storePreferenceEntry(slug, options.configPath);
  const live = found !== undefined && !isRetiredEntry(found) ? found : undefined;
  if (live !== undefined && options.overwrite !== true) {
    throw new FileAlreadyExistsError(path, {
      kind: "preference",
      displayPath: vault === null ? path : relative(vault, path),
    });
  }
  const frontmatter = preferenceFrontmatter(owned, id);
  const written = withGuidance(
    storeFieldsOf(frontmatter),
    owned,
    frontmatter,
    renderPreferenceBody(owned),
  );
  const privacy = preferencePrivacy(vault, written, [callerInput(input, PREFERENCE_OPAQUE_FIELDS)]);
  // A record only proposes the fields it names, so the fields a retired
  // life left in the fold are cleared explicitly (`null`): a retire's
  // metadata never rides on a live preference, and a slug brought back
  // starts with no prose of its old life, as a fresh page would.
  const cleared = clearedFields(found, written, live === undefined);
  if (
    options.overwrite === true &&
    Object.keys(cleared).length === 0 &&
    fieldsUnchanged(preferenceFields(written), live)
  ) {
    recordPreferenceKey(vault, idKey, idContentHash, owned.created_at, id, path, privacy);
    return { path, id };
  }
  const fields = { ...written, ...cleared };
  storeWrite(
    () => preferenceStoreRecords(id, fields, options.authority ?? authorityFromOrigin(), privacy()),
    { vault, ...(options.configPath !== undefined ? { configPath: options.configPath } : {}) },
  );
  recordPreferenceKey(vault, idKey, idContentHash, owned.created_at, id, path, privacy);
  return { path, id };
}

/** Fields only a retire writes: never part of a live preference. */
const RETIRE_ONLY_FIELDS: ReadonlyArray<string> = Object.freeze([
  "retired_at",
  "retired_reason",
  "retired_by",
  "superseded_by",
  "user_rejected_reason",
]);

/**
 * The fields of `found` a write of `written` must clear: the retire-only
 * ones it holds, and, when the write brings a retired slug back
 * (`revive`), every field of the old life the write does not name (its
 * prose, scope, aliases, merge pointer, rejection and guidance fields),
 * so the result is the fresh page an unswitched machine writes beside the
 * retired one. The counters are derived, never fields.
 */
function clearedFields(
  found: StorePreference | undefined,
  written: Readonly<Record<string, unknown>>,
  revive: boolean,
): Record<string, null> {
  const out: Record<string, null> = {};
  if (found === undefined) return out;
  const names = revive ? Object.keys(found.state.fields) : RETIRE_ONLY_FIELDS;
  for (const name of names) {
    const held = found.state.fields[name];
    if (!(name in written) && held !== undefined && held !== null) out[name] = null;
  }
  return out;
}

export {
  derivedPreferenceBody,
  preferencePageBody,
  preferencePageProse,
  withPreferenceProse,
} from "./preference-body.ts";

/**
 * The store fields of a `writePreference` write, with the page body as
 * `text` when the caller handed prose guidance (`howToApply`), the one
 * part of the body the fields do not render. A write without guidance
 * leaves `text` as it is: the page writer re-renders the body from the
 * fields, and prose another writer left in the fold is not overwritten.
 */
function withGuidance(
  fields: Record<string, unknown>,
  owned: WritePreferenceInput,
  meta: FrontmatterMap,
  body: string,
): Record<string, unknown> {
  if (!owned.howToApply?.trim()) return fields;
  const prose = preferencePageProse(meta, body, false);
  return prose === null ? fields : { ...fields, [PREFERENCE_TEXT_FIELD]: prose };
}

/**
 * The `owner:` a write emits, in one place for every writer.
 *
 * Three sources, in this order, and the order is the whole rule:
 *
 *   1. **The caller's explicit token** - after the owner-write gate has
 *      had its say ({@link gateNamedOwner}): the token still decides,
 *      but under `integrity.owner_scope_writes` a name that disagrees
 *      with the resolved identity is refused rather than honoured, so
 *      the claim a write records is one the caller was allowed to make.
 *      An absent explicit token skips the gate entirely, which is what
 *      keeps the restore and import paths byte-identical.
 *   2. **What the file already says.** A rewrite NEVER re-owns. Ownership
 *      is a property of the agent that created the memory, so a dream
 *      pass, a merge or a refresh run by anyone cannot quietly transfer
 *      it, and a page created before the gate was switched on stays
 *      shared rather than being retro-owned by whoever rewrote it first.
 *   3. **The server-resolved writing identity**, and only when creating a
 *      new file with `integrity.owner_scope_delivery` switched on.
 *
 * With the gate `off` this returns the input untouched, so a vault that
 * never opted in is byte-identical - the same contract `agent-scope.ts`
 * and the delivery collector state for the read side.
 *
 * `warn` stamps as `fail` does, deliberately: it exists so an operator
 * can see what `fail` would withhold before tightening the gate, and a
 * mode that wrote no ownership would leave nothing to look at.
 *
 * Where they look is the FILES. This stamp is the whole of `warn`'s
 * observability today: the read surfaces are inert under `warn`
 * (`owner-scope-view.ts` states why), so the population `fail` would
 * start withholding is visible by reading `owner:` off
 * `Brain/preferences/`, not by any per-response field.
 *
 * The gate is read through {@link loadIntegrityConfigForWrite}, NOT the
 * safe loader every reader uses. This is the WRITE side of the
 * reader/writer asymmetry that loader documents: an unreadable
 * `_brain.yaml` resolves STRICT for a reader, which only withholds more,
 * but strict here means STAMP - so a single bad token in the YAML would
 * have started marking new pages with an owner the operator never asked
 * for, permanently, since ownership is carried forward and never
 * re-derived. A writer cannot infer an intent to enable ownership from a
 * file it could not read, so the write is refused with the parse failure
 * named. Absent config is a different condition and still resolves to
 * the defaults, i.e. `off`.
 */
function withResolvedOwner(
  vault: string | null,
  path: string,
  input: WritePreferenceInput,
  configPath: string | undefined,
  subject?: WriteSubject,
): WritePreferenceInput {
  const owner = resolvedOwnerFor(vault, path, input.owner, configPath, subject);
  return owner === undefined ? input : { ...input, owner };
}

/**
 * The `owner:` value a NEW preference file at `path` must carry, or
 * `undefined` for "write no `owner:` field".
 *
 * The rule {@link withResolvedOwner} documents, exposed on its own so a
 * writer that does not build a {@link WritePreferenceInput} can still
 * ask it. `import-claude-memory.ts` is that writer: it renders its own
 * frontmatter and calls `atomicWriteFileSync` directly, so it never
 * reached `writePreference` and every memory it imported landed
 * ownerless and was then delivered to every agent - while the claim
 * "every production preference writer stamps the identity" was held true
 * by a hand-written list of four writers that did not include it.
 *
 * Exported rather than duplicated for that reason: a second copy of this
 * decision is how the fifth writer gets it wrong again.
 */
export function resolvedOwnerFor(
  vault: string | null,
  path: string,
  explicit: string | undefined,
  configPath: string | undefined,
  subject?: WriteSubject,
): string | undefined {
  const given = explicit?.trim();
  if (given) return gateNamedOwner(vault, path, given, configPath, subject);
  let mode: string;
  try {
    mode = loadIntegrityConfigForWrite(vault).owner_scope_delivery;
  } catch (err) {
    throw new Error(
      `preference owner cannot be resolved: Brain/_brain.yaml exists but could not be ` +
        `read (${err instanceof Error ? err.message : String(err)}), so whether ` +
        `integrity.owner_scope_delivery asks this write to stamp an owner is unknown. ` +
        `A writer does not guess that: stamping would mark this page with an owner the ` +
        `operator may never have asked for, and skipping would leave it shared under a ` +
        `gate that may be on. Fix the file, then re-run.`,
      { cause: err },
    );
  }
  if (mode === GATE_MODE.off) return undefined;
  if (vault === null || preferencesStoreOnly(vault, configPath)) {
    // Store-only: the preference the fold holds carries its owner forward.
    const held = storePreferenceEntry(basename(path, ".md").slice("pref-".length), configPath);
    if (held !== undefined && !isRetiredEntry(held)) {
      const owner = held.state.fields["owner"];
      return typeof owner === "string" && owner.trim() !== "" ? owner.trim() : undefined;
    }
  } else if (existsSync(path)) return carriedOwner(path).owner;
  const agent = subject?.agent ?? resolveAgentName(configPath);
  const stamp = ownerStampFor(agent);
  if (stamp === null) {
    throw new Error(
      `preference owner cannot be resolved: integrity.owner_scope_delivery is ` +
        `${JSON.stringify(mode)}, which stamps the writing agent onto every new ` +
        `preference, and the resolved identity ${JSON.stringify(agent)} does not ` +
        `reduce to one ownership token - it is blank, it is not one string, or it is a ` +
        `placeholder name (${JSON.stringify(UNCONFIGURED_AGENT_NAME)} and the rest of ` +
        `PLACEHOLDER_AGENT_VALUES), which owner-scope delivery refuses as an identity ` +
        `and therefore refuses as an owner; set VAULT_AGENT_NAME or 'agent_name' in ` +
        `the plugin config to a real, non-placeholder name`,
    );
  }
  return stamp;
}

/**
 * The owner-write gate (write-side-trust, Task 8), consulted ONLY on the
 * explicit-owner arm: a caller-named owner is a claim, and
 * `integrity.owner_scope_writes` decides whether this caller may make it.
 * An absent explicit token never reaches here, so the restore and import
 * paths are byte-identical whatever the gate says.
 *
 * The gate mode reads through {@link loadIntegrityConfigSafe}, NOT the
 * writer loader the stamp arm uses, and the difference is the same
 * reader/writer asymmetry the stamp arm documents, resolved the other way
 * for a refusal gate. Strict here means REFUSE - the unreadable config
 * cannot loosen this gate, it can only close it - so failing closed to
 * `fail` is the conservative direction and the operator's typo stops the
 * foreign-owner write instead of waving it through. An unreadable
 * permissions document raises through Lane A's loader with the field
 * named, which is that document's own fail-closed contract.
 *
 * Under `warn` a cross-owner write passes and exactly one decision-ledger
 * row is appended with the gate key as its source: warn exists so an
 * operator can watch what `fail` would refuse, and the row IS the
 * watching. The row condition recomputes the same normalised comparison
 * the predicate makes - the module exposes only the pinned predicate and
 * key - and only the case `fail` would refuse logs, so a matching-owner
 * write stays silent.
 *
 * A failed ledger append never fails the write: the append contract
 * returns `audit_reason` instead of throwing, and the verdict the caller
 * already received must not be retroactively withdrawn because
 * accountability could not be recorded.
 */
function gateNamedOwner(
  vault: string | null,
  path: string,
  given: string,
  configPath: string | undefined,
  subject?: WriteSubject,
): string {
  // The credential-minted subject wins over the config resolution
  // (write-side-trust, Task 7): a token's owner gate answers for the
  // token's agent, never for whoever the process config names.
  const resolved = subject?.agent ?? resolveAgentName(configPath);
  const gateMode = loadIntegrityConfigSafe(vault).owner_scope_writes;
  // The permissions document: the operator's shared setting, or the legacy
  // file on an unswitched machine (document-source.ts).
  const { document } = loadPermissionsDocumentFor(vault, configPath);
  const verdict = refuseCrossOwnerWrite({
    explicitOwner: given,
    resolvedIdentity: resolved,
    gateMode,
    document,
    subject: substrateSubject(subject ?? { agent: resolved, via: "config" }),
  });
  if (verdict.refused) {
    throw new Error(
      `preference write at ${vault === null ? path : relative(vault, path)}: ${verdict.reason}`,
    );
  }
  if (gateMode === GATE_MODE.warn) {
    logWatchedOwnerWrite(vault, path, given, resolved, subject?.via ?? "config");
  }
  return given;
}

/**
 * The one `warn` ledger row for an explicit-owner preference write, or
 * nothing when the named owner agrees with the resolved identity (the
 * one case `fail` would not refuse is the one case there is nothing to
 * watch).
 */
function logWatchedOwnerWrite(
  vault: string | null,
  path: string,
  given: string,
  resolved: string,
  via: WriteSubject["via"] = "config",
): void {
  const named = normalizeAgentScope(given);
  const identity = normalizeAgentScope(normalizeAgentArgument(resolved) ?? undefined);
  if (named === null || identity === null || named === identity) return;
  appendDecisionLedger(vault, {
    ts: new Date().toISOString(),
    actor: resolved,
    via,
    action: "owner_write",
    target: vault === null ? path : relative(vault, path),
    verdict: GATE_MODE.warn,
    source: OWNER_SCOPE_WRITES_KEY,
    reason:
      `explicit owner ${JSON.stringify(given)} allowed under ${GATE_MODE.warn}; ` +
      `${OWNER_SCOPE_WRITES_KEY}=${GATE_MODE.fail} would refuse it ` +
      `(resolved identity ${JSON.stringify(resolved)})`,
  });
}

/** Attribution recorded on the notices the ownership carry-forward reads produce. */
const OWNER_CARRY_SITE = "brain.preference.owner";

/**
 * The ownership claim an existing preference file already carries, as a
 * spreadable slice - `{}` when the file makes no claim this parser can
 * reduce to one token.
 *
 * An unreadable file RAISES rather than resolving to `{}`. Every other
 * degraded read on this path can afford to fall soft, but this one
 * decides a boundary: resolving to "no claim" would republish an
 * owner-private memory to every agent on the next rewrite, and nothing
 * would have said so. A claim the parser cannot reduce to one token
 * (`owner:` as a list or a mapping) is left alone instead, because the
 * tiered frontmatter merge preserves it verbatim and re-emitting it as a
 * normalised string would rewrite bytes this writer does not own.
 */
function carriedOwner(path: string): { owner?: string } {
  const [meta, , notices] = parseFrontmatterWithNotices(path, { site: OWNER_CARRY_SITE });
  const unreadable = notices.find((n) => n.code === DEGRADATION_CODE.frontmatterUnreadable);
  if (unreadable) {
    throw new Error(
      `preference owner cannot be carried forward: ${path} exists but could not be ` +
        `read (${unreadable.detail}), so the ownership this rewrite must preserve ` +
        `is unknown`,
    );
  }
  const raw = meta["owner"];
  return typeof raw === "string" && raw.trim().length > 0 ? { owner: raw.trim() } : {};
}

/**
 * The identity-defining fields of a preference for idempotency hashing.
 * Timestamps, dream-owned counters, and confidence are excluded so a
 * retried write (or a force-confirmed re-record) with the same rule
 * dedupes regardless of when it arrives.
 */
function preferencePayloadFields(
  input: WritePreferenceInput,
  slug: string,
): Record<string, unknown> {
  return {
    slug,
    topic: input.topic.trim(),
    principle: sanitisePrinciple(input.principle),
    scope: input.scope?.trim(),
    status: input.status,
    evidenced_by: [...input.evidenced_by],
    // `owner` drives owner-scoped visibility and is written to frontmatter,
    // so a retry that only changes it must NOT silently dedupe — fold it into
    // the idempotency hash (mirrors the write path at recordPreference).
    owner: input.owner?.trim(),
  };
}

/**
 * Record the idempotency key after a successful preference write so a
 * future retry dedupes. No-op when no key was supplied.
 */
function recordPreferenceKey(
  vault: string | null,
  idKey: string | undefined,
  contentHash: string | undefined,
  createdAt: string,
  id: string,
  path: string,
  privacy: OperationPrivacy,
): void {
  if (!idKey || contentHash === undefined) return;
  rememberKey(vault, {
    key: idKey,
    contentHash,
    createdAt,
    ref: { id, path: vault === null ? path : relative(vault, path) },
    private: privacy,
  });
}

/**
 * Predicate twin of {@link writePreference}'s content-equality
 * short-circuit. Returns `true` iff calling `writePreference(vault,
 * input, { overwrite: true })` would change the on-disk bytes
 * (file missing, or file present with different content). The dream
 * pass uses this to decide whether a pref needs to land in the
 * refresh set — emitting a refresh entry triggers a snapshot + log
 * event, so we must not emit one if the rewrite would be a no-op.
 *
 * Cheap: one stat + one readFileSync + one render of frontmatter +
 * body. Caller-side cost is negligible compared with the writePref
 * + log overhead avoided when the body is up to date.
 */
export function wouldRewritePreference(vault: string | null, input: WritePreferenceInput): boolean {
  const slug = validateSlug(input.slug);
  const path = preferencePathOf(vault, slug);
  if (vault === null || preferencesStoreOnly(vault)) {
    // Store-only: the write changes something when a field the fold holds
    // would take a new value (the store twin of the byte comparison).
    try {
      const found = storePreferenceEntry(slug);
      if (found === undefined || isRetiredEntry(found)) return true;
      const owned = withResolvedOwner(vault, path, input, undefined);
      const frontmatter = preferenceFrontmatter(owned, `pref-${slug}`);
      const written = withGuidance(
        storeFieldsOf(frontmatter),
        owned,
        frontmatter,
        renderPreferenceBody(owned),
      );
      return !fieldsUnchanged(preferenceFields(written), found);
    } catch {
      return true;
    }
  }
  if (!existsSync(path)) return true;
  try {
    const id = `pref-${slug}`;
    // The same ownership resolution the write performs, or this
    // predicate reports "would change" on every owner-carrying
    // preference forever: `writePreference` carries the existing owner
    // forward, and a render that omitted it would never match the bytes
    // on disk. No config path is needed - the file exists, so the
    // resolution can only carry forward, never stamp.
    const owned = withResolvedOwner(vault, path, input, undefined);
    const rendered = preferenceFrontmatter(owned, id);
    const body = renderPreferenceBody(owned);
    // The same tier merge the overwrite write performs, or this
    // predicate reports "would change" on every pass forever against a
    // file carrying a user-tier field the render does not emit: the
    // merge preserves the field, the comparison against a render that
    // dropped it never matches, and each pass re-plans the rewrite the
    // previous pass just performed. The write's fallback order is
    // mirrored too - an unreadable existing file or schema pack
    // compares against the plain render.
    let metadata = rendered;
    try {
      const [existingMeta] = parseFrontmatter(path);
      metadata = mergeFrontmatterTiered(existingMeta, rendered, {
        kind: "brain-preference",
        pack: loadSchemaPack(vault),
      });
    } catch (exc) {
      if (exc instanceof FrontmatterTierConflictError) throw exc;
    }
    const next = formatFrontmatter(metadata, body);
    const prev = readFileSync(path, "utf8");
    return next !== prev;
  } catch {
    // Conservative: a read or render failure should not silently
    // mark the file as up-to-date.
    return true;
  }
}

function preferenceFrontmatter(input: WritePreferenceInput, id: string): FrontmatterMap {
  const tags = composePreferenceTags(input);
  const confidence = input.confidence ?? BRAIN_CONFIDENCE.low;
  const pinned = input.pinned ?? false;
  const applied = input.applied_count ?? 0;
  const violated = input.violated_count ?? 0;
  // Round numeric confidence to 4 decimals so a no-op rerun produces
  // byte-identical YAML even if upstream callers pass a value with
  // floating-point jitter. `null` sentinel mirrors the other Group C
  // null-encoded fields so the simple parser keeps round-tripping.
  const confidenceValueRaw = input.confidence_value;
  const confidenceValueField =
    confidenceValueRaw === undefined || confidenceValueRaw === null
      ? "null"
      : Math.round(confidenceValueRaw * 10000) / 10000;

  // §24: Group C derived fields gain `_` prefix so the visual
  // boundary between "what dream owns" and "what the user owns"
  // becomes obvious in Obsidian. Identity (`kind`, `id`, `created_at`,
  // `unconfirmed_until`, `topic`, `principle`, `scope`, `tags`,
  // `aliases`, `supersedes`) and user-editable (`pinned`) stay
  // unprefixed. Parser accepts both shapes; writer only emits the new.
  const metadata: FrontmatterMap = {
    kind: "brain-preference",
    id,
    created_at: input.created_at,
    // Use a textual sentinel for `null` so the simple parser surfaces
    // an empty string and the loader coerces back to `null`. We store
    // the literal text "null" rather than an empty value to keep the
    // emitted YAML one-token per line and the field always present.
    _confirmed_at: input.confirmed_at ?? "null",
    unconfirmed_until: input.unconfirmed_until,
    tags: [...tags],
    topic: input.topic.trim(),
    _status: input.status,
    principle: sanitisePrinciple(input.principle),
    _evidenced_by: [...input.evidenced_by],
    _applied_count: applied,
    _violated_count: violated,
    _last_evidence_at: input.last_evidence_at ?? "null",
    _confidence: confidence,
    _confidence_value: confidenceValueField,
    pinned,
  };
  // Brain Integrity Suite additive fields. Both follow the
  // `_lifecycle` precedent: emit only when the caller supplies a
  // value so legacy fixtures and the starter bundle stay
  // byte-identical with absent-as-default reader semantics.
  if (input.revision !== undefined) metadata["_revision"] = input.revision;
  if (input.content_hash) metadata["_content_hash"] = input.content_hash;
  if (input.scope?.trim()) metadata["scope"] = input.scope.trim();
  if (input.owner?.trim()) metadata["owner"] = input.owner.trim();
  if (input.knowledge_pack?.trim()) {
    metadata[KNOWLEDGE_PACK_FIELD] = input.knowledge_pack.trim();
  }
  // Only emit a non-default provenance; absent reads as `stated`, so an
  // existing preference stays byte-identical.
  if (input.provenance !== undefined && input.provenance !== "stated") {
    metadata["provenance"] = input.provenance;
  }
  if (input.supersedes?.trim()) metadata["supersedes"] = input.supersedes.trim();
  if (input.aliases && input.aliases.length > 0) {
    metadata["aliases"] = [...input.aliases];
  }
  if (input.schema_type?.trim()) {
    metadata["schema_type"] = validateSchemaToken(input.schema_type, "schema_type");
  }
  if (input.memory_layer !== undefined) {
    metadata["memory_layer"] = validateMemoryLayer(input.memory_layer, "writePreference");
  }
  if (input.memory_branch?.trim()) {
    metadata["memory_branch"] = validateMemoryBranch(input.memory_branch, "writePreference");
  }
  for (const field of PREFERENCE_RELATION_FIELDS) {
    const values = input[field];
    if (values && values.length > 0) metadata[field] = [...values];
  }
  // `_lifecycle` is emitted only when the caller supplies it. Legacy
  // call sites stay byte-identical; new writers (dream refresh pass,
  // lint consolidate) opt in by passing the field. Readers fall back
  // to `stable` via `readLifecycle()`.
  if (input.lifecycle !== undefined) {
    metadata["_lifecycle"] = input.lifecycle;
  }
  // `tier` is user-editable (unprefixed). Emitted only when supplied;
  // readers fall back to `supporting` via `readTier()`.
  if (input.tier !== undefined) {
    metadata["tier"] = input.tier;
  }
  // `commitment` tier (B3): validated on write, emitted only when a valid
  // tier is supplied so unset preferences stay byte-identical.
  const commitment = validateCommitmentTier(input.commitment);
  if (commitment !== null) {
    metadata["commitment"] = commitment;
  }
  // Brain lifecycle suite (F5): bi-temporal validity, emitted only when
  // supplied (e.g. dream filled it from the source signal's ISO text).
  // Reader-side support already exists via readBitemporalSlots; legacy
  // callers stay byte-identical.
  if (input.valid_from?.trim()) metadata["valid_from"] = input.valid_from.trim();
  if (input.valid_until?.trim()) metadata["valid_until"] = input.valid_until.trim();
  // Caller-settable expiration (C5): validated + emitted only when
  // supplied so legacy callers stay byte-identical. Reader-side support
  // is via parsePreference's optional-scalar read + the expiration filter.
  if (input.expiration_date?.trim()) {
    metadata[EXPIRATION_DATE_FIELD] = normalizeExpirationDate(input.expiration_date);
  }
  // Freshness trend (t_ee09a6ce): stamped by the dream refresh pass;
  // emitted only when supplied so legacy callers stay byte-identical.
  if (input.freshness_trend?.trim()) metadata["freshness_trend"] = input.freshness_trend.trim();
  if (input.visibility !== undefined && input.visibility.length > 0) {
    metadata["visibility"] = [...input.visibility];
  }
  return metadata;
}

function composePreferenceTags(input: WritePreferenceInput): string[] {
  const out: string[] = [];
  const seen = new Set<string>();
  const push = (t: string): void => {
    if (!seen.has(t)) {
      seen.add(t);
      out.push(t);
    }
  };
  // Composed values obey the ONE shared tag rule (`src/core/tags.ts`, via
  // `tag-syntax.ts`), with the same polarity as the signal composer: the
  // topic segment is slugified then validated; scope segments and
  // `extraTags` entries are caller-controlled input, refused unrewritten
  // with the field named. A comma-separated scope composes one tag per
  // segment (`scopeTagValues`); `lenientScopeTags` relaxes the scope
  // refusal for rewrites of persisted records.
  push("brain");
  push("brain/preference");
  push(`brain/topic/${requireObsidianTagValue(slugify(input.topic.trim()), "topic")}`);
  for (const scope of scopeTagValues(input.scope ?? "", {
    record: `pref-${input.slug}`,
    lenient: input.lenientScopeTags === true,
  })) {
    push(`brain/scope/${scope}`);
  }
  for (const t of input.extraTags ?? []) {
    if (t.trim()) push(requireObsidianTagValue(t.trim(), "extraTags"));
  }
  return out;
}

// ----- Parsers --------------------------------------------------------------

export { DERIVED_FIELDS };

/**
 * Rename `_`-prefixed Group C keys (`_status`, `_applied_count`, ...)
 * to their canonical un-prefixed form so every downstream
 * `meta[name]` call site keeps working. Returns a shallow copy of
 * `meta`; original is untouched. Exported because the backlink
 * index and other raw-frontmatter consumers need the same rule.
 */
export function normalizeDerivedKeys(meta: Record<string, unknown>): Record<string, unknown> {
  const out: Record<string, unknown> = { ...meta };
  for (const name of DERIVED_FIELDS) {
    if (name in out && out[name] !== undefined) {
      throw new Error(
        `frontmatter field '${name}' must use the '_'-prefixed shape ('_${name}'); ` +
          "un-prefixed Group C keys are no longer accepted",
      );
    }
    const prefixed = `_${name}`;
    if (prefixed in out && out[prefixed] !== undefined) {
      out[name] = out[prefixed];
      delete out[prefixed];
    }
  }
  return out;
}

/**
 * A preference's frontmatter under the field names the brain store folds
 * (dual writes, task 1.11): derived keys lose their on-disk `_` prefix and
 * the textual `"null"` sentinel becomes `null`, so the store holds what
 * the file means rather than how it is spelled.
 */
export function storeFieldsOf(meta: Record<string, unknown>): Record<string, unknown> {
  const out = normalizeDerivedKeys(meta);
  for (const name of DERIVED_FIELDS) if (out[name] === "null") out[name] = null;
  return out;
}

const DERIVED_FIELD_SET: ReadonlySet<string> = new Set(DERIVED_FIELDS);

/** The derived field a retire decides itself, at the retiring caller's authority. */
const RETIRE_DECIDED_FIELDS: ReadonlyArray<string> = Object.freeze(["status"]);

/**
 * The single privacy verdict of a preference write
 * (`store/operation-privacy.ts`), from the fields the store records carry:
 * the frontmatter reserving the preference as private, or any content
 * field (`principle`, `evidenced_by`, `supersedes` and the other
 * relationship fields, ...) naming a private or unresolvable page or
 * carrying a `<private>` region. `extra` is further content of the same
 * operation (the writer's caller input, a pin's log event). Judged once,
 * on first use.
 */
export function preferencePrivacy(
  vault: string | null,
  fields: Readonly<Record<string, unknown>>,
  extra: ReadonlyArray<JudgedContent> = [],
): OperationPrivacy {
  return operationPrivacy(vault, {
    target: () => isPrivateFrontmatter(fields),
    content: [{ value: fields, opaque: PREFERENCE_OPAQUE_FIELDS }, ...extra],
  });
}

/**
 * The brain store records of one preference write (dual writes, task
 * 1.11). Fields the fold resolves by authority first: when a human writes,
 * only the fields the human decided carry human authority. The derived
 * fields the dream pass owns ({@link DERIVED_FIELDS}, minus `decided`, the
 * ones this write itself decides) go out in a second record at agent
 * authority, so a later dream write can still win them, as it does on the
 * file. Every record keeps the scope the whole preference has and the
 * partition of the write's one privacy verdict (`isPrivate`).
 */
export function preferenceStoreRecords(
  id: string,
  fields: Readonly<Record<string, unknown>>,
  authority: Authority,
  isPrivate: boolean,
  decided: ReadonlyArray<string> = [],
): DualWriteRecord[] | null {
  const whole = preferenceSetRecord({ id, frontmatter: fields, authority, private: isPrivate });
  if (whole === null) return null;
  if (authority !== "human") return [whole];
  const keep = new Set(decided);
  const own: Record<string, unknown> = {};
  const derived: Record<string, unknown> = {};
  for (const [name, value] of Object.entries(fields)) {
    if (DERIVED_FIELD_SET.has(name) && !keep.has(name)) derived[name] = value;
    else own[name] = value;
  }
  const placement = { scope: whole.scope ?? null };
  const out: DualWriteRecord[] = [];
  for (const record of [
    preferenceSetRecord({ id, frontmatter: own, authority, private: isPrivate }),
    preferenceSetRecord({ id, frontmatter: derived, authority: "agent", private: isPrivate }),
  ]) {
    if (record !== null) out.push({ ...record, ...placement });
  }
  return out;
}

/**
 * Parse a preference file. Defaults `pinned` to `false` when the field
 * is absent (§5.3). Throws {@link BrainStatusFolderMismatchError} when
 * the file lives in `preferences/` but its `status` reads `retired`
 * (or any other state outside `unconfirmed` / `confirmed`).
 *
 * Derived Group C fields use the `_`-prefixed shape on disk
 * (`_status:`, `_applied_count:`, ...); {@link normalizeDerivedKeys}
 * renames them to the un-prefixed form for downstream readers.
 */
export function parsePreference(
  path: string,
  options: ParsePreferenceOptions = {},
): BrainPreference {
  // The body is unused for preferences — it is purely human prose;
  // every machine-actionable field lives in the frontmatter.
  return preferenceFromMeta(parseFrontmatter(path)[0], path, options);
}

/**
 * The preference `pref-<slug>` of the vault: its page on an unswitched
 * machine, the store's fold once switched (task 2.10), or `null` when it
 * does not exist (or is retired). Parsed by the same rules either way.
 */
export function loadPreference(
  vault: string | null,
  slug: string,
  options: ParsePreferenceOptions & { readonly configPath?: string } = {},
): BrainPreference | null {
  const path = preferencePathOf(vault, slug);
  // No vault means store-only too (design D14).
  if (vault === null || preferencesStoreOnly(vault, options.configPath)) {
    const page = storePreferenceMeta(slug, options.configPath);
    return page === null || page.retired ? null : preferenceFromMeta(page.meta, path, options);
  }
  return existsSync(path) ? parsePreference(path, options) : null;
}

/**
 * Whether the preference `pref-<slug>` is active, retired or absent: its
 * pages on an unswitched machine, the store's fold once switched.
 */
export function preferencePresence(
  vault: string | null,
  slug: string,
  configPath?: string,
): "active" | "retired" | "absent" {
  if (vault === null || preferencesStoreOnly(vault, configPath)) {
    const entry = storePreferenceEntry(slug, configPath);
    if (entry === undefined) return "absent";
    return isRetiredEntry(entry) ? "retired" : "active";
  }
  if (existsSync(preferencePath(vault, slug))) return "active";
  return existsSync(retiredPath(vault, slug)) ? "retired" : "absent";
}

/**
 * The preference `pref-<slug>` as its page would carry it, rebuilt from
 * the store's fold: the fold's fields under their on-disk names (derived
 * fields `_`-prefixed, `null` as the textual sentinel), the counters the
 * fold derives, and the page's identity keys. The result goes through the
 * page writer and parser once, so every value has the type the legacy
 * parser gives it. `null` when the fold does not hold the preference.
 */
export function storePreferenceMeta(
  slug: string,
  configPath?: string,
): {
  readonly meta: FrontmatterMap;
  readonly retired: boolean;
  /** The page body the fold carries (`text`), or `null` when no writer wrote one. */
  readonly text: string | null;
} | null {
  const entry = storePreferenceEntry(slug, configPath);
  if (entry === undefined) return null;
  return { ...storeEntryMeta(entry, slug), text: textOfFields(entry.state.fields) };
}

function preferenceFromMeta(
  rawMeta: FrontmatterMap,
  path: string,
  options: ParsePreferenceOptions,
): BrainPreference {
  const meta = normalizeDerivedKeys(rawMeta);

  requireField(meta, "kind", path);
  if (meta["kind"] !== "brain-preference") {
    throw new BrainParseError(
      `preference kind must be 'brain-preference'; got ${JSON.stringify(meta["kind"])}`,
      path,
    );
  }

  const status = requireString(meta, "status", path);
  // Reject unknown status values BEFORE the folder invariant: a malformed
  // file should never coerce into a typed `BrainPreference.status`
  // downstream, regardless of which folder it sits in. We tolerate
  // `status: "retired"` here because that case is the dedicated
  // status-folder-mismatch the parser surfaces below as a typed error
  // (doctor downgrades it to a warning) — see §4 of the design doc.
  const statusValues = Object.values(BRAIN_PREFERENCE_STATUS) as ReadonlyArray<string>;
  // `tombstoned` (Belief lifecycle suite, t_7d5a3589) is a cross-type
  // lifecycle status the tombstone module stamps into `_status` in place.
  // It is tolerated on read - like `retired` - so an audit read and the
  // doctor see a coherent tombstoned entry rather than a corrupt file;
  // recall / inject / active.md / dream exclude it via `isTombstoned`.
  if (!statusValues.includes(status) && status !== "retired" && status !== BRAIN_TOMBSTONE_STATUS) {
    throw new BrainParseError(
      `preference status must be one of ${statusValues.join(", ")}; got ${JSON.stringify(status)}`,
      path,
    );
  }
  enforceStatusFolderInvariant(path, status, "preferences");

  const id = requireString(meta, "id", path);
  const created_at = requireString(meta, "created_at", path);
  const unconfirmed_until = requireString(meta, "unconfirmed_until", path);
  const tags = requireStringArray(meta, "tags", path);
  const topic = requireString(meta, "topic", path);
  const principle = requireString(meta, "principle", path);

  const evidenced_by = optionalStringArray(meta, "evidenced_by", path);
  const confirmed_at = optionalNullableString(meta, "confirmed_at", path);
  const last_evidence_at = optionalNullableString(meta, "last_evidence_at", path);
  // Provenance level: validated through the shared narrowing guard, never cast.
  const provenance = asProvenanceLevel(meta["provenance"]);

  const result: BrainPreference = {
    kind: "brain-preference",
    id,
    created_at,
    confirmed_at,
    unconfirmed_until,
    tags,
    topic,
    status: status as BrainPreferenceStatus,
    principle,
    evidenced_by,
    applied_count: optionalNumber(meta, "applied_count", 0, path),
    violated_count: optionalNumber(meta, "violated_count", 0, path),
    last_evidence_at,
    confidence: parseConfidence(meta, path),
    confidence_value: parseConfidenceValue(meta, path),
    pinned: parsePinned(meta),
    revision: optionalNumber(meta, "revision", 0, path),
    ...(optionalScalarString(meta, "content_hash") !== undefined
      ? { content_hash: optionalScalarString(meta, "content_hash") }
      : {}),
    ...(optionalScalarString(meta, "scope") !== undefined
      ? { scope: optionalScalarString(meta, "scope") }
      : {}),
    ...(optionalOwnerField(meta) !== undefined ? { owner: optionalOwnerField(meta) } : {}),
    ...(provenance !== null ? { provenance } : {}),
    ...(optionalScalarString(meta, "freshness_trend") !== undefined
      ? { freshness_trend: optionalScalarString(meta, "freshness_trend") }
      : {}),
    ...(optionalScalarString(meta, "expiration_date") !== undefined
      ? { expiration_date: optionalScalarString(meta, "expiration_date") }
      : {}),
    // Surfaced only when the value is a well-formed stamp: a hand-typed
    // `knowledge_pack:` that is not one names no pack an uninstall keys on.
    ...(parseKnowledgePackStamp(meta[KNOWLEDGE_PACK_FIELD]) !== null
      ? { knowledge_pack: String(meta[KNOWLEDGE_PACK_FIELD]).trim() }
      : {}),
    ...(optionalScalarString(meta, "supersedes") !== undefined
      ? { supersedes: optionalScalarString(meta, "supersedes") }
      : {}),
    ...(readMergedInto(meta) !== null ? { merged_into: readMergedInto(meta)! } : {}),
    ...(readCommitmentTier(meta) !== null ? { commitment: readCommitmentTier(meta)! } : {}),
    ...(meta["aliases"] !== undefined && Array.isArray(meta["aliases"])
      ? { aliases: [...(meta["aliases"] as ReadonlyArray<string>)] }
      : {}),
    ...spreadSchemaMetadata(meta, path, "preference_types", options),
    ...spreadMemorySemantics(meta, path),
    ...spreadBiTemporal(meta),
  };
  return Object.freeze(result);
}

// `promised_to` stays out: pledge projection rides the shared
// frontmatter-relations ingest (see relation-vocab.ts), and the
// dated-commitments design rejects projecting pledges into preference
// facts as duplication.
type PreferenceRelationField = Exclude<DefaultRelationType, "superseded_by" | "promised_to">;

const PREFERENCE_RELATION_FIELDS = Object.freeze(
  DEFAULT_RELATION_TYPES.filter(
    (field): field is PreferenceRelationField =>
      field !== "superseded_by" && field !== "promised_to",
  ),
);

function spreadMemorySemantics(
  meta: Record<string, unknown>,
  path: string,
): {
  readonly memory_layer?: BrainMemoryLayer;
  readonly memory_branch?: string;
  readonly related?: ReadonlyArray<string>;
  readonly extends?: ReadonlyArray<string>;
  readonly depends_on?: ReadonlyArray<string>;
  readonly refines?: ReadonlyArray<string>;
  readonly contradicts?: ReadonlyArray<string>;
} {
  const out: Record<string, BrainMemoryLayer | string | ReadonlyArray<string>> = {};
  const memoryLayer = optionalScalarString(meta, "memory_layer");
  if (memoryLayer !== undefined) {
    out["memory_layer"] = validateMemoryLayer(memoryLayer, path);
  }
  const memoryBranch = optionalScalarString(meta, "memory_branch");
  if (memoryBranch !== undefined) {
    out["memory_branch"] = validateMemoryBranch(memoryBranch, path);
  }
  for (const field of PREFERENCE_RELATION_FIELDS) {
    const values = optionalStringList(meta, field, path);
    if (values !== undefined) out[field] = values;
  }
  return out;
}

function spreadSchemaMetadata(
  meta: Record<string, unknown>,
  path: string,
  category: "preference_types" | "signal_types",
  options: ParsePreferenceOptions,
): { readonly schema_type?: string } {
  const raw = optionalScalarString(meta, "schema_type");
  if (raw === undefined) return {};
  const schemaType = validateSchemaToken(raw, "schema_type");
  const vocab = options.schemaVocabulary;
  if (vocab !== undefined && !isKnownSchemaToken(vocab, category, schemaType)) {
    throw new BrainParseError(
      `schema_type ${JSON.stringify(schemaType)} is not declared in ${category}`,
      path,
    );
  }
  return { schema_type: schemaType };
}

function validateMemoryLayer(value: string, path: string): BrainMemoryLayer {
  if (isBrainMemoryLayer(value)) return value;
  const allowed = Object.values(BRAIN_MEMORY_LAYER).join(", ");
  throw new BrainParseError(
    `preference field 'memory_layer' must be one of ${allowed}; got ${JSON.stringify(value)}`,
    path,
  );
}

function validateMemoryBranch(value: string, path: string): string {
  try {
    return validateSlug(value);
  } catch (err) {
    const reason = err instanceof Error ? err.message : String(err);
    throw new BrainParseError(`preference field 'memory_branch' is invalid: ${reason}`, path, {
      cause: err,
    });
  }
}

/**
 * Read the additive bi-temporal slots (`valid_from`, `valid_until`,
 * `recorded_at`) from a frontmatter map. Returns a partial object
 * with only the slots the file actually carries; absent on legacy
 * files. Shared between `parsePreference` and `parseRetired` so the
 * spread call site stays one-line and the slot names live in exactly
 * one place.
 */
function spreadBiTemporal(meta: Record<string, unknown>): {
  readonly valid_from?: string;
  readonly valid_until?: string;
  readonly recorded_at?: string;
} {
  const validFrom = optionalScalarString(meta, "valid_from");
  const validUntil = optionalScalarString(meta, "valid_until");
  const recordedAt = optionalScalarString(meta, "recorded_at");
  return {
    ...(validFrom !== undefined ? { valid_from: validFrom } : {}),
    ...(validUntil !== undefined ? { valid_until: validUntil } : {}),
    ...(recordedAt !== undefined ? { recorded_at: recordedAt } : {}),
  };
}

/**
 * Parse a retired-preference file. Mirrors {@link parsePreference} but
 * enforces the `retired/` folder invariant and validates the
 * `retired_reason` enum.
 *
 * Shares {@link normalizeDerivedKeys} with `parsePreference` so
 * both forms of Group C frontmatter parse identically.
 */
export function parseRetired(path: string, options: ParsePreferenceOptions = {}): BrainRetired {
  return parseRetiredMeta(parseFrontmatter(path)[0], path, options);
}

/**
 * {@link parsePreference} over frontmatter already read: a page's, or one
 * rebuilt from the store's fold ({@link storePreferenceMeta}), so a reader
 * that switched to the store parses by the page's rules (task 2.10).
 */
export function parsePreferenceMeta(
  meta: FrontmatterMap,
  path: string,
  options: ParsePreferenceOptions = {},
): BrainPreference {
  return preferenceFromMeta(meta, path, options);
}

/** {@link parseRetired} over frontmatter already read (see {@link parsePreferenceMeta}). */
export function parseRetiredMeta(
  rawMeta: FrontmatterMap,
  path: string,
  options: ParsePreferenceOptions = {},
): BrainRetired {
  const meta = normalizeDerivedKeys(rawMeta);

  requireField(meta, "kind", path);
  if (meta["kind"] !== "brain-retired") {
    throw new BrainParseError(
      `retired kind must be 'brain-retired'; got ${JSON.stringify(meta["kind"])}`,
      path,
    );
  }

  const status = requireString(meta, "status", path);
  if (status !== "retired") {
    throw new BrainStatusFolderMismatchError(
      "retired file frontmatter status is not 'retired'",
      path,
      status,
      "retired",
    );
  }
  enforceStatusFolderInvariant(path, status, "retired");

  const id = requireString(meta, "id", path);
  const retired_at = requireString(meta, "retired_at", path);
  const reasonStr = requireString(meta, "retired_reason", path);
  const reasonValues = Object.values(BRAIN_RETIRED_REASON) as ReadonlyArray<string>;
  if (!reasonValues.includes(reasonStr)) {
    throw new BrainParseError(
      `retired_reason must be one of ${reasonValues.join(", ")}; got ${JSON.stringify(reasonStr)}`,
      path,
    );
  }
  const retired_by = requireString(meta, "retired_by", path);
  const created_at = requireString(meta, "created_at", path);
  const tags = requireStringArray(meta, "tags", path);
  const topic = requireString(meta, "topic", path);
  const principle = requireString(meta, "principle", path);

  const result: BrainRetired = {
    kind: "brain-retired",
    id,
    status: "retired",
    retired_at,
    retired_reason: reasonStr as BrainRetiredReason,
    retired_by,
    created_at,
    tags,
    topic,
    principle,
    evidenced_by: optionalStringArray(meta, "evidenced_by", path),
    applied_count: optionalNumber(meta, "applied_count", 0, path),
    violated_count: optionalNumber(meta, "violated_count", 0, path),
    last_evidence_at: optionalNullableString(meta, "last_evidence_at", path),
    confidence: parseConfidence(meta, path),
    confidence_value: parseConfidenceValue(meta, path),
    pinned: parsePinned(meta),
    ...(optionalScalarString(meta, "scope") !== undefined
      ? { scope: optionalScalarString(meta, "scope") }
      : {}),
    // Retirement KEEPS ownership - see `BrainRetired.owner`.
    ...(optionalOwnerField(meta) !== undefined ? { owner: optionalOwnerField(meta) } : {}),
    ...(optionalScalarString(meta, "superseded_by") !== undefined
      ? { superseded_by: optionalScalarString(meta, "superseded_by") }
      : {}),
    ...(meta["aliases"] !== undefined && Array.isArray(meta["aliases"])
      ? { aliases: [...(meta["aliases"] as ReadonlyArray<string>)] }
      : {}),
    ...spreadSchemaMetadata(meta, path, "preference_types", options),
    ...spreadMemorySemantics(meta, path),
    ...(optionalScalarString(meta, "user_rejected_reason") !== undefined
      ? {
          user_rejected_reason: optionalScalarString(meta, "user_rejected_reason"),
        }
      : {}),
    ...spreadBiTemporal(meta),
  };
  return Object.freeze(result);
}

// ----- preferences/ -> retired/ mover --------------------------------------

/**
 * Move a preference into `Brain/retired/`. Rewrites the frontmatter
 * with the retire metadata (status, kind, retired_at, retired_reason,
 * retired_by, optional superseded_by) and preserves the inherited
 * fields (topic, principle, evidenced_by, …).
 *
 * Body decision: we keep the original "## Principle" / "## Origin" /
 * "## How to apply" sections and append a "## Retired" section that
 * names the reason and pointer. The design doc §5.4 is silent on the
 * body shape; keeping the prose intact (rather than truncating it)
 * preserves the audit trail value — a future reader sees both what the
 * rule was and why it left.
 *
 * The move is performed as: write the new file atomically under
 * `retired/`, then `unlink` the original under `preferences/`. If the
 * write fails, the original stays untouched. If the unlink fails after
 * a successful write, the caller is left with both copies — `o2b brain
 * doctor` flags the duplicate id.
 */
export function moveToRetired(
  vault: string | null,
  prefPath: string,
  reason: BrainRetiredReason,
  opts: MoveToRetiredOptions,
): MoveToRetiredResult {
  // Pre-condition: ensure the source path is actually inside the
  // canonical `preferences/` folder. Doing this check *before* any I/O
  // means a buggy caller cannot trick us into deleting an unrelated
  // file: a misrouted call fails fast with no destructive side effect.
  // With no vault the paths are vault-relative and the store write checks
  // the store identity (design D14).
  const dirs = vault === null ? brainDirsOf(null) : brainDirsForWrite(vault);
  if (dirname(prefPath) !== dirs.preferences) {
    throw new Error(`moveToRetired: source path was not under preferences/: ${prefPath}`);
  }

  // Store-only (task 2.10): the preference is read from the store's fold
  // and the retire is records only; no page is written or removed.
  const storeOnly = vault === null || preferencesStoreOnly(vault);
  const [meta, body] = storeOnly ? storeRetireSource(prefPath) : parseFrontmatter(prefPath);
  if (meta["kind"] !== "brain-preference") {
    throw new Error(
      `moveToRetired: expected a preference file; got kind ${JSON.stringify(meta["kind"])} (${prefPath})`,
    );
  }
  const oldId = requireString(meta, "id", prefPath);
  if (!oldId.startsWith("pref-")) {
    throw new Error(
      `moveToRetired: preference id must start with 'pref-'; got ${oldId} (${prefPath})`,
    );
  }
  const slug = oldId.slice("pref-".length);
  if (!slug) {
    throw new Error(`moveToRetired: empty slug derived from id ${oldId}`);
  }

  const newId = `ret-${slug}`;
  const newPath = retiredPathOf(vault, slug);

  // Build the new frontmatter map. We preserve every inherited field
  // verbatim (`topic`, `principle`, `evidenced_by`, counters, …), drop
  // the active-state fields that no longer apply (`unconfirmed_until`,
  // `confirmed_at`), and stamp the retire metadata on top.
  const derivedSet = new Set<string>(DERIVED_FIELDS);
  const newMeta: FrontmatterMap = {};
  for (const [k, v] of Object.entries(meta)) {
    // Identity keys overwritten below.
    if (k === "kind" || k === "id" || k === "status" || k === "_status") continue;
    // Fields that don't apply to retired (drop both shapes per §24).
    if (k === "unconfirmed_until") continue;
    if (k === "confirmed_at" || k === "_confirmed_at") continue;
    if (k === "tags") {
      // Replace the `brain/preference` tag with `brain/retired`.
      const arr = Array.isArray(v) ? [...v] : [];
      newMeta["tags"] = arr.map((t) => (t === "brain/preference" ? "brain/retired" : t));
      continue;
    }
    // Group C derived fields go to disk in the `_`-prefixed shape so
    // parseRetired's `normalizeDerivedKeys` accepts the file. `meta`
    // is the normalised in-memory view, so the keys here are still
    // un-prefixed and need re-prefixing on write.
    if (derivedSet.has(k)) {
      newMeta[`_${k}`] = v as never;
      continue;
    }
    newMeta[k] = v as never;
  }
  newMeta["kind"] = "brain-retired";
  newMeta["id"] = newId;
  newMeta["_status"] = "retired";
  newMeta["retired_at"] = opts.now.toISOString();
  newMeta["retired_reason"] = reason;
  newMeta["retired_by"] = opts.retired_by;
  if (opts.superseded_by?.trim()) {
    newMeta["superseded_by"] = opts.superseded_by.trim();
  }
  if (opts.user_rejected_reason?.trim()) {
    newMeta["user_rejected_reason"] = opts.user_rejected_reason.trim();
  }

  // Add the prior `pref-<slug>` basename as an Obsidian alias on the
  // retired file. Wikilinks in append-only logs and signal frontmatter
  // were written when the file still lived in `preferences/`; without
  // this alias they would stop resolving the moment the file is
  // renamed. Obsidian's wikilink resolver checks `aliases` after
  // basename, so `[[pref-<slug>]]` continues to land on the right note
  // without rewriting any historical entry.
  const existingAliases = Array.isArray(newMeta["aliases"])
    ? (newMeta["aliases"] as ReadonlyArray<string>)
    : [];
  if (!existingAliases.includes(oldId)) {
    newMeta["aliases"] = [oldId, ...existingAliases];
  }

  // A retire is a field change of the same preference id (`status:
  // retired`), never a removal. The retired page's identity keys (`id:
  // ret-<slug>`, `kind`, `aliases`) are not fields of `pref-<slug>`, so they
  // stay out; the status is what a retire decides, at the caller's
  // authority. Values carry the types the preference writer writes: the
  // page parser reads every scalar as text, and `pinned: "false"` is not
  // the boolean the fold folds.
  const lifecycleRecords = () => {
    const {
      id: _id,
      kind: _kind,
      aliases: _aliases,
      ...lifecycle
    } = typedPreferenceFields(storeFieldsOf(newMeta));
    // Once switched, a preference the fold holds as private (any of its
    // records sits in `private/`, whatever its fields say) keeps its
    // retire there too: one entity, one partition, as the other writers.
    const heldPrivate = storeOnly && (storePreferenceEntry(slug)?.private ?? true);
    return preferenceStoreRecords(
      oldId,
      lifecycle,
      opts.authority ?? authorityFromOrigin(),
      heldPrivate || preferencePrivacy(vault, lifecycle)(),
      RETIRE_DECIDED_FIELDS,
    );
  };
  routeWrite({
    legacy: () => {
      // Re-render the body from scratch so the retired file carries the
      // v0.10.1 shape (only sections with content), even if the source
      // pref was last written in the v0.9.x placeholder format. Evidence
      // is collected from the live log so the snapshot reflects how the
      // rule was actually used right up to retirement.
      const renderInput: WritePreferenceInput = {
        slug,
        topic: requireString(meta, "topic", prefPath),
        principle: requireString(meta, "principle", prefPath),
        created_at: requireString(meta, "created_at", prefPath),
        unconfirmed_until: requireString(meta, "unconfirmed_until", prefPath),
        status: BRAIN_PREFERENCE_STATUS.confirmed, // body render is status-agnostic
        evidenced_by: optionalStringArray(meta, "evidenced_by", prefPath),
        ...(opts.evidenceApplied !== undefined ? { recentApplied: opts.evidenceApplied } : {}),
        ...(opts.evidenceViolated !== undefined ? { recentViolated: opts.evidenceViolated } : {}),
      };
      // moveToRetired is also called outside dream (CLI reject) — when the
      // caller did not pre-fetch evidence, we collect it here so the
      // retired file is the canonical historical snapshot in both paths.
      let renderInputWithEvidence: WritePreferenceInput = renderInput;
      if (renderInput.recentApplied === undefined && renderInput.recentViolated === undefined) {
        // Late-bound import to avoid a cyclic dependency: evidence.ts
        // imports nothing from preference.ts at module load time.
        // eslint-disable-next-line @typescript-eslint/no-require-imports
        const ev = (
          require("./evidence.ts") as typeof import("./evidence.ts")
        ).collectEvidenceForSlug(vault, slug, { sinceIso: renderInput.created_at });
        renderInputWithEvidence = {
          ...renderInput,
          recentApplied: ev.applied,
          recentViolated: ev.violated,
        };
      }
      const renderedBody = renderPreferenceBody(renderInputWithEvidence);
      const newBody = appendRetiredSection(renderedBody, reason, opts);
      void body; // original source body is intentionally discarded — see above.

      writeFrontmatterAtomic(newPath, newMeta, newBody, {
        overwrite: false,
        existsErrorKind: "retired",
        vaultForRelativePath: legacyVaultOf(vault, "moveToRetired"),
      });

      // Confirm the new file actually landed before unlinking the source.
      if (!existsSync(newPath)) {
        throw new Error(`moveToRetired: write of ${newPath} reported success but file is absent`);
      }
      unlinkSync(prefPath);
    },
    // Brain store dual write (task 1.11) on an unswitched machine: off by
    // default, never fails this write.
    store: lifecycleRecords,
    context: { vault },
  });

  // Per-preference mutation audit (opt-in, Brain lifecycle suite F1).
  // Keyed by the ORIGINAL `pref-<slug>` id so create -> ... -> retire
  // all land in one trail. A retire is a lifecycle transition, so it
  // always records (the audit's no-op rule only suppresses `update`).
  if (opts.audit) {
    const principle = requireString(meta, "principle", prefPath);
    const scope = typeof meta["scope"] === "string" ? (meta["scope"] as string) : undefined;
    const revRaw = meta["_revision"];
    const contentHash = computeContentHash(principle, scope);
    appendPrefAudit(
      vault,
      {
        pref_id: oldId,
        op: PREF_AUDIT_OP.retire,
        agent: opts.audit.agent,
        reason,
        revision_before: typeof revRaw === "number" ? revRaw : null,
        revision_after: null,
        hash_before: contentHash,
        hash_after: contentHash,
        private: isPrivateFrontmatter(meta),
      },
      { now: opts.now },
    );
  }

  return { path: newPath, id: newId };
}

/**
 * The preference a store-only retire moves, from the store's fold, as the
 * page `parseFrontmatter` would have read (and an empty body: the retired
 * page is not written). Throws when the fold holds no active preference
 * of that id, as the page read throws for a missing page.
 */
function storeRetireSource(prefPath: string): [FrontmatterMap, string] {
  const slug = basename(prefPath, ".md").slice("pref-".length);
  const page = slug === "" ? null : storePreferenceMeta(slug);
  if (page === null || page.retired) {
    throw new Error(`moveToRetired: the brain store holds no active preference pref-${slug}`);
  }
  return [page.meta, ""];
}

// ----- Field helpers --------------------------------------------------------

function enforceStatusFolderInvariant(
  path: string,
  status: string,
  expectedFolder: "preferences" | "retired",
): void {
  // Resolve the immediate parent directory's basename. Files outside
  // the canonical `Brain/<folder>/...` get a softer treatment: we let
  // the caller use the parser on a synthetic path (e.g. tests writing
  // to a tmpdir) so long as the status itself is coherent.
  const parent = basename(dirname(path));
  if (expectedFolder === "preferences") {
    // We accept `preferences` as the canonical folder. A status of
    // `retired` here is the mismatch case the design doc §4 calls out.
    if (
      parent === "preferences" &&
      status !== BRAIN_PREFERENCE_STATUS.unconfirmed &&
      status !== BRAIN_PREFERENCE_STATUS.confirmed &&
      status !== BRAIN_PREFERENCE_STATUS.quarantine &&
      // A tombstoned preference stays in `preferences/` for audit; the
      // lifecycle module marks it in place rather than moving the file.
      status !== BRAIN_TOMBSTONE_STATUS
    ) {
      throw new BrainStatusFolderMismatchError(
        "preference file frontmatter status does not match preferences/ folder",
        path,
        status,
        "preferences",
      );
    }
  } else {
    if (parent === "retired" && status !== "retired") {
      throw new BrainStatusFolderMismatchError(
        "retired file frontmatter status does not match retired/ folder",
        path,
        status,
        "retired",
      );
    }
  }
}

function requireField(meta: Record<string, unknown>, field: string, path: string): void {
  if (!(field in meta) || meta[field] === undefined || meta[field] === null) {
    throw new BrainParseError(`preference missing field: ${field}`, path);
  }
  if (typeof meta[field] === "string" && (meta[field] as string).trim() === "") {
    throw new BrainParseError(`preference missing field: ${field}`, path);
  }
}

function requireString(meta: Record<string, unknown>, field: string, path: string): string {
  requireField(meta, field, path);
  const v = meta[field];
  if (typeof v !== "string") {
    throw new BrainParseError(`preference field '${field}' must be a string`, path);
  }
  return v;
}

function requireStringArray(
  meta: Record<string, unknown>,
  field: string,
  path: string,
): ReadonlyArray<string> {
  requireField(meta, field, path);
  const v = meta[field];
  if (!Array.isArray(v)) {
    throw new BrainParseError(`preference field '${field}' must be an array`, path);
  }
  for (const item of v) {
    if (typeof item !== "string") {
      throw new BrainParseError(`preference field '${field}' must be an array of strings`, path);
    }
  }
  return [...(v as ReadonlyArray<string>)];
}

function optionalStringArray(
  meta: Record<string, unknown>,
  field: string,
  path: string,
): ReadonlyArray<string> {
  const v = meta[field];
  if (v === undefined || v === null) return [];
  if (!Array.isArray(v)) {
    throw new BrainParseError(`preference field '${field}' must be an array`, path);
  }
  for (const item of v) {
    if (typeof item !== "string") {
      throw new BrainParseError(`preference field '${field}' must be an array of strings`, path);
    }
  }
  return [...(v as ReadonlyArray<string>)];
}

function optionalStringList(
  meta: Record<string, unknown>,
  field: PreferenceRelationField,
  path: string,
): ReadonlyArray<string> | undefined {
  const v = meta[field];
  if (v === undefined || v === null) return undefined;
  if (typeof v === "string") return v.trim() ? [v] : [];
  if (!Array.isArray(v)) {
    throw new BrainParseError(
      `preference field '${field}' must be a string or array of strings`,
      path,
    );
  }
  for (const item of v) {
    if (typeof item !== "string") {
      throw new BrainParseError(
        `preference field '${field}' must be a string or array of strings`,
        path,
      );
    }
  }
  return [...(v as ReadonlyArray<string>)];
}

/**
 * Parse a string field whose semantic value is nullable. Both the
 * literal string `"null"` and an empty string surface as JS `null` so
 * the on-disk roundtrip survives the simple YAML emitter (which has no
 * native null token).
 */
function optionalNullableString(
  meta: Record<string, unknown>,
  field: string,
  path: string,
): string | null {
  const v = meta[field];
  if (v === undefined || v === null) return null;
  if (typeof v !== "string") {
    throw new BrainParseError(`preference field '${field}' must be a string or null`, path);
  }
  const trimmed = v.trim();
  if (trimmed === "" || trimmed === "null") return null;
  return v;
}

function optionalNumber(
  meta: Record<string, unknown>,
  field: string,
  fallback: number,
  path: string,
): number {
  const v = meta[field];
  if (v === undefined || v === null || v === "") return fallback;
  // The simple parser surfaces all values as strings; numerics included.
  if (typeof v === "number") return v;
  if (typeof v === "string") {
    const n = Number(v);
    if (!Number.isFinite(n)) {
      throw new BrainParseError(
        `preference field '${field}' must be a finite number; got ${JSON.stringify(v)}`,
        path,
      );
    }
    return n;
  }
  throw new BrainParseError(`preference field '${field}' must be a number`, path);
}

/**
 * Read the `owner:` frontmatter field (context-integrity-gates, Unit A).
 *
 * Distinct from {@link optionalScalarString} because a present-but-
 * non-string value must NOT read as absent here: Obsidian Properties
 * writes any list-shaped field as a YAML sequence, and `owner:` parsed as
 * an array would otherwise make an owner-private memory ownerless — that
 * is, shared with every agent. Such a claim resolves to
 * {@link OWNER_UNRESOLVED}, which no requested scope can equal, so the
 * memory reads as somebody else's. A usable string is stored VERBATIM,
 * exactly as before; normalization for comparison stays in
 * `preferenceOwner`.
 */
function optionalOwnerField(meta: Record<string, unknown>): string | undefined {
  const raw = meta["owner"];
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw !== "string") return OWNER_UNRESOLVED;
  return raw.trim() === "" ? undefined : raw;
}

function optionalScalarString(meta: Record<string, unknown>, field: string): string | undefined {
  const v = meta[field];
  if (v === undefined || v === null) return undefined;
  if (typeof v !== "string") return undefined;
  const trimmed = v.trim();
  return trimmed === "" ? undefined : v;
}

function parseConfidence(meta: Record<string, unknown>, path: string): BrainConfidence {
  const v = meta["confidence"];
  if (v === undefined || v === null || v === "") return BRAIN_CONFIDENCE.low;
  if (typeof v !== "string") {
    throw new BrainParseError("preference field 'confidence' must be a string", path);
  }
  const values = Object.values(BRAIN_CONFIDENCE) as ReadonlyArray<string>;
  if (!values.includes(v)) {
    throw new BrainParseError(
      `preference field 'confidence' must be one of ${values.join(", ")}; got ${JSON.stringify(v)}`,
      path,
    );
  }
  return v as BrainConfidence;
}

/**
 * Parse the numeric `confidence_value` field.
 *
 * Returns `null` when the field is absent, empty, or carries the
 * literal sentinel `"null"` (the writer's null encoding for the
 * simple YAML formatter). Otherwise must be a finite number in
 * `[0, 1]`; out-of-range / non-finite / non-numeric values raise a
 * hard parse error — drifting numeric confidence into `> 1` or
 * `NaN` would corrupt every downstream comparison silently.
 */
function parseConfidenceValue(meta: Record<string, unknown>, path: string): number | null {
  const v = meta["confidence_value"];
  if (v === undefined || v === null || v === "" || v === "null") return null;
  let n: number | null = null;
  if (typeof v === "number") {
    n = v;
  } else if (typeof v === "string") {
    const trimmed = v.trim();
    // Whitespace-only string is the "null" sentinel in disguise.
    // `Number("")` coerces to `0`, which would otherwise smuggle in a
    // confident-zero band for a file the writer never produced a
    // value for.
    if (trimmed.length === 0 || trimmed === "null") return null;
    const candidate = Number(trimmed);
    if (Number.isFinite(candidate)) n = candidate;
  }
  if (n === null || !Number.isFinite(n) || n < 0 || n > 1) {
    throw new BrainParseError(
      `preference field 'confidence_value' must be a number in [0, 1]; got ${JSON.stringify(v)}`,
      path,
    );
  }
  return n;
}

/**
 * Coerce `pinned` to boolean with a hard default of `false`. Accepts
 * the literal string forms ("true"/"false") emitted by the simple
 * formatter and the native boolean if a richer parser ever lands.
 *
 * Exported (t_f7bef96a) so the search indexer persists the SAME coercion
 * into `documents.pinned` instead of duplicating it: one rule, one
 * spelling, so the ranking signal and the preference flows can never
 * disagree about what a note's `pinned` frontmatter says.
 */
export function parsePinned(meta: Record<string, unknown>): boolean {
  const v = meta["pinned"];
  if (v === undefined || v === null || v === "") return false;
  if (typeof v === "boolean") return v;
  if (typeof v === "string") {
    if (v === "true") return true;
    if (v === "false") return false;
  }
  // Unexpected representations fall back to false; we treat this as a
  // forward-compat soft default rather than an error so a hand-edited
  // file with an oddly-quoted boolean still parses.
  return false;
}

// Internal use only: prevent "unused variable" lint after destructuring.
void join;