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
11.4 KB
Raw Blame
/**
 * The store side of the lane page store: the path helpers the store side
 * needs (`lanePagesInStore`, `heldInStore`, `insideBrain`, `brainRelOf`,
 * `placeOf`, `isLaneEntryPath`), the fold accessors and the record
 * builders of the lane entry store, and the keep rule that holds a
 * replaced private entry private. Every write call stays in
 * `lane-pages.ts`; this module only reads the file system and builds the
 * records of a write (design D14 of brain-store-and-topics).
 */

import { existsSync, readFileSync, statSync } from "node:fs";
import { isAbsolute, join, relative, sep } from "node:path";

import { BRAIN_ROOT_REL } from "../brain/path-constants.ts";
import { canonicalJson } from "../integrity/digest.ts";
import type { FrontmatterMap } from "../types.ts";
import { laneFoldIncomplete, laneStoreFold } from "./lane-fold-cache.ts";
import { laneNameRefusal, lanePlaceOf } from "./lane-paths.ts";
import {
  laneEntryKey,
  laneEntryRecord,
  laneEntryRemoveRecord,
  STANDING_RULE_LANE,
  type LaneEntryValue,
} from "./lane-records.ts";
import { lanePrivacyRow, laneTextParts, rawToKeep } from "./lane-raw.ts";
import { opaqueFields } from "./operation-privacy.ts";
import { isPrivateFrontmatter } from "./private-page.ts";
import { rowNamesPrivatePage } from "./reference-privacy.ts";
import { storeOnlyMode } from "./store-only.ts";
import type { Authority, StorePartition } from "./constants.ts";
import { authorityFromOrigin, type DualWriteRecord } from "./dual-write.ts";

/** Whether lane pages of `vault` live in the store on this machine. */
export function lanePagesInStore(vault: string): boolean {
  return storeOnlyMode({ vault }).storeOnly;
}

/** Fields of a lane page that are stamps and ids, never page references. */
const PAGE_OPAQUE_FIELDS = opaqueFields("slug", "date", "valid_from", "content_hash", "revision");

/**
 * Does the store hold `path` on this machine: a store-only machine and a
 * path under `<vault>/Brain/`. Any other path (a user's `skills/` or
 * `runbooks/` page a lane module also reads) stays a file in both modes.
 */
export function heldInStore(vault: string, path: string): boolean {
  return lanePagesInStore(vault) && insideBrain(vault, path);
}

/** Whether `path` lies under `<vault>/Brain/` (or is it). */
export function insideBrain(vault: string, path: string): boolean {
  const rel = relative(join(vault, BRAIN_ROOT_REL), path);
  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
}

export function brainRelOf(vault: string, path: string): string {
  return relative(join(vault, BRAIN_ROOT_REL), path).split(sep).join("/");
}

function placeOf(vault: string, path: string): { lane: string; entry: string } {
  const rel = brainRelOf(vault, path);
  const place = lanePlaceOf(rel);
  if (place === null) {
    throw new Error(`not a Brain lane page: ${path}: ${laneNameRefusal(rel) ?? "no lane entry"}`);
  }
  return place;
}

function isLaneEntryPath(vault: string, path: string): boolean {
  return insideBrain(vault, path) && lanePlaceOf(brainRelOf(vault, path)) !== null;
}

// ----- The store side -----------------------------------------------------------

/** The live lane entries of the configured store, by `<lane>/<entry>`. */
export function storeEntries(): ReadonlyMap<string, LaneEntryValue> {
  return laneStoreFold().entries;
}

/**
 * The physical time (ms) of the newest record of the live lane entry at
 * `path`, the store's stand-in for a file's mtime; `null` when there is no
 * such entry. A file's mtime on a path the store does not hold.
 */
export function laneEntryClockMs(vault: string, path: string): number | null {
  if (!heldInStore(vault, path)) {
    try {
      return statSync(path).mtimeMs;
    } catch {
      return null;
    }
  }
  const { lane, entry } = placeOf(vault, path);
  return laneStoreFold().clocks.get(laneEntryKey(lane, entry)) ?? null;
}

