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
/**
 * Response-shape layer (signals-that-survive, unit 8, t_80b01448).
 *
 * The validator itself, the frozen descriptors declared for the
 * model-authored write paths, and the two discipline rules that keep the
 * layer usable: descriptors stay inside the subset the validator can
 * express, and the layer never borrows the knowledge vocabulary's noun.
 */

import { describe, expect, test } from "bun:test";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import * as responseShapeModule from "../../../src/core/brain/response-shape.ts";
import { parseDistillClaims } from "../../../src/core/brain/distill/distill-source.ts";
import { parseDeriveFactInput } from "../../../src/core/brain/derived-fact.ts";
import { parseResearchReportInput } from "../../../src/core/brain/research/research.ts";
import {
  DERIVED_FACT_SHAPE,
  DESIGN_NOTE_SHAPE,
  DISTILL_CLAIMS_SHAPE,
  EXTRACTED_SIGNALS_SHAPE,
  MODEL_AUTHORED_SHAPES,
  SKILL_PAGE_DRAFT_SHAPE,
  RESEARCH_REPORT_SHAPE,
  ResponseShapeError,
  SHAPE_DESCRIPTOR_KEYS,
  SHAPE_ROOT_PATH,
  SHAPE_TYPES,
  SHAPE_VIOLATION_CODES,
  assertResponseShape,
  checkResponseShape,
  formatShapeViolation,
  type ShapeDescriptor,
} from "../../../src/core/brain/response-shape.ts";

/** Object nesting an object descriptor reaches, counting through array items. */
function objectNestingDepth(descriptor: ShapeDescriptor): number {
  if (descriptor.type === "object" || descriptor.properties !== undefined) {
    const children = Object.values(descriptor.properties ?? {});
    return 1 + children.reduce((deepest, child) => Math.max(deepest, objectNestingDepth(child)), 0);
  }
  if (descriptor.items !== undefined) return objectNestingDepth(descriptor.items);
  return 0;
}

/** Every descriptor node reachable from a root, root included. */
function descriptorNodes(descriptor: ShapeDescriptor): ShapeDescriptor[] {
  const nodes = [descriptor];
  for (const child of Object.values(descriptor.properties ?? {})) {
    nodes.push(...descriptorNodes(child));
  }
  if (descriptor.items !== undefined) nodes.push(...descriptorNodes(descriptor.items));
  if (typeof descriptor.additionalProperties === "object") {
    nodes.push(...descriptorNodes(descriptor.additionalProperties));
  }
  return nodes;
}

/** Deepest object nesting a shallow descriptor may declare: object -> array -> object. */
const MAX_OBJECT_NESTING = 2;

describe("checkResponseShape", () => {
  test("accepts a payload that satisfies the descriptor", () => {
    expect(checkResponseShape(DISTILL_CLAIMS_SHAPE, [{ text: "a claim" }])).toEqual([]);
  });

  test("reports a type mismatch with a structured code and path", () => {
    const violations = checkResponseShape(DISTILL_CLAIMS_SHAPE, [{ text: "ok" }, { text: 42 }]);
    expect(violations).toHaveLength(1);
    expect(violations[0]).toEqual({
      code: SHAPE_VIOLATION_CODES.typeMismatch,
      path: "$[1].text",
      message: "expected string",
    });
  });

  test("reports a missing required property", () => {
    const violations = checkResponseShape(DERIVED_FACT_SHAPE, {
      topic: "t",
      principle: "p",
      premises: ["pref-a"],
      level: "deduced",
    });
    expect(violations).toEqual([
      {
        code: SHAPE_VIOLATION_CODES.missingProperty,
        path: SHAPE_ROOT_PATH,
        message: "missing required property 'slug'",
      },
    ]);
  });

  test("renders a violation as the path-prefixed line the callers print", () => {
    const [violation] = checkResponseShape({ type: "string" }, 1);
    expect(formatShapeViolation(violation!)).toBe("$: expected string");
  });
});

describe("assertResponseShape", () => {
  test("returns silently for a conforming payload", () => {
    expect(() =>
      assertResponseShape("demo", RESEARCH_REPORT_SHAPE, {
        title: "T",
        sources: ["a"],
        findings: [{ statement: "s", sources: ["a"] }],
      }),
    ).not.toThrow();
  });

  test("throws a named error carrying code, path and message as fields", () => {
    let caught: unknown;
    try {
      assertResponseShape("demo", RESEARCH_REPORT_SHAPE, {
        title: "T",
        sources: ["a"],
        findings: [{ statement: "s" }],
      });
    } catch (err) {
      caught = err;
    }
    expect(caught).toBeInstanceOf(ResponseShapeError);
    const err = caught as ResponseShapeError;
    expect(err.name).toBe("ResponseShapeError");
    expect(err.code).toBe(SHAPE_VIOLATION_CODES.missingProperty);
    expect(err.path).toBe("$.findings[0]");
    expect(err.message).toContain("missing required property 'sources'");
    expect(err.surface).toBe("demo");
    expect(err.violations).toEqual([
      {
        code: SHAPE_VIOLATION_CODES.missingProperty,
        path: "$.findings[0]",
        message: "missing required property 'sources'",
      },
    ]);
  });
});

