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
43.3 KB
Raw Blame
/**
 * Canonical entity registry operations (Memory Integrity Suite).
 *
 * Write-side contract: one canonical entity per `(category, normalized
 * name)`. `upsertEntity` resolves through names AND aliases before
 * creating anything, so duplicates are refused at the write seam;
 * doctor lints catch the ones that arrive by hand-editing or sync.
 * All operations are deterministic - the caller injects the clock.
 *
 * Writes run in one of two LANES ({@link resolveWriteTarget}): the canonical
 * one, and the quarantine holding untrusted-provenance records. A name can be
 * claimed once in each, which is not a duplicate - only one of the two is a
 * canonical entity, and the quarantined claim is a record OF a claim rather
 * than a record the vault stands behind.
 *
 * Files stay plain Obsidian Markdown. Every rewrite preserves unknown
 * frontmatter keys the operator may have added by hand.
 */

import { join } from "node:path";
import { statSync } from "node:fs";

import type { FrontmatterMap } from "../../types.ts";
import { slugify } from "../../vault.ts";
import { isKnownRelation, normalizeRelation } from "../../graph/relation-vocab.ts";
import { normalizeRelationTarget } from "../../graph/frontmatter-relations.ts";
import { isoSecond } from "../time.ts";
import { entityPath } from "../paths.ts";
import {
  assertValidEntityLabel,
  entityIdentityKey,
  InvalidEntityLabelError,
  normalizeEntityName,
  quoteVariantCollisionTail,
  validateEntityCategory,
  validateEntityLabel,
  type EntityLabelInvalidReason,
  type EntityLexiconHandle,
} from "./canonical.ts";
import { resolveEntityLexicon } from "./lexicon.ts";
import { resolveEntityLabelDenylist } from "./label-hygiene.ts";
import {
  PERSON_NICKNAMES_ARTIFACT_REL,
  PersonNicknameConfigError,
  resolvePersonNicknameMap,
} from "./person-nicknames.ts";
import {
  derivePersonNameVariants,
  EMPTY_PERSON_NICKNAME_INDEX,
  EMPTY_PERSON_NICKNAME_MAP,
  invertPersonNicknameMap,
  isPersonCategory,
  personNameComparisonForm,
  personVariantQueryForms,
  type PersonNicknameIndex,
  type PersonNicknameMap,
} from "./person-variants.ts";
import {
  buildEntityIndex,
  conflictClaimants,
  ENTITY_CONFLICT_KIND,
  findEntityConflict,
  parseEntityFile,
  type EntityIndex,
} from "./index-builder.ts";
import { ENTITY_STATUS_SCOPE, entityStatusInScope } from "./status-scope.ts";
import {
  INTAKE_TRUST,
  UNTRUSTED_SOURCE_FRONTMATTER_KEY,
  sourceContentHashFrontmatter,
  untrustedSourceFrontmatter,
} from "../trust/untrusted-provenance.ts";
import {
  BRAIN_ENTITY_ID_PREFIX,
  BRAIN_ENTITY_KIND,
  BRAIN_ENTITY_STATUS,
  type BrainEntity,
  type BrainEntityStatus,
  type EntityRef,
} from "./types.ts";
import {
  assertLaneWrite,
  lanePageExists,
  lanePagesInStore,
  laneStoreStamp,
  parseLanePage,
  writeLanePage,
} from "../../store/lane-pages.ts";

export interface UpsertEntityInput {
  readonly category: string;
  readonly name: string;
  readonly aliases?: ReadonlyArray<string>;
  /** Agent identity stamped as `source_agent`. */
  readonly agent: string;
  /** Injected clock for deterministic stamps. */
  readonly now: Date;
  /** Optional confidence label passed through verbatim. */
  readonly confidence?: string;
  /** Markdown body (current structured state). Replaces on update. */
  readonly body?: string;
  /**
   * Markdown body used only if this upsert CREATES the record; an update
   * keeps the body that is there. The intake path stamps a source citation
   * this way: whether the write creates or updates is decided here, in the
   * lane it resolves in, and a caller that answered that question for itself
   * with a canonical read would get it wrong for the quarantine lane - and
   * would silently drop the citation of the source that introduced the
   * record. {@link body} still wins when both are given.
   */
  readonly bodyOnCreate?: string;
  /** Config path for denylist resolution; env still wins when set. */
  readonly configPath?: string;
  /**
   * This write is being made under untrusted provenance (see
   * `intake/source-trust.ts`), which selects the LANE it resolves and writes
   * in - see {@link resolveWriteTarget}. A record it introduces lands
   * `quarantine` and carries the untrusted-source marker the retrieval gate
   * reads, so it is absent from every ordinary read until an operator
   * releases it with {@link archiveEntity}'s `restore`.
   *
   * Absent → the canonical lane, byte-identical to an upsert that never knew
   * about trust.
   */
  readonly untrustedOrigin?: boolean;
  /**
   * SHA-256 of the bytes of the source this record was extracted from, as
   * classified by `intake/source-trust.ts`.
   *
   * An AUDIT RECORD, not a gate: nothing in this release reads it back, and
   * that is the point rather than an omission - see
   * `SOURCE_CONTENT_HASH_FRONTMATTER_KEY` in
   * `../trust/untrusted-provenance.ts`. Stamped only when this
   * upsert CREATES the record, alongside {@link bodyOnCreate}, so the digest
   * and the `## Sources` citation always describe the SAME source; a later
   * mention would otherwise overwrite the hash while leaving the citation of
   * a different file in the body, and the page would misdescribe both.
   *
   * Absent → nothing is written, leaving the page byte-identical to one from
   * before this record existed.
   */
  readonly sourceContentHash?: string;
}

