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
9.0 KB
Raw Blame
/**
 * The devices a store knows, and retiring one (design D6, D11a; FORMAT.md
 * "State digests" and "Record kinds"): what `o2b store device list` and
 * `o2b store device retire` call.
 *
 *  - {@link listDevices}: every device with a record in a partition this
 *    machine holds, every device of the migration cohort and every device
 *    a retirement names, with its last record, its state (`switched`: it
 *    recorded its switch to the store; `legacy`: it did not; `retired`: a
 *    human retired it and it has written nothing since) and whether it is
 *    on the digest roster (a record in the last 30 days, not retired).
 *  - {@link retireDevice}: appends one `device-retire` record with
 *    `authority` `human` to the `settings` stream of `shared`, where the
 *    digest roster (`state-digest-compare.ts`) and the removal gate
 *    (`legacyDevices` in `store-migration/migration-records.ts`) read it.
 *    This machine's own id is refused, and so is a reason that would
 *    route the record to `private` (every machine must read it).
 *  - {@link returnedRetiredDevices}: retired devices that wrote a record
 *    after their retirement (a machine brought back, a reused id). They
 *    are on the roster again; doctor names them.
 */

import { isValidDeviceId } from "../config.ts";
import { legacyDevices, switchedDevices } from "../store-migration/migration-records.ts";
import { observeClock, type WallClock } from "./clock-store.ts";
import {
  AUTHORITY_FIELD,
  DAY_MS,
  DEVICE_RETIRE_KIND,
  DIGEST_ROSTER_WINDOW_DAYS,
  STORE_PARTITIONS,
} from "./constants.ts";
import { appendRecord } from "./appender.ts";
import {
  lastRecords,
  latestRetirements,
  returnedAfterRetirement,
  wroteAfter,
} from "./device-retirement.ts";
import type { StoreRecord } from "./envelope.ts";
import { parseHlc } from "./hlc.ts";
import { callerInput, opaqueFields, operationPrivacy } from "./operation-privacy.ts";
import { readPartition } from "./state-digest.ts";
import type { StoreHandle } from "./store-open.ts";
import { partitionDir } from "./store-paths.ts";

/** The stream retirements are written to, in `shared`. */
const RETIRE_STREAM = "settings";

export type DeviceState = "switched" | "legacy" | "retired";

export interface DeviceEntry {
  readonly device: string;
  /** Physical time of its last record in a held partition, `null` when it has none. */
  readonly lastSeenMs: number | null;
  readonly state: DeviceState;
  /** On the digest roster: a record in the roster window and not retired. */
  readonly onRoster: boolean;
  readonly thisMachine: boolean;
  /** A human retired it and it wrote a record after that. */
  readonly returnedAfterRetire: boolean;
}

export type DeviceRetireRefusalReason =
  | "own-device"
  | "invalid-device"
  | "private-reason"
  | "no-shared";

/** A retirement that was refused before anything was written. */
export class DeviceRetireRefusal extends Error {
  readonly reason: DeviceRetireRefusalReason;
  constructor(reason: DeviceRetireRefusalReason, message: string) {
    super(message);
    this.name = "DeviceRetireRefusal";
    this.reason = reason;
  }
}

const physical = (record: StoreRecord): number => parseHlc(record.hlc)!.physical;

/** Every shard of every partition this machine holds; an unreadable shard is skipped. */
function heldShards(store: Pick<StoreHandle, "root" | "partitions">) {
  return STORE_PARTITIONS.filter((p) => store.partitions.has(p)).flatMap((partition) =>
    readPartition(partitionDir(store.root, partition), { onUnreadable: () => {} }).map((shard) => ({
      partition,
      shard,
    })),
  );
}

/** Every record of every partition this machine holds; an unreadable shard is skipped. */
function heldRecords(store: Pick<StoreHandle, "root" | "partitions">): StoreRecord[] {
  return heldShards(store).flatMap(({ shard }) => shard.all);
}

/**
 * Retired devices that wrote a record after their latest retirement, with
 * that retirement and the time of their last record. Pure: `records` are
 * the records of the partitions to look at, retirements included.
 */
export function returnedRetiredDevices(
  records: Iterable<StoreRecord>,
): Array<{ device: string; retire: StoreRecord; lastRecordMs: number }> {
  return returnedAfterRetirement(records).map(({ device, retire, last }) => ({
    device,
    retire,
    lastRecordMs: physical(last),
  }));
}

