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
4.9 KB
Raw Blame
/**
 * The record of which `_brain.yaml` keys the validator understands, and
 * the block-entry protocol that keeps that record honest.
 *
 * One reason to change: how the validator declares and reports its key
 * vocabulary. The index is built BY CONSTRUCTION — a key becomes "known"
 * only because some branch registered it while checking for it — so it
 * can never drift from what the validator actually reads. That drift is
 * the bug class fixed in phase 0, where four blocks were parsed but
 * missing from a hand-maintained list and valid config produced a false
 * "unknown field" warning.
 */

import type { BrainConfigLoadWarning } from "./errors.ts";
import { requireMapBlock } from "./field-checks.ts";

/**
 * The set of configuration keys the validator understands, as observed
 * during one validation run.
 */
export interface BrainConfigKeyIndex {
  readonly topLevel: ReadonlySet<string>;
  /** Block key → sub-keys that block declares. Scalar keys are absent. */
  readonly subKeys: ReadonlyMap<string, ReadonlySet<string>>;
}

/**
 * Mutable accumulator behind {@link BrainConfigKeyIndex}. Every helper
 * that branches on a key registers it here, so the index is a
 * by-construction record of what the validator understands rather than a
 * second list that can drift from the first.
 */
export class KeyIndexCollector implements BrainConfigKeyIndex {
  readonly topLevel = new Set<string>();
  readonly subKeys = new Map<string, ReadonlySet<string>>();

  addTop(key: string): void {
    this.topLevel.add(key);
  }

  addSub(block: string, keys: Iterable<string>): void {
    const merged = new Set(this.subKeys.get(block) ?? []);
    for (const key of keys) merged.add(key);
    this.subKeys.set(block, merged);
  }
}

/**
 * Everything a single block parser needs: the raw root map, the label
 * rendered into error messages, the warning sink, and the key index it
 * must register itself with. Passed as one value so adding a fifth
 * concern later does not re-thread twenty signatures.
 */
export interface BlockParseContext {
  readonly obj: Record<string, unknown>;
  readonly source: string | null;
  readonly warnings: BrainConfigLoadWarning[];
  readonly keys: KeyIndexCollector;
}

/**
 * Record that this call site checked for `key` at the top level, then
 * report whether it's present. Every top-level block/field presence
 * check (`"vault" in obj`, etc.) MUST go through this - or `mergeBlock`,
 * for the four blocks that merge onto numeric defaults instead of being
 * fully optional - so the key index can never drift from the set of keys
 * the validator actually understands. A key that is never checked can
 * never be "known", by construction - there is no separate list to
 * forget to update.
 */
export function hasBlock(
  obj: Record<string, unknown>,
  key: string,
  knownBlockKeys: KeyIndexCollector,
): boolean {
  knownBlockKeys.addTop(key);
  return key in obj;
}

/**
 * Register an optional block and, when present, narrow it to a map.
 * Returns `undefined` for an absent block so the caller's whole body is
 * an early return rather than a nesting level.
 */
export function openBlock(
  ctx: BlockParseContext,
  blockKey: string,
): Record<string, unknown> | undefined {
  if (!hasBlock(ctx.obj, blockKey, ctx.keys)) return undefined;
  return requireMapBlock(ctx.obj[blockKey], blockKey, ctx.source);
}

/**
 * Push one forward-compat warning per key in `map` that isn't in `known`.
 * Replaces the per-block loop that used to mix `Set`, chained `!==`, and
 * (elsewhere) `.includes` for the same "unknown sub-key" check, each with
 * its own copy of the `${blockName}.${key}: unknown field ignored
 * (forward-compat)` message.
 */
export function warnUnknownKeys(
  ctx: BlockParseContext,
  map: Readonly<Record<string, unknown>>,
  known: ReadonlyArray<string>,
  blockName: string,
): void {
  const knownSet = new Set(known);
  ctx.keys.addSub(blockName, knownSet);
  for (const key of Object.keys(map)) {
    if (!knownSet.has(key)) {
      ctx.warnings.push({
        path: ctx.source ?? "<config>",
        message: `${blockName}.${key}: unknown field ignored (forward-compat)`,
      });
    }
  }
}

/**
 * Merge a parsed block (or `undefined`) with its default, returning a
 * plain object whose value types are validated downstream. A non-object
 * block (string, number, array) is a hard error — the user probably
 * miswrote the YAML.
 */
export function mergeBlock(
  blockKey: string,
  raw: unknown,
  fallback: Readonly<Record<string, number>>,
  source: string | null,
  knownBlockKeys: KeyIndexCollector,
  optionalKeys: ReadonlyArray<string> = [],
): Record<string, unknown> {
  knownBlockKeys.addTop(blockKey);
  knownBlockKeys.addSub(blockKey, [...Object.keys(fallback), ...optionalKeys]);
  if (raw === undefined) {
    return { ...fallback };
  }
  const rawMap = requireMapBlock(raw, blockKey, source);
  const merged: Record<string, unknown> = { ...fallback };
  for (const [k, v] of Object.entries(rawMap)) {
    merged[k] = v;
  }
  return merged;
}