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
24.0 KB
Raw Blame
/**
 * Decision-change receipts (Belief lifecycle suite, B4, t_3547314d).
 *
 * A `decision_change.v1` receipt is an append-only accountability record
 * emitted at the moment a belief changes: what it was (`before`), what it
 * became (`after`), the evidence that triggered the change, the
 * confidence delta, the alternatives considered, the actor, a rationale,
 * and a machine reason code. Receipts are append-only accountability, NOT
 * rollback (typed revertible history is a separate ADR wave, out of scope
 * here).
 *
 * Storage mirrors the truth ledger's shard discipline (`truth/store.ts`):
 * device-sharded append-only JSONL alongside the truth ledger shards
 * (`Brain/truth/decision-change[.<deviceId>].jsonl`), Syncthing-safe and
 * fail-closed per line. The claim reader ignores these shards (its regex
 * only matches `claims*.jsonl`), and this reader ignores claim shards.
 *
 * Durability + idempotency: the key is a sha256 of `subject + before +
 * after`, so replaying the same change is a no-op - the second append
 * finds the key already present and returns the existing receipt. The
 * schema is CLOSED: any field outside the accountable set (e.g. a hidden
 * free-text reasoning field) is rejected with a typed error. History is
 * queryable with an opaque cursor and exact counts. Reads never write.
 */