export interface UpsertEntityResult {
  readonly entity: BrainEntity;
  readonly created: boolean;
}

export interface ListEntitiesOptions {
  readonly category?: string;
  readonly status?: BrainEntityStatus;
}

export interface RelateEntitiesInput {
  readonly from: EntityRef;
  readonly relation: string;
  readonly to: EntityRef;
  readonly now: Date;
  /**
   * This edge is being written under untrusted provenance, which selects the
   * lane both endpoints resolve in ({@link resolveWriteTarget}) - an intake
   * that just quarantined two entities links THOSE, and never the operator's
   * records of the same names. Absent → the canonical lane, byte-identical
   * to a relate that never knew about trust.
   */
  readonly untrustedOrigin?: boolean;
}

export interface ArchiveEntityOptions {
  readonly now: Date;
  /**
   * Return a record that is outside the canonical scope - archived OR
   * quarantined - to active lookup. This is the named exit from quarantine:
   * without it a record that entered under untrusted provenance would be
   * invisible with no way back, and a status nothing can leave is a dead end
   * rather than a lane. A release that would collide with a canonical record
   * already holding the same name is refused with both ids - see the check in
   * {@link archiveEntity}.
   */
  readonly restore?: boolean;
}

// ----- Lookup ----------------------------------------------------------------

/**
 * The label of `entity` that a normalized `query` actually matched: its
 * canonical name when that is what matched, otherwise the alias that did.
 *
 * A collision message must compare the forms that COLLIDED. Falling back
 * to the canonical name when an alias matched would compare the wrong
 * pair, and the quote-variant cause would then be named on a collision it
 * does not explain, or omitted from one it does.
 */
function matchedLabel(entity: BrainEntity, query: string): string {
  if (normalizeEntityName(entity.name) === query) return entity.name;
  return entity.aliases.find((a) => normalizeEntityName(a) === query) ?? entity.name;
}

/**
 * A reference matched more than one record.
 *
 * Two readings, and the message must not offer the wrong one. Across
 * categories the reference is under-specified and the exit is the
 * category - the message this error has always carried. WITHIN one
 * category it is not under-specified at all: two canonical records claim
 * one identity key, no category can separate them, and telling the
 * operator to pass one would name an exit that cannot work. The quote
 * fold is one way a vault arrives there, and when it is the cause the
 * message says so and names the command that ends it.
 *
 * The DERIVED lane raises this same type for a different collision: a
 * form that reaches more than one person only through derivation - an
 * initial, a word order, an operator nickname. Those records are two
 * real people, not duplicates, so the remedy is a more specific
 * reference, not a merge; `derived` selects that message. The `name`
 * stays the historic one so generic handlers keyed on the string keep
 * working; callers that must tell the two collisions apart read the
 * flag.
 */
export class EntityAmbiguityError extends Error {
  /** True when the collision exists only through derivation, not declaration. */
  readonly derived: boolean;
  constructor(
    query: string,
    matches: ReadonlyArray<BrainEntity>,
    opts: { derived?: boolean } = {},
  ) {
    const ids = matches.map((m) => m.id).join(", ");
    let message: string;
    if (opts.derived === true) {
      message =
        `entity reference '${query}' matches ${matches.length} person records through a ` +
        `derived name form (an initial, a word order or an operator nickname): ${ids} - ` +
        "that form alone does not name one person. Query the full name or a declared " +
        "alias, or pass a category";
    } else {
      const categories = new Set(matches.map((m) => m.category));
      if (categories.size > 1) {
        message = `entity reference '${query}' is ambiguous across categories: ${ids} - pass a category`;
      } else {
        const normalized = normalizeEntityName(query);
        const tail = quoteVariantCollisionTail(...matches.map((m) => matchedLabel(m, normalized)));
        message =
          `entity reference '${query}' is claimed by ${matches.length} canonical records in one ` +
          `category (${[...categories][0]}): ${ids} - no category separates them, so one must be ` +
          `archived or merged${tail}`;
      }
    }
    super(message);
    this.name = "EntityAmbiguityError";
    this.derived = opts.derived === true;
  }
}

// ----- Derived person-form index ---------------------------------------------

/**
 * The canonical records that answer to one comparison form in each
 * lane: `declared` holds the records naming the form outright (name or
 * alias, any category), `derived` the PERSON records a derivation
 * kernel form of theirs reaches it through. Both lists are id-ordered,
 * because the index walk they are built from is.
 */
export interface PersonFormClaimants {
  readonly declared: ReadonlyArray<BrainEntity>;
  readonly derived: ReadonlyArray<BrainEntity>;
}

/**
 * Everything the derived person-form lanes need, built once per
 * signature: the entity index it was built from (also the entity-change
 * detector - the cache below reuses the index object identity the
 * entity-index memo already maintains), the INVERTED nickname index,
 * the config fault of an unusable nickname file if there was one, and
 * the comparison-form -> claimants map.
 */
export interface PersonDerivedIndex {
  readonly entityIndex: EntityIndex;
  readonly nicknames: PersonNicknameIndex;
  /** Present when `person-nicknames.json` exists but is unusable. */
  readonly nicknameError: PersonNicknameConfigError | null;
  readonly byForm: ReadonlyMap<string, PersonFormClaimants>;
}