describe("model-authored descriptors", () => {
  test("one descriptor per model-authored write path, all registered", () => {
    expect(new Set(Object.values(MODEL_AUTHORED_SHAPES))).toEqual(
      new Set([
        DISTILL_CLAIMS_SHAPE,
        DERIVED_FACT_SHAPE,
        RESEARCH_REPORT_SHAPE,
        EXTRACTED_SIGNALS_SHAPE,
        SKILL_PAGE_DRAFT_SHAPE,
        DESIGN_NOTE_SHAPE,
      ]),
    );
  });

  test("every descriptor is frozen all the way down", () => {
    for (const [surface, descriptor] of Object.entries(MODEL_AUTHORED_SHAPES)) {
      for (const node of descriptorNodes(descriptor)) {
        expect(Object.isFrozen(node), `${surface} descriptor node is mutable`).toBe(true);
      }
    }
  });

  test("no descriptor uses a construct the subset validator cannot express", () => {
    const allowedKeys = new Set<string>(SHAPE_DESCRIPTOR_KEYS);
    const allowedTypes = new Set<string>(SHAPE_TYPES);
    for (const [surface, descriptor] of Object.entries(MODEL_AUTHORED_SHAPES)) {
      for (const node of descriptorNodes(descriptor)) {
        for (const key of Object.keys(node)) {
          expect(allowedKeys.has(key), `${surface} descriptor declares '${key}'`).toBe(true);
        }
        if (node.type !== undefined) {
          expect(allowedTypes.has(node.type), `${surface} descriptor type '${node.type}'`).toBe(
            true,
          );
        }
      }
    }
  });

  test("descriptors stay shallow: required keys, primitives, arrays of objects", () => {
    for (const [surface, descriptor] of Object.entries(MODEL_AUTHORED_SHAPES)) {
      expect(
        objectNestingDepth(descriptor),
        `${surface} descriptor is too deep`,
      ).toBeLessThanOrEqual(MAX_OBJECT_NESTING);
    }
  });
});

describe("layer discipline", () => {
  test("the knowledge vocabulary's noun is absent from everything this layer emits", () => {
    // Asserted over the surface a caller can observe - exported names, the
    // descriptor vocabulary, the violation codes and a thrown message - rather
    // than over the module text, where a comment could fail the suite and a
    // borrowed noun in a caller could not.
    for (const name of Object.keys(responseShapeModule)) {
      expect(name).not.toMatch(/schema/i);
    }
    for (const key of SHAPE_DESCRIPTOR_KEYS) expect(key).not.toMatch(/schema/i);
    for (const code of Object.values(SHAPE_VIOLATION_CODES)) {
      expect(code).not.toMatch(/schema/i);
    }
    const thrown = (() => {
      try {
        assertResponseShape("demo", DERIVED_FACT_SHAPE, {});
      } catch (err) {
        return err as ResponseShapeError;
      }
      return null;
    })();
    expect(thrown!.name).not.toMatch(/schema/i);
    expect(thrown!.message).not.toMatch(/schema/i);
  });

  test("no configuration or environment can change a verdict", () => {
    const payload = { title: "T", sources: [""], findings: [{ statement: "s", sources: [""] }] };
    const baseline = checkResponseShape(RESEARCH_REPORT_SHAPE, payload);
    expect(baseline.length).toBeGreaterThan(0);

    const configHome = mkdtempSync(join(tmpdir(), "o2b-response-shape-cfg-"));
    const configPath = join(configHome, "config.yaml");
    // A config declaring every plausible opt-out spelling, at the path the
    // whole codebase resolves settings from, plus the same spellings as env.
    writeFileSync(
      configPath,
      [
        "vault: /nonexistent",
        "response_shape: false",
        "response_shape_enabled: false",
        "response_shape_strict: false",
        "validation: off",
        "",
      ].join("\n"),
      "utf8",
    );
    const hostile: Record<string, string> = {
      OPEN_SECOND_BRAIN_CONFIG: configPath,
      OPEN_SECOND_BRAIN_RESPONSE_SHAPE_ENABLED: "false",
      OPEN_SECOND_BRAIN_RESPONSE_SHAPE: "off",
      NODE_ENV: "production",
    };
    const saved = new Map(Object.keys(hostile).map((key) => [key, process.env[key]]));
    try {
      for (const [key, value] of Object.entries(hostile)) process.env[key] = value;
      // The validator, and the three ingress functions that own the callers'
      // half of the contract, all still refuse the same payload by the same
      // path - a gate introduced in a caller would break exactly here.
      expect(checkResponseShape(RESEARCH_REPORT_SHAPE, payload)).toEqual(baseline);
      expect(() => assertResponseShape("demo", RESEARCH_REPORT_SHAPE, payload)).toThrow(
        ResponseShapeError,
      );
      expect(() => parseResearchReportInput(payload)).toThrow(ResponseShapeError);
      expect(() => parseDistillClaims([{ text: 1 }])).toThrow(ResponseShapeError);
      expect(() => parseDeriveFactInput({ topic: "t" })).toThrow(ResponseShapeError);
    } finally {
      for (const [key, value] of saved) {
        if (value === undefined) delete process.env[key];
        else process.env[key] = value;
      }
      rmSync(configHome, { recursive: true, force: true });
    }
  });
});