import { mkdirSync, appendFileSync, readdirSync, readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { join } from "node:path";

import { resolveDeviceId } from "../../config.ts";
import {
  JSONL_LEDGER_EXT,
  jsonlLedgerGrammar,
  parseShardedName,
  shardedFileName,
} from "../ledger-shards.ts";
import { appendLogEvent } from "../log.ts";
import { decodeOffsetCursor, encodeOffsetCursor } from "../offset-cursor.ts";
import { BRAIN_LOG_EVENT_KIND } from "../types.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import { readLedgerRows } from "../../store/read/ledger-rows.ts";
import { isStoreOnly } from "../../store/store-only.ts";
import { routeWrite } from "../../store/store-write.ts";
import { DUAL_WRITE_LEDGERS, ledgerRowRecord } from "../../store/dual-write-records.ts";
import { rowNamesPrivatePage } from "../../store/reference-privacy.ts";

/** Schema tag stamped on every receipt line. */
export const DECISION_CHANGE_SCHEMA_VERSION = "decision_change.v1";

/**
 * Sentinel `before`/`after` state for a receipt whose belief did not
 * exist on that side of the change (a creation has no prior state). The
 * closed schema requires a non-empty string, so an absent state is this
 * explicit marker rather than the empty string.
 */
export const RECEIPT_ABSENT_STATE = "(absent)";

/**
 * Closed reason-code vocabulary for decision-record change receipts. A
 * decision mutation stamps exactly one of these so the change trail is
 * machine-filterable alongside the lifecycle codes (supersede/tombstone).
 * `openResolved` (write-side-trust wave, Task 10) stamps the transition
 * that closed an open decision by minting a real decision page: the
 * receipt's subject is the OPEN record, so the trail answers "which
 * parked question became this decision".
 */
export const DECISION_CHANGE_REASON = Object.freeze({
  record: "decision-record",
  outcome: "decision-outcome",
  rating: "decision-rating",
  openResolved: "open-resolved",
} as const);

/** Same canonical UTC shape the truth ledger and log writer emit. */
const ISO_UTC_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;

/** `decision-change.jsonl` or `decision-change.<deviceId>.jsonl`, via the shared ledger-shard grammar. */
const RECEIPT_STEM = "decision-change";
export const RECEIPT_GRAMMAR = jsonlLedgerGrammar(RECEIPT_STEM);

/** Cap on the length of any single string field (mirrors note-text caps). */
const FIELD_MAX_LEN = 2000;

/** Default page size for {@link queryDecisionChangeHistory}. */
export const DECISION_HISTORY_DEFAULT_LIMIT = 50;

/**
 * The one `errno` that means the receipt store was never created, as
 * opposed to created and unreachable. See
 * {@link readDecisionChangeReceipts}.
 */
const DIR_ABSENT_ERRNO = "ENOENT";

/** Every failure path in this module raises this typed error. */
export class ReceiptError extends Error {
  constructor(message: string, options?: ErrorOptions) {
    super(message, options);
    this.name = "ReceiptError";
  }
}

// ----- Shapes ---------------------------------------------------------------

export interface DecisionChangeReceipt {
  readonly v: typeof DECISION_CHANGE_SCHEMA_VERSION;
  readonly ts: string;
  /** Id/wikilink of the belief that changed. */
  readonly subject: string;
  /** Canonical before-state string. */
  readonly before: string;
  /** Canonical after-state string. */
  readonly after: string;
  /** Wikilinks/ids of the evidence that triggered the change. */
  readonly evidence_triggers: ReadonlyArray<string>;
  /** Confidence movement (after - before), or `null` when not applicable. */
  readonly confidence_delta: number | null;
  /** Alternatives considered but not chosen. */
  readonly alternatives: ReadonlyArray<string>;
  /** Agent/human who made the change. */
  readonly actor: string;
  /** Accountable justification (a permitted free-text field). */
  readonly rationale: string;
  /** Machine reason code (e.g. `supersede`, `tombstone`, `confidence-refresh`). */
  readonly reason_code: string;
  /** sha256(subject + before + after); replays are no-ops. */
  readonly idempotency_key: string;
}

export interface AppendReceiptInput {
  readonly subject: string;
  readonly before: string;
  readonly after: string;
  readonly evidenceTriggers?: ReadonlyArray<string>;
  readonly confidenceDelta?: number | null;
  readonly alternatives?: ReadonlyArray<string>;
  readonly actor: string;
  readonly rationale?: string;
  readonly reasonCode: string;
  /** ISO-8601 UTC instant; defaults to now. */
  readonly ts?: string;
  readonly configPath?: string;
}

export interface AppendReceiptResult {
  readonly appended: boolean;
  readonly path: string;
  readonly receipt: DecisionChangeReceipt;
}

/**
 * The closed set of accepted input keys. Any key outside this set is a
 * schema violation - this is what rejects a hidden free-text reasoning
 * field smuggled onto the input.
 */
const ALLOWED_INPUT_KEYS: ReadonlySet<string> = new Set([
  "subject",
  "before",
  "after",
  "evidenceTriggers",
  "confidenceDelta",
  "alternatives",
  "actor",
  "rationale",
  "reasonCode",
  "ts",
  "configPath",
]);

// ----- Paths ----------------------------------------------------------------

/** Receipt shards live alongside the truth ledger shards. */
export function receiptsDir(vault: string): string {
  return join(vault, "Brain", "truth");
}

/**
 * The receipt shard this device appends to.
 *
 * @throws {@link ConfigReadError} when the device-local config naming this
 *   device cannot be read. Propagated rather than falling back to the
 *   legacy un-sharded `decision-change.jsonl`: `resolveDeviceId` would
 *   otherwise mint and persist a fresh id over a config it could not read
 *   (see its docblock), and a silent shard switch would scatter one
 *   device's receipts across two files with nothing recording why. The
 *   error names the file and the way out; the CLI verb wrapping this call
 *   prints it, and `O2B_DEVICE_ID` resolves the append without the file.
 */
export function receiptShardPath(vault: string, configPath?: string): string {
  const deviceId = resolveDeviceId(configPath);
  const name = shardedFileName(RECEIPT_STEM, deviceId, JSONL_LEDGER_EXT);
  return join(receiptsDir(vault), name);
}

// ----- Validation -----------------------------------------------------------

function requireString(value: unknown, label: string): string {
  if (typeof value !== "string" || value.trim() === "") {
    throw new ReceiptError(`receipt: ${label} is required`);
  }
  if (value.length > FIELD_MAX_LEN) {
    throw new ReceiptError(`receipt: ${label} exceeds ${FIELD_MAX_LEN} chars`);
  }
  return value.trim();
}

function optionalStringList(value: unknown, label: string): ReadonlyArray<string> {
  if (value === undefined || value === null) return [];
  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
    throw new ReceiptError(`receipt: ${label} must be a list of strings`);
  }
  return value.map((v) => (v as string).trim()).filter((v) => v.length > 0);
}

