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
16.5 KB
Raw Blame
/**
 * Response-shape validation for model-authored write paths
 * (signals-that-survive, unit 8, t_80b01448).
 *
 * Three write paths accept a payload the calling agent authored - distilled
 * claims, a derived fact, a synthesized research report - and commit it
 * straight into the vault. Loose parsing there does not surface as an error:
 * it surfaces later as corrupted knowledge. This module is the ingress gate
 * those paths validate against BEFORE any normalization runs.
 *
 * The validator is the JSON-subset checker the Model Context Protocol output
 * contract has always used, promoted here so there is exactly ONE definition;
 * `src/mcp/output-contract.ts` now consumes it rather than owning a twin.
 *
 * Two properties are deliberate and load-bearing:
 *
 *   - Validation is UNCONDITIONAL. This module reads no settings and no
 *     environment. A gate that can be switched off is a gate the write path
 *     cannot rely on, and one defaulting to today's tolerance would ship the
 *     strict path inert - the silent no-op this project forbids.
 *   - Descriptors stay SHALLOW: required keys, primitive types, arrays of
 *     objects. Over-constraining an extraction payload degrades recall, which
 *     is the failure this layer must not cause.
 *
 * The layer is named for response *shape* throughout, and never borrows the
 * noun the knowledge vocabulary already owns, so the two cannot be confused
 * with each other - a test pins that naming so it cannot drift back.
 */

/** Value kinds a descriptor can require. */
export const SHAPE_TYPES = Object.freeze([
  "object",
  "array",
  "string",
  "number",
  "integer",
  "boolean",
  "null",
] as const);

export type ShapeType = (typeof SHAPE_TYPES)[number];

/** The complete set of keys a descriptor node may declare. */
export const SHAPE_DESCRIPTOR_KEYS = Object.freeze([
  "type",
  "required",
  "properties",
  "items",
  "enum",
  "additionalProperties",
  "nonBlank",
] as const);

/**
 * One node of a response-shape descriptor. Anything outside
 * {@link SHAPE_DESCRIPTOR_KEYS} is not expressible here - by design: a
 * descriptor a reader can hold in their head is a descriptor that stays
 * accurate.
 */
export interface ShapeDescriptor {
  readonly type?: ShapeType;
  readonly required?: ReadonlyArray<string>;
  readonly properties?: Readonly<Record<string, ShapeDescriptor>>;
  readonly items?: ShapeDescriptor;
  readonly enum?: ReadonlyArray<unknown>;
  readonly additionalProperties?: boolean | ShapeDescriptor;
  /**
   * String values only: an empty or whitespace-only string is a violation.
   * A key can be present and still carry no content, and on these write paths
   * a blank string is not a value - it is a missing one wearing the right
   * type. Declaring that here keeps `required` about presence and lets the
   * descriptor say what the parsers it replaced said.
   */
  readonly nonBlank?: boolean;
}

/** Stable codes a violation is classified under; never assembled from prose. */
export const SHAPE_VIOLATION_CODES = Object.freeze({
  typeMismatch: "shape_type_mismatch",
  missingProperty: "shape_missing_property",
  unexpectedProperty: "shape_unexpected_property",
  disallowedValue: "shape_disallowed_value",
  blankString: "shape_blank_string",
} as const);

/** Wording of a blank-string violation, kept as the parsers it replaced read. */
const BLANK_STRING_MESSAGE = "must be a non-empty string";

export type ShapeViolationCode = (typeof SHAPE_VIOLATION_CODES)[keyof typeof SHAPE_VIOLATION_CODES];

/** One structural defect, located by path and classified by code. */
export interface ShapeViolation {
  readonly code: ShapeViolationCode;
  /** JSON-path-ish location, e.g. `$.findings[0].sources`. */
  readonly path: string;
  /** The defect, without the path - callers render `<path>: <message>`. */
  readonly message: string;
}

/** Path assigned to the payload root. */
export const SHAPE_ROOT_PATH = "$";

/** Render one violation as the single line a caller prints or joins. */
export function formatShapeViolation(violation: ShapeViolation): string {
  return `${violation.path}: ${violation.message}`;
}

/**
 * Check `value` against `descriptor`, returning every violation found. An
 * empty array means the payload conforms. Pure: reads nothing but its
 * arguments, so the same payload always produces the same verdict.
 */
