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
7.5 KB
Raw Blame
/**
 * `o2b brain migrate-store --dry-run` (task 2.2, design D11): what a
 * migration of this vault into the brain store would do, computed from the
 * legacy tree alone and written nowhere.
 *
 * The report names:
 *
 *  - the devices seen in the legacy tree: the cohort (every device id in a
 *    legacy shard name, with no age limit) and the roster (those whose
 *    shards changed in the last {@link DIGEST_ROSTER_WINDOW_DAYS} days);
 *  - per surface and lane: its planned destination, how many files, bytes
 *    and items it holds, and for a stream how many of those items each
 *    partition would receive under the phase 1 privacy rules;
 *  - every item that cannot be read as its surface writes it, with its
 *    path and line;
 *  - every legacy file or folder no mapping covers. Any such entry fails
 *    the dry run (`ok: false`).
 *
 * It never writes: no store, no index, no cache, no lock, no log event.
 */

import { join, relative, sep } from "node:path";

import { DIGEST_ROSTER_WINDOW_DAYS } from "../store/constants.ts";
import {
  describeDestination,
  DESTINATION_KIND,
  type Destination,
  type Locator,
} from "./destinations.ts";
import {
  itemPartition,
  itemRecords,
  legacyRootNames,
  migrationCatalogue,
  recordDestination,
  type CatalogueEntry,
} from "./catalogue.ts";
import { unclaimedEntries, type UnmappedEntry } from "./legacy-claims.ts";
import { emptyTally, scanLocator, type ScanTally } from "./legacy-scan.ts";

/** The most unparseable items a report lists one by one. */
export const DRY_RUN_PROBLEM_LIST_CAP = 500;

const DAY_MS = 86_400_000;

/** Partition counts of one stream surface. */
export interface PartitionCounts {
  shared: number;
  private: number;
  "private-when-held": number;
}

/** One surface or lane in the report. */
export interface SurfaceReport {
  readonly id: string;
  readonly label: string;
  readonly source: "state-surface" | "lane";
  /** Vault-relative location, `/`-separated. */
  readonly path: string;
  readonly destination: DestinationSummary;
  readonly planned: string;
  readonly present: boolean;
  readonly files: number;
  readonly bytes: number;
  readonly items: number;
  /** Per-partition item counts; null for a surface that is not a stream. */
  readonly partitions: PartitionCounts | null;
  readonly unparseable: number;
}

export interface DestinationSummary {
  readonly to: Destination["to"];
  readonly stream?: string;
  readonly ledger?: string | null;
  readonly kind?: string;
  readonly partition?: string;
}

export interface DeviceReport {
  readonly device: string;
  readonly files: number;
  readonly items: number;
  readonly last_seen: string;
  readonly in_roster: boolean;
}

export interface UnparseableReport {
  readonly surface: string;
  readonly path: string;
  readonly line: number | null;
  readonly reason: string;
}

export interface MigrationDryRun {
  readonly dry_run: true;
  /** True when every legacy entry has a mapping. */
  readonly ok: boolean;
  readonly vault: string;
  readonly devices: {
    readonly roster_window_days: number;
    readonly cohort: ReadonlyArray<DeviceReport>;
    readonly roster: ReadonlyArray<string>;
    readonly unsharded_files: number;
  };
  readonly surfaces: ReadonlyArray<SurfaceReport>;
  readonly unparseable: ReadonlyArray<UnparseableReport>;
  /** Unparseable items beyond {@link DRY_RUN_PROBLEM_LIST_CAP}. */
  readonly unparseable_not_listed: number;
  readonly unmapped: ReadonlyArray<UnmappedEntry>;
  readonly totals: {
    readonly items: number;
    readonly unparseable: number;
    readonly unmapped: number;
  };
}

