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
36.2 KB
Raw Blame
/**
 * Restore the preference section of a bank bundle (Brain Portability &
 * Interop suite, Unit E2).
 *
 * The bundle carried preferences from the day it shipped and reported
 * them as a count, because "preferences have a delicate confidence /
 * audit lifecycle" that a naive restore would flatten. That reasoning
 * was right about the hazard and wrong about the conclusion: the
 * lifecycle has an owner. {@link writePreferenceTxn} is the documented
 * single chokepoint for every preference write - it takes the lock,
 * re-reads the record inside it, runs the expectations chain, stamps
 * `_content_hash` on promotion, bumps `_revision` only when bytes
 * change, appends edit history and appends the audit line. Restoring
 * THROUGH it maintains the lifecycle instead of overwriting it.
 *
 * Three decisions shape this module:
 *
 *   1. **Conflicts are decided by revision, never by import order.**
 *      Each row is written under {@link noRevisionRewind}, so a bundle
 *      that is behind the vault is refused and a divergence at an equal
 *      revision is refused. Reversing the row order cannot change any
 *      outcome.
 *   2. **A row that does not restore is REPORTED, never dropped.** Every
 *      carried row lands in exactly one of `restored` or `failed`, with a
 *      machine-readable reason; `restored.length + failed.length` always
 *      equals `carried`. A count of carried rows that silently exceeds
 *      what landed on disk is the misleading success this unit exists to
 *      remove.
 *   3. **What cannot be reconstructed is NAMED.** The rendered markdown
 *      body is a projection of the frontmatter plus the vault's own
 *      evidence log; the writer re-renders it from the fields that do
 *      restore, so prose it did not derive from those fields does not
 *      survive. {@link PREFERENCE_FIELDS_NOT_RESTORED} says so in the
 *      result rather than leaving the caller to discover it.
 *   4. **What IS reconstructed is named too.** A bundle taken before the
 *      trial window entered the export projection carries none, and a bank
 *      bundle IS the backup - if the source vault is gone there is no
 *      re-export to fall back on. A row whose window is inert (any status
 *      but `unconfirmed`) restores on a window derived from its own
 *      `confirmed_at` / `created_at`, listed in `derived`; a row whose
 *      deadline is still live is refused, because inventing one would
 *      re-date a promotion. See {@link resolveTrialWindow}.
 *   5. **A contention the restore CREATES is reported.** `topic` is written
 *      verbatim, and the dream pass indexes topics through a fold, so an
 *      imported spelling can contend with a local one for a single topic
 *      key - a state in which consolidation for that key plans nothing and
 *      the inbox grows. The restore neither rewrites the topic (the vault
 *      would then record something the bundle did not say) nor refuses the
 *      row (a backup-recovery path is the worst place for a new failure
 *      mode); it names the collision. See {@link RestoredTopicKeyCollision}.
 *   6. **A lost IDENTITY is refused; a redacted payload is not.** A bundle
 *      an earlier build produced can carry {@link REDACTION_PLACEHOLDER} in
 *      a field that names the record - its id, its topic, an alias. The
 *      placeholder is one constant, so those rows do not merely arrive
 *      anonymous: they arrive as the SAME record, and restoring two of them
 *      writes one file twice while reporting two rules. Such a row is
 *      refused with `redacted_identifier`. A placeholder in the principle
 *      is an honest redaction the operator chose and restores untouched.
 *      See {@link refuseRedactedIdentity}.
 *
 * The audit records the transition the txn derived (`create` /
 * `promote` / `update`) with {@link PREFERENCE_RESTORE_AUDIT_REASON} as
 * the reason. The op stays the truthful lifecycle transition - a restore
 * that promotes IS a promotion - and the reason says where the write
 * came from, which is strictly more than a `restore` op could carry.
 */

import { REDACTION_PLACEHOLDER } from "../../redactor.ts";
import {
  collectPreferenceRows,
  type ExportedPreferenceRow,
  type PreferenceParseFailure,
} from "../export.ts";
import { topicKey } from "../dream-plan.ts";
import {
  BrainCollisionError,
  BRAIN_COLLISION_KIND,
  noRevisionRewind,
  writePreferenceTxn,
} from "../preference-txn.ts";
import type { WritePreferenceInput } from "../preference.ts";
import { loadBrainConfig } from "../policy.ts";
import { DEFAULT_BRAIN_CONFIG } from "../policy/defaults.ts";
import { isoSecond } from "../time.ts";
import {
  BRAIN_CONFIDENCE,
  BRAIN_PREFERENCE_STATUS,
  type BrainConfidence,
  type BrainPreferenceStatus,
} from "../types.ts";