function buildPersonDerivedIndex(
  entityIndex: EntityIndex,
  nicknames: PersonNicknameIndex,
  nicknameError: PersonNicknameConfigError | null,
): PersonDerivedIndex {
  const byForm = new Map<string, { declared: BrainEntity[]; derived: BrainEntity[] }>();
  const claim = (form: string, lane: "declared" | "derived", entity: BrainEntity): void => {
    if (!form) return;
    let entry = byForm.get(form);
    if (entry === undefined) {
      entry = { declared: [], derived: [] };
      byForm.set(form, entry);
    }
    const list = entry[lane];
    if (!list.some((e) => e.id === entity.id)) list.push(entity);
  };
  for (const entity of entityIndex.entities) {
    if (!entityStatusInScope(entity.status, ENTITY_STATUS_SCOPE.canonical)) continue;
    const declared = [entity.name, ...entity.aliases].map((f) => normalizeEntityName(f));
    // Every canonical entity claims its declared forms; only person
    // categories also derive (the kernel emits nothing for the others).
    for (const form of declared) {
      claim(personNameComparisonForm(form), "declared", entity);
    }
    if (!isPersonCategory(entity.category)) continue;
    for (const form of declared) {
      for (const variant of derivePersonNameVariants(form, nicknames)) {
        claim(variant, "derived", entity);
      }
    }
  }
  return Object.freeze({
    entityIndex,
    nicknames,
    nicknameError,
    byForm: Object.freeze(byForm),
  });
}

interface PersonDerivedCacheEntry {
  readonly entityIndex: EntityIndex;
  readonly nicknameSignature: string;
  readonly value: PersonDerivedIndex;
}

/** Per-vault memo. Small (a process serves one vault); capped defensively. */
const PERSON_DERIVED_CACHE = new Map<string, PersonDerivedCacheEntry>();
const PERSON_DERIVED_CACHE_MAX = 16;

let unstableSignatureCounter = 0;

/**
 * The nickname file's change signature: nanosecond mtime plus byte size
 * when it exists, a fixed marker when it does not. A stat failure other
 * than a missing file yields a fresh marker each call, so an unreadable
 * file is never cached - the read path keeps surfacing the fault.
 */
function personNicknameFileSignature(vault: string): string {
  if (lanePagesInStore(vault)) {
    return lanePageExists(vault, join(vault, PERSON_NICKNAMES_ARTIFACT_REL))
      ? `store\0${laneStoreStamp(vault)}`
      : "missing";
  }
  try {
    const st = statSync(join(vault, PERSON_NICKNAMES_ARTIFACT_REL), { bigint: true });
    return `${st.mtimeNs}\0${st.size}`;
  } catch (err) {
    if (typeof err === "object" && err !== null && (err as { code?: string }).code === "ENOENT") {
      return "missing";
    }
    unstableSignatureCounter += 1;
    return `unstable-${unstableSignatureCounter}`;
  }
}

/**
 * Resolve the derived person-form index for `vault`, reusing the last
 * build while neither the entity files nor the nickname file changed.
 * The entity side is detected through the entity index's own memo
 * (object identity), the nickname side through its mtime/size
 * signature - so a per-query expansion, a registry read or a doctor
 * scan each pay the parse and the derivation once per signature instead
 * of per call. An unusable nickname file is captured as
 * `nicknameError` (consumers keep their documented degradations); any
 * other fault propagates.
 */
export function resolvePersonDerivedIndex(vault: string): PersonDerivedIndex {
  const entityIndex = buildEntityIndex(vault);
  const nicknameSignature = personNicknameFileSignature(vault);
  const cached = PERSON_DERIVED_CACHE.get(vault);
  if (
    cached !== undefined &&
    cached.entityIndex === entityIndex &&
    cached.nicknameSignature === nicknameSignature
  ) {
    return cached.value;
  }
  let map: PersonNicknameMap;
  let nicknameError: PersonNicknameConfigError | null = null;
  try {
    map = resolvePersonNicknameMap(vault);
  } catch (err) {
    if (!(err instanceof PersonNicknameConfigError)) throw err;
    nicknameError = err;
    map = EMPTY_PERSON_NICKNAME_MAP;
  }
  const value = buildPersonDerivedIndex(
    entityIndex,
    map.size > 0 ? invertPersonNicknameMap(map) : EMPTY_PERSON_NICKNAME_INDEX,
    nicknameError,
  );
  if (PERSON_DERIVED_CACHE.size >= PERSON_DERIVED_CACHE_MAX && !PERSON_DERIVED_CACHE.has(vault)) {
    const oldest = PERSON_DERIVED_CACHE.keys().next().value;
    if (oldest !== undefined) PERSON_DERIVED_CACHE.delete(oldest);
  }
  PERSON_DERIVED_CACHE.set(vault, { entityIndex, nicknameSignature, value });
  return value;
}

/**
 * The DERIVED lane of canonical read resolution: the person variants
 * (write-honesty-egress-consent, F3) - first-initial-plus-surname,
 * reversed word order, operator nicknames - consulted only after the
 * exact name/alias lanes above have missed. The lookup joins the query's
 * forms (itself plus its comparison form - the dotted-initial and
 * comma spellings) against the shared claimants map, over the declared
 * lane too: a "Last, First" spelling that comparison-folds onto a
 * canonical name resolves here rather than nowhere. A unique match
 * resolves; more than one is the same ambiguity the exact lane reports,
 * through the derived message - two real people sharing a form are not
 * duplicates to merge. Like the exact lane it resolves canonical-scope
 * records only, so a quarantined person's variants resolve nothing.
 */
