Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.1 KB
Raw Blame
/**
 * Health: `getHealth` once for both engines (FOUNDATIONS 1, F4a).
 *
 * Three statements, no per-page rows returned to TypeScript:
 *   1. counters: page, chunk and link counts, embedding coverage, missing
 *      embeddings, dead links, entity link/timeline coverage. Entity pages
 *      are the types the active schema pack(s) declare as entities (#4772),
 *      resolved per source by `HealthDeps.entityTypes` and bound as text[]
 *      parameters; an unavailable pack binds an empty list and the result
 *      says so in `entity_types_status`;
 *   2. the linkable scope (live, unquarantined pages the shared orphan policy
 *      keeps, rendered in SQL by `orphanExclusionSql`) grouped by page type,
 *      with islanded and with-timeline counts per type. The brain_score
 *      timeline component's pack-aware grading (#5828) applies per type here;
 *   3. `most_connected`: live, in-scope link endpoints grouped per entity page.
 * Statement 2 is separate because, folded into statement 1, the combined
 * plan cost crosses Postgres's JIT thresholds on a 20k-page brain and JIT
 * compilation alone costs more than the query.
 *
 * Planner robustness: PGLite has no autovacuum, so a brain can be queried
 * before its first ANALYZE. Without statistics the planner underestimates
 * every filtered relation and picks nested loops that re-scan a subquery or
 * materialized set per outer row. The per-page and per-link checks that
 * were exposed to that (linkable flags, entity link coverage, endpoint scope
 * in `most_connected`, the chunk-to-page lookup) are written as primary-key
 * lookups the planner cannot reorder: scalar subqueries, or a LATERAL
 * subquery fenced with OFFSET 0. They stay linear with or without statistics.
 *
 * Scope (#4592): `sourceIds` > `sourceId` > brain-wide; duplicate ids count
 * once. Every count, coverage numerator and denominator, degree and the
 * islanded predicate confine to the scope; a link contributes only when both
 * endpoints are in scope, so a granted-to-ungranted edge never leaks the far
 * side through a degree or rescues a page from orphan-hood. Page-scoped
 * counts exclude soft-deleted pages (#1305); chunk and link counts stay raw,
 * matching getStats. Endpoint liveness (gbrain#4153): an inbound link counts
 * only when its source page is live, an outbound link only when its target
 * is. Quarantined pages (#4280) leave the entity denominators and the
 * linkable scope; machine leaf types leave the linkable scope through the
 * policy.
 *
 * Both engines ran these reads on the pool with no scope transaction, so the
 * statements take `LegacyUnscopedRead`.
 */
import type { BrainHealth } from '../types.ts';
import { MIN_ENTITY_PAGES_FOR_COVERAGE } from '../types.ts';
import { effectiveLinkExtractorWatermark } from '../link-extraction-watermark.ts';
import { QUARANTINE_FILTER_FRAGMENT } from '../quarantine.ts';
import { loadOrphanPolicyOverrides, orphanExclusionSql } from '../orphan-policy.ts';
import { loadTimelineGradedPredicate } from '../timeline-grading.ts';
import { quoteIdentifier } from '../search/embedding-column.ts';
import { entityTypePredicateSql, type EntityTypeResolution } from '../schema-pack/entity-types.ts';
import type { LegacyUnscopedRead } from './brands.ts';
import { sqlFragment, trustedSql } from './fragment.ts';
import { compileRowNormalizer } from './normalize.ts';

/** What getHealth needs from its engine besides the executor. */
export interface HealthDeps {
  /** Name of the registry-active embedding column (legacy column when the registry is unreadable). */
  embeddingColumn(): Promise<string>;
  countStalePagesForExtraction(opts: { sourceId?: string; versionTs: string }): Promise<number>;
  getConfig(key: string): Promise<string | null>;
  /**
   * #4772: the entity type lists for the requested scope (null = brain-wide),
   * resolved per source from the active schema pack(s) by
   * `schema-pack/entity-types.ts`; `pack_unavailable` carries an empty filter.
   */
  entityTypes(scope: readonly string[] | null): Promise<EntityTypeResolution>;
}

interface LinkableTypeGroup {
  type: string;
  linkable: number;
  islanded: number;
  with_timeline: number;
}

interface HealthAggregateRow {
  page_count: number;
  embed_coverage: number;
  dead_links: number;
  missing_embeddings: number;
  link_count: number;
  entity_page_count: number;
  link_coverage: number;
  timeline_coverage: number;
}

const normalizeAggregate = compileRowNormalizer<HealthAggregateRow>({
  page_count: 'bigint',
  dead_links: 'bigint',
  missing_embeddings: 'bigint',
  link_count: 'bigint',
  entity_page_count: 'bigint',
});

