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
6.8 KB
Raw Blame
/**
 * Semantic-checker registry (salience-lifecycle-enrichment, unit 0).
 *
 * `ShapeDescriptor` is deliberately shallow, so constraints that read more
 * than one value at a time - cardinality, cross-item rules, caps and floors
 * - cannot be written there without deepening the descriptor language the
 * response-shape layer keeps flat on purpose. They live here instead, beside
 * it, following the research citation check that already validates set
 * membership next to its descriptor. What this suite pins:
 *
 *  1. A check registers under a surface name and is found by it; the
 *     registry can name every surface it holds.
 *  2. Registration is fail-loud: a second check for the same surface throws
 *     rather than silently replacing the first, and a blank surface is
 *     refused.
 *  3. The gate is FAIL-CLOSED: asserting a surface nobody registered throws
 *     a named refusal. An unchecked surface must never read as a clean one.
 *  4. A conforming payload passes silently, like `assertResponseShape`.
 *  5. A violating payload throws `ResponseCheckError` carrying the surface,
 *     the first violation's code and path, and the complete violation list -
 *     routing is on fields, never on parsed prose.
 *  6. Violation codes come from the frozen vocabulary: a check returning a
 *     code outside it is itself refused, so no refusal reaches a caller
 *     unnamed.
 *  7. The constraints the descriptor language cannot express are expressible
 *     here - a worked cardinality rule (exactly one recommended alternative)
 *     and a worked cross-item rule (every cited source was consulted).
 */

import { expect, test } from "bun:test";

import {
  assertResponseCheck,
  getResponseCheck,
  listResponseCheckSurfaces,
  registerResponseCheck,
  ResponseCheckError,
  SEMANTIC_VIOLATION_CODES,
  semanticViolation,
  type ResponseCheck,
} from "../../../src/core/brain/response-checks.ts";
import { SHAPE_ROOT_PATH } from "../../../src/core/brain/response-shape.ts";

/** Payload shape the worked cardinality example validates. */
interface Alternatives {
  readonly alternatives: ReadonlyArray<{ readonly name: string; readonly recommended: boolean }>;
}

const exactlyOneRecommended: ResponseCheck = (payload) => {
  const alternatives = (payload as Alternatives).alternatives;
  const recommended = alternatives.filter((a) => a.recommended);
  if (recommended.length === 1) return [];
  return [
    semanticViolation(
      SEMANTIC_VIOLATION_CODES.cardinality,
      `${SHAPE_ROOT_PATH}.alternatives`,
      `expected exactly one recommended alternative, found ${recommended.length}`,
    ),
  ];
};

test("a check registers under a surface name and is found by it", () => {
  const surface = "test_lookup";
  registerResponseCheck(surface, exactlyOneRecommended);
  expect(getResponseCheck(surface)).toBe(exactlyOneRecommended);
  expect(listResponseCheckSurfaces()).toContain(surface);
  expect(getResponseCheck("test_never_registered")).toBeUndefined();
});

test("registration is fail-loud: no duplicate surface, no blank surface", () => {
  const surface = "test_duplicate";
  registerResponseCheck(surface, exactlyOneRecommended);
  expect(() => registerResponseCheck(surface, exactlyOneRecommended)).toThrow(/already registered/);
  expect(() => registerResponseCheck("   ", exactlyOneRecommended)).toThrow(/surface/);
});

test("asserting a surface nobody registered is a named refusal, never a clean pass", () => {
  let thrown: unknown;
  try {
    assertResponseCheck("test_unregistered_surface", { anything: true });
  } catch (err) {
    thrown = err;
  }
  expect(thrown).toBeInstanceOf(ResponseCheckError);
  const error = thrown as ResponseCheckError;
  expect(error.code).toBe(SEMANTIC_VIOLATION_CODES.unregistered);
  expect(error.surface).toBe("test_unregistered_surface");
  expect(error.message).toContain("test_unregistered_surface");
});

test("a conforming payload passes silently", () => {
  const surface = "test_conforming";
  registerResponseCheck(surface, exactlyOneRecommended);
  expect(() =>
    assertResponseCheck(surface, {
      alternatives: [
        { name: "a", recommended: true },
        { name: "b", recommended: false },
      ],
    }),
  ).not.toThrow();
});

test("a violating payload throws with the surface, the code, the path, and every violation", () => {
  const surface = "test_violating";
  registerResponseCheck(surface, exactlyOneRecommended);
  let thrown: unknown;
  try {
    assertResponseCheck(surface, {
      alternatives: [
        { name: "a", recommended: true },
        { name: "b", recommended: true },
      ],
    });
  } catch (err) {
    thrown = err;
  }
  expect(thrown).toBeInstanceOf(ResponseCheckError);
  const error = thrown as ResponseCheckError;
  expect(error.name).toBe("ResponseCheckError");
  expect(error.surface).toBe(surface);
  expect(error.code).toBe(SEMANTIC_VIOLATION_CODES.cardinality);
  expect(error.path).toBe("$.alternatives");
  expect(error.violations).toHaveLength(1);
  expect(Object.isFrozen(error.violations)).toBe(true);
  expect(error.message).toBe(
    `${surface} response checks violated: $.alternatives: expected exactly one recommended alternative, found 2`,
  );
});

test("a check returning a code outside the frozen vocabulary is itself refused", () => {
  const surface = "test_unnamed_code";
  registerResponseCheck(surface, () => [
    { code: "made_up_code", path: SHAPE_ROOT_PATH, message: "no" } as never,
  ]);
  expect(() => assertResponseCheck(surface, {})).toThrow(/made_up_code/);
  expect(Object.isFrozen(SEMANTIC_VIOLATION_CODES)).toBe(true);
});

test("cross-item rules the descriptor language cannot express live here", () => {
  const surface = "test_cross_item";
  registerResponseCheck(surface, (payload) => {
    const report = payload as {
      readonly sources: ReadonlyArray<string>;
      readonly findings: ReadonlyArray<{ readonly sources: ReadonlyArray<string> }>;
    };
    const consulted = new Set(report.sources);
    return report.findings.flatMap((finding, index) =>
      finding.sources
        .filter((source) => !consulted.has(source))
        .map((source) =>
          semanticViolation(
            SEMANTIC_VIOLATION_CODES.setMembership,
            `${SHAPE_ROOT_PATH}.findings[${index}].sources`,
            `cites a source not in the consulted set: ${JSON.stringify(source)}`,
          ),
        ),
    );
  });

  expect(() =>
    assertResponseCheck(surface, { sources: ["a"], findings: [{ sources: ["a"] }] }),
  ).not.toThrow();

  let thrown: unknown;
  try {
    assertResponseCheck(surface, {
      sources: ["a"],
      findings: [{ sources: ["a"] }, { sources: ["b", "c"] }],
    });
  } catch (err) {
    thrown = err;
  }
  const error = thrown as ResponseCheckError;
  expect(error.code).toBe(SEMANTIC_VIOLATION_CODES.setMembership);
  expect(error.violations).toHaveLength(2);
  expect(error.path).toBe("$.findings[1].sources");
});