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
32.6 KB
Raw Blame
/**
 * Claim ledger store (t_d6849b56): device-sharded append-only JSONL
 * under `Brain/truth/`, merging the `log-jsonl.ts` shard discipline
 * (Syncthing-safe concurrent appends) with the `activation/store.ts`
 * derived-fold discipline (the state file is a recomputable cache,
 * never authority).
 *
 *   - `claims.jsonl`              - legacy/un-sharded shard (empty id);
 *   - `claims.<deviceId>.jsonl`   - one append-only file per device;
 *   - `state.json`                - derived fold, safe to delete.
 *
 * Every line carries `v: TRUTH_SCHEMA_VERSION` and parses fail-closed:
 * malformed or unknown-version lines surface as warnings, never throw.
 */

import {
  existsSync,
  mkdirSync,
  appendFileSync,
  readdirSync,
  readFileSync,
  rmSync,
  statSync,
  writeFileSync,
} from "node:fs";
import { join } from "node:path";

import { resolveDeviceId } from "../../config.ts";
import { parseFrontmatter } from "../../vault.ts";
import type { FrontmatterMap } from "../../types.ts";
import { vaultRelative } from "../../path-safety.ts";
import {
  JSONL_LEDGER_EXT,
  jsonlLedgerGrammar,
  parseShardedName,
  shardedFileName,
} from "../ledger-shards.ts";
import { normalizeEntityName } from "../entities/canonical.ts";
import { VALID_FROM_KEY, VALID_UNTIL_KEY } from "../lifecycle/temporal-replace.ts";
import { resolveNotePath } from "../note-path.ts";
import { ANCHORED_WIKILINK_RE, stripWikilinkDecoration } from "../wikilink.ts";
import { computeTruthState } from "./fold.ts";
import {
  isValidityPoint,
  resolveIngestWindow,
  validityWindowMs,
  type SourceValidityWindow,
} from "./validity.ts";
import type {
  ClaimEvent,
  ClaimExtractor,
  ClaimParseWarning,
  ClaimQuantity,
  ClaimSlot,
  ClaimSuccession,
  ClaimSweepOutcome,
  ClaimVersion,
  ReadClaimEventsResult,
  TruthConflict,
  TruthState,
} from "./types.ts";
import { TRUTH_SCHEMA_VERSION } 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, truthClaimRowRecord } from "../../store/dual-write-records.ts";
import { claimSourceIsPrivate } from "../../store/reference-privacy.ts";

/** Default cap on retained claim events (explicit sweep only). */
export const CLAIM_EVENT_MAX_COUNT = 10000;

/**
 * Cap on a caller-supplied `sample_id` (answer-trust review L2.1): the
 * id is copied onto every claim stated against the sample, so an
 * unbounded one could multiply one call's payload across the whole
 * ledger.
 */
export const SAMPLE_ID_MAX_LENGTH = 256;

/** Control characters (C0 plus DEL) an opaque sample id may not carry. */
const SAMPLE_ID_CONTROL_CHARS_RE = /[\u0000-\u001F\u007F]/;

/**
 * Whether a TRIMMED `sample_id` is acceptable at the write boundary:
 * non-empty, at most {@link SAMPLE_ID_MAX_LENGTH} characters, and free
 * of control characters. Shared by the store append and the stated
 * boundary so both surfaces refuse identically.
 */
export function isValidClaimSampleId(value: string): boolean {
  return (
    value !== "" && value.length <= SAMPLE_ID_MAX_LENGTH && !SAMPLE_ID_CONTROL_CHARS_RE.test(value)
  );
}

// Same canonical UTC shape the log writer emits; see ISO_UTC_TS_RE in
// log-jsonl.ts for why this stays strict.
export const ISO_UTC_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;

/**
 * A validity window the append boundary refuses: an unparseable bound,
 * or an empty or inverted window. Typed so a tool surface can map it to
 * its invalid-params failure class (MCP INVALID_PARAMS, CLI exit 2)
 * instead of letting it answer as an internal error - the same
 * mistyped-input discipline the since/until and limit guards follow.
 * The refusal itself stays strict: nothing is written.
 */
