Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
25.4 KB
Raw Blame
/**
 * The one writer of shared brain settings (design D4, D14 item 3): what
 * `o2b brain settings get|set|unset|list` and the `brain_settings` MCP tool
 * call.
 *
 *  - **Store-only machine** (`../../store/store-only.ts`, also with no
 *    vault): a `set` appends one `setting-set` record, an `unset` one
 *    `setting-unset` record, to the `settings` stream of `shared`, under
 *    the key the migration uses (`brain.<block>.<field>`, `brain.<key>`
 *    for a scalar). Nothing is written under the vault's `Brain/`. The
 *    authority is the caller's: `human` from the CLI, `agent` from MCP.
 *    The settings fold resolves by authority, then clock, so an agent
 *    record could never displace a human one; such a write is refused
 *    instead of being written and ignored.
 *  - **Unswitched machine**: the key is edited in place in
 *    `Brain/_brain.yaml` (`./settings-yaml-edit.ts`), as before the store.
 *
 * A store-native setting (`STORE_NATIVE_SETTINGS` in `./settings-names.ts`,
 * such as `view.language`) has no `_brain.yaml` home: it is a store record
 * under its own key on every machine, switched or not, checked by its own
 * validator.
 *
 * An operator-only key (`OPERATOR_ONLY_SETTINGS` in `./settings-keys.ts`:
 * the integrity gates, the read, index, capture and write boundaries, the
 * promotion guardrails) is refused to an agent in both modes.
 *
 * Only `shared` keys of the classification (`./settings-keys.ts`) are
 * written. A `device` key is answered with the machine-config line to add
 * instead, and `schema_version` is no setting. Every value goes through
 * the same validator `_brain.yaml` goes through, over the settings in
 * force, before anything is written.
 */

import { existsSync, readFileSync } from "node:fs";
import lockfile from "proper-lockfile";

import { canonicalJson } from "../../integrity/digest.ts";
import { atomicWriteFileSync } from "../../fs-atomic.ts";
import { foldSettings, type SettingsFold } from "../../store/fold-settings.ts";
import { protectionStore, StoreUnavailableError } from "../../store/read/protection-store.ts";
import { readStreamRecords } from "../../store/read/stream-read.ts";
import { storeOnlyMode } from "../../store/store-only.ts";
import type { StoreInspection } from "../../store/store-open.ts";
import { brainConfigPath } from "../paths.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import { parseBrainYaml } from "../yaml-parse.ts";
import { BrainConfigError } from "./errors.ts";
import { readRawBrainSettingsFromStore } from "./settings-source.ts";
import {
  BrainSettingError,
  defaultOf,
  isYamlValue,
  KEY_PREFIX,
  resolveSettingName,
  STORE_NATIVE_SETTINGS,
  withDeviceValue,
  type SettingAuthority,
  type SettingTarget,
} from "./settings-names.ts";
import { BRAIN_YAML_KEYS, isOperatorOnlySetting } from "./settings-keys.ts";
import {
  editBrainYamlKey,
  REMOVE_KEY,
  UnrepresentableValueError,
  type YamlSettingValue,
} from "./settings-yaml-edit.ts";
import { validateBrainConfigDetailed } from "./validate.ts";
import {
  refuseOverStrongerEntry,
  slotDecider,
  refuseWholeListOverStrongerEntries,
} from "./settings-entry-authority.ts";
import { storeCommit, type StoreChange } from "./settings-store-commit.ts";

export {
  BrainSettingError,
  parseSettingValue,
  resolveSettingName,
  type BrainSettingErrorCode,
  type SettingAuthority,
} from "./settings-names.ts";

/** Where a settings read looks. */
export interface BrainSettingsReadContext {
  /** The vault (`null`: none configured, which reads the store). */
  readonly vault: string | null;
  readonly configPath?: string;
}

export interface BrainSettingsWriteContext extends BrainSettingsReadContext {
  readonly authority: SettingAuthority;
  /** The writing agent's name, stamped on the record. */
  readonly agent: string;
}

/** Where the settings of this machine live. */
export type BrainSettingsMode = "store" | "legacy";