export function checkResponseShape(
  descriptor: ShapeDescriptor,
  value: unknown,
  path: string = SHAPE_ROOT_PATH,
): ShapeViolation[] {
  const violations: ShapeViolation[] = [];

  if (descriptor.enum && !descriptor.enum.some((allowed) => Object.is(allowed, value))) {
    violations.push(
      makeViolation(
        SHAPE_VIOLATION_CODES.disallowedValue,
        path,
        `expected one of ${descriptor.enum.map(String).join(", ")}`,
      ),
    );
    return violations;
  }

  if (descriptor.type && !matchesType(value, descriptor.type)) {
    violations.push(typeViolation(path, descriptor.type));
    return violations;
  }

  if (descriptor.nonBlank === true && typeof value === "string" && value.trim().length === 0) {
    violations.push(makeViolation(SHAPE_VIOLATION_CODES.blankString, path, BLANK_STRING_MESSAGE));
    return violations;
  }

  if (descriptor.type === "object" || descriptor.properties || descriptor.required) {
    if (!isRecord(value)) {
      if (!descriptor.type) violations.push(typeViolation(path, "object"));
      return violations;
    }

    for (const requiredKey of descriptor.required ?? []) {
      if (!hasOwn(value, requiredKey)) {
        violations.push(
          makeViolation(
            SHAPE_VIOLATION_CODES.missingProperty,
            path,
            `missing required property '${requiredKey}'`,
          ),
        );
      }
    }

    const properties = descriptor.properties ?? {};
    for (const [key, childDescriptor] of Object.entries(properties)) {
      if (hasOwn(value, key)) {
        violations.push(...checkResponseShape(childDescriptor, value[key], `${path}.${key}`));
      }
    }

    const additional = descriptor.additionalProperties;
    if (additional === false) {
      for (const key of Object.keys(value)) {
        if (!hasOwn(properties, key)) {
          violations.push(
            makeViolation(
              SHAPE_VIOLATION_CODES.unexpectedProperty,
              path,
              `unexpected property '${key}'`,
            ),
          );
        }
      }
    } else if (typeof additional === "object") {
      for (const [key, childValue] of Object.entries(value)) {
        if (!hasOwn(properties, key)) {
          violations.push(...checkResponseShape(additional, childValue, `${path}.${key}`));
        }
      }
    }
  }

  if (descriptor.type === "array" || descriptor.items) {
    if (!Array.isArray(value)) {
      if (!descriptor.type) violations.push(typeViolation(path, "array"));
      return violations;
    }
    const items = descriptor.items;
    if (items) {
      value.forEach((item, index) => {
        violations.push(...checkResponseShape(items, item, `${path}[${index}]`));
      });
    }
  }

  return violations;
}

/**
 * An agent-authored payload did not match the shape its write path declares.
 * Carries the defect structurally - `code`, `path`, and the full violation
 * list - so a caller routes on fields rather than parsing the message.
 * Nothing has been written when this is thrown.
 */
export class ResponseShapeError extends Error {
  /** Code of the first violation; the full set is on {@link violations}. */
  readonly code: ShapeViolationCode;
  /** Path of the first violation. */
  readonly path: string;
  /** The write path that declared the descriptor, e.g. `distill_claims`. */
  readonly surface: string;
  readonly violations: ReadonlyArray<ShapeViolation>;

  constructor(surface: string, violations: ReadonlyArray<ShapeViolation>) {
    const first = violations[0];
    if (first === undefined) {
      throw new TypeError("ResponseShapeError requires at least one violation");
    }
    super(`${surface} response shape violated: ${violations.map(formatShapeViolation).join("; ")}`);
    this.name = "ResponseShapeError";
    this.code = first.code;
    this.path = first.path;
    this.surface = surface;
    this.violations = Object.freeze([...violations]);
  }
}

/**
 * Fail-closed gate: return silently when the payload conforms, throw
 * {@link ResponseShapeError} otherwise. There is no tolerant mode and no key
 * that relaxes it - a violating payload is never coerced, never partially
 * accepted, and never dropped.
 */