export class ClaimWindowRefusal extends Error {
  constructor(message: string) {
    super(message);
    this.name = "ClaimWindowRefusal";
  }
}

// `claims.jsonl` or `claims.<deviceId>.jsonl`; device ids are lowercase
// slugs, and Syncthing conflict copies are never shards (the shared
// ledger-shard grammar rejects them).
const CLAIMS_STEM = "claims";
export const CLAIMS_GRAMMAR = jsonlLedgerGrammar(CLAIMS_STEM);

/** Extension appended when a source target names no file as given. */
const NOTE_EXTENSION = ".md";

/**
 * The source record's frontmatter validity window, or null when the
 * source is unreadable or carries no validity frontmatter (the ingest
 * default rule, truth-correctable-time-aware task 3). The source is a
 * provenance wikilink or vault-relative path: the wikilink decoration
 * is stripped, the target resolves inside the vault only (a traversal
 * or symlink escape reads as unreadable), and the target is tried as
 * given, then with a `.md` suffix (the Obsidian extensionless-link
 * shape). Only `valid_from` / `valid_until` participate; an mtime is
 * never consulted, because an mtime is an assertion-time proxy, not
 * validity.
 *
 * `readable` is the caller's reach gate, when the append answers at a
 * caller reach (the MCP tools; the CLI verb runs at operator reach and
 * passes none). A candidate the gate withholds is treated EXACTLY like
 * an absent one - skipped like a missing file, so a source the caller
 * cannot read resolves no window and leaves no signal distinguishing
 * withheld from absent anywhere in the event or the response.
 */
function sourceFrontmatterWindow(
  vault: string,
  source: string,
  readable?: (rel: string) => boolean,
): SourceValidityWindow | null {
  // The vault path a source names: the anchored wikilink body when the
  // source is a wikilink, else the source verbatim - then alias/anchor
  // decoration off, folder segments and `.md` kept (the same body
  // discipline every vault-path resolver applies).
  const anchored = ANCHORED_WIKILINK_RE.exec(source.trim());
  const target = stripWikilinkDecoration(anchored !== null ? anchored[1]! : source.trim());
  if (target === "") return null;
  const candidates = target.endsWith(NOTE_EXTENSION) ? [target] : [target, target + NOTE_EXTENSION];
  for (const candidate of candidates) {
    let path: string;
    try {
      path = resolveNotePath(vault, candidate, { mustExist: false });
    } catch {
      return null; // lexical traversal or symlink escape: unreadable.
    }
    // Only a REGULAR file names a page: a directory at the bare
    // spelling is not the record and must not shadow its `.md` twin -
    // the same regular-file rule the artifact-ref view's isVaultFile
    // applies on the read side. An unreadable candidate is skipped like
    // a missing one.
    try {
      if (!statSync(path).isFile()) continue;
    } catch {
      continue;
    }
    // A page the caller may not read does not exist for them: skip it
    // like a missing file rather than refusing, so the extensionless
    // spelling's .md twin resolves exactly as it would had the bare
    // candidate never existed.
    if (readable !== undefined && !readable(vaultRelative(path, vault))) continue;
    // parseFrontmatter never raises on an unreadable file; it yields an
    // empty map, which reads as a windowless source.
    const [meta] = parseFrontmatter(path);
    const validFrom = frontmatterWindowBound(meta, VALID_FROM_KEY);
    const validUntil = frontmatterWindowBound(meta, VALID_UNTIL_KEY);
    if (validFrom === undefined && validUntil === undefined) return null;
    return { validFrom, validUntil };
  }
  return null;
}

function frontmatterWindowBound(meta: FrontmatterMap, key: string): string | undefined {
  const value = meta[key];
  return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
}

export function truthDir(vault: string): string {
  return join(vault, "Brain", "truth");
}

export function truthStatePath(vault: string): string {
  return join(truthDir(vault), "state.json");
}

