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
6.8 KB
Raw Blame
/**
 * The shared settings fold (design D4, spec "Shared store settings";
 * task 1.6): values every machine must agree on, stored as records in the
 * `settings` stream of the `shared` partition instead of in device-local
 * config, so a change made on one machine applies on every other once the
 * record syncs.
 *
 * Input records:
 *
 *  - `setting-set` `{ authority, key, value }`: proposes `value` for `key`.
 *  - `setting-unset` `{ authority, key }`: a tombstone; the key falls back
 *    to its default.
 *  - `setting-entry` `{ authority, key, entry, present }`: adds or removes
 *    one entry of a schema field list `brain.schema.<field>` (task 3.12);
 *    a key that holds one folds per entry (`./fold-setting-lists.ts`). An
 *    entry record for any other key is rejected, and so is a `setting-set`
 *    of a list key whose value is no list: it would hide the stored list
 *    from every reader of the pack while deciding no entry of it.
 *
 * Each other key is one register, resolved by authority, then clock. Keys this
 * version knows are validated (see {@link SETTING_RULES}); a record with
 * an invalid value is rejected and does not take effect. Unknown keys
 * (written by a newer release) fold as plain JSON values, so an older
 * machine keeps them instead of losing them.
 */

import {
  SETTING_ENTRY_KIND,
  SETTING_SET_KIND,
  SETTING_TOPIC_MIN_RECORDS,
  SETTING_TOPIC_MIN_SESSIONS,
  SETTING_TOPIC_QUIET_DAYS,
  SETTING_UNSET_KIND,
  SETTING_VIEW_LANGUAGE,
  type SettingKey,
} from "./constants.ts";
import type { StoreRecord } from "./envelope.ts";
import {
  foldListSetting,
  isListSettingKey,
  listValueRejection,
  settingEntryRejection,
} from "./fold-setting-lists.ts";
import {
  prepareRecords,
  recordAuthority,
  RegisterSet,
  TOMBSTONE,
  type RegisterState,
  type RejectedRecord,
} from "./fold.ts";

/** Setting keys: dot-separated lowercase words with underscores. */
export const SETTING_KEY_RE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){0,7}$/;

/** Validation and default of a known key. */
interface SettingRule {
  readonly valid: (value: unknown) => boolean;
  readonly expected: string;
  readonly fallback: unknown;
}

const positiveInt = (value: unknown): boolean =>
  typeof value === "number" && Number.isSafeInteger(value) && value >= 1;

/** Language tags such as `en`, `ru` or `pt-BR`. */
const LANGUAGE_RE = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8}){0,3}$/;

/** The keys this version knows: what a valid value is, and the default. */
export const SETTING_RULES: Readonly<Record<SettingKey, SettingRule>> = Object.freeze({
  [SETTING_VIEW_LANGUAGE]: {
    valid: (value) => typeof value === "string" && LANGUAGE_RE.test(value),
    expected: "a language tag such as en or pt-BR",
    fallback: null,
  },
  [SETTING_TOPIC_MIN_RECORDS]: { valid: positiveInt, expected: "a positive integer", fallback: 5 },
  [SETTING_TOPIC_MIN_SESSIONS]: { valid: positiveInt, expected: "a positive integer", fallback: 2 },
  [SETTING_TOPIC_QUIET_DAYS]: { valid: positiveInt, expected: "a positive integer", fallback: 30 },
});

function ruleOf(key: string): SettingRule | undefined {
  return Object.hasOwn(SETTING_RULES, key) ? SETTING_RULES[key as SettingKey] : undefined;
}

export interface SettingsFold {
  /** Resolved keys, inserted in code unit order. */
  readonly settings: ReadonlyMap<string, RegisterState<unknown>>;
  /** Per-entry registers of the list keys that hold a `setting-entry` record. */
  readonly lists: ReadonlyMap<string, ReadonlyMap<string, RegisterState<string>>>;
  readonly rejected: ReadonlyArray<RejectedRecord>;
}

function rejection(record: StoreRecord): string | null {
  if (recordAuthority(record) === null) return "missing or invalid authority";
  const key = record.body["key"];
  if (typeof key !== "string" || !SETTING_KEY_RE.test(key)) return "missing or invalid key";
  if (record.kind === SETTING_UNSET_KIND) return null;
  if (record.kind === SETTING_ENTRY_KIND) return settingEntryRejection(record);
  if (!("value" in record.body) || record.body["value"] === null) return "value is required";
  if (isListSettingKey(key)) return listValueRejection(key, record.body["value"]);
  const rule = ruleOf(key);
  if (rule !== undefined && !rule.valid(record.body["value"])) {
    return `${key} must be ${rule.expected}`;
  }
  return null;
}

/** Fold setting records (any order, duplicates allowed). */
export function foldSettings(input: Iterable<StoreRecord>): SettingsFold {
  const { records } = prepareRecords(input);
  const valid: StoreRecord[] = [];
  const listKeys = new Set<string>();
  const rejected: RejectedRecord[] = [];
  for (const record of records) {
    if (
      record.kind !== SETTING_SET_KIND &&
      record.kind !== SETTING_UNSET_KIND &&
      record.kind !== SETTING_ENTRY_KIND
    )
      continue;
    const reason = rejection(record);
    if (reason !== null) {
      rejected.push({ id: record.id, kind: record.kind, reason });
      continue;
    }
    valid.push(record);
    if (record.kind === SETTING_ENTRY_KIND) listKeys.add(record.body["key"] as string);
  }
  const registers = new RegisterSet<unknown>();
  const byListKey = new Map<string, StoreRecord[]>();
  for (const record of valid) {
    const key = record.body["key"] as string;
    if (listKeys.has(key)) {
      const list = byListKey.get(key) ?? [];
      list.push(record);
      byListKey.set(key, list);
      continue;
    }
    const value = record.kind === SETTING_UNSET_KIND ? TOMBSTONE : record.body["value"];
    registers.offer(key, { record, authority: recordAuthority(record)!, value });
  }
  const resolved = new Map<string, RegisterState<unknown>>();
  for (const key of registers.keys()) resolved.set(key, registers.get(key)!);
  const lists = new Map<string, ReadonlyMap<string, RegisterState<string>>>();
  for (const [key, list] of byListKey) {
    const folded = foldListSetting(key, list);
    if (folded === null) continue;
    resolved.set(key, folded.state);
    lists.set(key, folded.slots);
  }
  const settings = new Map<string, RegisterState<unknown>>();
  for (const key of [...resolved.keys()].toSorted()) settings.set(key, resolved.get(key)!);
  return { settings, lists, rejected };
}

/**
 * The effective value of `key`: the folded value, or the key's default
 * when it was never set or a removal won (`null` for an unknown key).
 */
export function settingValue(fold: SettingsFold, key: string): unknown {
  const state = fold.settings.get(key);
  if (state !== undefined && !state.removed) return state.value;
  return ruleOf(key)?.fallback ?? null;
}

/** The resolved settings as plain JSON, for the state digest. */
export function settingsFingerprint(fold: SettingsFold): unknown {
  const out: Record<string, unknown> = {};
  for (const [key, state] of fold.settings) {
    out[key] = { value: state.value, removed: state.removed, winner: state.winner.record.id };
  }
  return { settings: out, rejected: fold.rejected.map((r) => r.id) };
}