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.6 KB
Raw Blame
/**
 * Needs-llm-step envelope spine (salience-lifecycle-enrichment, unit 0).
 *
 * Three shapes already speak this grammar - the durable write-session
 * envelope, the diarization step, the rollup envelope - and until now none
 * of them named it. The spine names it once. What this suite pins:
 *
 *  1. The spine field set is exactly `status`, `step`, `prompt`,
 *     `schema_hints`, `target_path`: the intersection of the three, and
 *     nothing beyond it. A field only two of them carry is not spine.
 *  2. `buildNeedsLlmStep` stamps the status literal itself, so no
 *     construction site can spell it a fourth way - including a fields
 *     object that carries a `status` of its own at runtime.
 *  3. The built envelope is frozen and owns its hint list: the array the
 *     caller passed cannot mutate the envelope afterwards.
 *  4. Key order of the built object is `status` first, then the caller's
 *     fields in declaration order - the serialized shape the CLI and MCP
 *     surfaces already emit for these envelopes.
 *  5. A blank step, prompt, or target_path is refused by name; an empty
 *     hint list is legal (a step can genuinely carry no hints).
 *  6. Adoption is type-level and additive: the diarization step and the
 *     rollup envelope ARE the spine, and the durable `WriteSessionEnvelope`
 *     still carries every spine field with the same names and types.
 *  7. Adoption changed no bytes: a rollup envelope serializes exactly as it
 *     did before the spine landed, key order included, and the diarization
 *     step's key order is unchanged.
 */