/**
 * The 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 `claims.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 claims
 *   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 claimShardPath(vault: string, configPath?: string): string {
  const deviceId = resolveDeviceId(configPath);
  const name = shardedFileName(CLAIMS_STEM, deviceId, JSONL_LEDGER_EXT);
  return join(truthDir(vault), name);
}

export interface AppendClaimInput {
  readonly ts: string;
  readonly agent: string;
  readonly entity: string;
  readonly aspect: string;
  readonly value: string;
  readonly valueKind?: ClaimEvent["valueKind"];
  readonly quantity?: ClaimQuantity;
  /**
   * Validity window start; absent keys mean windowless (contract item
   * 1). An absent bound resolves from the source record's frontmatter
   * `valid_from` when the source is readable at the caller's reach
   * (`AppendClaimOptions.readableSource`), and the resolved value is
   * frozen on the event; an unreadable, withheld or windowless source
   * leaves the event windowless.
   */
  readonly validFrom?: string;
  /** Validity window end, exclusive; resolved per bound like `validFrom`. */
  readonly validUntil?: string;
  /**
   * Presence-gated provenance tag (schema v1). This binary writes only
   * `agent_stated`; reads tolerate any non-empty string for forward
   * compatibility.
   */
  readonly extractor?: ClaimExtractor;
  /**
   * Presence-gated attribution id (schema v1): the caller-supplied
   * recall/context-pack quality-sample id this claim was stated against.
   * Opaque - stored TRIMMED (the same normalization the stated-claims
   * path applies, so a threaded id and its stored form always match),
   * never otherwise normalized, never logged beside answer or source
   * text. A present-but-blank, over-long or control-character-bearing
   * value refuses the append by name (a blank id means nothing and is
   * not coerced to absent); an absent one serializes nothing,
   * byte-identical to the pre-attribution ledger.
   */
  readonly sample_id?: string;
  readonly source: string;
}

export interface AppendClaimOptions {
  readonly configPath?: string;
  /**
   * The caller's reach gate over the source page, asked with the
   * vault-relative path of every candidate the source resolves to.
   * Absent at operator reach (the CLI verb): every source is
   * resolvable, today's behavior. Present on the MCP tools: a source
   * the caller cannot read is treated exactly like an absent one - no
   * window resolves from it, so the frozen event and the response
   * shape carry no signal distinguishing a withheld source from a
   * missing one (the window read must not become a frontmatter oracle
   * over pages the caller may not see).
   */
  readonly readableSource?: (rel: string) => boolean;
}

export interface AppendClaimResult {
  readonly path: string;
  readonly event: ClaimEvent;
}

/**
 * Validate, normalize identity fields, append one JSONL line to this
 * device's shard, and refresh the derived state cache.
 */