function computeIdempotencyKey(subject: string, before: string, after: string): string {
  return createHash("sha256").update(`${subject}\n${before}\n${after}`, "utf8").digest("hex");
}

/**
 * Reduce a receipt subject to its bare identifier for read-side matching.
 *
 * Receipts store `subject` in whichever shape the writer had on hand: a
 * decision record's B4 hook stamps a wikilink (`[[decision-adopt-bun]]`,
 * `record.ts`), while the lifecycle tombstone/supersede hook stamps a bare
 * vault-relative path (`Brain/decisions/decision-adopt-bun.md`,
 * `lifecycle/tombstone.ts`). A history query filtering by subject would
 * otherwise require the caller to know which writer produced a given
 * receipt. This strips, in order: a `[[ ]]` wikilink fence (and any
 * `|alias` display suffix), a leading directory prefix, and a trailing
 * `.md` extension - so the bare id, wikilink, and full-path forms of the
 * same subject all normalize to one value. Storage is untouched; this is
 * read-side normalization only, applied at query time in
 * {@link queryDecisionChangeHistory}.
 */
export function normalizeDecisionSubject(raw: string): string {
  let value = raw.trim();
  const fence = /^\[\[([^\]]+)\]\]$/.exec(value);
  if (fence) value = fence[1]!.trim();
  const pipe = value.indexOf("|");
  if (pipe >= 0) value = value.slice(0, pipe).trim();
  const slash = Math.max(value.lastIndexOf("/"), value.lastIndexOf("\\"));
  if (slash >= 0) value = value.slice(slash + 1);
  if (value.toLowerCase().endsWith(".md")) value = value.slice(0, -3);
  return value;
}

// ----- Append ---------------------------------------------------------------

/**
 * Validate and append one decision-change receipt. Idempotent: if a
 * receipt with the same `subject + before + after` key already exists,
 * this is a no-op returning the existing receipt with `appended: false`.
 */