export function assertResponseShape(
  surface: string,
  descriptor: ShapeDescriptor,
  value: unknown,
): void {
  const violations = checkResponseShape(descriptor, value);
  if (violations.length > 0) throw new ResponseShapeError(surface, violations);
}

// ----- Declared descriptors, one per model-authored write path -------------

/** Surface label of the source-distillation claims payload. */
export const DISTILL_CLAIMS_SURFACE = "distill_claims";
/** Surface label of the derived-fact payload. */
export const DERIVED_FACT_SURFACE = "derived_fact";
/** Surface label of the research-report synthesis payload. */
export const RESEARCH_REPORT_SURFACE = "research_report";
/** Surface label of the model-mined session-signal payload. */
export const EXTRACTED_SIGNALS_SURFACE = "extracted_signals";
/** Surface label of the skill draft written from a mature vault page. */
export const SKILL_PAGE_DRAFT_SURFACE = "skill_page_draft";
/** Surface label of the one-shot design note. */
export const DESIGN_NOTE_SURFACE = "design_note";

const STRING_SHAPE: ShapeDescriptor = { type: "string" };
const STRING_LIST_SHAPE: ShapeDescriptor = { type: "array", items: STRING_SHAPE };
/** A string that must carry content - the previous parsers' `requiredString`. */
const FILLED_STRING_SHAPE: ShapeDescriptor = { type: "string", nonBlank: true };
const FILLED_STRING_LIST_SHAPE: ShapeDescriptor = {
  type: "array",
  items: FILLED_STRING_SHAPE,
};

/**
 * Atomic claims distilled from one source. Deliberately open to extra keys:
 * a claim carrying a field this version does not read is not a reason to
 * reject the whole distillation.
 */
export const DISTILL_CLAIMS_SHAPE: ShapeDescriptor = freezeDescriptor({
  type: "array",
  items: {
    type: "object",
    required: ["text"],
    properties: { text: STRING_SHAPE, block: STRING_SHAPE },
  },
});

/**
 * A second-order conclusion plus the premises it was reasoned from. `level`
 * is checked as a string here; the derivation vocabulary itself is owned by
 * `provenance.ts` and narrowed there, so it is never duplicated.
 */
export const DERIVED_FACT_SHAPE: ShapeDescriptor = freezeDescriptor({
  type: "object",
  required: ["slug", "topic", "principle", "premises", "level"],
  properties: {
    slug: STRING_SHAPE,
    topic: STRING_SHAPE,
    principle: STRING_SHAPE,
    premises: STRING_LIST_SHAPE,
    level: STRING_SHAPE,
  },
});

/**
 * A synthesized report: consulted sources plus findings that cite them.
 *
 * Every string here is required to carry content. The citation contract is
 * checked by SET MEMBERSHIP - a finding's source must be one of the consulted
 * sources - so a blank source satisfies a blank citation and an uncited claim
 * passes as a cited one. That contract can only be as strong as the strings it
 * compares, which is why the constraint belongs here rather than downstream.
 */
export const RESEARCH_REPORT_SHAPE: ShapeDescriptor = freezeDescriptor({
  type: "object",
  required: ["title", "sources", "findings"],
  properties: {
    title: FILLED_STRING_SHAPE,
    sources: FILLED_STRING_LIST_SHAPE,
    findings: {
      type: "array",
      items: {
        type: "object",
        required: ["statement", "sources"],
        properties: { statement: FILLED_STRING_SHAPE, sources: FILLED_STRING_LIST_SHAPE },
      },
    },
  },
});

/**
 * Taste signals a model mined from one imported session's user turns.
 *
 * Structure only. The two rules that actually protect the inbox - at most
 * N items per session, and a floor under each item's confidence - read the
 * whole list or compare a number against a limit, so they live in the
 * semantic-check registry beside this descriptor rather than inside it.
 * `sign` is checked against the two-member sign vocabulary here because a
 * third value is a structural defect, not a judgement call.
 */
export const EXTRACTED_SIGNALS_SHAPE: ShapeDescriptor = freezeDescriptor({
  type: "object",
  required: ["items"],
  properties: {
    items: {
      type: "array",
      items: {
        type: "object",
        required: ["topic", "signal", "principle", "confidence"],
        properties: {
          topic: FILLED_STRING_SHAPE,
          signal: { enum: ["positive", "negative"] },
          principle: FILLED_STRING_SHAPE,
          confidence: { type: "number" },
          scope: STRING_SHAPE,
          // Optional plan turn id, for the decision-model pre-filter's
          // regret measurement. Absent behaves as before.
          source_turn: STRING_SHAPE,
        },
      },
    },
  },
});