/** Identity prefix every preference id and file basename carries. */
const PREFERENCE_ID_PREFIX = "pref-";

/**
 * Reason recorded on the audit line so the trail says where the write
 * came from. Machine-readable, like every other value on that line.
 */
export const PREFERENCE_RESTORE_AUDIT_REASON = "bundle_restore";

/** Agent recorded when the caller supplies no identity of its own. */
export const DEFAULT_RESTORE_AGENT = "bank-import";

/**
 * Why one carried preference did not land. Closed vocabulary: the values
 * travel out of TypeScript in the bank-import result and its `--json`
 * rendering, so an operator reads them to decide what to do next.
 */
export const PREFERENCE_RESTORE_FAILURE = Object.freeze({
  /** The row is not a preference record: a field is missing or mistyped. */
  malformedRow: "malformed_row",
  /**
   * The row predates the trial window being exported AND its deadline is
   * still live - an `unconfirmed` rule, whose `unconfirmed_until` decides
   * when it expires. Restoring it would mean inventing a deadline, which
   * re-dates the rule's promotion - so the row is refused and named
   * instead. A row whose window is inert derives one; see
   * {@link resolveTrialWindow}.
   */
  missingTrialWindow: "missing_trial_window",
  /** The vault is ahead of the bundle, or diverges at the same revision. */
  revisionConflict: "revision_conflict",
  /** Another writer holds the preference's sync lock. */
  preferenceLocked: "preference_locked",
  /** The write itself was refused (validation, vault identity, I/O). */
  writeRejected: "write_rejected",
  /**
   * An identity-bearing field carries {@link REDACTION_PLACEHOLDER}: the
   * preference id, its topic, or one of its aliases. The export boundary
   * now refuses to emit such a bundle, but a bundle written by an earlier
   * build - or by any tool that scrubbed the payload before handing it
   * over - can still carry one, and the placeholder is a CONSTANT: two
   * rows redacted in the same field land on the same identity, so the
   * second silently overwrites the first. See {@link refuseRedactedIdentity}.
   */
  redactedIdentifier: "redacted_identifier",
} as const);

export type PreferenceRestoreFailure =
  (typeof PREFERENCE_RESTORE_FAILURE)[keyof typeof PREFERENCE_RESTORE_FAILURE];

export const PREFERENCE_RESTORE_FAILURES: ReadonlyArray<PreferenceRestoreFailure> = Object.freeze(
  Object.values(PREFERENCE_RESTORE_FAILURE),
);

export function isPreferenceRestoreFailure(value: unknown): value is PreferenceRestoreFailure {
  return (
    typeof value === "string" &&
    (PREFERENCE_RESTORE_FAILURES as ReadonlyArray<string>).includes(value)
  );
}

/**
 * Exported fields the restore deliberately does not reconstruct, typed
 * against the projection so a name here can never drift from a real
 * field. `body` is the only member: it is rendered from `evidenced_by`,
 * the evidence slices the vault's own log supplies, and any `How to
 * apply` prose the caller passed at write time - so a write reproduces
 * the parts derived from restored fields and nothing else.
 */
export const PREFERENCE_FIELDS_NOT_RESTORED: ReadonlyArray<keyof ExportedPreferenceRow> =
  Object.freeze(["body"]);

/**
 * The row field a derived trial window was read from. Closed vocabulary:
 * these values travel out of TypeScript in the bank-import result and its
 * `--json` rendering, so an operator reads them to decide whether to accept
 * the restored value.
 */
export const TRIAL_WINDOW_DERIVED_FROM = Object.freeze({
  confirmedAt: "confirmed_at",
  createdAt: "created_at",
} as const);

export type TrialWindowDerivedFrom =
  (typeof TRIAL_WINDOW_DERIVED_FROM)[keyof typeof TRIAL_WINDOW_DERIVED_FROM];

/**
 * One carried row that landed on a value the bundle did not carry, and
 * where that value came from. Reported so a restore that reconstructed
 * something says so, rather than presenting a derived field as one the
 * backup contained.
 */
export interface PreferenceRestoreDerivation {
  readonly id: string;
  /** Position in the carried section, matching {@link PreferenceRestoreFailureRecord}. */
  readonly index: number;
  readonly field: keyof ExportedPreferenceRow;
  /** The value written. */
  readonly value: string;
  readonly derivedFrom: TrialWindowDerivedFrom;
}