export function appendDecisionChangeReceipt(
  vault: string,
  input: AppendReceiptInput,
): AppendReceiptResult {
  // Closed-schema gate: reject any unexpected field before doing anything.
  for (const key of Object.keys(input)) {
    if (!ALLOWED_INPUT_KEYS.has(key)) {
      throw new ReceiptError(`receipt: unexpected field ${JSON.stringify(key)} is not permitted`);
    }
  }

  const subject = requireString(input.subject, "subject");
  const before = requireString(input.before, "before");
  const after = requireString(input.after, "after");
  const actor = requireString(input.actor, "actor");
  const reasonCode = requireString(input.reasonCode, "reasonCode");
  const rationale =
    input.rationale === undefined || input.rationale === null
      ? ""
      : requireString(input.rationale, "rationale");
  const evidenceTriggers = optionalStringList(input.evidenceTriggers, "evidenceTriggers");
  const alternatives = optionalStringList(input.alternatives, "alternatives");
  let confidenceDelta: number | null = null;
  if (input.confidenceDelta !== undefined && input.confidenceDelta !== null) {
    if (typeof input.confidenceDelta !== "number" || !Number.isFinite(input.confidenceDelta)) {
      throw new ReceiptError("receipt: confidenceDelta must be a finite number or null");
    }
    confidenceDelta = input.confidenceDelta;
  }
  const ts = input.ts ?? new Date().toISOString();
  if (!ISO_UTC_TS_RE.test(ts)) {
    throw new ReceiptError(`receipt: ts must be canonical ISO-8601 UTC: ${JSON.stringify(ts)}`);
  }

  const idempotencyKey = computeIdempotencyKey(subject, before, after);

  // Idempotency: a matching key already on disk makes this a no-op. The
  // read raises rather than reporting an empty store when the directory
  // exists and cannot be listed, so a replay under a denied read refuses
  // instead of appending a second copy of the same change.
  const readOptions = input.configPath !== undefined ? { configPath: input.configPath } : {};
  const storeOnly = isStoreOnly({ vault, ...readOptions });
  const existing = readDecisionChangeReceipts(vault, readOptions).receipts.find(
    (r) => r.idempotency_key === idempotencyKey,
  );
  if (existing) {
    // The same `path` rule as an append: the shard on an unswitched
    // machine, the store ledger once switched (no legacy path that never
    // exists there).
    return Object.freeze({
      appended: false,
      path: storeOnly ? RECEIPT_STORE_SOURCE : receiptShardPath(vault, input.configPath),
      receipt: existing,
    });
  }

  const receipt: DecisionChangeReceipt = Object.freeze({
    v: DECISION_CHANGE_SCHEMA_VERSION,
    ts,
    subject,
    before,
    after,
    evidence_triggers: Object.freeze([...evidenceTriggers]),
    confidence_delta: confidenceDelta,
    alternatives: Object.freeze([...alternatives]),
    actor,
    rationale,
    reason_code: reasonCode,
    idempotency_key: idempotencyKey,
  });

  // One `decision-receipts` ledger row on a store-only machine (design D14
  // item 1), this device's receipt shard plus the dual write otherwise. A
  // receipt about a private item (its subject, evidence or rationale names
  // a private or unjudgeable preference or page) stays out of `shared`.
  const routed = routeWrite({
    legacy: () => {
      // Vault-identity write guard (context-integrity-gates, Unit J).
      assertVaultIdentityForWrite(vault);
      mkdirSync(receiptsDir(vault), { recursive: true });
      const shard = receiptShardPath(vault, input.configPath);
      appendFileSync(shard, JSON.stringify(receipt) + "\n");
      return shard;
    },
    store: () =>
      ledgerRowRecord(
        DUAL_WRITE_LEDGERS.decisionReceipts,
        receipt,
        rowNamesPrivatePage(vault, receipt) ? "private" : "shared",
      ),
    context: { vault, ...(input.configPath !== undefined ? { configPath: input.configPath } : {}) },
  });
  // The store ledger names the receipt once switched, for an append and a
  // replay alike (never a device-local shard path).
  const path = routed.mode === "legacy" ? routed.value : RECEIPT_STORE_SOURCE;
  // Surface the change in the merged activity timeline. Emitted only on an
  // actual append, never on an idempotent replay, so the log never
  // double-counts a change. Fail-soft: a log hiccup must not lose the receipt.
  try {
    appendLogEvent(
      vault,
      {
        timestamp: ts,
        eventType: BRAIN_LOG_EVENT_KIND.decisionChangeReceipt,
        body: {
          subject,
          reason_code: reasonCode,
          idempotency_key: idempotencyKey,
          agent: actor,
        },
      },
      { failOpen: true },
    );
  } catch {
    // The JSONL receipt is authoritative; the timeline mirror is best-effort.
  }
  return Object.freeze({ appended: true, path, receipt });
}

// ----- Read -----------------------------------------------------------------

export interface ReceiptParseWarning {
  readonly path: string;
  readonly lineNumber: number;
  readonly message: string;
}

export interface ReadReceiptsResult {
  readonly receipts: ReadonlyArray<DecisionChangeReceipt>;
  readonly warnings: ReadonlyArray<ReceiptParseWarning>;
}

/**
 * Read every receipt merged across device shards, sorted by
 * (ts, shardId, line). Fail-closed per line: a malformed or
 * unknown-version line surfaces as a warning. Never writes.
 *
 * ## An unreadable directory is not an empty one
 *
 * The directory read used to be wrapped in a bare `catch` returning no
 * receipts and no warnings, which gave a vault whose `Brain/truth/` the
 * process cannot enter exactly the answer a vault that has never
 * recorded a decision gets. Two consequences, both real:
 *
 *   - every read surface - the history query, the audit join - reported
 *     "no decisions" for a store it had not looked at;
 *   - the idempotency probe in {@link appendDecisionChangeReceipt} reads
 *     through this function, so an unreadable directory read as "no
 *     prior receipt with this key" and the append went ahead. The one
 *     guard against a duplicated accountability record was disabled by
 *     precisely the condition under which it mattered most.
 *
 * So only ABSENCE is quiet, and it is quiet because a vault that has
 * never appended a receipt legitimately has no directory. Every other
 * failure - a permission denial, a file standing where the directory
 * should be, an I/O error - raises {@link ReceiptError} naming the path.
 * Per-shard failures below stay warnings: there the reader knows what it
 * did and did not read, and can say so.
 *
 * @throws {@link ReceiptError} when the receipt directory exists and
 *   cannot be listed.
 */