/** The answer of {@link getBrainSetting}, one row of {@link listBrainSettings}. */
export interface BrainSettingView {
  /** `<block>.<field>`, or the scalar key. */
  readonly name: string;
  /** The store setting key, `brain.<name>`. */
  readonly key: string;
  /** Whether a value is set (a record in force, or a line in `_brain.yaml`). */
  readonly set: boolean;
  /** The set value; `null` when none is set and the default applies. */
  readonly value: unknown;
  /** The shipped default, when there is one. */
  readonly default?: unknown;
  /** The authority of the record in force (store only). */
  readonly authority?: string;
  /** The id of the record in force (store only). */
  readonly record?: string;
  readonly source: "store" | "brain-yaml" | "default";
}

export interface BrainSettingWrite {
  readonly name: string;
  readonly key: string;
  /** The value now in force (`null` after an unset). */
  readonly value: unknown;
  readonly previous: unknown;
  readonly changed: boolean;
  readonly mode: BrainSettingsMode;
  /** The id of the record written (store mode, when something changed). */
  readonly record?: string;
}

function modeOf(ctx: BrainSettingsReadContext): BrainSettingsMode {
  if (ctx.vault === null) return "store";
  const mode = storeOnlyMode({
    vault: ctx.vault,
    ...(ctx.configPath !== undefined ? { configPath: ctx.configPath } : {}),
  });
  return mode.storeOnly ? "store" : "legacy";
}

// ----- Store mode -------------------------------------------------------------

/** The shared settings fold, with the shards it could not see. */
interface SharedRead {
  readonly fold: SettingsFold;
  /** `shared/<rel>` of settings shards unreadable, or gone since this machine read them. */
  readonly unseen: ReadonlyArray<string>;
}

function sharedRead(ctx: BrainSettingsReadContext): SharedRead {
  let store: StoreInspection | null;
  try {
    store = protectionStore(ctx.configPath, { needShared: true });
  } catch (err) {
    if (!(err instanceof StoreUnavailableError)) throw err;
    // A switched machine whose store cannot be opened: the operator's
    // value is unknown, as with an unseen shard. The reach-safe twin of
    // the error's message goes out, not the raw one: it can name a held
    // partition's file, and this list reaches callers at remote reach.
    return { fold: foldSettings([]), unseen: [err.publicMessage] };
  }
  if (store === null || !store.partitions.has("shared")) {
    return { fold: foldSettings([]), unseen: [] };
  }
  const read = readStreamRecords(store.root, "shared", { stream: "settings" });
  return {
    fold: foldSettings(read.records),
    unseen: read.unreadable.map((rel) => `shared/${rel}`),
  };
}

function sharedFold(ctx: BrainSettingsReadContext): SettingsFold {
  return sharedRead(ctx).fold;
}

/**
 * Refuse an agent's store write while a settings shard cannot be seen: the
 * operator's value of the setting may be in it, and whether it is in
 * force decides the write (design D14, fail closed). The operator's own
 * writes go on: a human value outranks every other.
 */
function refuseUnseen(target: SettingTarget, read: SharedRead, authority: SettingAuthority) {
  if (authority === "human" || read.unseen.length === 0) return;
  throw new BrainSettingError(
    "settings_unreadable",
    `${target.name} cannot be changed by an agent while a shared settings shard cannot be read ` +
      `(${read.unseen.join(", ")}): the operator's value may be in it. Run \`o2b brain doctor\`, ` +
      "then retry once the shard reads again",
  );
}

function storeView(target: SettingTarget, fold: SettingsFold): BrainSettingView {
  const state = fold.settings.get(target.key);
  const fallback =
    target.native !== undefined ? target.native.default : defaultOf(target.block, target.field);
  const base = {
    name: target.name,
    key: target.key,
    ...(fallback !== undefined ? { default: fallback } : {}),
  };
  if (state === undefined || state.removed) {
    return { ...base, set: false, value: null, source: "default" };
  }
  return {
    ...base,
    set: true,
    value: state.value,
    authority: state.winner.authority,
    record: state.winner.record.id,
    source: "store",
  };
}