export function storeEntry(vault: string, path: string): LaneEntryValue | null {
  const { lane, entry } = placeOf(vault, path);
  return storeEntries().get(laneEntryKey(lane, entry)) ?? null;
}

/**
 * Whether the lane fold may miss a record ({@link laneFoldIncomplete}: an
 * `events` shard unreadable or gone since this machine read it, or a
 * record in `private` whose body blob has not arrived): an entry's private records may
 * be among them, so every privacy verdict over the fold fails closed
 * (design D14).
 */
export function foldIncomplete(): boolean {
  return laneFoldIncomplete(laneStoreFold());
}

/** Whether the live entry `value` was written to the `private` partition. */
export function livesInPrivate(value: LaneEntryValue): boolean {
  return laneStoreFold().privateKeys.has(laneEntryKey(value.lane, value.entry));
}

/**
 * Whether the store holds `path` on this machine as a live entry of the
 * `private` partition. An entry can be private by partition alone, with no
 * `visibility:` in its fields, so an exporter that turns entries back into
 * pages asks here to keep the privacy (review finding F333). A path the
 * store does not hold is no private entry. While the fold may miss a
 * record ({@link foldIncomplete}), every lane entry reads as private (fail
 * closed).
 */
export function laneEntryInPrivate(vault: string, path: string): boolean {
  if (!heldInStore(vault, path)) return false;
  if (lanePlaceOf(brainRelOf(vault, path)) === null) return false;
  if (foldIncomplete()) return true;
  const value = storeEntry(vault, path);
  return value !== null && livesInPrivate(value);
}

/** The partition the live entry `value` lives in. */
export function partitionOf(value: LaneEntryValue): StorePartition {
  return livesInPrivate(value) ? "private" : "shared";
}

/**
 * The tombstone of a live entry, in the partition the entry lives in
 * whatever the rest of its operation is (`Located`, content-free): a
 * device that holds only `shared` must see a shared entry's tombstone.
 * `onlyIfApart`: the tombstone of an entry a write replaces, needed only
 * when the replacement lands in another partition. `partition`: where the
 * entry lives, when the caller read it from the same fold as `value`.
 */
export function tombstoneOf(
  value: LaneEntryValue,
  onlyIfApart = false,
  partition: StorePartition = partitionOf(value),
): DualWriteRecord {
  return {
    ...laneEntryRemoveRecord({
      lane: value.lane,
      entry: value.entry,
      authority: authorityFor(value.lane),
      private: partition === "private",
    }),
    located: { partition, content: false, ...(onlyIfApart ? { onlyIfApart: true } : {}) },
  };
}

/**
 * The tombstone a write replacing the entry at `path` adds before its new
 * record: the old entry lives in `shared`, so if the new value lands in
 * `private` (a raise), a device that holds only `shared` sees the entry
 * go rather than keep reading the old value. Nothing when no shared entry
 * is replaced; the append drops it when the new value stays in `shared`.
 */
export function replacedShared(vault: string, path: string): DualWriteRecord[] {
  if (!isLaneEntryPath(vault, path)) return [];
  const prior = storeEntry(vault, path);
  return prior !== null && !livesInPrivate(prior) ? [tombstoneOf(prior, true)] : [];
}

/** An entry's fields as a fresh map: a caller may edit what it reads. */
export function fieldsCopy(value: LaneEntryValue): FrontmatterMap {
  return structuredClone(value.fields) as FrontmatterMap;
}

/** Whether `value` already holds exactly these fields and text. */
export function sameEntry(
  value: LaneEntryValue | null,
  fields: Readonly<Record<string, unknown>>,
  text: string,
  raw?: string,
): boolean {
  return (
    value !== null &&
    value.text === text &&
    canonicalJson(value.fields) === canonicalJson(fields) &&
    value.raw === raw
  );
}