/** Every device this store knows, sorted by id; see the module docblock. */
export function listDevices(
  store: StoreHandle,
  options: { readonly nowMs?: number } = {},
): DeviceEntry[] {
  const nowMs = options.nowMs ?? Date.now();
  const shards = heldShards(store);
  const records = shards.flatMap(({ shard }) => shard.all);
  const last = lastRecords(records);
  const retirements = latestRetirements(records);
  const devices = new Set<string>([...last.keys(), ...retirements.keys()]);
  // The cohort devices still on the legacy layout, store records or not.
  for (const device of legacyDevices(store, [])) devices.add(device);
  // One pass over the shards already read, not a re-read per device, and
  // over the shared settings stream alone, the source the store-only write
  // path and the removal gate read (`isDeviceSwitched`), so a switch record
  // that landed anywhere else counts in neither.
  const switched = switchedDevices(
    shards
      .filter(({ partition, shard }) => partition === "shared" && shard.stream === "settings")
      .flatMap(({ shard }) => shard.records),
  );
  const since = nowMs - DIGEST_ROSTER_WINDOW_DAYS * DAY_MS;
  return [...devices].toSorted().map((device): DeviceEntry => {
    const own = last.get(device);
    const retire = retirements.get(device);
    const returned = retire !== undefined && wroteAfter(own, retire);
    const retired = retire !== undefined && !returned;
    const lastSeenMs = own !== undefined ? physical(own) : null;
    let state: DeviceState = "legacy";
    if (retired) state = "retired";
    else if (switched.has(device)) state = "switched";
    return {
      device,
      lastSeenMs,
      state,
      onRoster: !retired && lastSeenMs !== null && lastSeenMs >= since,
      thisMachine: device === store.device,
      returnedAfterRetire: returned,
    };
  });
}

export interface RetireDeviceInput {
  readonly device: string;
  readonly reason?: string;
  /** The writing agent's name, stamped on the record. */
  readonly agent: string;
  /** The vault private pages are judged against; `null` for none. */
  readonly vault: string | null;
  readonly now?: WallClock;
}

export type RetireDeviceResult =
  | { readonly status: "retired"; readonly record: StoreRecord }
  | { readonly status: "already-retired"; readonly record: StoreRecord };

/** Retire `input.device`; see the module docblock. Throws {@link DeviceRetireRefusal}. */
export function retireDevice(store: StoreHandle, input: RetireDeviceInput): RetireDeviceResult {
  const { device } = input;
  if (!isValidDeviceId(device)) {
    throw new DeviceRetireRefusal(
      "invalid-device",
      `"${device}" is not a device id: lowercase letters, digits and hyphens`,
    );
  }
  if (device === store.device) {
    throw new DeviceRetireRefusal(
      "own-device",
      `${device} is this machine; retire a device from another machine that shares the store`,
    );
  }
  if (!store.partitions.has("shared")) {
    throw new DeviceRetireRefusal(
      "no-shared",
      "this machine does not hold the shared partition, where retirements are recorded; " +
        "run the command on a machine that does",
    );
  }
  const reason = input.reason?.trim();
  const body: Record<string, unknown> = {
    [AUTHORITY_FIELD]: "human",
    device,
    ...(reason ? { reason } : {}),
  };
  // Every machine reads retirements from `shared`, so a reason that would
  // route the record to `private` is refused rather than written where the
  // roster never looks (one verdict over the caller input, fail closed).
  const verdict = operationPrivacy(input.vault, {
    content: [callerInput({ reason: reason ?? "" }, opaqueFields())],
  });
  if (verdict()) {
    throw new DeviceRetireRefusal(
      "private-reason",
      "the reason names a private page or carries a <private> region; a retirement is read " +
        "by every machine, so give a reason without them",
    );
  }
  const records = heldRecords(store);
  const own = lastRecords(records).get(device);
  const retire = latestRetirements(records).get(device);
  if (retire !== undefined && !wroteAfter(own, retire)) {
    return { status: "already-retired", record: retire };
  }
  // The retirement must sort after every record of the device this machine
  // has seen, or a record in the same millisecond from a device id that
  // sorts later would read as written after it: raise the clock past it.
  if (own !== undefined) {
    observeClock(store.deviceStateDir, store.device, parseHlc(own.hlc)!, input.now);
  }
  const { record } = appendRecord(
    store,
    {
      partition: "shared",
      stream: RETIRE_STREAM,
      kind: DEVICE_RETIRE_KIND,
      agent: input.agent,
      body,
    },
    input.now !== undefined ? { now: input.now } : {},
  );
  return { status: "retired", record };
}