/**
 * Two or more preferences whose topics fold onto one dream-pass topic key
 * after a restore - the destination's own rules and the bundle's rows taken
 * together.
 *
 * The restore writes `topic` VERBATIM (see {@link toRestoreRow}), so an
 * import can create a contention the dream pass then refuses to plan
 * through. Reported here for the same reason the dream pass reports it:
 * the pass plans nothing for a contended key, and an operator who is never
 * told will see consolidation stop and the inbox grow with no cause named.
 */
export interface RestoredTopicKeyCollision {
  /** The folded key the claimants share. */
  readonly key: string;
  /** The distinct raw topics claiming it, in code-unit order. */
  readonly topics: ReadonlyArray<string>;
  /** The ids of every claiming preference, in code-unit order. */
  readonly prefIds: ReadonlyArray<string>;
}

/** One carried row that did not land, and why. */
export interface PreferenceRestoreFailureRecord {
  /** The row's preference id, or `null` when it carried no usable one. */
  readonly id: string | null;
  /** Position in the carried section, so a null id is still locatable. */
  readonly index: number;
  readonly reason: PreferenceRestoreFailure;
  /** `field=<name>` for a structural refusal, else the writer's message. */
  readonly detail: string;
}

export interface PreferenceRestoreResult {
  /** Rows the bundle carried. Always `restored.length + failed.length`. */
  readonly carried: number;
  /** Preference ids written through the audited transaction. */
  readonly restored: ReadonlyArray<string>;
  readonly failed: ReadonlyArray<PreferenceRestoreFailureRecord>;
  /** Exported fields a restore cannot reconstruct; see the constant. */
  readonly fieldsNotRestored: ReadonlyArray<keyof ExportedPreferenceRow>;
  /**
   * Rows that landed on a field the bundle did not carry, and where the
   * value came from. A subset of `restored`, never of `failed`.
   */
  readonly derived: ReadonlyArray<PreferenceRestoreDerivation>;
  /**
   * Folded topic keys that more than one raw topic now claims in the
   * destination vault as a result of this restore. Empty for a restore that
   * created none - the ordinary case.
   *
   * Read together with {@link topicScanUnreadable}: an empty list beside a
   * non-empty one is "no collision among the rules I could read", not "no
   * collision".
   */
  readonly topicKeyCollisions: ReadonlyArray<RestoredTopicKeyCollision>;
  /**
   * Destination preference files the prior-topic scan could not parse.
   *
   * The scan reads the DESTINATION vault to learn which topics each
   * existing rule already claims, and `collectExportRows` refuses the whole
   * directory when any file in it is unreadable - correctly, for an export,
   * where "there is no caller for whom a shorter list is the right answer".
   * An import is that caller. Letting the refusal through made one
   * pre-existing malformed rule in the destination abort an entire import,
   * wholesale, on a condition that has nothing to do with the bundle being
   * carried; the rows would have written fine.
   *
   * So the import proceeds on the readable rules and says so here. Empty
   * for a healthy destination, which is every ordinary run, so a clean
   * result is unchanged. Non-empty means {@link topicKeyCollisions} is a
   * partial answer and every surface that renders one must render this too.
   */
  readonly topicScanUnreadable: ReadonlyArray<PreferenceParseFailure>;
  /**
   * Ids whose bundled status was `confirmed` (or otherwise past its
   * trial) but which landed `unconfirmed` because the restore ran
   * untrusted - the default. Each one gets the vault's standard trial
   * window (`dream.unconfirmed_window_days`) instead of its carried
   * promotion state, so whoever controls the bundle file does not also
   * control which rules the vault treats as live. Empty for a trusted
   * restore.
   */
  readonly demotedToUnconfirmed: ReadonlyArray<string>;
}