function resolveDerived(derived: PersonDerivedIndex, ref: EntityRef): BrainEntity | null {
  const query = normalizeEntityName(ref.query);
  if (!query) return null;
  const category = ref.category !== undefined ? validateEntityCategory(ref.category) : undefined;
  const matches: BrainEntity[] = [];
  const seenIds = new Set<string>();
  for (const form of personVariantQueryForms(query)) {
    const claimants = derived.byForm.get(form);
    if (claimants === undefined) continue;
    for (const entity of [...claimants.declared, ...claimants.derived]) {
      if (category !== undefined && entity.category !== category) continue;
      if (seenIds.has(entity.id)) continue;
      seenIds.add(entity.id);
      matches.push(entity);
    }
  }
  if (matches.length > 1) {
    matches.sort((a, b) => a.id.localeCompare(b.id));
    throw new EntityAmbiguityError(ref.query, matches, { derived: true });
  }
  return matches[0] ?? null;
}

/**
 * Resolve a ref at the CANONICAL status scope for reading: canonical
 * name first, then alias - and only after BOTH miss, the derived
 * person-variant lane ({@link resolveDerived}). The index's lookup maps
 * are built at the same canonical scope, so the exact branches agree by
 * construction rather than by coincidence.
 *
 * The WRITE path deliberately does not come through here-then-derived
 * as one step: {@link resolveWriteTarget} calls {@link resolveActive}
 * alone, so a write resolves on declared forms only. A record is
 * updated or claimed by the names it chose, never by a form derivation
 * invented for it - and a quarantined namesake's variants (which the
 * canonical scope never holds anyway) stay unreachable in both lanes.
 */
function resolveActive(index: EntityIndex, ref: EntityRef): BrainEntity | null {
  const query = normalizeEntityName(ref.query);
  if (!query) return null;
  if (ref.category !== undefined) {
    const category = validateEntityCategory(ref.category);
    const byName = index.byKey.get(`${category}:${query}`);
    if (byName) return byName;
    const byAlias = index.byAlias.get(query);
    return byAlias && byAlias.category === category ? byAlias : null;
  }
  const matches = index.entities.filter(
    (e) =>
      entityStatusInScope(e.status, ENTITY_STATUS_SCOPE.canonical) &&
      (normalizeEntityName(e.name) === query ||
        e.aliases.some((a) => normalizeEntityName(a) === query)),
  );
  if (matches.length > 1) throw new EntityAmbiguityError(ref.query, matches);
  return matches[0] ?? null;
}

/**
 * Resolve a ref inside the QUARANTINE lane: the records that hold a name
 * without being entitled to it, which no read scope admits. Kept separate
 * from {@link resolveActive} rather than chained after it, because the two
 * answer for different authorities and a write belongs to exactly one.
 */
function resolveQuarantined(index: EntityIndex, ref: EntityRef): BrainEntity | null {
  const query = normalizeEntityName(ref.query);
  if (!query) return null;
  const category = ref.category !== undefined ? validateEntityCategory(ref.category) : undefined;
  const matches = index.entities.filter(
    (e) =>
      e.status === BRAIN_ENTITY_STATUS.quarantine &&
      (category === undefined || e.category === category) &&
      (normalizeEntityName(e.name) === query ||
        e.aliases.some((a) => normalizeEntityName(a) === query)),
  );
  if (matches.length > 1) throw new EntityAmbiguityError(ref.query, matches);
  return matches[0] ?? null;
}

/**
 * Resolve the record a WRITE lands on, in the lane the write belongs to.
 *
 * This is the seam where an untrusted source could otherwise take a name for
 * good. A single "who holds this name" resolution that answered canonical
 * first and quarantined second looked like the careful choice - it kept a
 * re-ingest from forking a second page - but it answered the same for a
 * write the vault had vouched for. So the first scraped page to mention
 * `Acme Corp` created the quarantined record, and every later TRUSTED write
 * of that name landed INSIDE it: the update arm copies the target's status,
 * so the record stayed quarantined, kept the untrusted-source marker in its
 * carried-forward frontmatter, and stayed invisible to `getEntity`, to the
 * default listing, to alias resolution and to the retrieval gate - reported
 * to the writer as `created: false`, which reads as "already there".
 *
 * The lanes are separate identity spaces instead:
 *
 *   - a TRUSTED write resolves canonical records only. A quarantined
 *     namesake does not hold the name against it: the write creates its own
 *     record, `created: true`, readable, unmarked. It is also not refused,
 *     which matters - refusing would let any hostile page reserve a name the
 *     operator then could not use.
 *   - an UNTRUSTED write resolves quarantined records only. Re-ingesting the
 *     same untrusted source still updates its own record rather than forking
 *     one, but an untrusted mention of a name the operator already holds can
 *     no longer reach that record - not its aliases, not its `source_agent`,
 *     not its body, not its edges. Nothing it carries can arrive unmarked.
 *
 * Neither direction can therefore capture the other, and the two spaces are
 * joined only where a human is present: {@link archiveEntity}'s `restore`,
 * which refuses a release that would collide.
 */
function resolveWriteTarget(
  index: EntityIndex,
  ref: EntityRef,
  untrustedOrigin: boolean,
): BrainEntity | null {
  return untrustedOrigin ? resolveQuarantined(index, ref) : resolveActive(index, ref);
}