function authorityFor(lane: string): Authority {
  return lane === STANDING_RULE_LANE ? "human" : authorityFromOrigin();
}

export function isPrivateEntry(
  vault: string,
  fields: Readonly<Record<string, unknown>>,
  text: string,
  raw?: string,
): boolean {
  return (
    isPrivateFrontmatter(fields) ||
    rowNamesPrivatePage(
      existsSync(vault) ? vault : null,
      lanePrivacyRow(fields, text, raw),
      PAGE_OPAQUE_FIELDS,
    )
  );
}

export function entryRecord(
  vault: string,
  path: string,
  fields: Readonly<Record<string, unknown>>,
  text: string,
  isPrivate: boolean,
  /**
   * `located`: `isPrivate` is where an existing entry lives (a move), and
   * the record stays there; the lane's private-when-held rule would send
   * a shared entry's move, its tombstone included, to `private`, where a
   * device without that partition never sees the old entry removed.
   */
  placement: "judged" | "located" = "judged",
  raw?: string,
): DualWriteRecord {
  const { lane, entry } = placeOf(vault, path);
  const agent =
    typeof fields["agent"] === "string" && fields["agent"].trim() !== ""
      ? fields["agent"].trim()
      : undefined;
  const kept = rawToKeep(path, raw, fields, text);
  return laneEntryRecord({
    lane,
    entry,
    fields,
    text,
    ...(kept !== undefined ? { raw: kept } : {}),
    authority: authorityFor(lane),
    ...(agent !== undefined ? { agent } : {}),
    private: isPrivate,
    // The lanes the migration imports as blobs are private wherever this
    // machine holds the private partition (`surface-map.ts` `blobLane`).
    ...(placement === "judged" && PRIVATE_WHEN_HELD_LANES.has(lane)
      ? { privateWhenHeld: true }
      : {}),
  });
}

/** Lanes whose records go to `private` whenever this machine holds it. */
const PRIVATE_WHEN_HELD_LANES: ReadonlySet<string> = new Set(["source-archive"]);

/**
 * Whether a write to `path` replaces a private lane entry (design D14, one
 * verdict per operation, fail closed). Such an entry stays private whatever
 * the new content says: an overwrite that drops the visibility field must
 * never land the entry's text in `shared`. Nothing lowers an entry's
 * partition; an operator who wants it shared removes it and writes it anew.
 *
 * Two halves, because on an unswitched machine the legacy file is replaced
 * before the dual-write record is built:
 *  - {@link legacyPagePrivate}, read before the write: the legacy page's
 *    own frontmatter (an unswitched machine only; a legacy page has no
 *    partition).
 *  - {@link storedEntryPrivate}, read when the record is built: the live
 *    store entry lives in `private` or its fields reserve it.
 */
export function legacyPagePrivate(vault: string, path: string): boolean {
  if (!isLaneEntryPath(vault, path) || heldInStore(vault, path) || !existsSync(path)) return false;
  try {
    return isPrivateFrontmatter(laneTextParts(path, readFileSync(path, "utf8")).fields);
  } catch {
    // A page that exists but cannot be read cannot be judged: fail closed.
    return true;
  }
}

/**
 * See {@link legacyPagePrivate}. While the fold may miss a record
 * ({@link foldIncomplete}), the entry may be private in it: the write is judged private (on a machine without
 * the `private` partition, refused).
 */
export function storedEntryPrivate(vault: string, path: string): boolean {
  if (!isLaneEntryPath(vault, path)) return false;
  if (foldIncomplete()) return true;
  const value = storeEntry(vault, path);
  return value !== null && (livesInPrivate(value) || isPrivateFrontmatter(value.fields));
}

/**
 * A lane file's text as an entry's fields and text: a page's frontmatter
 * and body, a JSON object as the fields, anything else (malformed JSON
 * included, which the legacy writer also writes as it is) as text.
 */
export { laneTextParts } from "./lane-raw.ts";