export function readDecisionChangeReceipts(
  vault: string,
  options: { readonly configPath?: string } = {},
): ReadReceiptsResult {
  // A store-only machine (design D14 item 1) reads the `decision-receipts`
  // ledger rows, sorted by `ts` with fold order breaking ties. The machine
  // config decides the mode and the store, as it does for the append.
  const context = {
    vault,
    ...(options.configPath !== undefined ? { configPath: options.configPath } : {}),
  };
  if (isStoreOnly(context)) {
    const warnings: ReceiptParseWarning[] = [];
    const receipts: DecisionChangeReceipt[] = [];
    readLedgerRows<unknown>(DUAL_WRITE_LEDGERS.decisionReceipts, () => [], context).forEach(
      (row, index) => {
        const receipt = coerceReceipt(row, RECEIPT_STORE_SOURCE, index + 1, warnings);
        if (receipt !== null) receipts.push(receipt);
      },
    );
    return {
      receipts: receipts.toSorted((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0)),
      warnings,
    };
  }
  const dir = receiptsDir(vault);
  let names: string[];
  try {
    names = readdirSync(dir).toSorted();
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === DIR_ABSENT_ERRNO) {
      return { receipts: [], warnings: [] };
    }
    throw new ReceiptError(
      `receipt: failed to list ${dir}: ${(err as Error).message ?? String(err)}`,
      { cause: err },
    );
  }

  interface Tagged {
    readonly receipt: DecisionChangeReceipt;
    readonly shardId: string;
    readonly line: number;
  }
  const tagged: Tagged[] = [];
  const warnings: ReceiptParseWarning[] = [];

  for (const name of names) {
    const shard = parseShardedName(name, RECEIPT_GRAMMAR);
    if (shard === null) continue;
    const shardId = shard.shardId;
    const path = join(dir, name);
    let text: string;
    try {
      text = readFileSync(path, "utf8");
    } catch (err) {
      warnings.push({
        path,
        lineNumber: 0,
        message: `failed to read shard: ${(err as NodeJS.ErrnoException).message ?? String(err)}`,
      });
      continue;
    }
    const lines = text.split(/\r?\n/);
    for (let i = 0; i < lines.length; i++) {
      const line = lines[i]!;
      if (line.trim() === "") continue;
      let parsed: unknown;
      try {
        parsed = JSON.parse(line);
      } catch {
        warnings.push({ path, lineNumber: i + 1, message: `malformed JSONL line` });
        continue;
      }
      const receipt = coerceReceipt(parsed, path, i + 1, warnings);
      if (receipt !== null) tagged.push({ receipt, shardId, line: i });
    }
  }

  tagged.sort((a, b) => {
    if (a.receipt.ts !== b.receipt.ts) return a.receipt.ts < b.receipt.ts ? -1 : 1;
    if (a.shardId !== b.shardId) return a.shardId < b.shardId ? -1 : 1;
    return a.line - b.line;
  });

  return { receipts: tagged.map((t) => t.receipt), warnings };
}

/** The `path` a warning about a store row names: the ledger it came from. */
const RECEIPT_STORE_SOURCE = `store:ledgers/${DUAL_WRITE_LEDGERS.decisionReceipts}`;