/** Validate `raw` with `value` placed at the target; throws `invalid_setting_value`. */
function validateCandidate(
  raw: Record<string, unknown>,
  target: SettingTarget,
  value: unknown,
  source: string,
): void {
  const candidate: Record<string, unknown> = { ...raw };
  if (target.field === undefined) {
    if (value === REMOVE_KEY) delete candidate[target.block];
    else candidate[target.block] = value;
  } else {
    const current = candidate[target.block];
    const block: Record<string, unknown> =
      current !== null && typeof current === "object" && !Array.isArray(current)
        ? { ...(current as Record<string, unknown>) }
        : {};
    if (value === REMOVE_KEY) delete block[target.field];
    else block[target.field] = value;
    candidate[target.block] = block;
  }
  let config;
  try {
    ({ config } = validateBrainConfigDetailed(candidate, source));
  } catch (err) {
    if (err instanceof BrainConfigError)
      throw new BrainSettingError("invalid_setting_value", err.message);
    throw err;
  }
  // Block parsers drop a field they do not read without a warning, so a
  // field is known when it has a shipped default or survives validation.
  if (value === REMOVE_KEY || target.field === undefined) return;
  if (defaultOf(target.block, target.field) !== undefined) return;
  const block = (config as unknown as Record<string, unknown>)[target.block];
  const known =
    block !== null &&
    typeof block === "object" &&
    Object.hasOwn(block as Record<string, unknown>, target.field);
  if (!known)
    throw new BrainSettingError("unknown_setting", `"${target.name}" is not a brain setting`);
}

/**
 * Refuse an agent's write to an operator-only setting (`settings-keys.ts`
 * `OPERATOR_ONLY_SETTINGS`), in both modes and whether or not the
 * operator ever set it: such a key holds a safety or privacy boundary.
 */
function refuseOperatorOnly(target: SettingTarget, authority: SettingAuthority): void {
  if (authority === "human") return;
  if (
    target.native !== undefined
      ? target.native.operatorOnly !== true
      : !isOperatorOnlySetting(target.block, target.field)
  )
    return;
  throw new BrainSettingError(
    "operator_only_setting",
    `${target.name} holds a safety or privacy boundary; only the operator sets it. ` +
      `Ask the operator to run \`o2b brain settings set ${target.name} <value>\` or ` +
      `\`o2b brain settings unset ${target.name}\``,
  );
}

function refuseOverHuman(target: SettingTarget, fold: SettingsFold, authority: SettingAuthority) {
  const state = fold.settings.get(target.key);
  if (authority === "human" || state === undefined || state.winner.authority !== "human") return;
  throw new BrainSettingError(
    "human_value_in_force",
    `${target.name} was ${state.removed ? "reset to its default" : "set"} by the operator ` +
      "(human authority); an agent cannot change it. " +
      `Ask the operator to run \`o2b brain settings set ${target.name} <value>\` or ` +
      `\`o2b brain settings unset ${target.name}\``,
  );
}

/**
 * The legacy twin of {@link refuseOverHuman}: `_brain.yaml` records no
 * authority, so a value that differs from the shipped default is taken
 * as the operator's, and an agent may neither change nor unset it. A key
 * still at its default (or absent) stays the agent's to change.
 */
function refuseOverOperatorYaml(
  target: SettingTarget,
  before: BrainSettingView,
  fallback: unknown,
  authority: SettingAuthority,
): void {
  if (authority === "human" || !before.set) return;
  if (fallback !== undefined && canonicalJson(before.value) === canonicalJson(fallback)) return;
  throw new BrainSettingError(
    "human_value_in_force",
    `${target.name} counts as the operator's: this settings file records no author, and the ` +
      "value differs from the shipped default (an agent's own earlier write included); an " +
      `agent cannot change it. Ask the operator to run \`o2b brain settings set ${target.name} ` +
      `<value>\` or \`o2b brain settings unset ${target.name}\``,
  );
}

/** A change of {@link writeSharedSettingEntries}: one entry of a list setting. */
export interface SharedSettingEntryChange {
  readonly name: string;
  readonly entry: string;
  /** `true` adds the entry, `false` removes it. */
  readonly present: boolean;
  /**
   * A removal every reader applies already (a reference the pack drops on
   * read): skipped, not refused, where this authority may not write it.
   * `decidedBy` is the record that decided the entry's slot in the read
   * the repair was judged on: when another record decides the slot now (a
   * replacement another device wrote meanwhile), the repair is skipped,
   * and the removal it writes is conditional on that record
   * (`if_decided_by`), so the fold keeps a replacement delivered only
   * after the repair was written too: it never removes what it did not
   * judge.
   */
  readonly repair?: { readonly decidedBy: string };
}