import { afterEach, beforeEach, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { diarize } from "../../../src/core/brain/diarization.ts";
import { upsertEntity } from "../../../src/core/brain/entities/registry.ts";
import {
  buildNeedsLlmStep,
  LlmStepError,
  NEEDS_LLM_STEP,
  NEEDS_LLM_STEP_KEYS,
  type LlmStepFields,
  type NeedsLlmStep,
} from "../../../src/core/brain/llm-step.ts";
import type { LinkCandidateManifest } from "../../../src/core/brain/notes/link-candidates.ts";
import { planRollupLadder } from "../../../src/core/brain/rollup-ladder.ts";
import type { WriteSessionEnvelope } from "../../../src/core/brain/write-session/types.ts";

const RUN_ID = "dream-2026-07-19-100000";
const NOW = new Date("2026-07-19T10:00:00Z");

/**
 * The manifest a fired rung is handed. A value, because the planner is
 * pure - see `RollupLadderInput.linkCandidates`.
 */
const LINK_CANDIDATES: LinkCandidateManifest = Object.freeze({
  candidates: Object.freeze(["analytical-engine"]),
  total: 1,
  truncated: false,
  selection: "all",
});

/**
 * The rollup envelope, byte-for-byte and in key order - it crosses the
 * CLI and MCP boundaries as JSON.
 *
 * The spine's own keys are exactly where they were when this pin was
 * first captured (before the spine existed). What moved in
 * nothing-writes-silently is that the lane's own `link_candidates` is
 * appended AFTER `target_path`, with the one constraint line naming it
 * added to `schema_hints`: a consumer field, in the consumer's position,
 * leaving every existing position where it was.
 */
const ROLLUP_ENVELOPE_JSON =
  '{"status":"needs-llm-step","step":"rollup:fact","tier":"fact","produces":"rollup",' +
  '"prompt":"Consolidate the 5 new fact items since the last rollup into one rollup-tier ' +
  'summary note. Cite the items you fold in; submit the full note.",' +
  '"schema_hints":["frontmatter: required YAML block with at least a `kind` key",' +
  '"tier: rollup (the rollup\'s tier weight)",' +
  '"wikilinks: link_candidates carries all 1 note names this vault offers; a name it does ' +
  'not carry is not one you can cite and the link will dangle"],' +
  '"target_path":"Brain/rollups/rollup-rollup-dream-2026-07-19-100000.md",' +
  '"link_candidates":{"candidates":["analytical-engine"],"total":1,"truncated":false,' +
  '"selection":"all"}}';

/** Compile-time pin: anything passed here carries the whole spine. */
function acceptsSpine(_envelope: NeedsLlmStep): void {}
/** Compile-time pin: anything passed here carries the spine's payload fields. */
function acceptsSpineFields(_fields: LlmStepFields): void {}

function fired() {
  const plan = planRollupLadder({
    factCount: 5,
    ledger: null,
    thresholds: { fact: 5, identity: 2 },
    runId: RUN_ID,
    linkCandidates: () => LINK_CANDIDATES,
  });
  return plan.entries[0]!.envelope;
}

test("the spine field set is the intersection of the shapes that already speak the grammar", () => {
  expect([...NEEDS_LLM_STEP_KEYS]).toEqual([
    "status",
    "step",
    "prompt",
    "schema_hints",
    "target_path",
  ]);
  const built = buildNeedsLlmStep({
    step: "s",
    prompt: "p",
    schema_hints: [],
    target_path: "Brain/x.md",
  });
  // The constant cannot drift from the builder's own output.
  expect(Object.keys(built)).toEqual([...NEEDS_LLM_STEP_KEYS]);
});

test("the builder stamps the status literal and freezes what it returns", () => {
  const built = buildNeedsLlmStep({
    step: "profile-prose",
    prompt: "Write the prose.",
    schema_hints: ["body: replace only the marker"],
    target_path: "Brain/profiles/ent-person-ada.md",
  });
  expect(built.status).toBe(NEEDS_LLM_STEP);
  expect(NEEDS_LLM_STEP).toBe("needs-llm-step");
  expect(Object.isFrozen(built)).toBe(true);
  expect(Object.isFrozen(built.schema_hints)).toBe(true);
});

test("the envelope owns its hint list: mutating the caller's array cannot reach it", () => {
  const hints = ["body: replace only the marker"];
  const built = buildNeedsLlmStep({
    step: "profile-prose",
    prompt: "Write the prose.",
    schema_hints: hints,
    target_path: "Brain/profiles/ent-person-ada.md",
  });
  hints.push("smuggled");
  expect(built.schema_hints).toEqual(["body: replace only the marker"]);
});

test("status leads the key order and the caller's extra fields keep their place", () => {
  const built = buildNeedsLlmStep({
    step: "rollup:fact",
    tier: "fact",
    produces: "rollup",
    prompt: "Consolidate.",
    schema_hints: ["tier: rollup"],
    target_path: "Brain/rollups/r.md",
  });
  expect(Object.keys(built)).toEqual([
    "status",
    "step",
    "tier",
    "produces",
    "prompt",
    "schema_hints",
    "target_path",
  ]);
});

test("a runtime status on the caller's fields cannot displace the stamped literal", () => {
  // The type forbids this; a payload assembled at runtime - a spread of a
  // wider record, a parsed object - does not go through the type.
  const hostile = {
    status: "done",
    step: "profile-prose",
    prompt: "Write the prose.",
    schema_hints: ["a hint"],
    target_path: "Brain/profiles/p.md",
  } as unknown as LlmStepFields;
  const built = buildNeedsLlmStep(hostile);
  expect(built.status).toBe(NEEDS_LLM_STEP);
  // And it does not reappear later in the object either.
  expect(Object.keys(built)).toEqual([...NEEDS_LLM_STEP_KEYS]);
});

test("a blank step, prompt, or target path is refused by name", () => {
  const base = {
    step: "profile-prose",
    prompt: "Write the prose.",
    schema_hints: ["a hint"],
    target_path: "Brain/profiles/p.md",
  };
  expect(() => buildNeedsLlmStep({ ...base, step: "  " })).toThrow(LlmStepError);
  expect(() => buildNeedsLlmStep({ ...base, step: "  " })).toThrow(/step/);
  expect(() => buildNeedsLlmStep({ ...base, prompt: "" })).toThrow(/prompt/);
  expect(() => buildNeedsLlmStep({ ...base, target_path: "\t" })).toThrow(/target_path/);
  // A step with nothing to hint at is legal.
  expect(buildNeedsLlmStep({ ...base, schema_hints: [] }).schema_hints).toEqual([]);
});

test("the rollup envelope is the spine, and serializes as it did before adoption", () => {
  const envelope = fired();
  acceptsSpine(envelope);
  acceptsSpineFields(envelope);
  expect(JSON.stringify(envelope)).toBe(ROLLUP_ENVELOPE_JSON);
  for (const key of NEEDS_LLM_STEP_KEYS) expect(Object.hasOwn(envelope, key)).toBe(true);
});

test("the durable write-session envelope still carries every spine field", () => {
  const envelope: WriteSessionEnvelope = {
    status: "needs-llm-step",
    session_id: "ws-1",
    kind: "artifact",
    step: "artifact",
    prompt: "Write the note.",
    schema_hints: ["frontmatter: kind"],
    errors: [],
    attempts_left: 3,
    expires_at: "2026-07-20T10:00:00Z",
    target_path: "Brain/notes/n.md",
    existing: null,
  };
  // The superset keeps its own fields; only the spine payload is shared,
  // because its `status` widens to the full session-status union.
  acceptsSpineFields(envelope);
  for (const key of NEEDS_LLM_STEP_KEYS) expect(Object.hasOwn(envelope, key)).toBe(true);
});

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-llm-step-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
  upsertEntity(vault, {
    category: "person",
    name: "Ada Lovelace",
    agent: "test",
    now: NOW,
    body: "Ada Lovelace designed an early programming method.",
  });
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

test("the diarization step is the spine, with the spine's key order unchanged", () => {
  const report = diarize(vault, { query: "Ada Lovelace" }, { now: NOW, ownerScope: null });
  acceptsSpine(report.llmStep);
  // The lane's own `link_candidates` is appended after the spine, in the
  // consumer position the rollup's `tier`/`produces` already occupy: the
  // spine's five keys are still the first five, in order.
  expect(Object.keys(report.llmStep)).toEqual([
    "status",
    "step",
    "prompt",
    "schema_hints",
    "target_path",
    "link_candidates",
  ]);
  expect(report.llmStep.status).toBe(NEEDS_LLM_STEP);
});