export interface RestorePreferencesOptions {
  /** Identity recorded on the audit line and the edit-history entries. */
  readonly agent?: string;
  /** Clock for the audit timestamp; defaults to wall-clock. */
  readonly now?: () => Date;
  /**
   * Restore rows with the status the bundle carries - a true round-trip
   * of a bundle the operator vouches for. Default FALSE: the `<file>`
   * argument of `bank-import` is untrusted input, and a row that arrived
   * `confirmed` / `high` / `pinned` would otherwise dictate live agent
   * rules on landing, bypassing the trial window every first-party write
   * path observes. Untrusted restores demote such rows to `unconfirmed`
   * and list them in {@link PreferenceRestoreResult.demotedToUnconfirmed}.
   */
  readonly trustedRestore?: boolean;
  /**
   * Restore as a KNOWLEDGE-PACK install carrying this provenance stamp
   * (`<name>@<digest12>`). A pack is someone else's knowledge rather than
   * this vault's backup, so nothing it carries about its source vault's
   * lifecycle survives: EVERY row - an `unconfirmed` one included, whose
   * carried deadline would otherwise be the bundle author's choice - lands
   * `unconfirmed` on a fresh trial window dated from the install instant,
   * with its evidence links, counters, revision and pin cleared, and the
   * stamp written. Ignored together with `trustedRestore`: a pack install
   * is never a trusted restore. The audit reason is
   * {@link KNOWLEDGE_PACK_INSTALL_AUDIT_REASON}.
   */
  readonly knowledgePack?: string;
}

/** Audit reason a knowledge-pack install records on each preference it writes. */
export const KNOWLEDGE_PACK_INSTALL_AUDIT_REASON = "knowledge_pack_install";

/** Structural refusal carrying the field that failed the guard. */
class RowShapeError extends Error {
  readonly reason: PreferenceRestoreFailure;
  readonly field: string;

  constructor(reason: PreferenceRestoreFailure, field: string) {
    super(`field=${field}`);
    this.name = "RowShapeError";
    this.reason = reason;
    this.field = field;
  }
}

const isNonEmptyString = (value: unknown): value is string =>
  typeof value === "string" && value.trim() !== "";

const isStringArray = (value: unknown): value is ReadonlyArray<string> =>
  Array.isArray(value) && value.every((item) => typeof item === "string");

/**
 * Refuse a value that carries the redactor's placeholder in a field that
 * IS an identity.
 *
 * The distinction this draws is the whole point of the guard. A
 * placeholder in PAYLOAD text - a principle, a body - is an honest
 * redaction the operator chose, and the row restores with it: the rule is
 * still the rule, minus a secret nobody wanted in a backup. A placeholder
 * in an IDENTIFIER is a lost identity. `id` names the file the rule is
 * written to, `topic` is the key the dream pass folds and consolidates on,
 * and an alias is an inbound wikilink target. Worse, the placeholder is a
 * single constant, so two rows redacted in the same field are not two
 * anonymous rules - they are one, and restoring both writes one file twice
 * while reporting two.
 *
 * `includes` rather than equality: a partially-redacted identifier lost
 * exactly as much identity as a wholly-redacted one, and two rows redacted
 * at the same position collide the same way.
 */
function refuseRedactedIdentity(value: string, field: string): void {
  if (value.includes(REDACTION_PLACEHOLDER)) {
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.redactedIdentifier, field);
  }
}

function requireText(row: Record<string, unknown>, field: string): string {
  const value = row[field];
  if (!isNonEmptyString(value))
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.malformedRow, field);
  return value;
}

function optionalText(row: Record<string, unknown>, field: string): string | null {
  const value = row[field];
  if (value === undefined || value === null) return null;
  if (typeof value !== "string")
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.malformedRow, field);
  return value.trim() === "" ? null : value;
}

function optionalCount(row: Record<string, unknown>, field: string): number {
  const value = row[field];
  if (value === undefined || value === null) return 0;
  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.malformedRow, field);
  }
  return value;
}

function optionalStrings(row: Record<string, unknown>, field: string): ReadonlyArray<string> {
  const value = row[field];
  if (value === undefined || value === null) return [];
  if (!isStringArray(value))
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.malformedRow, field);
  return value;
}

function readStatus(row: Record<string, unknown>): BrainPreferenceStatus {
  const value = row["status"];
  const members = Object.values(BRAIN_PREFERENCE_STATUS) as ReadonlyArray<string>;
  if (typeof value !== "string" || !members.includes(value)) {
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.malformedRow, "status");
  }
  return value as BrainPreferenceStatus;
}

function readConfidence(row: Record<string, unknown>): BrainConfidence {
  const value = row["confidence"];
  if (value === undefined || value === null) return BRAIN_CONFIDENCE.low;
  const members = Object.values(BRAIN_CONFIDENCE) as ReadonlyArray<string>;
  if (typeof value !== "string" || !members.includes(value)) {
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.malformedRow, "confidence");
  }
  return value as BrainConfidence;
}

function readConfidenceValue(row: Record<string, unknown>): number | null {
  const value = row["confidence_value"];
  if (value === undefined || value === null) return null;
  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.malformedRow, "confidence_value");
  }
  return value;
}