/**
 * Write entry changes of list settings as one store operation, one
 * `setting-entry` record each (task 3.12): a list setting folds per entry,
 * so an edit another device makes meanwhile is kept. Store mode only. An
 * entry whose register a stronger authority decides (an agent changing an
 * entry the operator set or left out) refuses the whole batch, since the
 * fold would ignore it. Returns the ids of the records written.
 */
export function writeSharedSettingEntries(
  ctx: BrainSettingsWriteContext,
  changes: ReadonlyArray<SharedSettingEntryChange>,
): string[] {
  if (modeOf(ctx) !== "store") {
    throw new Error("writeSharedSettingEntries: store mode only (this machine reads _brain.yaml)");
  }
  const read = sharedRead(ctx);
  const pending: StoreChange[] = [];
  for (const change of changes) {
    const target = resolveSettingName(change.name);
    if (
      change.repair !== undefined &&
      slotDecider(read.fold, target.key, change.entry) !== change.repair.decidedBy
    ) {
      continue;
    }
    refuseOperatorOnly(target, ctx.authority);
    refuseUnseen(target, read, ctx.authority);
    try {
      refuseOverStrongerEntry(target, read.fold, change.entry, ctx.authority);
    } catch (err) {
      if (change.repair !== undefined && err instanceof BrainSettingError) continue;
      throw err;
    }
    pending.push({
      target,
      value: null,
      entry: {
        text: change.entry,
        present: change.present,
        ...(change.repair !== undefined ? { ifDecidedBy: change.repair.decidedBy } : {}),
      },
    });
  }
  return pending.length === 0 ? [] : storeCommit(ctx, pending);
}

// ----- Legacy mode ------------------------------------------------------------

function readYaml(vault: string): { path: string; text: string } {
  const path = brainConfigPath(vault);
  if (!existsSync(path)) {
    throw new BrainSettingError(
      "no_settings_file",
      "this vault has no brain settings file yet; run `o2b brain init` first",
    );
  }
  return { path, text: readFileSync(path, "utf8") };
}

function yamlView(target: SettingTarget, parsed: Record<string, unknown>): BrainSettingView {
  const top = parsed[target.block];
  const value =
    target.field === undefined
      ? top
      : top !== null && typeof top === "object" && !Array.isArray(top)
        ? (top as Record<string, unknown>)[target.field]
        : undefined;
  const fallback = defaultOf(target.block, target.field);
  const set = value !== undefined;
  return {
    name: target.name,
    key: target.key,
    set,
    value: set ? value : null,
    ...(fallback !== undefined ? { default: fallback } : {}),
    source: set ? "brain-yaml" : "default",
  };
}

/**
 * Run `fn` holding the lock `schema-mutate.ts` takes on `_brain.yaml`
 * (proper-lockfile's `<file>.lock`), so a settings write and a schema
 * mutation, or two settings writes, never both read the old text and
 * lose one edit. The sync API has no retries, so it spins briefly (about
 * one second). The spin blocks this process's event loop: a holder of the
 * lock in the same process (an async `withFileLock` of a schema mutation
 * in a long-lived MCP server) cannot release it meanwhile, so the write
 * fails with the lock-holder error and is retried by its caller.
 */
function withSettingsFileLock<T>(path: string, fn: () => T): T {
  let release: (() => void) | null = null;
  let lastError: unknown;
  for (let attempt = 0; attempt < 40 && release === null; attempt++) {
    try {
      release = lockfile.lockSync(path, { stale: 30_000, realpath: false });
    } catch (exc) {
      if ((exc as NodeJS.ErrnoException).code !== "ELOCKED") throw exc;
      lastError = exc;
      Bun.sleepSync(25);
    }
  }
  if (release === null) {
    const msg = lastError instanceof Error ? lastError.message : String(lastError);
    throw new Error(`another writer holds the brain settings file lock: ${msg}`);
  }
  try {
    return fn();
  } finally {
    release();
  }
}

/**
 * Run `fn` over the settings file's text under its lock, after the write
 * guard; a missing file refuses before the lock is taken.
 */