/**
 * Read resolution: the exact lanes, then - only on a full miss - the
 * derived person-variant lane. An unusable nickname file is an
 * operator-data fault, not a read outage, so read resolution degrades
 * to exact-only (the posture `PersonNicknameConfigError`'s docblock
 * pins for every consumer).
 */
export function getEntity(vault: string, ref: EntityRef): BrainEntity | null {
  const index = buildEntityIndex(vault);
  const exact = resolveActive(index, ref);
  if (exact !== null) return exact;
  let derived: PersonDerivedIndex;
  try {
    derived = resolvePersonDerivedIndex(vault);
  } catch {
    return null;
  }
  return resolveDerived(derived, ref);
}

/**
 * List entities. Without a `status`, the listing is the READABLE scope: the
 * statuses a surface may show, which is `active` and `archived` exactly as
 * before, and never `quarantine`. A `status` is an explicit ask and is
 * honoured verbatim - that is how an operator sees what is quarantined.
 */
export function listEntities(vault: string, opts: ListEntitiesOptions = {}): BrainEntity[] {
  const category = opts.category !== undefined ? validateEntityCategory(opts.category) : undefined;
  return buildEntityIndex(vault).entities.filter(
    (e) =>
      (category === undefined || e.category === category) &&
      (opts.status === undefined
        ? entityStatusInScope(e.status, ENTITY_STATUS_SCOPE.readable)
        : e.status === opts.status),
  );
}

// ----- Write helpers ---------------------------------------------------------

const ENTITY_FIELD_ORDER = [
  "kind",
  "entity_id",
  "category",
  "name",
  "aliases",
  "status",
  "source_agent",
  "confidence",
  "created_at",
  "updated_at",
  "archived_at",
  "tags",
] as const;

const ENTITY_OWN_FIELDS: ReadonlySet<string> = new Set(ENTITY_FIELD_ORDER);

/**
 * Rewrite an entity file: known fields in canonical order, then the
 * operator's extra frontmatter keys (relations among them) verbatim.
 */
function writeEntityFile(
  vault: string,
  path: string,
  fields: FrontmatterMap,
  extras: FrontmatterMap,
  body: string,
  opts: { overwrite: boolean },
): void {
  const meta: FrontmatterMap = {};
  for (const key of ENTITY_FIELD_ORDER) {
    const value = fields[key];
    if (value !== undefined) meta[key] = value;
  }
  for (const [key, value] of Object.entries(extras)) {
    if (!ENTITY_OWN_FIELDS.has(key)) meta[key] = value;
  }
  writeLanePage(vault, path, meta, body, {
    overwrite: opts.overwrite,
    existsErrorKind: "entity",
  });
}

/** Validate requested aliases against the rest of the registry. */
function checkAliasClaims(
  index: EntityIndex,
  category: string,
  selfId: string | null,
  ownName: string,
  aliases: ReadonlyArray<string>,
): string[] {
  const kept: string[] = [];
  const seen = new Set<string>();
  for (const raw of aliases) {
    const alias = raw.trim();
    const normalized = normalizeEntityName(alias);
    if (!normalized || normalized === normalizeEntityName(ownName)) continue;
    if (seen.has(normalized)) continue;
    seen.add(normalized);
    const aliasHolder = index.byAlias.get(normalized);
    if (aliasHolder && aliasHolder.id !== selfId) {
      // The holder's own spelling of the claimed form, so the collision
      // message can say whether the two labels differ by anything other
      // than quote shape. Falling back to its canonical name would compare
      // the wrong pair, so the alias that actually matched is found first.
      const heldForm =
        aliasHolder.aliases.find((a) => normalizeEntityName(a) === normalized) ?? aliasHolder.name;
      throw new Error(
        `alias '${alias}' is already claimed by ${aliasHolder.id} (${aliasHolder.path})` +
          quoteVariantCollisionTail(alias, heldForm),
      );
    }
    const nameHolder = index.byKey.get(`${category}:${normalized}`);
    if (nameHolder && nameHolder.id !== selfId) {
      throw new Error(
        `alias '${alias}' collides with the canonical name of ${nameHolder.id} (${nameHolder.path})` +
          quoteVariantCollisionTail(alias, nameHolder.name),
      );
    }
    kept.push(alias);
  }
  return kept;
}

/** Allocate an unused `ent-<category>-<slug>` id (suffix -2, -3, ... on collision). */
function allocateEntityId(index: EntityIndex, category: string, name: string): string {
  const base = `${BRAIN_ENTITY_ID_PREFIX}${category}-${slugify(name)}`;
  const taken = new Set(index.entities.map((e) => e.id));
  if (!taken.has(base)) return base;
  for (let i = 2; ; i++) {
    const candidate = `${base}-${i}`;
    if (!taken.has(candidate)) return candidate;
  }
}

/**
 * Refuse a write onto an identity key more than one canonical record
 * already claims.
 *
 * The index keeps the walk's FIRST claimant in `byKey` so reads stay
 * deterministic, which is right for a read and wrong for a write: the
 * update arm would rewrite that record's `source_agent`, `updated_at` and
 * body, keep its label rather than the caller's, leave every other
 * claimant untouched, and report `created: false` - which reads as
 * "already there". A caller cannot tell that from a successful update,
 * and the record it did not mean to write was chosen by directory order.
 *
 * Refused for ANY contested key, not only the quote-variant one: the
 * silent wrong-record write does not depend on how the vault arrived at
 * two claimants. When the fold IS how it arrived, the message adds the
 * cause and the registered command, because that is the collision an
 * operator meets for the first time straight after an upgrade.
 *
 * Only the canonical lane is checked. `conflicts` is built at the
 * canonical status scope, so a quarantined namesake is not a claimant of
 * this key; the untrusted lane's own multiple-match case is the ambiguity
 * error in {@link resolveQuarantined}.
 */