function summarize(destination: Destination): DestinationSummary {
  if (destination.to === DESTINATION_KIND.stream) {
    return {
      to: destination.to,
      stream: destination.stream,
      ledger: destination.ledger,
      kind: destination.kind,
      partition: destination.partition,
    };
  }
  if (destination.to === DESTINATION_KIND.blob) {
    return { to: destination.to, partition: destination.partition };
  }
  return { to: destination.to };
}

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

function scanEntry(
  vault: string,
  entry: CatalogueEntry,
): { tally: ScanTally; partitions: PartitionCounts | null } {
  const tally = emptyTally();
  const destination = recordDestination(entry);
  const partitions: PartitionCounts | null =
    destination === null ? null : { shared: 0, private: 0, "private-when-held": 0 };
  for (const locator of entry.locators) {
    scanLocator(locator, tally, (item) => {
      if (destination === null || partitions === null) return;
      partitions[itemPartition(itemRecords(vault, destination, item))] += 1;
    });
  }
  return { tally, partitions };
}

export interface MigrationDryRunOptions {
  /** The clock the roster window is measured against; defaults to now. */
  readonly nowMs?: number;
}

/** Plan the migration of `vault` without writing anything. */
export function planMigrationDryRun(
  vault: string,
  options: MigrationDryRunOptions = {},
): MigrationDryRun {
  const nowMs = options.nowMs ?? Date.now();
  const surfaces: SurfaceReport[] = [];
  const unparseable: UnparseableReport[] = [];
  const devices = new Map<string, { files: number; items: number; lastSeenMs: number }>();
  const allLocators: Locator[] = [];
  let unshardedFiles = 0;
  let problems = 0;
  let items = 0;

  const catalogue = migrationCatalogue(vault);
  for (const entry of catalogue) {
    allLocators.push(...entry.locators);
    const { tally, partitions } = scanEntry(vault, entry);
    for (const [device, seen] of tally.devices) {
      const total = devices.get(device) ?? { files: 0, items: 0, lastSeenMs: 0 };
      total.files += seen.files;
      total.items += seen.items;
      total.lastSeenMs = Math.max(total.lastSeenMs, seen.lastSeenMs);
      devices.set(device, total);
    }
    unshardedFiles += tally.unshardedFiles;
    problems += tally.problems.length;
    items += tally.items;
    for (const problem of tally.problems) {
      if (unparseable.length >= DRY_RUN_PROBLEM_LIST_CAP) break;
      unparseable.push({ surface: entry.id, ...problem, path: vaultRel(vault, problem.path) });
    }
    surfaces.push({
      id: entry.id,
      label: entry.label,
      source: entry.source,
      path: vaultRel(vault, entry.primary),
      destination: summarize(entry.mapping.destination),
      planned: describeDestination(entry.mapping.destination),
      present: tally.files > 0,
      files: tally.files,
      bytes: tally.bytes,
      items: tally.items,
      partitions,
      unparseable: tally.problems.length,
    });
  }

  const unmapped = unclaimedEntries(
    vault,
    legacyRootNames(vault, catalogue).map((top) => join(vault, top)),
    allLocators,
  );
  const windowStart = nowMs - DIGEST_ROSTER_WINDOW_DAYS * DAY_MS;
  const cohort: DeviceReport[] = [...devices.entries()]
    .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
    .map(([device, seen]) => ({
      device,
      files: seen.files,
      items: seen.items,
      last_seen: new Date(seen.lastSeenMs).toISOString(),
      in_roster: seen.lastSeenMs >= windowStart,
    }));

  return {
    dry_run: true,
    ok: unmapped.length === 0,
    vault,
    devices: {
      roster_window_days: DIGEST_ROSTER_WINDOW_DAYS,
      cohort,
      roster: cohort.filter((d) => d.in_roster).map((d) => d.device),
      unsharded_files: unshardedFiles,
    },
    surfaces,
    unparseable,
    unparseable_not_listed: problems - unparseable.length,
    unmapped,
    totals: { items, unparseable: problems, unmapped: unmapped.length },
  };
}