function legacyLocked<T>(vault: string, fn: (text: string) => T): T {
  assertVaultIdentityForWrite(vault);
  const { path } = readYaml(vault);
  return withSettingsFileLock(path, () => fn(readYaml(vault).text));
}

function legacyCommitLocked(vault: string, target: SettingTarget, requested: unknown): void {
  // A block in the file must carry its required fields, so an unset of a
  // block field writes the shipped default; a top-level key is removed.
  const fallback = defaultOf(target.block, target.field);
  const value =
    requested === REMOVE_KEY &&
    target.field !== undefined &&
    fallback !== undefined &&
    isYamlValue(fallback)
      ? fallback
      : requested;
  const { path, text } = readYaml(vault);
  let next: string;
  try {
    next = editBrainYamlKey(
      text,
      target.block,
      target.field,
      value === REMOVE_KEY ? REMOVE_KEY : (value as YamlSettingValue),
    );
  } catch (err) {
    if (err instanceof UnrepresentableValueError) {
      throw new BrainSettingError("invalid_setting_value", `${target.name}: ${err.message}`);
    }
    throw err;
  }
  let parsed: Record<string, unknown>;
  try {
    parsed = parseBrainYaml(next) as Record<string, unknown>;
  } catch (err) {
    throw new BrainSettingError(
      "invalid_setting_value",
      `${target.name}: ${(err as Error).message}`,
    );
  }
  const back = readBack(parsed, target);
  validateCandidate(parsed, target, back === undefined ? REMOVE_KEY : back, path);
  const wanted = value === REMOVE_KEY ? undefined : value;
  if (
    (back === undefined) !== (wanted === undefined) ||
    canonicalJson(back ?? null) !== canonicalJson(wanted ?? null)
  ) {
    throw new BrainSettingError(
      "invalid_setting_value",
      `${target.name}: the value cannot be written to the settings file as given`,
    );
  }
  atomicWriteFileSync(path, next);
}

function readBack(parsed: Record<string, unknown>, target: SettingTarget): unknown {
  const top = parsed[target.block];
  if (target.field === undefined) return top;
  return top !== null && typeof top === "object" && !Array.isArray(top)
    ? (top as Record<string, unknown>)[target.field]
    : undefined;
}

// ----- Public operations ------------------------------------------------------

/** The value of one shared setting on this machine. */
export function getBrainSetting(ctx: BrainSettingsReadContext, name: string): BrainSettingView {
  const target = resolveSettingName(name);
  if (target.native !== undefined || modeOf(ctx) === "store") {
    return storeView(target, sharedFold(ctx));
  }
  const { text } = readYaml(ctx.vault!);
  return yamlView(target, parseBrainYaml(text) as Record<string, unknown>);
}

/** The store-native settings that are set, read from the store in either mode. */
function nativeViews(ctx: BrainSettingsReadContext): BrainSettingView[] {
  const fold = sharedFold(ctx);
  return Object.keys(STORE_NATIVE_SETTINGS)
    .map((name) => storeView(resolveSettingName(name), fold))
    .filter((view) => view.set);
}

/** Every shared setting that is set on this machine, sorted by name. */
export function listBrainSettings(ctx: BrainSettingsReadContext): {
  readonly mode: BrainSettingsMode;
  readonly settings: ReadonlyArray<BrainSettingView>;
} {
  const mode = modeOf(ctx);
  const names: string[] = [];
  const native = nativeViews(ctx);
  if (mode === "store") {
    const fold = sharedFold(ctx);
    for (const [key, state] of fold.settings) {
      if (!key.startsWith(KEY_PREFIX) || state.removed) continue;
      names.push(key.slice(KEY_PREFIX.length));
    }
    const settings = names
      .flatMap((n) => {
        try {
          return [storeView(resolveSettingName(n), fold)];
        } catch {
          return []; // a key this release does not classify, or a device key
        }
      })
      .concat(native)
      .toSorted((a, b) => (a.name < b.name ? -1 : 1));
    return { mode, settings };
  }
  // A vault with no settings file yet has no legacy keys; the store-native
  // ones are still listed, as `get` answers them.
  const parsed = existsSync(brainConfigPath(ctx.vault!))
    ? (parseBrainYaml(readYaml(ctx.vault!).text) as Record<string, unknown>)
    : {};
  for (const [block, value] of Object.entries(parsed)) {
    if (!Object.hasOwn(BRAIN_YAML_KEYS, block)) continue;
    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
      for (const field of Object.keys(value)) names.push(`${block}.${field}`);
    } else {
      names.push(block);
    }
  }
  const settings = names
    .flatMap((n) => {
      try {
        return [yamlView(resolveSettingName(n), parsed)];
      } catch {
        return [];
      }
    })
    .concat(native)
    .toSorted((a, b) => (a.name < b.name ? -1 : 1));
  return { mode, settings };
}