export async function getHealth(
  exec: LegacyUnscopedRead,
  opts: { sourceId?: string; sourceIds?: string[] } | undefined,
  deps: HealthDeps,
): Promise<BrainHealth> {
  const requested = opts?.sourceIds ?? (opts?.sourceId ? [opts.sourceId] : null);
  const scope = requested === null ? null : [...new Set(requested)];
  const [column, orphanOverrides, isTimelineGraded, entityTypes] = await Promise.all([
    deps.embeddingColumn(),
    loadOrphanPolicyOverrides(deps),
    loadTimelineGradedPredicate(deps),
    deps.entityTypes(scope),
  ]);
  const col = trustedSql(quoteIdentifier(column));
  const isEntity = entityTypePredicateSql('p', entityTypes.filter);
  const inScope = {
    p: scope === null ? sqlFragment`` : sqlFragment`AND p.source_id = ANY(${scope}::text[])`,
    src: scope === null ? sqlFragment`` : sqlFragment`AND src.source_id = ANY(${scope}::text[])`,
    tgt: scope === null ? sqlFragment`` : sqlFragment`AND tgt.source_id = ANY(${scope}::text[])`,
  };
  // Endpoint checks by primary key; NULL (not true) when the row is missing.
  const liveSrc = sqlFragment`(SELECT src.deleted_at IS NULL ${inScope.src} FROM pages src WHERE src.id = l.from_page_id)`;
  const liveTgt = sqlFragment`(SELECT tgt.deleted_at IS NULL ${inScope.tgt} FROM pages tgt WHERE tgt.id = l.to_page_id)`;
  const deadLinkScope = scope === null
    ? sqlFragment``
    : sqlFragment`AND EXISTS (SELECT 1 FROM pages src WHERE src.id = l.from_page_id ${inScope.src})`;
  const linkCountScope = scope === null
    ? sqlFragment``
    : sqlFragment`WHERE EXISTS (SELECT 1 FROM pages src WHERE src.id = l.from_page_id ${inScope.src})
                    AND EXISTS (SELECT 1 FROM pages tgt WHERE tgt.id = l.to_page_id ${inScope.tgt})`;

  const { rows: [aggregate] } = await exec.run(sqlFragment`
    WITH entity_pages AS (
      SELECT p.id FROM pages p
      WHERE ${isEntity} AND p.deleted_at IS NULL
        AND ${trustedSql(QUARANTINE_FILTER_FRAGMENT)}
        ${inScope.p}
    ),
    chunk_pages AS (
      SELECT cc.page_id, count(*) AS chunks, count(*) FILTER (WHERE cc.${col} IS NOT NULL) AS embedded
        FROM content_chunks cc
       GROUP BY cc.page_id
    ),
    chunk_totals AS (
      -- #7212: coverage counts the same live, eligible chunks as missing_embeddings; a soft-deleted page's retained chunks count in neither.
      SELECT COALESCE(sum(c.chunks) FILTER (WHERE f.eligible AND f.live), 0) AS eligible,
             COALESCE(sum(c.embedded) FILTER (WHERE f.eligible AND f.live), 0) AS eligible_embedded,
             COALESCE(sum(c.chunks - c.embedded) FILTER (WHERE f.eligible AND f.live), 0) AS missing
        FROM chunk_pages c
        CROSS JOIN LATERAL (
          SELECT p.deleted_at IS NULL AS live,
                 NOT jsonb_exists(COALESCE(p.frontmatter, '{}'::jsonb), 'embed_skip') AS eligible
            FROM pages p
           WHERE p.id = c.page_id ${inScope.p}
          OFFSET 0
        ) f
    )
    SELECT
      (SELECT count(*) FROM pages p WHERE p.deleted_at IS NULL ${inScope.p}) AS page_count,
      (SELECT CASE WHEN eligible = 0 THEN 1.0 ELSE eligible_embedded::float / eligible::float END
         FROM chunk_totals)::float AS embed_coverage,
      (SELECT count(*) FROM links l
        WHERE NOT EXISTS (SELECT 1 FROM pages p WHERE p.id = l.to_page_id)
          ${deadLinkScope}) AS dead_links,
      (SELECT missing::bigint FROM chunk_totals) AS missing_embeddings,
      (SELECT count(*) FROM links l ${linkCountScope}) AS link_count,
      (SELECT count(*) FROM entity_pages) AS entity_page_count,
      (SELECT count(*) FROM entity_pages e
        WHERE EXISTS (SELECT 1 FROM links l WHERE l.to_page_id = e.id AND ${liveSrc}))::float /
        GREATEST((SELECT count(*) FROM entity_pages), 1)::float AS link_coverage,
      (SELECT count(*) FROM entity_pages e
        WHERE EXISTS (SELECT 1 FROM timeline_entries te WHERE te.page_id = e.id))::float /
        GREATEST((SELECT count(*) FROM entity_pages), 1)::float AS timeline_coverage
  `);
  const h = normalizeAggregate(aggregate);

  const { rows: linkableGroups } = await exec.run<LinkableTypeGroup>(sqlFragment`
    WITH linkable_pages AS MATERIALIZED (
      SELECT p.type,
             (NOT EXISTS (SELECT 1 FROM links l WHERE l.to_page_id = p.id AND ${liveSrc})
              AND NOT EXISTS (SELECT 1 FROM links l WHERE l.from_page_id = p.id AND ${liveTgt})) AS islanded,
             EXISTS (SELECT 1 FROM timeline_entries te WHERE te.page_id = p.id) AS has_timeline
        FROM pages p
       WHERE p.deleted_at IS NULL
         AND ${trustedSql(QUARANTINE_FILTER_FRAGMENT)}
         ${inScope.p}
         AND NOT ${orphanExclusionSql('p', orphanOverrides)}
    )
    SELECT type, count(*)::int AS linkable,
           (count(*) FILTER (WHERE islanded))::int AS islanded,
           (count(*) FILTER (WHERE has_timeline))::int AS with_timeline
      FROM linkable_pages
     GROUP BY type
     ORDER BY type
  `);

  const { rows: connected } = await exec.run<{ slug: string; link_count: number }>(sqlFragment`
    WITH entity_pages AS (
      SELECT p.id, p.slug FROM pages p
      WHERE ${isEntity} AND p.deleted_at IS NULL
        AND ${trustedSql(QUARANTINE_FILTER_FRAGMENT)}
        ${inScope.p}
    ),
    endpoints AS (
      SELECT e.id, e.slug, 0 AS hit FROM entity_pages e
      UNION ALL
      SELECT e.id, e.slug, 1 AS hit FROM entity_pages e
        JOIN links l ON l.from_page_id = e.id AND ${liveTgt}
      UNION ALL
      SELECT e.id, e.slug, 1 AS hit FROM entity_pages e
        JOIN links l ON l.to_page_id = e.id AND l.from_page_id <> l.to_page_id AND ${liveSrc}
    )
    SELECT slug, sum(hit)::int AS link_count
      FROM endpoints
     GROUP BY id, slug
     ORDER BY link_count DESC, slug COLLATE "C", id
     LIMIT 5
  `);

  const watermark = await effectiveLinkExtractorWatermark(deps);
  const stalePages = scope === null
    ? await deps.countStalePagesForExtraction({ versionTs: watermark })
    : (await Promise.all(scope.map(sourceId =>
        deps.countStalePagesForExtraction({ sourceId, versionTs: watermark }),
      ))).reduce((a, b) => a + b, 0);

  let linkablePageCount = 0;
  let orphanPages = 0;
  let timelineGradedCount = 0;
  let linkableTimelinePages = 0;
  for (const group of linkableGroups) {
    linkablePageCount += Number(group.linkable);
    orphanPages += Number(group.islanded);
    if (!isTimelineGraded(group.type)) continue;
    timelineGradedCount += Number(group.linkable);
    linkableTimelinePages += Number(group.with_timeline);
  }

  const pageCount = h.page_count;
  const embedCoverage = Number(h.embed_coverage);
  const deadLinks = h.dead_links;
  const linkCount = h.link_count;
  const linkDensity = pageCount > 0 ? Math.min(linkCount / pageCount, 1) : 0;
  // A brain with no linkable (or no graded) pages gets full marks for the
  // orphan / timeline components: there is no curated graph to penalize.
  const timelineDensity = timelineGradedCount > 0 ? Math.min(linkableTimelinePages / timelineGradedCount, 1) : 1;
  const noOrphans = linkablePageCount > 0 ? 1 - (orphanPages / linkablePageCount) : 1;
  const noDeadLinks = pageCount > 0 ? 1 - Math.min(deadLinks / pageCount, 1) : 1;
  // Empty brains (pageCount === 0) score 100/100: nothing to embed, link or orphan.
  const embedCoverageScore = pageCount === 0 ? 35 : Math.round(embedCoverage * 35);
  const linkDensityScore = pageCount === 0 ? 25 : Math.round(linkDensity * 25);
  const timelineCoverageScore = pageCount === 0 ? 15 : Math.round(timelineDensity * 15);
  const noOrphansScore = pageCount === 0 ? 15 : Math.round(noOrphans * 15);
  const noDeadLinksScore = pageCount === 0 ? 10 : Math.round(noDeadLinks * 10);
  // gbrain#4147: below the small-N floor the entity ratios report null.
  const coverageGraded = h.entity_page_count >= MIN_ENTITY_PAGES_FOR_COVERAGE;

  return {
    page_count: pageCount,
    linkable_page_count: linkablePageCount,
    embed_coverage: embedCoverage,
    stale_pages: stalePages,
    orphan_pages: orphanPages,
    missing_embeddings: h.missing_embeddings,
    brain_score: embedCoverageScore + linkDensityScore + timelineCoverageScore + noOrphansScore + noDeadLinksScore,
    dead_links: deadLinks,
    entity_page_count: h.entity_page_count,
    entity_types_status: entityTypes.status,
    link_coverage: coverageGraded ? Number(h.link_coverage) : null,
    timeline_coverage: coverageGraded ? Number(h.timeline_coverage) : null,
    most_connected: connected.map(c => ({ slug: c.slug, link_count: Number(c.link_count) })),
    embed_coverage_score: embedCoverageScore,
    link_density_score: linkDensityScore,
    timeline_coverage_score: timelineCoverageScore,
    no_orphans_score: noOrphansScore,
    no_dead_links_score: noDeadLinksScore,
  };
}