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.6 KB
Raw Blame
/**
 * The quote check of a distillation: every quoted span in a claim is compared
 * with the evidence the claim rests on. Pure; no I/O.
 *
 * - A claim that cites a block is compared with that block only. A block that
 *   does not resolve is `block-not-found` (a duplicate id `block-ambiguous`),
 *   never a silent fall-back to the whole source: the citation is part of what
 *   the page asserts.
 * - A claim without a block is compared with the whole evidence text and, when
 *   it matches, is `verified-in-source`, a weaker outcome than
 *   `verified-in-block` that never reads as the stronger one.
 * - Evidence with no checkable text (`url-only`, or bytes that are not UTF-8)
 *   verifies nothing.
 *
 * A failed span loses exactly its two quotation marks; its words stay, and the
 * failure is named in the report. Unpaired marks are counted and left alone.
 * Matching runs over {@link normalizeForQuoteComparison} on both sides, so the
 * claim and source bytes themselves are never normalised.
 */

import { indexBlocks, lookupBlock, type BlockIndex } from "./block-resolve.ts";
import type { DistillClaim } from "./claim.ts";
import {
  findQuoteSpans,
  normalizeForQuoteComparison,
  quoteHaystack,
  spanOccursIn,
  unquoteSpans,
  type QuoteHaystack,
  type QuoteSpan,
} from "./quote-spans.ts";
import {
  QUOTE_CHECK_OUTCOME,
  QUOTE_FINDINGS_MAX,
  QUOTE_SPAN_PREVIEW_MAX_CHARS,
  VERIFIED_QUOTE_OUTCOMES,
  type QuoteCheckOutcome,
  type QuoteCheckReport,
  type QuoteFinding,
} from "./quote-verdict.ts";

/** What the claims are checked against. */
export type QuoteEvidence =
  | { readonly kind: "text"; readonly text: string }
  | { readonly kind: "not-text" }
  | { readonly kind: typeof QUOTE_CHECK_OUTCOME.urlOnly };

export interface QuoteCheckInput {
  readonly claims: ReadonlyArray<DistillClaim>;
  readonly evidence: QuoteEvidence;
}

export interface QuoteCheckResult {
  /** The claims as they may be written: every failed span unquoted. */
  readonly claims: ReadonlyArray<DistillClaim>;
  /** `null` when no claim contains a quoted span. */
  readonly report: QuoteCheckReport | null;
}

/** The outcome every span gets when the evidence holds no checkable text. */
const TEXTLESS_OUTCOME: Readonly<
  Record<Exclude<QuoteEvidence["kind"], "text">, QuoteCheckOutcome>
> = Object.freeze({
  "not-text": QUOTE_CHECK_OUTCOME.sourceNotText,
  [QUOTE_CHECK_OUTCOME.urlOnly]: QUOTE_CHECK_OUTCOME.urlOnly,
});

/**
 * The comparison target of one claim: normalised text to search, or an
 * outcome that settles every span of the claim without a search.
 */
type Target =
  | {
      readonly kind: "haystack";
      readonly haystack: QuoteHaystack;
      readonly verified: QuoteCheckOutcome;
      readonly failed: QuoteCheckOutcome;
    }
  | { readonly kind: "settled"; readonly outcome: QuoteCheckOutcome };

/**
 * Builds each claim's target. The whole source is normalised at most once,
 * its blocks are indexed at most once, and each cited block is resolved and
 * normalised at most once however many claims cite it.
 */
function targetResolver(evidence: QuoteEvidence): (claim: DistillClaim) => Target {
  if (evidence.kind !== "text") {
    const settled: Target = { kind: "settled", outcome: TEXTLESS_OUTCOME[evidence.kind] };
    return () => settled;
  }
  let wholeSource: Target | undefined;
  let blocks: BlockIndex | undefined;
  const byBlock = new Map<string, Target>();
  const blockTarget = (blockId: string): Target => {
    blocks ??= indexBlocks(evidence.text);
    const block = lookupBlock(blocks, blockId);
    switch (block.kind) {
      case "found":
        return {
          kind: "haystack",
          haystack: quoteHaystack(normalizeForQuoteComparison(block.text)),
          verified: QUOTE_CHECK_OUTCOME.verifiedInBlock,
          failed: QUOTE_CHECK_OUTCOME.notInBlock,
        };
      case "not-found":
        return { kind: "settled", outcome: QUOTE_CHECK_OUTCOME.blockNotFound };
      case "ambiguous":
        return { kind: "settled", outcome: QUOTE_CHECK_OUTCOME.blockAmbiguous };
    }
  };
  return (claim) => {
    if (claim.block === undefined) {
      wholeSource ??= {
        kind: "haystack",
        haystack: quoteHaystack(normalizeForQuoteComparison(evidence.text)),
        verified: QUOTE_CHECK_OUTCOME.verifiedInSource,
        failed: QUOTE_CHECK_OUTCOME.notInSource,
      };
      return wholeSource;
    }
    let target = byBlock.get(claim.block);
    if (target === undefined) {
      target = blockTarget(claim.block);
      byBlock.set(claim.block, target);
    }
    return target;
  };
}

function spanOutcome(span: QuoteSpan, target: Target): QuoteCheckOutcome {
  if (target.kind === "settled") return target.outcome;
  return spanOccursIn(span.inner, target.haystack) ? target.verified : target.failed;
}

/** The span's own text, cut at the preview cap without splitting a code point. */
function preview(inner: string): string {
  const codePoints = Array.from(inner);
  return codePoints.length <= QUOTE_SPAN_PREVIEW_MAX_CHARS
    ? inner
    : codePoints.slice(0, QUOTE_SPAN_PREVIEW_MAX_CHARS).join("");
}

/**
 * Check every quoted span of every claim against the evidence. Returns the
 * claims as they may be written (failed spans unquoted) and the report, or a
 * `null` report when no claim contains a span.
 */
export function checkClaimQuotes(input: QuoteCheckInput): QuoteCheckResult {
  const targetFor = targetResolver(input.evidence);
  const findings: QuoteFinding[] = [];
  let checked = 0;
  let verifiedInBlock = 0;
  let verifiedInSource = 0;
  let unpaired = 0;

  const claims = input.claims.map((claim, index) => {
    const scan = findQuoteSpans(claim.text);
    unpaired += scan.unpaired;
    if (scan.spans.length === 0) return claim;
    const target = targetFor(claim);
    const failed: QuoteSpan[] = [];
    for (const span of scan.spans) {
      checked++;
      const outcome = spanOutcome(span, target);
      if (!VERIFIED_QUOTE_OUTCOMES.has(outcome)) {
        failed.push(span);
        findings.push({ claim: index, outcome, span: preview(span.inner) });
      } else if (outcome === QUOTE_CHECK_OUTCOME.verifiedInBlock) verifiedInBlock++;
      else verifiedInSource++;
    }
    return failed.length === 0 ? claim : { ...claim, text: unquoteSpans(claim.text, failed) };
  });

  if (checked === 0) return { claims: input.claims, report: null };
  const returned = findings.slice(0, QUOTE_FINDINGS_MAX);
  return {
    claims,
    report: {
      checked,
      verified_in_block: verifiedInBlock,
      verified_in_source: verifiedInSource,
      unquoted: findings.length,
      unpaired,
      findings: returned,
      total: findings.length,
      returned: returned.length,
      truncated: returned.length < findings.length,
    },
  };
}