function coerceReceipt(
  parsed: unknown,
  path: string,
  lineNumber: number,
  warnings: ReceiptParseWarning[],
): DecisionChangeReceipt | null {
  if (typeof parsed !== "object" || parsed === null) {
    warnings.push({ path, lineNumber, message: "not an object" });
    return null;
  }
  const r = parsed as Record<string, unknown>;
  if (r["v"] !== DECISION_CHANGE_SCHEMA_VERSION) {
    warnings.push({ path, lineNumber, message: `unknown schema version ${String(r["v"])}` });
    return null;
  }
  if (
    typeof r["subject"] !== "string" ||
    typeof r["before"] !== "string" ||
    typeof r["after"] !== "string" ||
    typeof r["idempotency_key"] !== "string"
  ) {
    warnings.push({ path, lineNumber, message: "missing required field" });
    return null;
  }
  return Object.freeze({
    v: DECISION_CHANGE_SCHEMA_VERSION,
    ts: typeof r["ts"] === "string" ? r["ts"] : "",
    subject: r["subject"] as string,
    before: r["before"] as string,
    after: r["after"] as string,
    evidence_triggers: Array.isArray(r["evidence_triggers"])
      ? (r["evidence_triggers"] as string[]).filter((v) => typeof v === "string")
      : [],
    confidence_delta:
      typeof r["confidence_delta"] === "number" ? (r["confidence_delta"] as number) : null,
    alternatives: Array.isArray(r["alternatives"])
      ? (r["alternatives"] as string[]).filter((v) => typeof v === "string")
      : [],
    actor: typeof r["actor"] === "string" ? (r["actor"] as string) : "",
    rationale: typeof r["rationale"] === "string" ? (r["rationale"] as string) : "",
    reason_code: typeof r["reason_code"] === "string" ? (r["reason_code"] as string) : "",
    idempotency_key: r["idempotency_key"] as string,
  });
}

// ----- History query --------------------------------------------------------

export interface DecisionHistoryQuery {
  /** Filter to a single subject id/wikilink. */
  readonly subject?: string;
  /** Opaque cursor from a prior page's `nextCursor`. */
  readonly cursor?: string;
  /** Page size; defaults to {@link DECISION_HISTORY_DEFAULT_LIMIT}. */
  readonly limit?: number;
  /**
   * Keep only the receipts this answers true for, before the total and
   * the page are taken, so a dropped receipt moves neither. Absent, every
   * receipt is kept.
   */
  readonly keep?: (receipt: DecisionChangeReceipt) => boolean;
}

export interface DecisionHistoryPage {
  readonly receipts: ReadonlyArray<DecisionChangeReceipt>;
  /** Exact count of receipts matching the filter (across all pages). */
  readonly total: number;
  /** Opaque cursor for the next page, or `null` when exhausted. */
  readonly nextCursor: string | null;
}

/**
 * The decisions history speaks the canonical core offset-cursor encoding
 * (src/core/brain/offset-cursor.ts); its wire form (`o:<offset>` base64url)
 * is unchanged since this surface shipped it first. A malformed cursor is
 * still a `ReceiptError` on this surface's contract.
 */
function decodeReceiptCursor(cursor: string): number {
  try {
    return decodeOffsetCursor(cursor);
  } catch {
    throw new ReceiptError("receipt: malformed cursor");
  }
}

/**
 * Paginated, subject-filterable history over the receipt log. Returns the
 * page, an opaque `nextCursor` (null when exhausted), and the exact total
 * matching the filter. Read-only: never appends.
 */
export function queryDecisionChangeHistory(
  vault: string,
  query: DecisionHistoryQuery,
): DecisionHistoryPage {
  const limit = query.limit ?? DECISION_HISTORY_DEFAULT_LIMIT;
  if (!Number.isInteger(limit) || limit <= 0) {
    throw new ReceiptError("receipt: limit must be a positive integer");
  }
  const offset = query.cursor !== undefined ? decodeReceiptCursor(query.cursor) : 0;

  const read = readDecisionChangeReceipts(vault).receipts;
  const all = query.keep === undefined ? read : read.filter(query.keep);
  let matching = all;
  if (query.subject !== undefined) {
    // Read-side only: receipts store subjects in whichever shape their
    // writer had on hand (bare id, wikilink, or vault-relative path), so
    // both sides are normalized to the bare id before comparing.
    const wanted = normalizeDecisionSubject(query.subject);
    matching = all.filter((r) => normalizeDecisionSubject(r.subject) === wanted);
  }
  const total = matching.length;
  const page = matching.slice(offset, offset + limit);
  const nextOffset = offset + page.length;
  const nextCursor = nextOffset < total ? encodeOffsetCursor(nextOffset) : null;
  return Object.freeze({ receipts: page, total, nextCursor });
}