export function appendClaimEvent(
  vault: string,
  input: AppendClaimInput,
  opts: AppendClaimOptions = {},
): AppendClaimResult {
  const entity = normalizeEntityName(input.entity);
  const aspect = normalizeEntityName(input.aspect);
  if (entity === "") throw new Error("claim entity must not be empty");
  if (aspect === "") throw new Error("claim aspect must not be empty");
  const value = input.value.trim();
  if (value === "") throw new Error("claim value must not be empty");
  if (input.agent.trim() === "") throw new Error("claim agent must not be empty");
  if (input.source.trim() === "") throw new Error("claim source must not be empty");
  if (!ISO_UTC_TS_RE.test(input.ts)) {
    throw new Error(`claim ts must be canonical ISO-8601 UTC: ${JSON.stringify(input.ts)}`);
  }
  // Ingest window defaults (truth-correctable-time-aware, task 3):
  // explicit input wins outright; a bound the caller left open resolves
  // from the source record's frontmatter `valid_from` / `valid_until`
  // when the source is readable at the caller's reach, and the resolved
  // value is frozen on the event. An unreadable, withheld (see
  // `AppendClaimOptions.readableSource`) or windowless source stores a
  // windowless event - byte-identical to the pre-window ledger. The
  // source is read only when a bound is actually missing, so the fully
  // explicit path performs no extra I/O; mtime is never consulted.
  const needsSourceWindow = input.validFrom === undefined || input.validUntil === undefined;
  const resolved = resolveIngestWindow(
    input,
    needsSourceWindow ? sourceFrontmatterWindow(vault, input.source, opts.readableSource) : null,
  );
  // Validity windows (contract item 1): presence-gated, strictly
  // validated, and never guessed. An unparsable bound or an empty or
  // inverted window refuses the append by name - typed, so the tool
  // surfaces answer it as invalid params rather than an internal error.
  if (resolved.validFrom !== undefined && !isValidityPoint(resolved.validFrom)) {
    throw new ClaimWindowRefusal(
      `claim validFrom must be a bare ISO date or canonical UTC timestamp: ${JSON.stringify(resolved.validFrom)}`,
    );
  }
  if (resolved.validUntil !== undefined && !isValidityPoint(resolved.validUntil)) {
    throw new ClaimWindowRefusal(
      `claim validUntil must be a bare ISO date or canonical UTC timestamp: ${JSON.stringify(resolved.validUntil)}`,
    );
  }
  const window = validityWindowMs(resolved.validFrom, resolved.validUntil);
  if (
    window !== null &&
    window.fromMs !== null &&
    window.untilMs !== null &&
    window.fromMs >= window.untilMs
  ) {
    throw new ClaimWindowRefusal(
      `claim validity window is empty or inverted: validFrom ${JSON.stringify(resolved.validFrom)} does not parse before validUntil ${JSON.stringify(resolved.validUntil)}`,
    );
  }
  // Extractor (truth-correctable-time-aware, task 4): presence-gated,
  // strict on write (this binary emits exactly one tag), tolerant on
  // read. Annotation only - the tag never touches conflict semantics.
  if (input.extractor !== undefined && input.extractor !== "agent_stated") {
    throw new Error(`claim extractor must be agent_stated: ${JSON.stringify(input.extractor)}`);
  }
  // Sample id (answer-trust, task B1): presence-gated, opaque, stored
  // TRIMMED - the same normalization the stated path applies - so a
  // threaded id and its stored form always match and the provenance join
  // resolves what was threaded. A present-but-blank, over-long or
  // control-character-bearing value refuses the append by name, naming
  // the cap (review L2.1); an absent one serializes nothing.
  const sampleId = input.sample_id === undefined ? undefined : input.sample_id.trim();
  if (sampleId !== undefined && !isValidClaimSampleId(sampleId)) {
    throw new Error(
      `claim sample_id must be a non-empty string of at most ${SAMPLE_ID_MAX_LENGTH} characters without control characters`,
    );
  }

  const event: ClaimEvent = Object.freeze({
    v: TRUTH_SCHEMA_VERSION,
    ts: input.ts,
    agent: input.agent.trim(),
    entity,
    aspect,
    value,
    valueKind: input.valueKind ?? "text",
    ...(input.quantity !== undefined ? { quantity: input.quantity } : {}),
    ...(resolved.validFrom !== undefined ? { validFrom: resolved.validFrom } : {}),
    ...(resolved.validUntil !== undefined ? { validUntil: resolved.validUntil } : {}),
    source: input.source.trim(),
    ...(input.extractor !== undefined ? { extractor: input.extractor } : {}),
    ...(sampleId !== undefined ? { sample_id: sampleId } : {}),
  });

  // One `truth-claims` ledger row on a store-only machine (design D14
  // item 1), this device's claim shard plus the dual write otherwise. A
  // claim taken from a private page goes to `private` only.
  const routed = routeWrite({
    legacy: () => {
      // Vault-identity write guard (context-integrity-gates, Unit J).
      assertVaultIdentityForWrite(vault);
      mkdirSync(truthDir(vault), { recursive: true });
      const shard = claimShardPath(vault, opts.configPath);
      appendFileSync(shard, JSON.stringify(event) + "\n");
      return shard;
    },
    store: () => truthClaimRowRecord(event, claimSourceIsPrivate(vault, event.source)),
    context: { vault, ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}) },
  });
  if (routed.mode === "legacy") {
    writeTruthState(vault, computeTruthState(readClaimEvents(vault).events));
  }
  // Once switched the claim is a ledger row: its location is the ledger's
  // name, never the device path of a store shard (which would reach a
  // remote caller of `brain_truth ingest` as an absolute host path).
  let path = "";
  if (routed.mode === "legacy") path = routed.value;
  else if (routed.records.length > 0) path = TRUTH_STORE_NAME;
  return Object.freeze({ path, event });
}