/**
 * A SKILL.md draft written from one mature vault page.
 *
 * Every field must carry content: a skill with a blank description is a
 * skill no lexical matcher can ever surface, and a blank body is an
 * installed file that teaches nothing. What is NOT here is the charset
 * rule on `name` - the descriptor language has no pattern key, and the
 * name becomes a DIRECTORY under the skills root, so the constraint is a
 * semantic check beside this descriptor rather than a widening of it.
 */
export const SKILL_PAGE_DRAFT_SHAPE: ShapeDescriptor = freezeDescriptor({
  type: "object",
  required: ["name", "description", "triggers", "body"],
  properties: {
    name: FILLED_STRING_SHAPE,
    description: FILLED_STRING_SHAPE,
    triggers: FILLED_STRING_LIST_SHAPE,
    body: FILLED_STRING_SHAPE,
  },
});

/**
 * A design note: named alternatives, one of them recommended.
 *
 * `recommended` is checked here only as a BOOLEAN. The rule that matters -
 * exactly one alternative carries `true` - reads the whole array at once,
 * which the descriptor language cannot express and is not being widened
 * to; it lives in the semantic-check registry beside this descriptor.
 */
export const DESIGN_NOTE_SHAPE: ShapeDescriptor = freezeDescriptor({
  type: "object",
  required: ["title", "alternatives"],
  properties: {
    title: FILLED_STRING_SHAPE,
    summary: FILLED_STRING_SHAPE,
    alternatives: {
      type: "array",
      items: {
        type: "object",
        required: ["name", "approach", "tradeoffs", "recommended"],
        properties: {
          name: FILLED_STRING_SHAPE,
          approach: FILLED_STRING_SHAPE,
          tradeoffs: FILLED_STRING_SHAPE,
          recommended: { type: "boolean" },
        },
      },
    },
  },
});

/**
 * Every declared descriptor, by surface. The registry exists so the shallow-
 * and-expressible discipline can be asserted over the whole set at once
 * rather than one descriptor at a time.
 */
export const MODEL_AUTHORED_SHAPES: Readonly<Record<string, ShapeDescriptor>> = Object.freeze({
  [DISTILL_CLAIMS_SURFACE]: DISTILL_CLAIMS_SHAPE,
  [DERIVED_FACT_SURFACE]: DERIVED_FACT_SHAPE,
  [RESEARCH_REPORT_SURFACE]: RESEARCH_REPORT_SHAPE,
  [EXTRACTED_SIGNALS_SURFACE]: EXTRACTED_SIGNALS_SHAPE,
  [SKILL_PAGE_DRAFT_SURFACE]: SKILL_PAGE_DRAFT_SHAPE,
  [DESIGN_NOTE_SURFACE]: DESIGN_NOTE_SHAPE,
});

// ----- Internals ----------------------------------------------------------

function makeViolation(code: ShapeViolationCode, path: string, message: string): ShapeViolation {
  return Object.freeze({ code, path, message });
}

function typeViolation(path: string, type: ShapeType): ShapeViolation {
  return makeViolation(SHAPE_VIOLATION_CODES.typeMismatch, path, `expected ${type}`);
}

/** Freeze a declared descriptor all the way down, so it cannot drift at runtime. */
function freezeDescriptor<T>(descriptor: T): T {
  if (descriptor !== null && typeof descriptor === "object") {
    for (const child of Object.values(descriptor)) freezeDescriptor(child);
    Object.freeze(descriptor);
  }
  return descriptor;
}

function matchesType(value: unknown, type: ShapeType): boolean {
  if (type === "null") return value === null;
  if (type === "array") return Array.isArray(value);
  if (type === "object") return isRecord(value);
  if (type === "integer") return typeof value === "number" && Number.isInteger(value);
  if (type === "number") return typeof value === "number" && Number.isFinite(value);
  return typeof value === type;
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function hasOwn(value: object, key: string): boolean {
  return Object.prototype.hasOwnProperty.call(value, key);
}