function readSlug(row: Record<string, unknown>): string {
  const id = requireText(row, "id");
  if (!id.startsWith(PREFERENCE_ID_PREFIX) || id.length <= PREFERENCE_ID_PREFIX.length) {
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.malformedRow, "id");
  }
  refuseRedactedIdentity(id, "id");
  return id.slice(PREFERENCE_ID_PREFIX.length);
}

/** The trial window a row will be written with, and where it came from. */
interface ResolvedTrialWindow {
  readonly value: string;
  /** Absent when the row carried the field itself - nothing was derived. */
  readonly derivedFrom?: TrialWindowDerivedFrom;
}

/**
 * The trial window to write for a row, derived only where the row's own
 * fields determine it.
 *
 * A bundle written before `unconfirmed_until` entered the export projection
 * carries no window at all, and a bank bundle IS the backup: when the source
 * vault is gone there is no re-export and no way to supply the field. So the
 * question is not whether to refuse, but for which rows a refusal is the
 * honest answer.
 *
 * Exactly one consumer reads the field - `planAutoRetires`, and only while a
 * preference is `unconfirmed`, where it is the expiry deadline. For every
 * other status the window is inert: the rule has already left its trial, and
 * `confirmed_at` (not `unconfirmed_until`) records when. For those rows the
 * window is derived CLOSED at the instant the row itself records - the exact
 * convention the force-confirmed writer already uses when it creates a rule
 * that skips the trial - so nothing is re-dated and no deadline is invented.
 *
 * An `unconfirmed` row is refused. Its deadline is live, it is not a function
 * of any field the row carries, and a fabricated one would silently move a
 * promotion - the class of defect this release exists to remove.
 */
function resolveTrialWindow(
  record: Record<string, unknown>,
  status: BrainPreferenceStatus,
  created_at: string,
): ResolvedTrialWindow {
  const carried = record["unconfirmed_until"];
  if (typeof carried === "string" && carried.trim() !== "") return { value: carried };
  if (carried !== undefined && carried !== null && typeof carried !== "string") {
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.malformedRow, "unconfirmed_until");
  }
  if (status === BRAIN_PREFERENCE_STATUS.unconfirmed) {
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.missingTrialWindow, "unconfirmed_until");
  }
  const confirmedAt = optionalText(record, "confirmed_at");
  if (confirmedAt !== null) {
    return { value: confirmedAt, derivedFrom: TRIAL_WINDOW_DERIVED_FROM.confirmedAt };
  }
  return { value: created_at, derivedFrom: TRIAL_WINDOW_DERIVED_FROM.createdAt };
}

/** An exported row mapped to a write input, plus what had to be derived. */
export interface RestoreRowMapping {
  readonly input: WritePreferenceInput;
  /** Fields the row did not carry and the restore reconstructed. */
  readonly derived: ReadonlyArray<Omit<PreferenceRestoreDerivation, "id" | "index">>;
}

/**
 * Reverse of `collectExportRows`' projection: an exported row becomes the
 * write input the audited transaction takes. Every field the projection
 * emits is either mapped here or listed in
 * {@link PREFERENCE_FIELDS_NOT_RESTORED} - there is no third option, and
 * the bundle round-trip test asserts exactly that.
 *
 * `topic` is written VERBATIM. The dream pass indexes topics through a fold
 * (`topicKey`), so a bundle spelling a topic differently from a rule the
 * destination already owns can create a contention that stops consolidation
 * for that key. Rewriting the topic to the local spelling would make the
 * vault record something the bundle did not say, and refusing the row would
 * add a failure mode to the one path whose purpose is recovering a backup.
 * So the restore writes what the bundle declared and REPORTS the collision -
 * see {@link RestoredTopicKeyCollision}, which is also the only place the
 * two call sites are reconciled.
 *
 * Throws {@link RowShapeError} for a row the guard refuses, so the caller
 * reports it per-entry instead of aborting the run.
 */