/**
 * The name a store-only claim append reports, and the `path` a warning
 * about a store row names: the truth ledger, not a shard path.
 */
export const TRUTH_STORE_NAME = `store:ledgers/${DUAL_WRITE_LEDGERS.truthClaims}`;

/**
 * Read every retained claim event merged across shards, sorted by
 * (ts, shardId, line). Fail-closed per line.
 */
export function readClaimEvents(vault: string): ReadClaimEventsResult {
  // A store-only machine (design D14 item 1) reads the `truth-claims`
  // ledger rows, sorted by `ts` with fold order breaking ties.
  if (isStoreOnly({ vault })) {
    const warnings: ClaimParseWarning[] = [];
    const events: ClaimEvent[] = [];
    readLedgerRows<unknown>(DUAL_WRITE_LEDGERS.truthClaims, () => [], { vault }).forEach(
      (row, index) => {
        const event = coerceClaim(row, TRUTH_STORE_NAME, index + 1, warnings);
        if (event !== null) events.push(event);
      },
    );
    return {
      events: events.toSorted((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0)),
      warnings,
    };
  }
  const dir = truthDir(vault);
  let names: string[];
  try {
    names = readdirSync(dir).toSorted();
  } catch {
    return { events: [], warnings: [] };
  }

  interface Tagged {
    readonly event: ClaimEvent;
    readonly shardId: string;
    readonly line: number;
  }
  const tagged: Tagged[] = [];
  const warnings: ClaimParseWarning[] = [];

  for (const name of names) {
    const shard = parseShardedName(name, CLAIMS_GRAMMAR);
    if (shard === null) continue;
    const shardId = shard.shardId;
    const path = join(dir, name);
    let text: string;
    try {
      text = readFileSync(path, "utf8");
    } catch (err) {
      const message = (err as NodeJS.ErrnoException).message ?? String(err);
      warnings.push({ path, lineNumber: 0, message: `failed to read shard: ${message}` });
      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: ${line.slice(0, 80)}`,
        });
        continue;
      }
      const event = coerceClaim(parsed, path, i + 1, warnings);
      if (event !== null) tagged.push({ event, shardId, line: i });
    }
  }

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

  return { events: tagged.map((t) => t.event), warnings };
}

function coerceClaim(
  raw: unknown,
  path: string,
  lineNumber: number,
  warnings: ClaimParseWarning[],
): ClaimEvent | null {
  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
    warnings.push({ path, lineNumber, message: "claim row is not an object" });
    return null;
  }
  const obj = raw as Record<string, unknown>;
  if (obj["v"] !== TRUTH_SCHEMA_VERSION) {
    warnings.push({
      path,
      lineNumber,
      message: `unknown claim schema version: ${String(obj["v"])}`,
    });
    return null;
  }
  const ts = obj["ts"];
  if (typeof ts !== "string" || !ISO_UTC_TS_RE.test(ts)) {
    warnings.push({ path, lineNumber, message: `invalid claim ts: ${String(ts)}` });
    return null;
  }
  for (const key of ["agent", "entity", "aspect", "value", "source"] as const) {
    if (typeof obj[key] !== "string" || (obj[key] as string).trim() === "") {
      warnings.push({ path, lineNumber, message: `claim row missing ${key}` });
      return null;
    }
  }
  const valueKind = obj["valueKind"];
  if (valueKind !== "text" && valueKind !== "quantity") {
    warnings.push({ path, lineNumber, message: `invalid claim valueKind: ${String(valueKind)}` });
    return null;
  }
  let quantity: ClaimQuantity | undefined;
  if (obj["quantity"] !== undefined) {
    const q = obj["quantity"];
    if (
      q === null ||
      typeof q !== "object" ||
      typeof (q as Record<string, unknown>)["value"] !== "number" ||
      !Number.isFinite((q as Record<string, unknown>)["value"])
    ) {
      warnings.push({ path, lineNumber, message: "invalid claim quantity payload" });
      return null;
    }
    const qo = q as Record<string, unknown>;
    const unit = qo["unit"];
    const action = qo["action"];
    if (unit !== null && typeof unit !== "string") {
      warnings.push({ path, lineNumber, message: "invalid claim quantity unit" });
      return null;
    }
    if (action !== null && typeof action !== "string") {
      warnings.push({ path, lineNumber, message: "invalid claim quantity action" });
      return null;
    }
    quantity = Object.freeze({
      value: qo["value"] as number,
      unit: unit as string | null,
      action: action as string | null,
    });
  }
  // Validity fields (contract item 1): tolerated when absent (old
  // lines), validated when present (new lines, schema v1). Unknown
  // keys stay ignored, so an older binary reading these lines degrades
  // to the assertion-time axis by construction.
  const rawValidFrom = obj["validFrom"];
  const rawValidUntil = obj["validUntil"];
  if (
    rawValidFrom !== undefined &&
    (typeof rawValidFrom !== "string" || !isValidityPoint(rawValidFrom))
  ) {
    warnings.push({
      path,
      lineNumber,
      message: `invalid claim validFrom: ${String(rawValidFrom)}`,
    });
    return null;
  }
  if (
    rawValidUntil !== undefined &&
    (typeof rawValidUntil !== "string" || !isValidityPoint(rawValidUntil))
  ) {
    warnings.push({
      path,
      lineNumber,
      message: `invalid claim validUntil: ${String(rawValidUntil)}`,
    });
    return null;
  }
  const validFrom = rawValidFrom as string | undefined;
  const validUntil = rawValidUntil as string | undefined;
  const window = validityWindowMs(validFrom, validUntil);
  if (
    window !== null &&
    window.fromMs !== null &&
    window.untilMs !== null &&
    window.fromMs >= window.untilMs
  ) {
    warnings.push({
      path,
      lineNumber,
      message: "invalid claim validity window: validFrom must parse before validUntil",
    });
    return null;
  }
  // Extractor (task 4): tolerated when absent, validated as a
  // non-empty string when present, passed through verbatim so a future
  // extractor value survives an upgrade cycle. Annotation only.
  const rawExtractor = obj["extractor"];
  if (
    rawExtractor !== undefined &&
    (typeof rawExtractor !== "string" || rawExtractor.trim() === "")
  ) {
    warnings.push({
      path,
      lineNumber,
      message: `invalid claim extractor: ${String(rawExtractor)}`,
    });
    return null;
  }
  const extractor = rawExtractor as ClaimExtractor | undefined;
  // Sample id (answer-trust, task B1): tolerated when absent (old
  // lines), validated as a non-empty string when present, passed through
  // verbatim - the id is opaque. Annotation only.
  const rawSampleId = obj["sample_id"];
  if (rawSampleId !== undefined && (typeof rawSampleId !== "string" || rawSampleId.trim() === "")) {
    warnings.push({
      path,
      lineNumber,
      message: `invalid claim sample_id: ${String(rawSampleId)}`,
    });
    return null;
  }
  const sampleId = rawSampleId as string | undefined;
  return Object.freeze({
    v: TRUTH_SCHEMA_VERSION,
    ts,
    agent: obj["agent"] as string,
    entity: obj["entity"] as string,
    aspect: obj["aspect"] as string,
    value: obj["value"] as string,
    valueKind,
    ...(quantity !== undefined ? { quantity } : {}),
    ...(validFrom !== undefined ? { validFrom } : {}),
    ...(validUntil !== undefined ? { validUntil } : {}),
    ...(extractor !== undefined ? { extractor } : {}),
    source: obj["source"] as string,
    ...(sampleId !== undefined ? { sample_id: sampleId } : {}),
  });
}

export function writeTruthState(vault: string, state: TruthState): void {
  // The state is a cache derived from the claims (design D14 item 11): a
  // store-only machine keeps none under the vault and refolds on read
  // ({@link readTruthState}).
  if (isStoreOnly({ vault })) return;
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  mkdirSync(truthDir(vault), { recursive: true });
  writeFileSync(truthStatePath(vault), JSON.stringify(state, null, 2) + "\n");
}

function isClaimVersion(v: unknown): v is ClaimVersion {
  if (v === null || typeof v !== "object") return false;
  const row = v as Record<string, unknown>;
  return (
    typeof row["value"] === "string" &&
    (row["valueKind"] === "text" || row["valueKind"] === "quantity") &&
    typeof row["ts"] === "string" &&
    typeof row["agent"] === "string" &&
    typeof row["source"] === "string" &&
    typeof row["assertCount"] === "number" &&
    Number.isInteger(row["assertCount"]) &&
    (row["assertCount"] as number) >= 1
  );
}

function isClaimSlot(v: unknown): v is ClaimSlot {
  if (v === null || typeof v !== "object") return false;
  const row = v as Record<string, unknown>;
  return (
    typeof row["entity"] === "string" &&
    typeof row["aspect"] === "string" &&
    isClaimVersion(row["current"]) &&
    Array.isArray(row["history"]) &&
    (row["history"] as unknown[]).every(isClaimVersion) &&
    typeof row["contested"] === "boolean"
  );
}

function isTruthConflict(v: unknown): v is TruthConflict {
  if (v === null || typeof v !== "object") return false;
  const row = v as Record<string, unknown>;
  return (
    typeof row["entity"] === "string" &&
    typeof row["aspect"] === "string" &&
    row["kind"] === "value_conflict" &&
    Array.isArray(row["values"]) &&
    (row["values"] as unknown[]).every(isClaimVersion) &&
    typeof row["priority"] === "number" &&
    Number.isFinite(row["priority"]) &&
    row["resolution"] === "ask_user" &&
    typeof row["detectedAt"] === "string"
  );
}

function isClaimEventLike(v: unknown): v is ClaimEvent {
  if (v === null || typeof v !== "object") return false;
  const row = v as Record<string, unknown>;
  return (
    row["v"] === TRUTH_SCHEMA_VERSION &&
    typeof row["ts"] === "string" &&
    ISO_UTC_TS_RE.test(row["ts"]) &&
    (["agent", "entity", "aspect", "value", "source"] as const).every(
      (key) => typeof row[key] === "string" && (row[key] as string).trim() !== "",
    ) &&
    (row["valueKind"] === "text" || row["valueKind"] === "quantity")
  );
}

function isClaimSuccession(v: unknown): v is ClaimSuccession {
  if (v === null || typeof v !== "object") return false;
  const row = v as Record<string, unknown>;
  return (
    typeof row["entity"] === "string" &&
    typeof row["aspect"] === "string" &&
    isClaimEventLike(row["predecessor"]) &&
    isClaimEventLike(row["successor"]) &&
    typeof row["detectedAt"] === "string"
  );
}

/**
 * Read the derived state cache; structurally invalid content (including
 * corrupt nested rows) reads as null and the caller refolds from events.
 */
export function readTruthState(vault: string): TruthState | null {
  // A store-only machine keeps no state cache: the state is folded from
  // the claim rows on every read.
  if (isStoreOnly({ vault })) return computeTruthState(readClaimEvents(vault).events);
  try {
    const parsed = JSON.parse(readFileSync(truthStatePath(vault), "utf8")) as TruthState;
    if (parsed.version !== TRUTH_SCHEMA_VERSION) return null;
    if (!Number.isInteger(parsed.events) || parsed.events < 0) return null;
    if (!(parsed.updatedAt === null || typeof parsed.updatedAt === "string")) return null;
    if (!Array.isArray(parsed.slots)) return null;
    if (!Array.isArray(parsed.conflicts)) return null;
    for (const slot of parsed.slots as ReadonlyArray<unknown>) {
      if (!isClaimSlot(slot)) return null;
    }
    for (const conflict of parsed.conflicts as ReadonlyArray<unknown>) {
      if (!isTruthConflict(conflict)) return null;
    }
    // Successions are presence-gated (contract item 1): absent is the
    // normal windowless shape, present must validate, and a corrupt
    // channel reads as null so the caller refolds from events.
    if (parsed.successions !== undefined) {
      if (!Array.isArray(parsed.successions)) return null;
      for (const succession of parsed.successions as ReadonlyArray<unknown>) {
        if (!isClaimSuccession(succession)) return null;
      }
    }
    return parsed;
  } catch {
    return null;
  }
}

export interface ClaimSweepOptions {
  /** At most this many newest events are kept. */
  readonly maxEvents?: number;
}

/**
 * Keep the newest N events across all shards (rewriting each shard
 * with only its surviving lines), then refold the derived state.
 * Sweeping is an explicit operator action - appends never auto-drop
 * history.
 */
export function sweepClaimEvents(vault: string, opts: ClaimSweepOptions): ClaimSweepOutcome {
  // A store-only machine (design D14 item 1) rewrites nothing under the
  // vault: its claims are append-only store rows, and the legacy shards it
  // may still hold are read-only until the tree leaves the vault.
  if (isStoreOnly({ vault })) {
    throw new Error(
      "claim sweep refused: this machine writes the brain store only, whose claim rows are " +
        "append-only; the legacy claim shards under the vault are read-only here",
    );
  }
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  const maxEvents = opts.maxEvents ?? CLAIM_EVENT_MAX_COUNT;
  const dir = truthDir(vault);
  let names: string[];
  try {
    names = readdirSync(dir).toSorted();
  } catch {
    // No event directory: refold an orphaned state file so stale slots
    // never outlive their events.
    if (existsSync(truthStatePath(vault))) {
      writeTruthState(vault, computeTruthState([]));
    }
    return Object.freeze({ removed: 0, kept: 0 });
  }

  // Collect (shard, line, ts) for every valid line; drop the oldest
  // beyond the cap. Invalid lines are preserved verbatim in place -
  // sweep bounds growth, doctor surfaces corruption.
  interface ShardLine {
    readonly name: string;
    readonly index: number;
    readonly raw: string;
    readonly ts: string | null;
  }
  const shards = new Map<string, string[]>();
  const valid: ShardLine[] = [];
  for (const name of names) {
    if (parseShardedName(name, CLAIMS_GRAMMAR) === null) continue;
    let text: string;
    try {
      text = readFileSync(join(dir, name), "utf8");
    } catch {
      continue;
    }
    const lines = text.split(/\r?\n/).filter((l) => l.trim() !== "");
    shards.set(name, lines);
    lines.forEach((raw, index) => {
      let ts: string | null = null;
      try {
        const parsed = JSON.parse(raw) as Record<string, unknown>;
        if (typeof parsed["ts"] === "string" && ISO_UTC_TS_RE.test(parsed["ts"])) {
          ts = parsed["ts"];
        }
      } catch {
        // Invalid lines never count toward the cap.
      }
      if (ts !== null) valid.push({ name, index, raw, ts });
    });
  }

  valid.sort((a, b) => {
    if (a.ts !== b.ts) return a.ts! < b.ts! ? -1 : 1;
    if (a.name !== b.name) return a.name < b.name ? -1 : 1;
    return a.index - b.index;
  });
  const overflow = valid.length > maxEvents ? valid.slice(0, valid.length - maxEvents) : [];
  const removedKeys = new Set(overflow.map((x) => `${x.name}\n${x.index}`));

  if (removedKeys.size > 0) {
    for (const [name, lines] of shards) {
      const kept = lines.filter((_, index) => !removedKeys.has(`${name}\n${index}`));
      const path = join(dir, name);
      if (kept.length === 0) {
        rmSync(path, { force: true });
      } else if (kept.length !== lines.length) {
        writeFileSync(path, kept.join("\n") + "\n");
      }
    }
  }

  writeTruthState(vault, computeTruthState(readClaimEvents(vault).events));
  return Object.freeze({ removed: overflow.length, kept: valid.length - overflow.length });
}