function assertIdentityKeyUncontested(index: EntityIndex, key: string, category: string): void {
  const conflict = findEntityConflict(index, ENTITY_CONFLICT_KIND.duplicateName, key);
  if (conflict === null) return;
  const claimants = conflictClaimants(index, conflict);
  const listed = claimants.map((c) => `${c.id} (${c.path})`).join(", ");
  const tail = quoteVariantCollisionTail(...claimants.map((c) => c.name));
  throw new Error(
    `identity '${key}' (${category}) is claimed by ${conflict.paths.length} canonical entity ` +
      `records: ${listed} - a write would land on the first of them and leave the rest, so it ` +
      `is refused. Archive or merge the duplicates first${tail}.`,
  );
}

// ----- Operations ------------------------------------------------------------

/**
 * Whether one of the tightened, lexicon-backed verdicts (recall-quality
 * A2) refuses `name` at a CREATION boundary, and which. The policy split
 * lives here, not in the predicate: a learned verdict is only precise
 * enough to refuse when it cannot be a coincidence -
 *
 *   - `function-word-run` refuses for a SINGLE token: a label that is
 *     nothing but one learned common word. A MULTI-token run can be a
 *     legitimate title in a lexically poor corpus, so it stays advisory
 *     (the doctor and the prune report it store-wide instead).
 *   - `shouted-heading` refuses only a MULTI-token label the store holds
 *     no prior occurrence of (as any record's name or alias): a two-word
 *     all-caps run is pasted `# HEADING` residue. A SINGLE-token shout is
 *     a brand or an acronym-in-expansion (NASA) and stays advisory - the
 *     doctor and the prune report it store-wide; when the store itself
 *     already vouches for the form, even a multi-token shout admits.
 *
 * Everything else - a stale or absent artifact, a caseless corpus, a
 * code-shaped label - returns null and the creation proceeds exactly as
 * before the lexicon existed.
 */
function tightenedCreateRefusal(
  name: string,
  index: EntityIndex,
  lexicon: EntityLexiconHandle,
): EntityLabelInvalidReason | null {
  const verdict = validateEntityLabel(name, { lexicon });
  if (verdict.valid) return null;
  if (verdict.reason === "function-word-run") {
    return name.split(/\s+/).length === 1 ? "function-word-run" : null;
  }
  if (verdict.reason === "shouted-heading") {
    // The design split (recall-quality design.md): the hard gate keeps the
    // MULTI-token, prior-occurrence-free shout; a single-token shout is a
    // brand or acronym-in-expansion and stays advisory via heal/doctor.
    if (name.split(/\s+/).length === 1) return null;
    return hasPriorStoredOccurrence(index, name) ? null : "shouted-heading";
  }
  return null;
}

/** True when any stored record (any status) already answers to `name`. */
function hasPriorStoredOccurrence(index: EntityIndex, name: string): boolean {
  const query = normalizeEntityName(name);
  return index.entities.some(
    (e) =>
      normalizeEntityName(e.name) === query ||
      e.aliases.some((a) => normalizeEntityName(a) === query),
  );
}