export function toRestoreRow(row: unknown): RestoreRowMapping {
  if (row === null || typeof row !== "object" || Array.isArray(row)) {
    throw new RowShapeError(PREFERENCE_RESTORE_FAILURE.malformedRow, "row");
  }
  const record = row as Record<string, unknown>;
  const slug = readSlug(record);
  const topic = requireText(record, "topic");
  refuseRedactedIdentity(topic, "topic");
  // `principle` is PAYLOAD, not identity: a redaction inside it is one the
  // operator chose, and the rule it states survives it. It is deliberately
  // not passed through the identity guard.
  const principle = requireText(record, "principle");
  const created_at = requireText(record, "created_at");
  const status = readStatus(record);
  // Read here, ahead of the trial window, for the same reason the window
  // is resolved after the structural fields: a row that lost an alias has
  // lost an identity whatever else is true of it, and `redacted_identifier`
  // should not lose the race to a window this restore could have derived.
  const aliases = record["aliases"] === null ? [] : optionalStrings(record, "aliases");
  for (const alias of aliases) refuseRedactedIdentity(alias, "aliases");
  // Resolved AFTER the structural fields so `missing_trial_window` means
  // what it says - an otherwise-complete row from a bundle written
  // before the window was exported - rather than doubling as the first
  // complaint about a row that is malformed in several ways at once.
  const trialWindow = resolveTrialWindow(record, status, created_at);
  const scope = optionalText(record, "scope");
  const input: WritePreferenceInput = {
    slug,
    topic,
    principle,
    created_at,
    unconfirmed_until: trialWindow.value,
    status,
    evidenced_by: optionalStrings(record, "evidenced_by"),
    confirmed_at: optionalText(record, "confirmed_at"),
    applied_count: optionalCount(record, "applied_count"),
    violated_count: optionalCount(record, "violated_count"),
    last_evidence_at: optionalText(record, "last_evidence_at"),
    confidence: readConfidence(record),
    confidence_value: readConfidenceValue(record),
    pinned: record["pinned"] === true,
    revision: optionalCount(record, "revision"),
    // The writer composes the canonical tags (`brain`, `brain/preference`,
    // `brain/topic/…`, `brain/scope/…`) itself and de-duplicates, so
    // handing it the exported set restores any extra tag the source
    // carried without duplicating the canonical four.
    extraTags: optionalStrings(record, "tags"),
    ...(scope !== null ? { scope } : {}),
    ...(aliases.length > 0 ? { aliases } : {}),
  };
  return {
    input,
    derived:
      trialWindow.derivedFrom === undefined
        ? []
        : [
            {
              field: "unconfirmed_until",
              value: trialWindow.value,
              derivedFrom: trialWindow.derivedFrom,
            },
          ],
  };
}

/** Map a typed collision to the reason an operator reads in the result. */
function reasonForCollision(kind: BrainCollisionError["kind"]): PreferenceRestoreFailure {
  if (kind === BRAIN_COLLISION_KIND.sourceLock) return PREFERENCE_RESTORE_FAILURE.preferenceLocked;
  if (kind === BRAIN_COLLISION_KIND.staleUpdate) return PREFERENCE_RESTORE_FAILURE.revisionConflict;
  return PREFERENCE_RESTORE_FAILURE.writeRejected;
}

/**
 * Restore every carried preference row through the audited transaction.
 * Never throws for a bad row: the run continues and the row is reported,
 * mirroring the per-entry tolerance of the graph importer.
 */