/** Set one shared setting; see the module docblock. */
export function setBrainSetting(
  ctx: BrainSettingsWriteContext,
  name: string,
  value: unknown,
): BrainSettingWrite {
  let target: SettingTarget;
  try {
    target = resolveSettingName(name);
  } catch (err) {
    throw withDeviceValue(err, value);
  }
  const nativeProblem = target.native?.invalid(value) ?? null;
  if (nativeProblem !== null) throw new BrainSettingError("invalid_setting_value", nativeProblem);
  if (!isYamlValue(value)) {
    throw new BrainSettingError(
      "invalid_setting_value",
      `${target.name}: a setting value is a string, number, boolean, null or a list of those`,
    );
  }
  return write(ctx, target, value);
}

/** Remove one shared setting so its default applies again. */
export function unsetBrainSetting(ctx: BrainSettingsWriteContext, name: string): BrainSettingWrite {
  return write(ctx, resolveSettingName(name), REMOVE_KEY);
}

function write(
  ctx: BrainSettingsWriteContext,
  target: SettingTarget,
  value: unknown,
): BrainSettingWrite {
  refuseOperatorOnly(target, ctx.authority);
  const removing = value === REMOVE_KEY;
  const native = target.native !== undefined;
  if (native || modeOf(ctx) === "store") {
    const read = sharedRead(ctx);
    refuseUnseen(target, read, ctx.authority);
    const fold = read.fold;
    const before = storeView(target, fold);
    const same = removing
      ? !before.set
      : before.set && canonicalJson(before.value) === canonicalJson(value);
    const result = {
      name: target.name,
      key: target.key,
      value: removing ? null : value,
      previous: before.value,
      mode: "store" as const,
    };
    if (same) return { ...result, value: before.value, changed: false };
    // A key folded per entry (task 3.12) is judged entry by entry: the key's
    // newest record says nothing about who decides each entry.
    const perEntry = fold.lists.has(target.key);
    if (perEntry && ctx.authority !== "human") {
      refuseWholeListOverStrongerEntries(target, fold, removing ? null : value, ctx.authority);
    } else refuseOverHuman(target, fold, ctx.authority);
    if (!native) {
      validateCandidate(
        readRawBrainSettingsFromStore(
          ctx.configPath !== undefined ? { configPath: ctx.configPath } : {},
        ),
        target,
        value,
        "brain settings",
      );
    }
    const [record] = storeCommit(ctx, [{ target, value }]);
    // What is in force now: for a key folded per entry the fold can keep
    // what a stronger authority decided, so the requested value is not
    // reported as if it were.
    const inForce = perEntry ? storeView(target, sharedFold(ctx)).value : result.value;
    return {
      ...result,
      value: inForce,
      changed: true,
      ...(record !== undefined ? { record } : {}),
    };
  }
  const vault = ctx.vault!;
  // The read the comparison and the refusal judge, and the edit, are one
  // section under the file lock: an operator edit landing in between is
  // judged, never overwritten from a stale read.
  return legacyLocked(vault, (text) => {
    const before = yamlView(target, parseBrainYaml(text) as Record<string, unknown>);
    const fallback = defaultOf(target.block, target.field);
    const same = removing
      ? !before.set ||
        (fallback !== undefined && canonicalJson(before.value) === canonicalJson(fallback))
      : before.set && canonicalJson(before.value) === canonicalJson(value);
    const result = {
      name: target.name,
      key: target.key,
      value: removing ? null : value,
      previous: before.value,
      mode: "legacy" as const,
    };
    if (same) return { ...result, value: before.value, changed: false };
    refuseOverOperatorYaml(target, before, fallback, ctx.authority);
    legacyCommitLocked(vault, target, value);
    return { ...result, changed: true };
  });
}