export function upsertEntity(vault: string, input: UpsertEntityInput): UpsertEntityResult {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const category = validateEntityCategory(input.category);
  // Label quality gate (A1): strip Markdown/punctuation decoration BEFORE
  // normalisation and reject structurally-junk or denylisted names with a
  // typed error at this creation boundary. The stored display name is the
  // sanitised form; for a clean label sanitisation is a no-op, so the
  // identity key stays byte-identical to before (backward compatibility).
  const denylist = resolveEntityLabelDenylist(input.configPath);
  // recall-quality A2: the store-learned lexicon is resolved beside the
  // denylist. A null handle (no artifact yet, or one that failed its
  // freshness re-validation) degrades every verdict below to the
  // pre-lexicon structural gate - it can never mis-reject.
  const lexicon = resolveEntityLexicon(vault);
  const name = assertValidEntityLabel(input.name, { denylist });
  const index = buildEntityIndex(vault);
  const stamp = isoSecond(input.now);

  // Resolve inside this write's own lane (see resolveWriteTarget): name key
  // first, alias second, and never across the trusted/untrusted boundary.
  const untrusted = input.untrustedOrigin === true;
  const key = entityIdentityKey(category, name);
  if (!untrusted) assertIdentityKeyUncontested(index, key, category);
  const target = resolveWriteTarget(index, { category, query: name }, untrusted);

  if (target === null) {
    // The name may be held by an archived entity - refuse with the remedy
    // instead of silently forking a second file for the same identity.
    const archivedHolder = index.entities.find(
      (e) =>
        e.status === BRAIN_ENTITY_STATUS.archived && entityIdentityKey(e.category, e.name) === key,
    );
    if (archivedHolder) {
      throw new Error(
        `entity '${name}' (${category}) exists but is archived: ${archivedHolder.id}. ` +
          "Restore it (entity archive --restore) or choose another name.",
      );
    }
    // Tightened verdicts (recall-quality A2) are hard at CREATION only:
    // the update arm above re-admits whatever the store already holds,
    // and a refused label never reaches a write below this point.
    if (lexicon !== null) {
      const refusal = tightenedCreateRefusal(name, index, lexicon);
      if (refusal !== null) throw new InvalidEntityLabelError(input.name, name, refusal);
    }
  }

  const aliases = checkAliasClaims(
    index,
    category,
    target?.id ?? null,
    target?.name ?? name,
    input.aliases ?? [],
  );

  if (target !== null) {
    const [meta, existingBody] = parseLanePage(vault, target.path);
    const mergedAliases = [...target.aliases];
    for (const alias of aliases) {
      if (!mergedAliases.some((a) => normalizeEntityName(a) === normalizeEntityName(alias))) {
        mergedAliases.push(alias);
      }
    }
    const fields: FrontmatterMap = {
      kind: BRAIN_ENTITY_KIND,
      entity_id: target.id,
      category: target.category,
      name: target.name,
      ...(mergedAliases.length > 0 ? { aliases: mergedAliases } : {}),
      status: target.status,
      source_agent: input.agent,
      ...(input.confidence !== undefined
        ? { confidence: input.confidence }
        : target.confidence !== undefined
          ? { confidence: target.confidence }
          : {}),
      created_at: target.created_at,
      updated_at: stamp,
      tags: ["brain", "brain/entity"],
    };
    // The target's status is carried forward, which is now safe by
    // construction: the lane guarantees a trusted write never sees a
    // quarantined target and an untrusted one never sees a canonical target.
    // The marker is re-asserted on the untrusted lane rather than trusted to
    // the frontmatter that was there, so status and marker cannot drift apart
    // through a hand edit or a partial sync.
    const extras: FrontmatterMap = {
      ...meta,
      ...(untrusted ? untrustedSourceFrontmatter(INTAKE_TRUST.untrusted) : {}),
    };
    writeEntityFile(vault, target.path, fields, extras, input.body ?? existingBody, {
      overwrite: true,
    });
    const entity = parseEntityFile(target.path, vault);
    if (entity === null) throw new Error(`entity file unreadable after write: ${target.path}`);
    return { entity, created: false };
  }

  const id = allocateEntityId(index, category, name);
  const path = entityPath(vault, category, id);
  // Untrusted provenance decides two things about the new record: the status
  // it lands at, and the marker the retrieval gate reads. Both come from the
  // one lane flag, so they cannot disagree.
  const fields: FrontmatterMap = {
    kind: BRAIN_ENTITY_KIND,
    entity_id: id,
    category,
    name,
    ...(aliases.length > 0 ? { aliases } : {}),
    status: untrusted ? BRAIN_ENTITY_STATUS.quarantine : BRAIN_ENTITY_STATUS.active,
    source_agent: input.agent,
    ...(input.confidence !== undefined ? { confidence: input.confidence } : {}),
    created_at: stamp,
    updated_at: stamp,
    tags: ["brain", "brain/entity"],
  };
  // Both records the lane writes on creation: the marker the retrieval gate
  // reads, and the audit digest of the bytes this record was extracted from.
  // Merged in one map so a page cannot carry one without the other having had
  // its chance.
  const extrasOnCreate: FrontmatterMap = {
    ...untrustedSourceFrontmatter(untrusted ? INTAKE_TRUST.untrusted : INTAKE_TRUST.trusted),
    ...sourceContentHashFrontmatter(input.sourceContentHash),
  };
  writeEntityFile(
    vault,
    path,
    fields,
    extrasOnCreate,
    input.body ?? input.bodyOnCreate ?? `# ${name}`,
    {
      overwrite: false,
    },
  );
  const entity = parseEntityFile(path, vault);
  if (entity === null) throw new Error(`entity file unreadable after write: ${path}`);
  return { entity, created: true };
}

/**
 * Why an endpoint did not resolve, and what to do about it. A canonical
 * relate that misses a name a quarantined record holds is not a missing
 * entity - it is a record the caller is not entitled to reach yet, and the
 * message names the release that changes that rather than leaving a dead end.
 */
function missingEndpoint(index: EntityIndex, ref: EntityRef, untrustedOrigin: boolean): string {
  const base = `entity not found: ${JSON.stringify(ref.query)}`;
  if (untrustedOrigin) return base;
  const quarantined = resolveQuarantined(index, ref);
  if (quarantined === null) return base;
  return (
    `${base} - ${quarantined.id} holds that name in quarantine, where an untrusted source ` +
    "introduced it. Release it (entity archive --restore) to relate it."
  );
}