export function restorePreferences(
  vault: string,
  rows: ReadonlyArray<unknown>,
  opts: RestorePreferencesOptions = {},
): PreferenceRestoreResult {
  const agent = opts.agent?.trim() ? opts.agent.trim() : DEFAULT_RESTORE_AGENT;
  // One clock for both opt-in sinks: the edit-history entry and the audit
  // line for a single row must carry the same instant.
  const clock = opts.now !== undefined ? { now: opts.now } : {};
  const restored: string[] = [];
  const failed: PreferenceRestoreFailureRecord[] = [];
  const derived: PreferenceRestoreDerivation[] = [];
  // The destination's topics BEFORE this run, so a row that overwrites a
  // rule of the same id replaces its claim rather than contending with it.
  // Partial by design, and reported: see `topicScanUnreadable`.
  const scan = collectPreferenceRows(vault);
  const priorTopics = new Map<string, string>();
  for (const existing of scan.rows) priorTopics.set(existing.id, existing.topic);
  const restoredTopics = new Map<string, string>();
  const demotedToUnconfirmed: string[] = [];
  const packStamp = opts.knowledgePack?.trim() ? opts.knowledgePack.trim() : null;
  const trusted = packStamp === null && opts.trustedRestore === true;
  const auditReason =
    packStamp === null ? PREFERENCE_RESTORE_AUDIT_REASON : KNOWLEDGE_PACK_INSTALL_AUDIT_REASON;
  const demotionWindowDays = unconfirmedWindowDays(vault);
  // The demotion window is dated from the restore instant, not the row's
  // own fields: a window derived from the bundle would let the bundle
  // author choose when the demoted rule goes live.
  const restoreInstant = opts.now !== undefined ? opts.now() : new Date();

  for (let index = 0; index < rows.length; index++) {
    const row = rows[index];
    const id = rowId(row);
    let mapping: RestoreRowMapping;
    try {
      mapping = toRestoreRow(row);
    } catch (exc) {
      failed.push(failure(id, index, exc));
      continue;
    }
    const { input } = mapping;
    // Untrusted default: no row arrives with live state the bundle chose.
    // The carried status/confidence/pin, promotion instant and trial
    // window are replaced with a fresh trial - same shape the first-party
    // write path gives every new rule - and the reset is named in the
    // result rather than applied in silence. That includes a row that is
    // ALREADY unconfirmed: it used to pass through verbatim, keeping a
    // carried `pinned: true`, `confidence: high` and an `unconfirmed_until`
    // the bundle author picked - a past one ends the trial on arrival.
    // A knowledge-pack install always lands the pack shape, trusted or not.
    const effective =
      packStamp !== null
        ? packInstallInput(input, restoreInstant, demotionWindowDays, packStamp)
        : trusted
          ? input
          : demoteToUnconfirmed(input, restoreInstant, demotionWindowDays);
    try {
      const result = writePreferenceTxn(
        vault,
        effective,
        [noRevisionRewind(effective.revision ?? 0)],
        { overwrite: true },
        { agent, ...clock },
        { agent, reason: auditReason, ...clock },
      );
      restored.push(result.id);
      restoredTopics.set(result.id, effective.topic);
      if (packStamp !== null) {
        // Only a row that arrived past its trial counts as demoted; an
        // `unconfirmed` row's window was restarted, which the pack result
        // states for every row at once.
        if (input.status !== BRAIN_PREFERENCE_STATUS.unconfirmed) {
          demotedToUnconfirmed.push(result.id);
        }
      } else if (effective !== input && liveStateChanged(input, effective)) {
        demotedToUnconfirmed.push(result.id);
      } else if (effective === input) {
        // Only a row that LANDED AS MAPPED can report derived fields - a
        // demoted row discarded the mapping's window with its status.
        for (const d of mapping.derived) derived.push({ id: result.id, index, ...d });
      }
    } catch (exc) {
      failed.push(failure(id, index, exc));
    }
  }

  return Object.freeze({
    carried: rows.length,
    restored: Object.freeze(restored),
    failed: Object.freeze(failed),
    fieldsNotRestored: PREFERENCE_FIELDS_NOT_RESTORED,
    derived: Object.freeze(derived),
    topicKeyCollisions: collisionsAfterRestore(priorTopics, restoredTopics),
    topicScanUnreadable: Object.freeze(scan.failures),
    demotedToUnconfirmed: Object.freeze(demotedToUnconfirmed),
  });
}

/**
 * Replace a row's live-state fields with a fresh trial, dated from the
 * restore instant. The revision is deliberately kept: the rewind guard
 * still compares it against the destination, and lowering it would let a
 * bundle with an old revision silently lose to a destination that has
 * moved on - the opposite direction of the same forgery.
 */
function demoteToUnconfirmed(
  input: WritePreferenceInput,
  restoreInstant: Date,
  windowDays: number,
): WritePreferenceInput {
  return {
    ...input,
    status: BRAIN_PREFERENCE_STATUS.unconfirmed,
    confidence: BRAIN_CONFIDENCE.low,
    pinned: false,
    confirmed_at: undefined,
    unconfirmed_until: isoSecond(addDays(restoreInstant, windowDays)),
  };
}

/**
 * A pack row as it lands: a fresh trial like {@link demoteToUnconfirmed},
 * plus everything that described the SOURCE vault's relationship with the
 * rule cleared. Evidence links name signals that exist only there, the
 * applied/violated counters count work done there, and the revision
 * numbers that vault's edits - carrying any of them would let the pack
 * author choose how established the rule looks here. Revision 0 also
 * means the rewind guard refuses a row whose id this vault already holds
 * at a later revision rather than overwriting it.
 */