export function relateEntities(vault: string, input: RelateEntitiesInput): BrainEntity {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const relation = normalizeRelation(input.relation);
  if (!isKnownRelation(relation)) {
    throw new Error(
      `unknown relation '${input.relation}' - the relation vocabulary is defined in relation-vocab.ts`,
    );
  }
  const index = buildEntityIndex(vault);
  // Both endpoints resolve in the edge's own lane: an intake that just
  // quarantined two entities must be able to link them, and the edge stays
  // inside the quarantine because both endpoints are unreadable - while an
  // untrusted edge can never attach itself to the operator's record of the
  // same name.
  const untrusted = input.untrustedOrigin === true;
  const from = resolveWriteTarget(index, input.from, untrusted);
  if (from === null) throw new Error(missingEndpoint(index, input.from, untrusted));
  const to = resolveWriteTarget(index, input.to, untrusted);
  if (to === null) throw new Error(missingEndpoint(index, input.to, untrusted));
  if (from.id === to.id) throw new Error("an entity cannot relate to itself");

  const [meta, body] = parseLanePage(vault, from.path);
  const existingRaw = meta[relation];
  const targets: string[] = Array.isArray(existingRaw)
    ? [...existingRaw]
    : typeof existingRaw === "string" && existingRaw.trim().length > 0
      ? [existingRaw]
      : [];
  const alreadyLinked = targets.some((t) => normalizeRelationTarget(String(t)) === to.id);
  if (!alreadyLinked) targets.push(`[[${to.id}]]`);

  const fields: FrontmatterMap = {
    kind: BRAIN_ENTITY_KIND,
    entity_id: from.id,
    category: from.category,
    name: from.name,
    ...(from.aliases.length > 0 ? { aliases: [...from.aliases] } : {}),
    status: from.status,
    ...(from.source_agent !== undefined ? { source_agent: from.source_agent } : {}),
    ...(from.confidence !== undefined ? { confidence: from.confidence } : {}),
    created_at: from.created_at,
    updated_at: isoSecond(input.now),
    tags: ["brain", "brain/entity"],
  };
  const extras: FrontmatterMap = { ...meta, [relation]: targets };
  writeEntityFile(vault, from.path, fields, extras, body, { overwrite: true });
  const entity = parseEntityFile(from.path, vault);
  if (entity === null) throw new Error(`entity file unreadable after write: ${from.path}`);
  return entity;
}

export function archiveEntity(
  vault: string,
  ref: EntityRef,
  opts: ArchiveEntityOptions,
): BrainEntity {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const index = buildEntityIndex(vault);
  let target: BrainEntity | null;
  if (opts.restore) {
    // Restore resolves what canonical lookup cannot see - archived AND
    // quarantined - because both are records that hold a name without being
    // reachable through it.
    const query = normalizeEntityName(ref.query);
    const matches = index.entities.filter(
      (e) =>
        !entityStatusInScope(e.status, ENTITY_STATUS_SCOPE.canonical) &&
        (ref.category === undefined || e.category === validateEntityCategory(ref.category)) &&
        (normalizeEntityName(e.name) === query ||
          e.aliases.some((a) => normalizeEntityName(a) === query)),
    );
    if (matches.length > 1) {
      throw new Error(
        `archived entity reference '${ref.query}' is ambiguous: ${matches.map((m) => m.id).join(", ")}`,
      );
    }
    target = matches[0] ?? null;
  } else {
    target = resolveActive(index, ref);
  }
  if (target === null) {
    throw new Error(
      `${opts.restore ? "archived " : ""}entity not found: ${JSON.stringify(ref.query)}`,
    );
  }

  const nextStatus = opts.restore ? BRAIN_ENTITY_STATUS.active : BRAIN_ENTITY_STATUS.archived;
  if (target.status === nextStatus) return target;

  if (opts.restore) {
    // Release is where the two write lanes meet again, and a trusted record
    // may have taken this name while the quarantined one was out of scope
    // (that is exactly what a trusted write does with a quarantined
    // namesake). Promoting into that collision would put two active records
    // on one identity key - a duplicate the index reports and no read can
    // resolve deterministically. Which of the two survives is a judgement
    // about the material, so it goes back to the operator with both ids.
    const key = entityIdentityKey(target.category, target.name);
    const holder = index.entities.find(
      (e) =>
        e.id !== target.id &&
        entityStatusInScope(e.status, ENTITY_STATUS_SCOPE.canonical) &&
        entityIdentityKey(e.category, e.name) === key,
    );
    if (holder) {
      throw new Error(
        `cannot restore ${target.id}: ${holder.id} already holds '${target.name}' ` +
          `(${target.category}). Archive or rename ${holder.id} first, or merge the two` +
          `${quoteVariantCollisionTail(target.name, holder.name)}.`,
      );
    }
  }

  const [meta, body] = parseLanePage(vault, target.path);
  const stamp = isoSecond(opts.now);
  const fields: FrontmatterMap = {
    kind: BRAIN_ENTITY_KIND,
    entity_id: target.id,
    category: target.category,
    name: target.name,
    ...(target.aliases.length > 0 ? { aliases: [...target.aliases] } : {}),
    status: nextStatus,
    ...(target.source_agent !== undefined ? { source_agent: target.source_agent } : {}),
    ...(target.confidence !== undefined ? { confidence: target.confidence } : {}),
    created_at: target.created_at,
    updated_at: stamp,
    ...(nextStatus === BRAIN_ENTITY_STATUS.archived ? { archived_at: stamp } : {}),
    tags: ["brain", "brain/entity"],
  };
  // `archived_at` must disappear on restore: writeEntityFile only emits
  // the keys present in `fields`, and extras never override own fields.
  // The untrusted-source marker must disappear too, and it is an EXTRA, so
  // it is dropped explicitly: a released record the retrieval gate still
  // excluded would be a restore that reads as success without being one.
  const extras: FrontmatterMap = { ...meta };
  if (opts.restore) delete extras[UNTRUSTED_SOURCE_FRONTMATTER_KEY];
  writeEntityFile(vault, target.path, fields, extras, body, { overwrite: true });
  const entity = parseEntityFile(target.path, vault);
  if (entity === null) throw new Error(`entity file unreadable after write: ${target.path}`);
  return entity;
}