function packInstallInput(
  input: WritePreferenceInput,
  installInstant: Date,
  windowDays: number,
  stamp: string,
): WritePreferenceInput {
  return {
    ...demoteToUnconfirmed(input, installInstant, windowDays),
    evidenced_by: [],
    applied_count: 0,
    violated_count: 0,
    last_evidence_at: null,
    confidence_value: null,
    revision: 0,
    // Aliases are inbound wikilink targets - identities in THIS vault's
    // link graph - and the `brain/` tag namespace is the writer's own
    // (it re-composes the canonical set). Neither is a pack's to claim.
    aliases: undefined,
    extraTags: (input.extraTags ?? []).filter((t) => t !== "brain" && !t.startsWith("brain/")),
    knowledge_pack: stamp,
  };
}

/** Did the untrusted reset change anything the row carried? */
function liveStateChanged(carried: WritePreferenceInput, reset: WritePreferenceInput): boolean {
  return (
    carried.status !== reset.status ||
    carried.confidence !== reset.confidence ||
    (carried.pinned ?? false) !== reset.pinned ||
    (carried.confirmed_at ?? undefined) !== reset.confirmed_at ||
    carried.unconfirmed_until !== reset.unconfirmed_until
  );
}

function addDays(date: Date, days: number): Date {
  return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
}

/**
 * The trial window the demotion grants, in days. Same source as every
 * first-party unconfirmed write (`dream.unconfirmed_window_days`), read
 * fail-soft: a destination vault with no readable `_brain.yaml` - a
 * fresh restore target before `brain init` - gets the shipped default,
 * because a missing config is not a reason to restore the row live.
 */
function unconfirmedWindowDays(vault: string): number {
  try {
    return loadBrainConfig(vault).dream.unconfirmed_window_days;
  } catch {
    return DEFAULT_BRAIN_CONFIG.dream.unconfirmed_window_days;
  }
}

/**
 * Folded topic keys claimed by more than one raw spelling once this restore
 * has landed. Byte-identical spellings are NOT a collision: that is the
 * ordinary "one topic, two rules" case the dream pass has always handled,
 * and reporting it here would be this unit inventing a finding it did not
 * cause - the same line `TopicKeyContention` draws.
 */
function collisionsAfterRestore(
  priorTopics: ReadonlyMap<string, string>,
  restoredTopics: ReadonlyMap<string, string>,
): ReadonlyArray<RestoredTopicKeyCollision> {
  if (restoredTopics.size === 0) return Object.freeze([]);
  const claimants = new Map<string, Map<string, Set<string>>>();
  const add = (id: string, topic: string): void => {
    const key = topicKey(topic);
    if (key === "") return;
    const byTopic = claimants.get(key) ?? new Map<string, Set<string>>();
    const ids = byTopic.get(topic) ?? new Set<string>();
    ids.add(id);
    byTopic.set(topic, ids);
    claimants.set(key, byTopic);
  };
  for (const [id, topic] of priorTopics) {
    // A restored row REPLACED the rule of the same id: its old topic is no
    // longer on disk and cannot be a claimant.
    if (restoredTopics.has(id)) continue;
    add(id, topic);
  }
  for (const [id, topic] of restoredTopics) add(id, topic);

  const out: RestoredTopicKeyCollision[] = [];
  for (const [key, byTopic] of [...claimants.entries()].toSorted(([a], [b]) =>
    a.localeCompare(b),
  )) {
    if (byTopic.size < 2) continue;
    // At least one claimant must come from THIS restore - a contention the
    // destination already had is not something the import created.
    const ids = [...byTopic.values()].flatMap((set) => [...set]);
    if (!ids.some((id) => restoredTopics.has(id))) continue;
    out.push(
      Object.freeze({
        key,
        topics: Object.freeze([...byTopic.keys()].toSorted()),
        prefIds: Object.freeze(ids.toSorted()),
      }),
    );
  }
  return Object.freeze(out);
}

/** The row's declared id when it has a usable one, `null` otherwise. */
function rowId(row: unknown): string | null {
  if (row === null || typeof row !== "object" || Array.isArray(row)) return null;
  const id = (row as Record<string, unknown>)["id"];
  return isNonEmptyString(id) ? id : null;
}

function failure(id: string | null, index: number, exc: unknown): PreferenceRestoreFailureRecord {
  if (exc instanceof RowShapeError) {
    return { id, index, reason: exc.reason, detail: exc.message };
  }
  if (exc instanceof BrainCollisionError) {
    return { id, index, reason: reasonForCollision(exc.kind), detail: exc.message };
  }
  return {
    id,
    index,
    reason: PREFERENCE_RESTORE_FAILURE.writeRejected,
    detail: exc instanceof Error ? exc.message : String(exc),
  };
}